chore: migrate mail themes to shared framework and locked upstream inputs

2026-10-09 18:34:36 +08:00
1 parent 5c0589f6f6
commit fec3ace600
@@ -1,83 +1,139 @@
 # 贡献指南 — Gitea 邮件模板

-## 参与方式
+## 添加主题

-### 添加新风格
+1. 执行 `cd tools && go run . create <名称>`，创建共享框架主题。
+2. 编辑 `themes/<名称>/theme.json` 和 `theme.css`。
+3. 在 `tools/` 中运行 `go run . upstream prepare`、`go test ./...` 和 `go run . preview all`。
+4. 检查英文、简体中文及另一种官方语言的桌面/移动端预览，随 PR 提交截图。

-1. 使用工具脚手架：`cd tools && go run . create <风格名称>` — 这会创建完整的目录结构和全部 11 种邮件类型的占位 `.tmpl` 文件
-2. 在 `themes/<风格名称>/` 中编写每个 `.tmpl` 文件，应用独特的视觉设计
-3. 重新生成预览：`cd tools && go run . preview all`（构建脚本会自动发现 `themes/` 下的所有主题目录并动态生成主题选择器）
-4. 提交包含截图渲染效果的 PR（单张图片 ≤ 50 KiB，建议 10–20 KiB）
+主题名称以小写字母开头，可包含小写字母、数字和连字符。主题只包含 `theme.json` 与 `theme.css`。新主题默认使用 `framed` 模式及 `standard` 框架布局；`layout` 选择共享框架中的结构预设。可选的 `shared` 模式仅注入 CSS，不添加框架控件。

-### 风格指南
+页头、操作按钮、失效提示/备用链接、侧栏和页脚统一由 `framework/mail/base/` 提供；结构预设位于 `framework/layouts/`，均属于框架，而非主题维护的邮件模板。`tools/builder/framework.go` 是唯一的官方操作值/翻译对齐层。通知分支、主题行、附件及上下文链接来自下载的官方模板，不得复制到各主题中。

- 每个风格必须包含全部 **11 种模板类型**
- 只使用 Gitea 内置模板函数
- 翻译键必须来自 Gitea 官方语言文件（`mail.*` 命名空间）
- **不要在以下模板中使用 `.DisplayName`**：collaborator、transfer、release、workflow_run、assigned、default
- 面向 600px 宽度的邮件客户端设计
- 尽可能在 Gmail、Outlook、Apple Mail 中测试
+## 设计规范

-### 报告 Bug
+- 主题仅定义展示样式，共享框架使用官方邮件值与翻译组织可复用控件。
+- 主题使用兼容邮件客户端的 CSS，框架负责展示结构；主题 CSS 不加载外部资源、不生成文字、不隐藏官方内容。框架引用实例托管的 Logo 是有意保留的图片引用。
+- 片段校验允许展示性的 table、tr、td、div、span 等节点及展示属性，检查桌面及 390px 移动端布局。
+- 尽可能测试 Gmail、Outlook、Apple Mail；浏览器预览不能模拟所有客户端的 CSS 支持。
+- 忠于原主题的配色、字体、边框、页头、按钮/备用链接及布局，不使用通用卡片或新增装饰替代既有设计。
+- 画廊截图使用 PNG，单张最多 50 KiB，建议 10–20 KiB。截图须来自当前源码构建，并关闭浮动信息面板。

-1. 检查引用的 Go 模板变量是否存在
-2. 验证翻译键是否与 Gitea 语言文件匹配
-3. 确认 `.DisplayName` 未在不支持的模板中使用
-4. 重新生成预览：`cd tools && go run . preview all`
-5. 提交 issue，注明风格名称、邮件类型及错误描述
+## 更新官方快照

-### 改进文档
+源码仅保留工具生成的 `gitea.lock.json`，记录稳定 Gitea 28+ 标签、不可变提交及文件校验值。官方模板、语言 JSON、图标、许可证和适配参考实现均下载到被忽略的 `build/upstream/`，不在仓库中维护副本。

-文档改进、预览截图、安装指南和翻译始终欢迎。
+### 命令参考

---
+以下命令均在 `tools/` 执行。三个子命令都支持 `--root <仓库根目录>`，默认值为相对当前工作目录的 `..`；参数放在子命令之后，含空格的路径须加引号。

