@routerhub/agent-rules 1.4.12 → 1.4.14

package/AGENTS.base.md

@@ -1,159 +1,89 @@
-## 页面内容英文、注释中文（tag: english-ui-chinese-comment）
-
-- 所有面向用户的页面内容（如按钮、输入框、提示、字段名等）必须全部使用英文，适配外国用户。
-- 代码注释、开发文档等统一使用中文，便于团队内部理解和维护。
-
 # Copilot Agent Rules - Base
 
-以下规则适用于所有使用此规则包的项目。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
-
-## 语言与回答
-
-- 始终使用中文回答。
-
-## 文件与目录约束
-
-- 不能随意修改核心业务文件和 API 相关代码。
-- 不要编写或修改 `README.md`（由项目维护）。
-- 先用`typings.d.ts` 中的类型定义，另外用的时候要确认下typings.d.ts中有这个类型定义，如果没有再自定义 TypeScript类型
-
-## 样式与 UI 约束
-
-- 前端项目统一使用 Tailwind CSS 编写样式，禁止新增 `*.module.scss`、`*.module.css` 或普通 `.css` 文件。
-- 如果项目尚未集成 Tailwind CSS，必须先完成 Tailwind 的安装和配置（包括 `tailwind.config.js/ts`、`postcss.config.js` 及在全局样式中引入 `@tailwind` 指令），再进行业务开发。
-- 所有新增样式必须通过 Tailwind 的工具类（utility classes）在 JSX/TSX 中直接编写，禁止新建样式文件。
-- 当 Tailwind 内置工具类无法满足需求时，优先在 `tailwind.config` 中通过 `extend` 扩展主题，其次使用 `@apply` 在全局样式中封装复合类名，最后才考虑行内 `style` 属性。
-- 复杂或重复的样式组合应提取为 Tailwind 组件类（通过 `@apply`）或封装为 React 组件，避免工具类堆砌过长。
-- 历史项目中已有的 `*.module.scss` 文件可保留使用，但新增功能和页面必须使用 Tailwind CSS。
-- 不允许使用 `span` 标签选择器。
-- 如果必须存在类名（历史代码场景），类名使用小驼峰命名，不使用下划线或中划线。
-
-## 命名与类型约束
-
-- 命名使用小驼峰或大驼峰，不使用下划线命名。
-- 变量或值命名时，至少使用两个单词。
-- TS 中不允许使用 `as`，不允许使用 `any`。
-- 组件 `props` 能复用类型时，必须优先复用，不要重复定义。
-
-## 常量与业务规则
-
-- 禁止硬编码数字判断；统一使用常量或枚举，并定义在 `Const.ts` 或 `constants.ts`。
-- `tab` 索引统一使用常量。
-- 时间相关处理统一使用 `dayjs`。
-- 数据回显优先使用对象展开运算符（`...`）。
-
-## 前端 API 生成规范
+以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
 
-- 前端 API 请求必须严格使用 OpenAPI 生成的 API 方法，禁止手写请求方法或绕过生成层直接调用接口。
-- 新增或变更接口后，必须先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发与联调。
-- 禁止在业务代码中直接拼接接口路径、手动声明重复请求类型或复制粘贴旧请求实现。
+## 语言与内容
 
-## 生产环境操作安全规则
+- 始终使用中文回答，代码注释使用中文，每行代码配中文注释。
+- 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
 
-- **严禁在未明确授权时操作线上/生产服务器**：只有当用户的指令中明确包含"生产环境"、"线上"、"prod"、"production"等关键词时，才允许在生产服务器上执行任何操作（如部署、重启、修改配置、执行脚本等）。
-- 若用户指令中没有上述关键词，默认只在本地或测试/开发环境中执行操作，不得擅自连接或操作生产服务器。
-- 执行生产环境操作前，必须再次向用户确认目标环境，确认无误后方可执行。
+## 文件约束
 
-## 分支管理规范（Git Flow）
+- 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。
+- TypeScript 类型优先复用 `typings.d.ts`，不存在时再自定义。
 
-- 所有新建分支必须遵循 Git Flow 命名规范，使用以下前缀：
-  - `feature/` - 新功能开发（如 `feature/user-authentication`）
-  - `refactor/` - 代码重构（如 `refactor/payment-module`）
-  - `bugfix/` - 缺陷修复（如 `bugfix/order-calculation`）
-  - `hotfix/` - 紧急生产修复（如 `hotfix/critical-security-issue`）
-  - `chore/` - 杂项维护（如 `chore/upgrade-dependencies`）
-  - `docs/` - 文档更新（如 `docs/api-reference`）
-  - `test/` - 测试相关（如 `test/add-unit-tests`）
-- 分支名称使用英文，单词间用中划线（-）分隔，全小写，简洁明了。
-- 禁止使用下划线、大写字母、中文或特殊字符。
-- 当用户要求提交本次修改时，git commit 提交信息必须使用中文描述，禁止使用英文。
-- **严禁使用 `git push --force` 或 `git push -f`**：AI 在任何情况下都不得执行 force push 操作，避免覆盖远程提交历史、丢失他人代码。如确需强制推送，必须由用户手动执行。
+## 命名与类型
 
