@routerhub/agent-rules 1.5.64 → 1.5.66

package/AGENTS.base.md

@@ -139,6 +139,7 @@ Closes #456
 - 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
 - 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
+- ⚠️ **HTML 报告/文档中的所有图片必须支持点击放大、全屏查看**：每张图片必须可点击，点击后弹出全屏遮罩层（lightbox），展示原图或放大版本，支持关闭（点击遮罩背景或关闭按钮）和键盘 ESC 关闭。实现方式：在 HTML 内嵌一段通用 JS 脚本，为所有图片绑定 click 事件，弹出全屏遮罩层展示该图片，遮罩层背景半透明黑色、图片居中自适应屏幕。
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
@@ -316,6 +317,15 @@ function FieldTooltip({ text }: { text: string }) {
 - `DeletedAt` 字段必须使用 `gorm.DeletedAt` 类型，严禁使用 `*time.Time`。`*time.Time` 不会触发 GORM v2 的软删除机制，会导致 `Delete()` 执行物理删除（DELETE FROM）而非软删除（UPDATE SET deleted_at）。
 - 新建 Model 时，优先嵌入已有的公共基础结构体（如包含 ID、CreatedAt、UpdatedAt、DeletedAt 的 BaseModel），避免各 Model 独立定义这些字段导致类型不一致。
 
+## 数据库 Auto-Migrate 规范
+
+- ⚠️ **禁止在代码中无条件执行 GORM AutoMigrate**。AutoMigrate 的执行必须由一个显式的开关（如配置项、环境变量或 feature flag）控制，默认关闭。
+- 应用启动时，如果检测到数据库 schema 与 Model 定义不匹配且 auto-migrate 开关未开启，必须：
+  1. **明确报错并拒绝启动**，在日志中输出具体的 schema 差异信息（哪些表/字段缺失或不匹配）。
+  2. **提示运维手动开启 auto-migrate 开关**，给出开关名称和开启方式（例如「请将配置 `DB_AUTO_MIGRATE` 设为 `true` 后重新部署」），禁止静默挂掉或输出含糊错误。
+- auto-migrate 脚本必须随代码一起提交并部署（满足「部署自包含」要求），只是执行时机由开关控制，确保运维可审计、可控制。
+- 生产环境 auto-migrate 执行完毕后，建议运维立即关闭开关并重新部署，避免后续非预期的 DDL 操作。
+
 <!-- @domain: devops -->
 
 ## 部署规则

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.64",
+  "version": "1.5.66",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -139,6 +139,7 @@ Closes #456
 - 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
 - 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
+- ⚠️ **HTML 报告/文档中的所有图片必须支持点击放大、全屏查看**：每张图片必须可点击，点击后弹出全屏遮罩层（lightbox），展示原图或放大版本，支持关闭（点击遮罩背景或关闭按钮）和键盘 ESC 关闭。实现方式：在 HTML 内嵌一段通用 JS 脚本，为所有图片绑定 click 事件，弹出全屏遮罩层展示该图片，遮罩层背景半透明黑色、图片居中自适应屏幕。
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。

package/rules/go-backend.md

@@ -13,3 +13,12 @@ outputName: "go-backend"
 
 - `DeletedAt` 字段必须使用 `gorm.DeletedAt` 类型，严禁使用 `*time.Time`。`*time.Time` 不会触发 GORM v2 的软删除机制，会导致 `Delete()` 执行物理删除（DELETE FROM）而非软删除（UPDATE SET deleted_at）。
 - 新建 Model 时，优先嵌入已有的公共基础结构体（如包含 ID、CreatedAt、UpdatedAt、DeletedAt 的 BaseModel），避免各 Model 独立定义这些字段导致类型不一致。
+
+## 数据库 Auto-Migrate 规范
+
+- ⚠️ **禁止在代码中无条件执行 GORM AutoMigrate**。AutoMigrate 的执行必须由一个显式的开关（如配置项、环境变量或 feature flag）控制，默认关闭。
+- 应用启动时，如果检测到数据库 schema 与 Model 定义不匹配且 auto-migrate 开关未开启，必须：
+  1. **明确报错并拒绝启动**，在日志中输出具体的 schema 差异信息（哪些表/字段缺失或不匹配）。
+  2. **提示运维手动开启 auto-migrate 开关**，给出开关名称和开启方式（例如「请将配置 `DB_AUTO_MIGRATE` 设为 `true` 后重新部署」），禁止静默挂掉或输出含糊错误。
+- auto-migrate 脚本必须随代码一起提交并部署（满足「部署自包含」要求），只是执行时机由开关控制，确保运维可审计、可控制。
+- 生产环境 auto-migrate 执行完毕后，建议运维立即关闭开关并重新部署，避免后续非预期的 DDL 操作。