-## 开发环境
-
- **Go 1.21+** 用于模板渲染和 CLI 工具；Go 模块需下载 `github.com/urfave/cli/v2` 及其依赖
-
-### 本地预览（静态）
-
-1. 先生成预览数据：`cd tools && go run . preview all`
-2. 在浏览器中打开 `preview/index.html` — 无需服务器
-
-### 开发服务器（实时重载）
-
-```bash
-cd tools && go run . dev
-# → http://localhost:3456
+```powershell
+# 在 tools/ 中显式指定仓库根目录：
+go run . upstream verify --root "D:\Work\Development\WebSites\GiteaMailTemplates"
 ```

-修改 `.tmpl` 文件后自动重建并推送至浏览器。HTTP 服务与 SSE 实时重载使用 Go 标准库实现，CLI 本身依赖 Go 模块。
+| 命令 | 用途 | 联网与写入行为 |
+|---|---|---|
+| `go run . upstream prepare` | 根据仓库锁文件准备精确匹配的输入 | 缓存不存在时按锁定提交下载，验证 SHA-256 后创建 `build/upstream/`；缓存存在时离线校验。不修改根锁文件。 |
+| `go run . upstream verify` | 对照根锁文件检查已有缓存 | 离线、只读，不下载；输出 `[PASS]` 及非英文缺键的 `[FALLBACK]` 列表。 |
+| `go run . upstream sync --tag vX.Y.Z` | 显式选择上游版本 | 通过 GitHub API 解析标签，按提交下载并校验快照，替换缓存并生成 `gitea.lock.json`。仅接受主版本不小于 28 的稳定 `vX.Y.Z` 标签。 |

-### 集成测试
+这些命令不支持隐式 `latest`、读取本地 Gitea 克隆、令牌参数或认证环境变量。`sync` 使用 `api.github.com`，首次 `prepare` 与 `sync` 下载使用 `raw.githubusercontent.com`；网络错误与 API 限流会报错，不会自动换版本。即使快照检查离线，Go 工具链与模块仍可能需要单独联网下载。

-将模板部署到 Gitea 实例后，请通过真实的邮件通知进行验证。管理后台的测试邮件
-（**Site Administration > Configuration > Mailer > Send Test Email**）不会使用
-自定义邮件模板——它走的是内置代码路径。
+### 已有克隆与离线使用

-最可靠的验证方式是触发一次真实的邮件通知，推荐使用密码重置流程：
+```bash
+cd tools
+go mod download
+go run . upstream prepare
+go run . upstream verify
+go test ./...
+go run . preview all
+```

-1. 退出登录，点击登录页的**"忘记密码"**
-2. 输入账户邮箱并提交
-3. 查看密码重置邮件——它将使用你的自定义邮件模板渲染
+`build all`、`preview all` 和 `dev` 会自动准备输入，但仍要求根锁文件存在。缓存完整且 Go 工具链/依赖已安装后可离线构建。`verify` 检查官方输入、适配参考实现哈希和官方英文键；框架新增键与操作锚点由构建和渲染检查，因此单独通过 `verify` 不代表兼容性验证完成。

---
+### 锁文件缺失与显式更新版本
+
+缺少 `gitea.lock.json` 时，`prepare`、`verify`、构建与预览均在读取锁文件时失败，即使 `build/upstream/lock.json` 仍在也不会代用。普通源码克隆应恢复受版本控制的根锁文件；有意首次初始化时，`sync` 不要求已有根锁文件：
+
+```bash
+cd tools
+# 当前源码基线；显式初始化，不是发布操作：
+go run . upstream sync --tag v28.0.0
+go run . upstream verify
+go test ./...
+go run . preview all
+```
+
+评审其它版本时显式替换标签，例如此处仍为 [PENDING] 的 `v28.1.0`。检查生成的锁文件差异，对齐共享框架与测试数据，执行全部检查及同版本实例冒烟测试后，再更新兼容性文档。`sync` 不构建主题、不更新 Markdown、不创建 Git 标签、不提交、不推送，也不发布。仅缓存缺失时不应使用它。
+
+翻译或邮件渲染参考实现哈希变化会阻止同步，须先复核 Go 适配逻辑；下载新版本并不等于确认兼容。官方英文须包含官方模板引用的键，构建另行检查框架键；其它语言缺键回退英文。缓存替换前的网络/校验失败不会修改原输入。缓存替换和根锁文件写入是两个操作：文件系统错误可能留下不一致状态，后续校验会失败，重试前先检查二者。
+
+### 缓存恢复
+
+`prepare` 拒绝损坏、不完整或锁文件不匹配的缓存，不合并、不静默修复；`sync` 也拒绝替换非空的无效快照。检查错误后，将精确的生成缓存目录移到备份位置，再按已复核的根锁文件执行 `prepare`。例如在 **仓库根目录的 PowerShell** 中，选择尚不存在的备份名称：
+
+```powershell
+Move-Item -LiteralPath .\build\upstream -Destination .\build\upstream.backup
+Set-Location tools
+go run . upstream prepare
+go run . upstream verify
+```
+
+不要删除整个 `build/` 或修改缓存中的官方文件。显式同步后如需回退，恢复之前已复核的根锁文件，再按同样方式重建缓存。避免多个 `sync`/`prepare`/构建进程同时操作同一缓存；替换输入前先停止 `dev`。
+
+邮件类型由快照发现，`tools/data/templates_config.json` 仅提供名称、描述和模拟上下文。新增官方邮件类型后，必须补充测试数据才能通过预览校验。
+
+Gitea v28.0.0 的波兰语 `mail.team_invite.text_1` 存在已确认的占位符缺陷。预览保留官方行为并报告 `[UPSTREAM-WARN]`，例外严格匹配官方原文。其他格式错误会使渲染失败。不要直接修改语言快照来隐藏官方问题。
+
+## 本地开发
+
+使用 **Go 1.24+**。CLI 依赖 urfave/cli，HTML 校验使用 Go 的 x/net 解析器。先执行 `go mod download` 和 `upstream prepare` 下载依赖及锁定输入，之后可离线构建。
+
+```bash
+cd tools
+go run . list
+go run . build all
+go run . preview all
+go run . dev
+# http://127.0.0.1:3456
+```
+
+`build` 将安装文件写入 `build/themes/<名称>/mail/`。`preview` 同时完成构建，生成小型清单和每种官方语言各自的 JS 数据包。直接打开 `preview/index.html` 即可静态预览，语言加载支持 `file://`。
+
+回环开发服务器监听主题 CSS/元数据、共享框架、锁文件/缓存和测试数据，通过 SSE 刷新。安装模板的 Logo 引用 `{{AppUrl}}assets/img/favicon.png`；仅静态预览的生成数据嵌入下载的官方图标，以支持离线显示。
+
+## 验证与发布
+
+测试检查框架适配与生成的确定性、操作锚点变化时失败、官方翻译键及通知语义保留。渲染覆盖全部主题/语言及推送、评审、回复、工作流和附件分支。控件及品牌区域是明确的展示增补；按钮文字、备用链接目标和 Logo 引用单独校验。
+
+发布前，在与快照标签一致的隔离 Gitea 实例中触发真实的密码重置或通知邮件。管理后台的测试邮件按钮不会使用自定义模板。确认模板加载并捕获邮件，避免向真实用户发送测试内容。
+
+可选的 `tools/integration` 测试使用临时 SQLite、用户、Git/SSH 路径及回环 SMTP 自动完成此流程。将 `GITEA_SMOKE_BINARY` 设为已校验官方 SHA-256、版本与快照一致的 Gitea 可执行文件，在 `tools/` 执行 `go test ./integration -v -count=1`。浏览器检查位于 `tools/qa`：生成预览后安装其可选依赖并运行 `npm test`；设置 `PREVIEW_DEV_URL` 可同时检查 HTTP 预览，`--update-gallery` 可更新截图。
+
+发行标签须与快照中的 Gitea 版本一致，在 `.github/release-notes/vX.Y.Z.md` 添加已复核的说明。工作流校验快照和测试，打包生成主题、多语言预览、文档及官方许可证/来源信息，再更新发布标签区块。源码修改与已发布兼容矩阵保持区分；历史标签和附件不变。
+
+手动打包时，先执行 `preview all`，再从仓库根目录运行 `python .github/scripts/package_release.py --version vX.Y.Z --output <新输出目录>`。发布工作流使用同一脚本；它校验源码/产物哈希和全部语言包，排除未声明的旧构建目录，并拒绝覆盖已有压缩包。
+
+## 报告问题
+
+注明快照标签/提交、主题、邮件类型、预览语言和错误。先运行 `go run . upstream verify` 与 `go run . preview all`，附上截图或渲染诊断。

 ## 提交规范