-## 代码风格与结构
+- 驼峰命名（小驼峰/大驼峰），禁止下划线；变量至少两个单词。
+- 禁止 `as` 和 `any`；`props` 类型优先复用，不重复定义。
 
-- 不允许写 `class`，统一使用函数式编程。
-- 不要写 `try/catch`。
-- 代码注释统一使用中文编写。
-- 每一行代码都必须有对应的中文注释，明确说明该行代码的作用。
-- 能复用现有函数或配置时，不要复制粘贴出第二份近似实现。
-- 发现重复或相似的代码、逻辑、样式时，必须主动提取并封装为公共函数、组件或工具方法，避免同类代码散落在多处；能封装的一律封装，降低维护成本。
-- 编写 Go 代码时，优先使用值传递与局部变量生命周期控制，避免不必要的内存逃逸（如无必要不要返回局部变量指针、避免在热路径中产生额外堆分配）。
-- 编写代码需遵循 SOLID 原则，并结合场景合理应用设计模式优化可维护性与扩展性，避免过度设计。
-- 编写代码时必须注重封装性：同一份数据、配置或字段定义只在一个地方维护，其余位置通过引用或派生获取；修改某个字段或逻辑时，应只需改动一处即可全局生效，禁止同一语义散落在多处需要逐一同步修改。
+## 代码风格
 
-## 测试用例规范
+- 函数式编程，不写 `class`，不写 `try/catch`。
+- 禁止重复实现：复用现有函数/组件/配置，发现重复必须提取封装为公共方法。
+- 同一数据/配置只在一处维护，其余通过引用获取，改一处全局生效。
+- 禁止硬编码数字；常量/枚举定义在 `Const.ts` 或 `constants.ts`，`tab` 索引统一使用常量，时间用 `dayjs`。
+- 遵循 SOLID 原则，避免过度设计；数据回显优先用展开运算符（`...`）。
+- 复用组件通过 `fromType`（值为当前页面名）区分来源，内部差异逻辑基于 `fromType` 分支。
 
-- 所有测试用例必须包含中文断言或校验内容，确保覆盖中文场景。
-- 编写测试用例时，测试描述、断言说明和相关说明文字统一使用中文。
-- 充值类测试用例如无特殊说明，默认使用充值 1 的测试数据执行验证。
-- 当同一个组件被复用时，传入 `fromType`（值为当前页面名）用于区分来源；组件内部差异逻辑基于 `fromType` 分支。
+## 样式（Tailwind CSS）
 
-## 新功能组件化原则
+- 统一 Tailwind CSS，禁止新增 `*.module.scss`、`*.module.css`、`.css` 文件（历史文件可保留）。
+- 项目未集成 Tailwind 时，先完成安装配置再开发。
+- 新增样式通过 utility classes 在 JSX/TSX 中编写；不满足时优先 `tailwind.config` extend → `@apply` 封装 → 行内 `style`。
+- 复杂/重复样式提取为 Tailwind 组件类或 React 组件，避免工具类堆砌。
+- 类名小驼峰，禁止 `span` 标签选择器。
 
-- 每次开发新功能时，尽可能将其封装为组件，方便后续在其它页面或场景中复用。
+## 组件复用
 
-## 需求文档前置规则
+- 优先复用已有组件，能通过 `props` 定制就不建新组件；新功能尽量封装为可复用组件。
 
-- 每次开始实现新需求前，必须先编写对应的需求说明 MD 文档。
-- 需求文档统一存放在项目根目录的 `docs/` 文件夹下。
-- 需求文档至少包含以下内容：需求目标、需求范围、功能要求、验收标准。
-- 如存在补充信息，需在文档中增加“备注”章节说明。
+## 前端 API 规范
 
-## 依赖安装规范
+- API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径。
+- 接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
 
-- 无论在 Docker 环境还是本地环境，安装和下载依赖都必须使用 `pnpm`，禁止使用 `npm install`、`yarn install` 等其它包管理器安装命令。
+## Go 语言规则
 
-## 构建与发版前检查
+- 优先值传递与局部变量生命周期控制，避免内存逃逸；无必要不返回局部变量指针。
+- 所有删除操作必须使用软删除机制；`DeletedAt` 字段类型必须用 `gorm.DeletedAt`，禁止用 `*time.Time`（后者不实现 `DeleteClausesInterface`，会导致硬删除）。
 
-- AI 写完代码后，必须先执行 `npm run format` 格式化本次修改涉及的文件。
-- 每次完成需求修改后，必须先打开一个新终端执行 `npm run build`。
-- 若构建报错，必须先修复所有错误并重新执行构建直至通过，再进行发版操作。
+## Git 规范
 
