chore: refresh docs and adapt workflows for Gitea

docs/README.zh-CN.md

@@ -1,48 +1,47 @@
 # Gitea 邮件模板
 <!-- DOC-TAGS: {"TRACKER":["LATEST-TESTED","UPSTREAM"],"RELEASE":["HEADER","SUMMARY"]} -->
 
-为自托管 [Gitea](https://about.gitea.com) 提供精心设计、可直接部署的多风格邮件模板。
+为自托管 [Gitea](https://about.gitea.com) 提供邮件主题、本地预览和自定义邮件模板构建工具。
+
+[English](../README.md) · [安装](#安装) · [预览](#预览) · [兼容性](../COMPATIBILITY.md) · [贡献指南](CONTRIBUTING.zh-CN.md)
 
 <!-- RELEASE:HEADER -->
 > 最新发布版：[v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
 <!-- /RELEASE:HEADER -->
 
----
+仓库包含十种主题，覆盖账户、仓库、议题和工作流等邮件通知。通知内容和翻译由 Gitea 提供，主题负责展示样式。
 
-## 设计理念
-
-大多数自托管 Gitea 实例使用默认的纯文本邮件模板。本项目提供了**开箱即用、视觉精美的替代方案**——每种方案都针对特定社区或受众设计，您可以选择最适合您用户的风格。
-
-`main` 分支使用锁定的官方输入及共享控件框架：Gitea 提供邮件值、通知逻辑与翻译，框架负责页头、按钮、备用链接和页脚，主题仅定义样式。官方文件在开发/CI 时下载，不在仓库中维护副本。该重构尚未发布，以 v28.0.0 为基线；源码克隆需先构建安装文件，发行包提供可直接复制的产物。使用已发布版本前，请查看[兼容性说明](../COMPATIBILITY.md)。
-
----
+`main` 分支的源码架构**尚未发布**，以 Gitea v28.0.0 为基线，通过锁定的官方文件和共享布局框架构建模板。已发布的压缩包保留原有内容和兼容范围。安装前，请根据 Gitea 版本查阅[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)，选择对应的发行包。
 
 ## 风格画廊
 
-下表展示仓库当前收录的主题；新增主题可作为独立目录放在 `themes/` 下，不受现有数量限制。
+| 预览 | 主题 | 样式特点 |
+|---|---|---|
+| ![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** | 藏蓝与金色、双线边框、衬线字体 |
+| ![Neon](images/neon.png) | **Neon** | 深色背景、粉红与青色、发光效果 |
+| ![Mono](images/mono.png) | **Mono** | 黑白配色、红色强调色、直角边框 |
+| ![Terra](images/terra.png) | **Terra** | 大地色调、陶土色按钮、衬线字体 |
+| ![Ink](images/ink.png) | **Ink** | 报刊式布局、侧栏、衬线字体与首字下沉 |
+| ![Aurora](images/aurora.png) | **Aurora** | 深紫色背景、青绿色强调色、柔和光晕 |
 
-| 预览 | 风格 | 受众 | 特点 |
-|---|---|---|---|
-| ![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** | 教育/研究 | 纸质色调、海军蓝与金色、双线边框、衬线字体 |
-| ![Neon](images/neon.png) | **Neon** | 游戏/Web3/创意科技 | 赛博朋克霓虹、粉红与青色、合成波能量 |
-| ![Mono](images/mono.png) | **Mono** | 设计工作室/编辑 | 瑞士粗野主义、黑白红强调、零圆角 |
-| ![Terra](images/terra.png) | **Terra** | 可持续/健康 | 大地色、陶土色按钮、自然风格细节、柔和卡片 |
-| ![Ink](images/ink.png) | **Ink** | 出版/新闻/文学 | 报刊分栏、海军蓝与金色分隔线、衬线字体及首字下沉 |
-| ![Aurora](images/aurora.png) | **Aurora** | 高端SaaS/正念 | 空灵光效渐变、深紫与青绿、大气光晕 |
-
-> 画廊展示共享框架的当前源码构建，并非历史发行包。保留原主题的配色、字体、页头及按钮/备用链接控件。查看[本地预览](../preview/index.html)及[截图说明](images/README.md)。
-
-[**本地预览画廊**](../preview/index.html) — 先按下文生成预览数据，再在浏览器中打开。
-
----
+截图展示当前源码的构建结果。其他邮件类型和语言可通过[本地预览](#预览)查看；更新截图请参阅[截图指南](images/README.md)。
 
 ## 安装
 
-源码克隆需按仓库提交的 `gitea.lock.json` 先构建（Go 1.24+，缓存不存在时首次构建下载锁定输入）。锁文件缺失会报错，不会自动选择最新版 Gitea：
+### 选择安装来源
+
+运行 `gitea --version` 确认实例版本，再按[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)选择模板版本。
+
+| 来源 | 邮件模板目录 | 准备步骤 |
+|---|---|---|
+| 发行压缩包 | `themes/<名称>/mail/` | 下载并解压推荐版本的发行包 |
+| 源码仓库 | `build/themes/<名称>/mail/` | 使用 Go 1.24 或更高版本构建 |
+
+从源码构建时，在仓库根目录执行：
 
 ```bash
 cd tools
@@ -50,37 +49,45 @@ go run . build all
 cd ..
 ```
 
-选择一种风格，将生成的 `mail/` 目录复制到 Gitea 自定义模板路径。发行压缩包中的路径为 `themes/<名称>/mail/`，源码构建后的路径为 `build/themes/<名称>/mail/`：
+缓存不存在时，首次构建会下载 `gitea.lock.json` 锁定的官方文件；后续构建会先校验缓存。构建需要根目录的锁文件，文件缺失或缓存损坏的处理方式见[准备与恢复说明](CONTRIBUTING.zh-CN.md#更新官方快照)。
+
+### 安装主题
+
+将所选主题 `mail/` 目录中的内容复制到 `<GITEA_CUSTOM>/templates/mail/`，然后重启 Gitea。复制前请确认实例实际使用的自定义目录。以下是常见部署路径示例：
+
+| 部署方式 | 自定义目录示例 |
+|---|---|
+| Linux 二进制部署 | `/var/lib/gitea/custom` |
+| Docker | `/data/gitea` |
+| Windows | `C:\gitea\custom` |
+
+例如，在使用 systemd 管理 Gitea 的 Linux 主机上，从已解压的发行包目录执行：
 
 ```bash
 mkdir -p /var/lib/gitea/custom/templates/mail
-cp -r build/themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
+cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
 systemctl restart gitea
 ```
 
-切换前备份当前邮件覆盖文件，根据上一主题的 `build.json` 移除其安装文件，再复制新主题完整输出；保留其他自定义模板。从 `framed` 切换到 `shared` 时，遗留的正文覆盖文件仍会使用旧布局，因此不能仅覆盖两个共享片段。
+使用源码构建产物时，将复制来源改为 `build/themes/horizon/mail/.`。Docker 和 Windows 部署请使用相应的容器或服务管理方式重启。
 
-请确认实例实际配置的自定义目录再安装；常见部署示例为 Linux 二进制部署的 `/var/lib/gitea/custom`、Docker 的 `/data/gitea`，以及 Windows 的 `C:\gitea\custom`，这些并非所有实例的统一默认路径。
+### 切换主题
+
+先备份已有邮件模板，再移除上一主题安装的文件，复制新主题的完整产物。当前源码构建会在 `build.json` 中记录生成的文件；历史发行包可参照压缩包内容确认文件范围。保留其他自定义模板。
+
+从 `framed` 切换到 `shared` 模式时，尤其需要清理旧主题文件，否则残留的覆盖模板可能继续使用原有布局。
 
 ### 确认生效
 
-管理后台的测试邮件不会使用自定义模板。要验证模板是否生效，请触发一次真实的
-邮件通知。最快的方式是密码重置：退出登录，点击登录页的**"忘记密码"**，查看
-重置邮件即可——它将使用你的自定义样式渲染。
-
----
+使用测试账户触发密码重置等邮件通知，检查邮件样式和链接。管理后台的测试邮件按钮不使用自定义邮件模板。
 
 ## 预览
 
-源码克隆需先生成被忽略的 `preview/rendered.js` 清单及逐语言数据包。后续发行包会包含全部官方语言的预览，现有 v28.0.0 及更早压缩包保持原内容。
+预览支持切换主题、邮件类型和语言，查看渲染结果或 HTML 源码，切换桌面与移动端视口，以及查看示例数据面板。v28.0.0 快照包含 11 种邮件类型和 28 种语言。
 
-### 官方输入命令（`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#更新官方快照)。
-
-**静态模式：**
+在源码仓库中生成预览数据：
 
 ```bash
 cd tools
@@ -88,56 +95,95 @@ go run . preview all
 cd ..
 ```
 
-然后在浏览器中打开 `preview/index.html`，无需启动服务器。
+在浏览器中打开 [preview/index.html](../preview/index.html)。语言数据按需加载，支持 `file://`，无需启动服务器。当前打包脚本生成的发行包包含这些数据；历史发行包保留其原有预览内容。
 
-**开发服务器（实时重载）：**
+### 开发服务器
 
 ```bash
 cd tools
 go run . dev
-# 在浏览器中打开 http://127.0.0.1:3456
 ```
 
-| 功能 | 静态 | Dev |
-|-----------|--------|-----|
-| Go 模板渲染 | [YES] | [YES] |
-| 主题/模板/语言切换 | [YES] | [YES] |
-| 实时重载 | [NO] | [YES] |
+打开 [http://127.0.0.1:3456](http://127.0.0.1:3456)。Go 服务器监听主题文件、共享框架、锁文件与缓存、预览测试数据的变化，重新构建后通过服务器发送事件（SSE）刷新页面。
 
-预览支持主题、邮件类型及全部官方语言切换（v28.0.0 快照含 28 种语言），以及 Modern/Source 视图、桌面/移动端尺寸和参数面板。语言数据按需加载，支持直接打开本地文件。`←→` 可切换选择框，`↑↓` 可切换选项，`d`/`m` 可切换视口。
+| 控件 | 选项或快捷键 |
+|---|---|
+| 主题、模板、语言和视图 | `←` / `→` 切换选择框，`↑` / `↓` 选择选项 |
+| 视图 | **Modern** 显示渲染结果，**Source** 显示生成的 HTML 文本 |
+| 视口 | **Desktop**（1386 × 780）、**Mobile**（390 × 780）；快捷键 `d` / `m` |
+| 信息面板 | `p` 展开或收起面板 |
 
----
+预览使用示例数据渲染模板。浏览器与邮件客户端对 CSS 的支持不同，部署前还需在目标邮件客户端中检查效果。
 
 ## 兼容性
 
-- **Gitea 28.0.0** — 使用模板发布版 v28.0.0；旧版 Gitea 请选用对应的旧版模板
 <!-- TRACKER:LATEST-TESTED -->
 - **最新测试：** Gitea 28.0.0
 <!-- /TRACKER:LATEST-TESTED -->
 <!-- RELEASE:SUMMARY -->
 - **最新发布版：** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
 <!-- /RELEASE:SUMMARY -->
-- 其它 Gitea 版本请先查看[逐版本兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)再选择模板压缩包；标记为 [PENDING] 的版本尚无已验证的推荐包。版本号相符的 v1.27.2 存在已知的推送通知问题。
 <!-- TRACKER:UPSTREAM -->
 - **上游 Gitea 28.1.0：** [PENDING]
 <!-- /TRACKER:UPSTREAM -->
-- 新源码架构支持 Gitea 28+，离线校验官方快照；源码状态及历史发行版限制详见[兼容性说明](../COMPATIBILITY.md)。
 
-## 模板类型
+当前源码架构面向 Gitea 28 及更高版本，兼容性按锁定版本验证。新的上游版本在完成评审前保持待验证状态。早期 Gitea 版本请使用[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)推荐的发行包；其中也记录了 v1.27.2 推送通知修复不完整的问题。
 
-邮件类型由官方输入发现，当前为 11 种：账户激活、邮箱验证、注册通知、密码重置、团队邀请、仓库协作者、仓库转移、新版发布、Actions 工作流、议题/合并请求指派及议题/合并请求更新。具体路径参见[英文 README](../README.md#template-types)。`framed` 主题使用同一对齐层与共享控件生成安装文件；可选的 `shared` 模式仅覆盖两个基础片段，不添加框架控件。
+生成的模板使用 Gitea 内置函数和官方翻译键，缺少的翻译回退为英文。锁定的 v28.0.0 语言文件存在已知的波兰语邀请文案格式缺陷，预览会报告 `[UPSTREAM-WARN]` 并保留官方输出。详见[已知限制](../COMPATIBILITY.md#snapshot-driven-source-status)。
 
-## 设计与翻译
+## 目录结构
 
-主题仅维护 CSS 与元数据；共享框架使用官方邮件值及翻译组织可复用控件，保留通知条件、主题行和功能链接目标。官方模板及语言文件下载到忽略的 `build/upstream/`，仅提交工具生成的 `gitea.lock.json`。语言缺键按 Gitea 规则回退英文。v28.0.0 波兰语邀请文案存在官方占位符缺陷，预览报告 `[UPSTREAM-WARN]` 并保留官方行为，详见[贡献指南](CONTRIBUTING.zh-CN.md#更新官方快照)。
+```text
+gitea.lock.json        # 官方标签、提交和文件校验值
+framework/            # 共享邮件控件和布局预设
+themes/<名称>/        # 主题元数据（theme.json）和样式（theme.css）
+tools/                # Go 命令行工具、构建工具和测试
+  cli/                # 命令定义
+  upstream/           # 快照下载、校验和翻译键发现
+  builder/            # 官方模板适配与主题生成
+  preview/            # 邮件渲染、语言适配和开发服务器
+  config/, data/      # 预览元数据和示例上下文
+  integration/, qa/   # 可选的 Gitea 实例与浏览器检查
+preview/              # 浏览器界面；生成的清单和语言数据包
+docs/                 # 简体中文指南和画廊图片
+.github/              # 工作流、发行说明、打包与版本追踪脚本
+build/upstream/       # 下载的官方文件，不纳入版本控制
+build/themes/         # 生成的安装模板，不纳入版本控制
+```
 
-## 文档与贡献
+官方模板定义通知数据、条件、主题行和 URL。共享框架将其组织为页头、操作按钮、备用链接和页脚，主题定义配色、字体与间距。`framed` 和 `shared` 模式的说明见[主题开发指南](CONTRIBUTING.zh-CN.md#添加主题)。
+
+### 模板类型
+
+邮件类型从锁定的快照中发现。v28.0.0 的邮件入口如下：
+
+| 文件 | 通知类型 |
+|---|---|
+| `mail/user/auth/activate.tmpl` | 账户激活 |
+| `mail/user/auth/activate_email.tmpl` | 邮箱验证 |
+| `mail/user/auth/register_notify.tmpl` | 注册通知 |
+| `mail/user/auth/reset_passwd.tmpl` | 密码重置 |
+| `mail/org/team_invite.tmpl` | 团队邀请 |
+| `mail/repo/collaborator.tmpl` | 添加仓库协作者 |
+| `mail/repo/transfer.tmpl` | 仓库所有权转移 |
+| `mail/repo/release.tmpl` | 发布新版本 |
+| `mail/repo/actions/workflow_run.tmpl` | Actions 工作流运行 |
+| `mail/repo/issue/assigned.tmpl` | 议题或合并请求指派 |
+| `mail/repo/issue/default.tmpl` | 议题或合并请求动态 |
+
+## 参与贡献
+
+欢迎改进主题、工具、文档和翻译。[贡献指南](CONTRIBUTING.zh-CN.md)介绍了本地环境准备、设计规范、检查要求和发布流程。
+
+## 相关文档
 
 - [English README](../README.md)
-- [简体中文 README](README.zh-CN.md)
-- [English CONTRIBUTING](../CONTRIBUTING.md)
-- [简体中文贡献指南](CONTRIBUTING.zh-CN.md)
+- [简体中文贡献指南](CONTRIBUTING.zh-CN.md) · [English contributor guide](../CONTRIBUTING.md)
+- [兼容性与模板参考](../COMPATIBILITY.md)
+- [画廊截图指南](images/README.md)
 
 ## 许可证
 
-MIT — 详见 [LICENSE](../LICENSE) 和[第三方声明](../THIRD_PARTY_NOTICES.md)。发行包保留官方 Gitea 许可证和快照来源信息。
+本项目采用 [MIT 许可证](../LICENSE)。生成的发行包保留 Gitea 许可证和快照来源信息，详见[第三方声明](../THIRD_PARTY_NOTICES.md)。
+
+本项目与 Gitea 官方无隶属关系。