- `style(<名称>):` — 特定风格的模板变更
- `preview:` — 预览工具变更
- `tools:` — Go 构建脚本变更
+- `style(<名称>):` — 主题展示样式
+- `preview:` — 浏览器预览
+- `tools:` — CLI、构建及快照工具
 - `docs:` — 文档和翻译
- `fix:` — Bug 修复
- `project:` — README、LICENSE、元文件
+- `fix:` — 修复
+- `refactor:` — 重构
+- `chore:` — 维护

-## 翻译
+## 翻译与许可证

 - [English CONTRIBUTING](../CONTRIBUTING.md)
 - 简体中文（本文）

-## 许可协议
-
-参与贡献即表示您同意将您的贡献以 MIT 许可证授权。
+贡献以 MIT 许可证授权，分发派生模板时须保留 Gitea 版权及官方许可证。
@@ -13,7 +13,7 @@

 大多数自托管 Gitea 实例使用默认的纯文本邮件模板。本项目提供了**开箱即用、视觉精美的替代方案**——每种方案都针对特定社区或受众设计，您可以选择最适合您用户的风格。

-`main` 分支中的模板可直接替换 Gitea 内置邮件模板，**无需补丁、插件或 fork**。使用已发布的压缩包前，请先查看[兼容性说明](../COMPATIBILITY.md)，了解旧版本的限制。
+`main` 分支使用锁定的官方输入及共享控件框架：Gitea 提供邮件值、通知逻辑与翻译，框架负责页头、按钮、备用链接和页脚，主题仅定义样式。官方文件在开发/CI 时下载，不在仓库中维护副本。该重构尚未发布，以 v28.0.0 为基线；源码克隆需先构建安装文件，发行包提供可直接复制的产物。使用已发布版本前，请查看[兼容性说明](../COMPATIBILITY.md)。

 ---