-## Docker 镜像构建规范
+- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
+- commit 信息必须中文，禁止 `git push --force`。
 
-- **所有镜像构建（包括部署测试环境、生产环境等）必须默认在本地使用 `docker build` 构建**，不需要询问用户选择构建方式，直接执行本地构建。
-- 本地构建成功后，使用 `docker push` 推送到远程镜像仓库，不得跳过本地构建直接在远程构建。
-- 镜像推送目标统一使用 GitHub Container Registry（`ghcr.io`），禁止推送到其它公共镜像仓库（如 Docker Hub）除非项目私有规则另有声明。
-- 推送前必须确保镜像已正确打 tag（如 `ghcr.io/<org>/<image>:<version>`），禁止推送 `latest` 以外无语义的标签。
+## 安全
 
-## 部署规范
+- 未明确授权不操作生产环境（指令需含"生产"/"线上"/"prod"/"production"），操作前二次确认。
 
-- 部署测试环境或生产环境时，必须使用 VS Code 内置浏览器打开 Portainer 管理界面，通过图形化操作完成部署（如更新镜像、重启服务、查看日志等），禁止通过 SSH 连接服务器手动执行 docker 命令部署。
-- Portainer 的地址和账号信息应在项目私有规则（`AGENTS.private.md`）或环境变量中配置，禁止硬编码。
+## 依赖与构建
 
-## 组件复用规则
+- 依赖安装统一 `pnpm`，禁止 `npm install`/`yarn install`。
+- 写完代码先 `npm run format`，再 `npm run build`，构建通过才可发版。
 
-- **优先复用项目中已存在的组件**，写新功能时尽量不要创建新组件。
-- 检查现有组件库中是否有可复用的基础组件（如表格、卡片、按钮、容器等）。
-- 能通过 `props` 定制的场景，不要创建新组件；优先改进现有组件的 `props` 接口。
-- 任何公共使用频率高的组件应统一维护，避免样式和逻辑分散。
+## Docker 与部署
 
-## 自动化测试规则
+- 默认本地 `docker build`，构建后 `docker push` 到 `ghcr.io`，推送前确保正确 tag。
+- 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
 
-- 自动化测试默认必须使用真实接口数据，禁止使用 mock/route.fulfill/本地伪造返回；仅在明确同意的情况下才允许使用模拟数据。
-- UI 自动化测试必须请求真实的后端接口，不允许使用本地 mock 数据或截断真实请求。
-- 写完业务后，必须自动打开 UI 自动化测试页面，执行 `pnpm run test:e2e:ui`，让开发者手动点击验证功能效果。
-- 只有在相关测试用例执行通过后，才允许继续执行 `npm run test:e2e:ui`；未通过时不得打开 UI 自动化测试页面。
-- 当用户要求“加测试用例”时，必须主动执行 `npm run test:e2e:ui` 供开发者查看具体效果，并明确说明本次主要涉及的测试用例名称或编号。
-- 打开 UI 自动化测试后，应明确告知当前业务对应的具体测试用例名称或编号，让开发者清楚当前验证范围。
-- 自动化测试执行完毕后，自动打开 UI 界面，允许开发者进行手动验证。
+## 测试
 
-- 如 UI 自动化测试端口被占用，需自动切换到未被占用的新端口，保证测试流程不中断。
+- 测试描述、断言使用中文，覆盖中文场景；充值类测试默认用充值 1 的数据。
+- 默认使用真实接口数据，禁止 mock；仅明确同意时允许模拟数据。
+- 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
+- 端口被占用时自动切换新端口。
 
-## 错误处理与日志
+## 错误日志
 
-- 统一使用 `console.error` 记录错误日志，禁止使用 `console.log` 输出错误信息。
-- 错误信息必须包含上下文（如函数名、模块名），便于快速定位问题。
-- 提交代码前，必须移除临时调试日志、临时注释和无效占位代码。
+- 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
+- 提交前移除调试日志和临时代码。
 
-## 优先级声明
+## 需求文档
 
-- 若规则之间有冲突，按以下优先级执行：
-  1. 项目私有规则（AGENTS.private.md）
-  2. 基础规则（此文件）
+- 新需求先在 `docs/` 写 MD 文档，含：目标、范围、功能要求、验收标准。
 
-## 页面内容英文化（tag: english-page-content）
+## 优先级
 
-- 页面所有具体内容（如按钮、输入框、提示、字段名等）必须全部使用英文，包括如 password、username、login、submit 等常见词汇，不允许出现中文或中英文混用。
-- 如有特殊需求需使用中文，需在项目私有规则中单独声明。
-- 本规则适用于所有前端页面及相关交互内容。
+1. 项目私有规则（AGENTS.private.md）
+2. 基础规则（此文件）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.4.12",
+  "version": "1.4.14",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "AGENTS.base.md",
+    "rules/",
     "merge.js",
     "AGENTS.private.example.md",
     "README.zh-CN.md",