@@ -26,15 +26,15 @@
 | ![Horizon](images/horizon.png) | **Horizon** | 企业/公司 | 蓝色强调色、石板灰排版、居中卡片 |
 | ![Terminal](images/terminal.png) | **Terminal** | 开发者/技术 | 暗色模式、等宽字体、绿色命令行风格 |
 | ![Ember](images/ember.png) | **Ember** | 社区/开源 | 暖琥珀色、圆角、人文主义、包容 |
-| ![Bloom](images/bloom.png) | **Bloom** | 创意/初创 | 磨砂玻璃、柔和蓝色光线、虹彩点缀 |
-| ![Heritage](images/heritage.png) | **Heritage** | 教育/研究 | 海军蓝与金色、衬线字体、经典、权威 |
+| ![Bloom](images/bloom.png) | **Bloom** | 创意/初创 | 蓝色玻璃卡片、柔和渐变、圆角按钮 |
+| ![Heritage](images/heritage.png) | **Heritage** | 教育/研究 | 纸质色调、海军蓝与金色、双线边框、衬线字体 |
 | ![Neon](images/neon.png) | **Neon** | 游戏/Web3/创意科技 | 赛博朋克霓虹、粉红与青色、合成波能量 |
 | ![Mono](images/mono.png) | **Mono** | 设计工作室/编辑 | 瑞士粗野主义、黑白红强调、零圆角 |
-| ![Terra](images/terra.png) | **Terra** | 可持续/健康 | 温暖大地色调、有机质感、人文衬线 |
-| ![Ink](images/ink.png) | **Ink** | 出版/新闻/文学 | 编辑印刷、深蓝与金色、报纸排版 |
+| ![Terra](images/terra.png) | **Terra** | 可持续/健康 | 大地色、陶土色按钮、自然风格细节、柔和卡片 |
+| ![Ink](images/ink.png) | **Ink** | 出版/新闻/文学 | 报刊分栏、海军蓝与金色分隔线、衬线字体及首字下沉 |
 | ![Aurora](images/aurora.png) | **Aurora** | 高端SaaS/正念 | 空灵光效渐变、深紫与青绿、大气光晕 |

-> 图片为 600px 宽截图，来自[本地预览](../preview/index.html)。截图方法参见 [images/README.md](images/README.md)。
+> 画廊展示共享框架的当前源码构建，并非历史发行包。保留原主题的配色、字体、页头及按钮/备用链接控件。查看[本地预览](../preview/index.html)及[截图说明](images/README.md)。

 [**本地预览画廊**](../preview/index.html) — 先按下文生成预览数据，再在浏览器中打开。

@@ -42,16 +42,25 @@

 ## 安装

-选择一种风格，将 `mail/` 目录复制到 Gitea 自定义模板路径：
+源码克隆需按仓库提交的 `gitea.lock.json` 先构建（Go 1.24+，缓存不存在时首次构建下载锁定输入）。锁文件缺失会报错，不会自动选择最新版 Gitea：

 ```bash
-cp -r themes/horizon/mail/* /var/lib/gitea/custom/templates/mail/
+cd tools
+go run . build all
+cd ..
+```
+
+选择一种风格，将生成的 `mail/` 目录复制到 Gitea 自定义模板路径。发行压缩包中的路径为 `themes/<名称>/mail/`，源码构建后的路径为 `build/themes/<名称>/mail/`：
+
+```bash
+mkdir -p /var/lib/gitea/custom/templates/mail
+cp -r build/themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
 systemctl restart gitea
 ```

-切换风格只需覆盖文件，无需更改配置。
+切换前备份当前邮件覆盖文件，根据上一主题的 `build.json` 移除其安装文件，再复制新主题完整输出；保留其他自定义模板。从 `framed` 切换到 `shared` 时，遗留的正文覆盖文件仍会使用旧布局，因此不能仅覆盖两个共享片段。

-`GITEA_CUSTOM` 决定自定义目录；常见路径为 Linux 二进制部署的 `/var/lib/gitea/custom`、Docker 的 `/data/gitea`，以及 Windows 的 `C:\gitea\custom`。
+请确认实例实际配置的自定义目录再安装；常见部署示例为 Linux 二进制部署的 `/var/lib/gitea/custom`、Docker 的 `/data/gitea`，以及 Windows 的 `C:\gitea\custom`，这些并非所有实例的统一默认路径。

 ### 确认生效

@@ -63,7 +72,13 @@ systemctl restart gitea

 ## 预览

-从源码克隆时，需先生成被忽略的 `preview/rendered.js`。现有 v28.0.0 及更早的压缩包未包含预览文件和画廊截图；更新后的打包流程会在后续构建中加入两者。
+源码克隆需先生成被忽略的 `preview/rendered.js` 清单及逐语言数据包。后续发行包会包含全部官方语言的预览，现有 v28.0.0 及更早压缩包保持原内容。
+
+### 官方输入命令（`upstream`）
+
+在 `tools/` 执行：`go run . upstream prepare` 根据已有锁文件下载尚不存在的缓存；`go run . upstream verify` 离线校验已有缓存；`go run . upstream sync --tag vX.Y.Z` 显式替换版本并生成锁文件。均支持子命令后的 `--root <仓库根目录>`，默认 `..`。
+
+缺少根锁文件时，准备、校验、构建与预览都会失败。普通克隆应恢复受版本控制的锁文件；有意初始化可运行 `go run . upstream sync --tag v28.0.0`。同步须联网，仅接受稳定 Gitea 28+ 标签，不更新文档或发布版本。损坏/版本不匹配的缓存需要检查后恢复，而非自动修复，详见[完整命令与恢复指南](CONTRIBUTING.zh-CN.md#更新官方快照)。

 **静态模式：**

@@ -80,16 +95,16 @@ cd ..
 ```bash
 cd tools
 go run . dev
-# 在浏览器中打开 http://localhost:3456
+# 在浏览器中打开 http://127.0.0.1:3456
 ```

 | 功能 | 静态 | Dev |
 |-----------|--------|-----|
 | Go 模板渲染 | [YES] | [YES] |
-| 主题/模板切换 | [YES] | [YES] |
+| 主题/模板/语言切换 | [YES] | [YES] |
 | 实时重载 | [NO] | [YES] |

-预览支持主题与模板切换、Modern/Source 视图、桌面/移动端尺寸以及模板参数面板。`←→` 可切换选择框，`↑↓` 可切换选项，`d`/`m` 可切换视口。
+预览支持主题、邮件类型及全部官方语言切换（v28.0.0 快照含 28 种语言），以及 Modern/Source 视图、桌面/移动端尺寸和参数面板。语言数据按需加载，支持直接打开本地文件。`←→` 可切换选择框，`↑↓` 可切换选项，`d`/`m` 可切换视口。

 ---

@@ -106,15 +121,15 @@ go run . dev
 <!-- TRACKER:UPSTREAM -->
 - **上游 Gitea 28.1.0：** [PENDING]
 <!-- /TRACKER:UPSTREAM -->
- 当前源码使用 Gitea 官方模板的数据路径；各发布版的限制详见 [兼容性说明](../COMPATIBILITY.md)
+- 新源码架构支持 Gitea 28+，离线校验官方快照；源码状态及历史发行版限制详见[兼容性说明](../COMPATIBILITY.md)。

 ## 模板类型

-每种风格都提供 11 种邮件类型：账户激活、邮箱验证、注册通知、密码重置、团队邀请、仓库协作者、仓库转移、新版发布、Actions 工作流、议题/合并请求指派及议题/合并请求更新。具体文件路径参见[英文 README](../README.md#template-types)。
+邮件类型由官方输入发现，当前为 11 种：账户激活、邮箱验证、注册通知、密码重置、团队邀请、仓库协作者、仓库转移、新版发布、Actions 工作流、议题/合并请求指派及议题/合并请求更新。具体路径参见[英文 README](../README.md#template-types)。`framed` 主题使用同一对齐层与共享控件生成安装文件；可选的 `shared` 模式仅覆盖两个基础片段，不添加框架控件。

 ## 设计与翻译

-模板采用适合邮件客户端的响应式布局，并提供按钮失效时可用的备用链接。通知正文使用 Gitea 的翻译系统；部分主题装饰性标签仍为英文，并非所有可见文字都已本地化。
+主题仅维护 CSS 与元数据；共享框架使用官方邮件值及翻译组织可复用控件，保留通知条件、主题行和功能链接目标。官方模板及语言文件下载到忽略的 `build/upstream/`，仅提交工具生成的 `gitea.lock.json`。语言缺键按 Gitea 规则回退英文。v28.0.0 波兰语邀请文案存在官方占位符缺陷，预览报告 `[UPSTREAM-WARN]` 并保留官方行为，详见[贡献指南](CONTRIBUTING.zh-CN.md#更新官方快照)。

 ## 文档与贡献

@@ -125,4 +140,4 @@ go run . dev

 ## 许可证

-MIT — 详见 [LICENSE](../LICENSE)。
+MIT — 详见 [LICENSE](../LICENSE) 和[第三方声明](../THIRD_PARTY_NOTICES.md)。发行包保留官方 Gitea 许可证和快照来源信息。
@@ -1,5 +1,7 @@
 # Style Preview Images

+> Images show the current snapshot-driven source build. Historical release archives retain their original templates and are not replaced by these screenshots.
+
 Place theme style screenshots of **Desktop** in PNG format here, captured from the [local preview](../../preview/index.html).

 ## Naming Convention
@@ -19,9 +21,11 @@ To ensure screenshots can be displayed in the README, please follow these size r

 ## How to Capture

-1. Start the dev server: `cd tools && go run . dev` (opens http://localhost:3456 in your browser)
-2. For each style, select the **"Activate Account"** template and **"Modern"** client mode in **"Desktop"**
+1. Start the dev server: `cd tools && go run . dev` and open http://127.0.0.1:3456 in your browser
+2. For each style, select the **"Register Notify"** template and **"Modern"** view, **"en-US"** language and **"Desktop"** viewport; close the floating inspector
 3. Take a screenshot of the rendered email (600px width recommended)
 4. Save as `<style-name>.png` in this directory

 > For a source clone, run `cd tools && go run . preview all`, return to the repository root, then open `preview/index.html` directly.
+
+For automated capture, install the optional dependencies in `tools/qa` and run `node preview.cjs --update-gallery` there. Set `BROWSER_EXECUTABLE_PATH` when using an installed Chrome/Edge instead of Playwright's bundled Chromium.