chore: 初始化项目与后端基础工程

2026-07-06 22:03:22 +08:00
commit 6833106829
34 changed files with 8398 additions and 0 deletions
@@ -0,0 +1,134 @@
+# AGENTS.md — AI 辅助开发协作规范
+
+> 本文件定义 AI 辅助开发（Windsurf Cascade / 其他 AI Agent）在本项目中的协作规则。
+> 所有 AI Agent 必须同时遵守 `.windsurfrules`、`.windsurfrules.DEV-RULES` 和本文件。
+
+---
+
+## 1. 文档阅读顺序
+
+开始任何开发任务前，AI Agent 必须按以下顺序阅读文档：
+
+1. **`.windsurfrules`** — 精简规则，了解技术栈和禁止事项
+2. **`.windsurfrules.DEV-RULES` §0** — 文档骨架，了解项目文档结构
+3. **`pmdocs/2-task.md`** — 查看当前任务状态和进度
+4. **`pmdocs/1-prd-finance-v1.md`** — 了解要开发的功能需求
+5. **`pmdocs/changes/CHANGELOG.md`** — 查看需求变更历史
+6. **`run.md`** — 了解如何启动和测试
+7. 对应模块的现有代码 — 了解代码风格和模式
+
+---
+
+## 2. 代码修改原则
+
+### 2.1 最小改动
+
+- 优先最小化修改，不重写已有代码
+- 不删除与本次修改无关的代码和注释
+- 不创建随机文件，除非任务明确需要
+
+### 2.2 遵循现有模式
+
+- 后端：遵循模块三件套（Controller + Service + Table）模式
+- 前端：遵循现有页面结构（列表页/详情页/表单页模板）
+- 复用公共组件，禁止重复造轮子
+
+### 2.3 同步更新文档
+
+- 修改代码涉及行为变更 → 更新 `pmdocs/2-task.md` 任务状态
+- 修改 DB 结构 → 更新 `run.md` 数据库命令
+- 修改技术栈版本 → 更新 `run.md` §1 和 `.windsurfrules`
+- 新增/修改 API → 更新 `pmdocs/1-prd-finance-v1.md`（如有接口说明）
+
+---
+
+## 3. 任务管理
+
+### 3.1 任务状态标记
+
+| 标记 | 含义 |
+|------|------|
+| `[ ]` | 未开始 |
+| `[~]` | 进行中 |
+| `[x]` | 已完成 |
+| `[!]` | 阻塞/有问题 |
+
+### 3.2 任务编号
+
+- `T1-W1-xx`：1期第1周第 xx 个任务
+- `T1-W2-xx`：1期第2周第 xx 个任务
+- `T2-W3-xx`：2期第3周第 xx 个任务
+
+---
+
+## 4. 测试纪律
+
+- 修 bug 必先写复现测试
+- 禁止删测试、禁止 `@skip`/`it.only` 进 PR
+- 后端测试用真实 PostgreSQL（`ruchu_finance_test`），禁止 mock DB
+- 测试覆盖率目标：70% 单元 / 20% 集成 / 10% E2E
+
+### 测试命令
+
+```bash
+# 后端
+java -cp apps/api/gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain -p apps/api test
+
+# 前端单元
+cd apps/web && npm run test
+
+# 前端 E2E
+cd apps/web && npm run test:e2e
+```
+
+> ⚠️ `./gradlew` 脚本有 bug，用上述 `java -cp` 命令替代。
+
+---
+
+## 5. 提交规范
+
+### 5.1 Git 提交信息
+
+```
+<type>(<scope>): <subject>
+
+<body>
+```
+
+- **type**：`feat`(新功能) / `fix`(修复) / `refactor`(重构) / `docs`(文档) / `test`(测试) / `chore`(杂项)
+- **scope**：模块名（contracts/payments/refunds/commissions/exchanges/insurances/salaries/workers/customers/reconcile/dashboard/auth/users/roles/permissions）
+- **subject**：简短描述（中文）
+
+示例：
+```
+feat(contracts): 合同列表页增加月份筛选
+fix(payments): 退款金额校验允许零元
+refactor(auth): 权限码从 user:manage 拆分为细粒度权限
+```
+
+### 5.2 禁止提交
+
+- 禁止提交 `.env` 文件（仅提交 `.env.example`）
+- 禁止提交 `build/` 目录
+- 禁止提交 `node_modules/`
+- 禁止提交敏感信息（密钥、密码、Token）
+
+---
+
+## 6. 已知问题
+
+| 问题 | 影响 | 解决方案 |
+|---|---|---|
+| `gradlew` 脚本 `escape_args` bug | 后端启动/测试失败 | 用 `java -cp` 命令替代（详见 `.windsurfrules.DEV-RULES` §5.2） |
+| Flyway checksum 不匹配 | 后端启动失败 | 手动更新 `flyway_schema_history`（详见 `.windsurfrules.DEV-RULES` §5.2） |
+| 业务 Controller 缺少 `@PreAuthorize` | 权限控制不完整 | 新增 Controller 必须加 `@PreAuthorize`，存量逐步补充 |
+
+---
+
+## 7. AI Agent 行为约束
+
+- **不猜测**：不确定时用工具查证，不编造 API/函数/参数
+- **不越权**：不修改未经授权的文件，不执行有副作用的命令
+- **不遗漏**：修改代码后同步更新相关文档和测试
+- **不简化**：不跳过错误处理、不删除边界检查、不忽略安全校验
+- **用中文沟通**：所有回复和注释使用中文
@@ -0,0 +1,88 @@
+# Cursor 规则文档索引
+
+本目录包含 Cursor AI 辅助开发的核心协作规范和工作流文档。
+
+## 文档概览
+
+### 核心工作流
+
+1. **[ai-coding-workflow.md](./ai-coding-workflow.md)** - Cursor 全局 AI Coding 协作规则
+   - 五阶段工作流：0-req → 1-prd → 2-task → 开发执行
+   - 统一编号体系和执行前读取顺序
+   - Definition of Done 标准
+
+2. **[quick-reference.md](./quick-reference.md)** - AI Coding 工作流快速参考
+   - 新项目强制检查点
+   - 阶段与产出对照表
+   - Definition of Ready & Done
+   - 禁止行为清单和紧急降级策略
+
+3. **[new-project-checkpoint.md](./new-project-checkpoint.md)** - 新项目初始化检查点
+   - 新项目识别条件
+   - 强制启动流程
+   - 检查点通过条件
+
+### 专项规范
+
+4. **[AGENTS.md](./AGENTS.md)** - AI 辅助开发协作规范（项目级）
+   - 文档阅读顺序
+   - 代码修改原则
+   - 任务管理和测试纪律
+   - 提交规范和已知问题
+
+5. **[change-management.md](./change-management.md)** - 需求变更管理
+   - 7 维度影响评估表
+   - 六步变更流程
+   - 变更文档模板
+
+6. **[architecture-and-design.md](./architecture-and-design.md)** - 架构与设计原则
+   - ADR 架构决策记录
+   - API/DB 变更约束
+   - 实体唯一代码规范
+   - 代码质量、测试、安全
+
+7. **[ui-components-standard.md](./ui-components-standard.md)** - UI/UX 与公共组件规范
+   - UI/UX 设计原则
+   - 公共组件抽取原则
+   - UI 公共组件登记表
+   - 组件参数膨胀应对策略
+
+## 使用指南
+
+### 新项目启动
+
+1. 阅读 `new-project-checkpoint.md` 了解新项目初始化流程
+2. 阅读 `ai-coding-workflow.md` 了解五阶段工作流
+3. 按照 `quick-reference.md` 中的阶段对照表推进
+
+### 日常开发
+
+1. 执行任务前，按 `ai-coding-workflow.md` §3.1.2 的顺序读取上下文
+2. 遵循 `AGENTS.md` 的代码修改原则
+3. 需求变更时，参考 `change-management.md` 的六步流程
+4. 重大技术决策时，参考 `architecture-and-design.md` 创建 ADR
+
+### 快速查询
+
+遇到以下情况，快速查阅对应文档：
+
+- **不确定当前阶段** → `quick-reference.md` 阶段对照表
+- **需要变更需求** → `change-management.md` 7 维评估
+- **API/DB 变更** → `architecture-and-design.md` 变更检查清单
+- **UI 组件重复** → `ui-components-standard.md` 抽取原则
+- **项目特定规则** → `AGENTS.md` 项目协作规范
+
+## 文档维护
+
+- 这些规则文档来源于 Cursor 全局规则
+- 项目级调整应在项目根目录的 `AGENTS.md` 中说明
+- 规则冲突时，优先级：用户明确指令 > 项目规则 > 全局规则
+
+## 相关文档
+
+项目其他重要文档：
+
+- `../pmdocs/` - 项目需求、PRD、任务文档
+- `../run.md` - 项目运行手册
+- `../.windsurfrules` - 项目精简规则（如果存在）
+- `../AGENTS.md` - 项目级 AI 协作规范（如果存在）
@@ -0,0 +1,241 @@
+# Cursor 全局 AI Coding 协作规则
+
+本规则应用于所有项目。核心目标是：先建立清晰需求与模块边界，再推进实现；以 `pmdocs/0-req-XXX.md` → `pmdocs/1-prd-XXX.md` → `pmdocs/2-task-XXX.md` → 开发执行的五阶段工作流为主。
+
+## 0. 优先级与适用范围
+
+### 0.1 指令优先级
+- 用户当前明确指令优先于本规则。
+- 项目内已有规范优先于本全局规则。
+- 本规则作为所有项目的默认协作、架构、编码、文档和质量基线。
+
+### 0.2 工作流主线
+- 涉及"做一个项目 / 实现一个功能 / 非平凡改造"的请求，默认使用五阶段工作流。
+- 统一使用 `pmdocs/` 作为 PM 文档目录：
+  - `pmdocs/0-req-XXX.md`：需求与目标文档
+  - `pmdocs/1-prd-XXX.md`：产品需求文档
+  - `pmdocs/2-task-XXX.md`：开发任务文档
+  - `pmdocs/changes/YYYY-MM-DD-序号-主题.md`：需求变更文档
+  - `pmdocs/CHANGELOG.md`：需求与 PM 文档变更索引
+  - `pmdocs/adr/YYYY-MM-DD-序号-主题.md`：架构决策记录
+  - `pmdocs/ui-components.md`：UI 公共组件登记表
+- 简单任务走快速流程，不强制产出三份阶段文档。
+
+### 0.3 简单任务定义
+满足以下情况之一，可走快速流程：
+- 单文件小改动，通常小于 50 行代码。
+- 明确 bug 修复，影响范围清晰。
+- 文案、样式、配置微调。
+- 只读检查、解释代码、运行一次命令、查看少量文件。
+
+快速流程：理解需求 → 简要确认 → 实施修改与必要验证 → 简洁说明结果。
+
+## 1. 语言与沟通
+
+- 所有与用户的交流必须使用简体中文。
+- 代码标识符、命令、日志、错误原文、文件路径、API 名称保持原语言。
+- 回复要直接、客观、简洁；不要输出冗长总结。
+- 除非用户明确要求，不使用 emoji。
+- 不确定时先提问，不擅自假设关键业务规则。
+- 提问应结构化：问题、背景、选项、建议。
+- 对用户能理解的内容，优先用模块关系、数据结构、数据流、状态机、作用域、伪代码表达，不沉迷函数级细节。
+
+## 2. 工作区与项目边界
+
+- 当前位于用户主目录时，只处理通用任务、系统探索、一次性命令和非项目工作。
+- 一旦任务属于某个明确项目，必须先切换到该项目根目录，再进行编辑、安装依赖、提交、创建文件等项目级操作。
+- 如果项目路径不明确，先询问用户。
+- 创建新项目时，优先放在 `~/Projects/` 或 `~/Developer/`；若不存在则放在用户主目录下。目录创建并初始化 Git 后，先切换到项目根目录，再继续脚手架、安装依赖或写代码。
+- 不回退用户或其他 agent 的脏变更。若冲突，先停下来询问。
+
+## 3. 五阶段工作流
+
+### 3.1 命名约定
+- 项目英文缩写记为 `XXX`，由用户提供或确认。
+- 阶段文档统一放在项目根目录下的 `pmdocs/` 独立目录：
+  - `pmdocs/0-req-XXX.md`：需求与目标文档
+  - `pmdocs/1-prd-XXX.md`：产品需求文档
+  - `pmdocs/2-task-XXX.md`：开发任务文档
+- 需求变更文档统一放在 `pmdocs/changes/`：
+  - `pmdocs/changes/YYYY-MM-DD-序号-主题.md`
+- 需求与 PM 文档变更索引统一使用：
+  - `pmdocs/CHANGELOG.md`
+- 架构决策记录统一放在 `pmdocs/adr/`：
+  - `pmdocs/adr/YYYY-MM-DD-序号-主题.md`
+- UI 公共组件登记表统一使用：
+  - `pmdocs/ui-components.md`
+
+### 3.1.1 统一编号体系
+
+- 需求条目使用 `REQ-001`、`REQ-002`。
+- PRD 功能使用 `PRD-FUNC-001`；产品场景使用 `SCENE-001`。
+- 开发任务使用 `TASK-001`，并映射到对应 `REQ`、`PRD-FUNC` 或 `SCENE`。
+- 需求变更使用 `CHG-YYYYMMDD-001`，并写入变更文档和 `pmdocs/CHANGELOG.md`。
+- 架构决策使用 `ADR-001`，并写入 `pmdocs/adr/YYYY-MM-DD-序号-主题.md`。
+- 权限码使用 `PERM_MODULE_ACTION`，例如 `PERM_USER_CREATE`、`PERM_ORDER_EXPORT`。
+- 编号一旦进入已确认文档，不复用、不重排；废弃项保留编号并标注状态。
+
+### 3.1.2 执行前读取顺序
+
+执行项目任务前，按以下顺序读取上下文，避免重复摸索：
+
+1. `run.md`：确认安装、启动、构建、测试、迁移命令。
+2. `pmdocs/2-task-XXX.md`：确认当前任务边界、验收标准、依赖关系。
+3. `pmdocs/changes/*.md`：若任务关联变更，确认变更原因、影响评估和状态。
+4. `pmdocs/1-prd-XXX.md`：确认产品场景、优先级、UI/UX 和公共组件规划。
+5. `pmdocs/0-req-XXX.md`：确认原始需求、非功能要求和范围边界。
+6. `pmdocs/adr/*.md`：若涉及技术栈、模块边界、认证、部署或数据方案，确认架构决策。
+
+原则：运行方式看 `run.md`，任务边界看 `2-task`，变更来源看 `changes`，产品原因看 `1-prd`，原始约束看 `0-req`，长期技术取舍看 `adr`。
+
+### 3.2 阶段 1：接收需求与目标
+- 完整读取和理解用户的需求描述或已有文档。
+- 识别目标用户、使用场景、优先级、性能、安全、数据规模、兼容性、第三方依赖等关键缺口。
+- 对模糊、矛盾或高风险信息先澄清。
+- 若需求明显过大，先拆出 MVP 与后续扩展边界。
+
+### 3.3 阶段 2：生成 `pmdocs/0-req-XXX.md`
+仅在阶段 1 信息足够后进行。
+
+文档必须包含：
+- 引言与目标
+- 术语表
+- 角色定义
+- 功能性需求，优先使用 EARS 格式：`WHEN / IF / WHILE / WHERE / THE ... SHALL ...`
+- 非功能性需求：性能、安全、兼容性、可用性、可扩展性、可维护性、合规性
+- 范围边界：包含 / 不包含
+- 关键约束与假设
+- 验收标准
+
+生成后必须请用户检查确认。未确认前不进入阶段 3。
+
+### 3.4 阶段 3：生成 `pmdocs/1-prd-XXX.md`
+仅在 `pmdocs/0-req-XXX.md` 确认通过后进行。
+
+文档必须包含：
+- 产品概述与定位
+- 目标与成功指标
+- 用户画像与核心场景，每个场景标注"痛点解法"
+- 功能清单与优先级，使用 MoSCoW，并映射回需求编号
+- 关键流程
+- 角色权限矩阵
+- UI/UX 设计原则：布局结构、导航方式、表单交互、列表/表格、筛选、分页、时间段选择、空状态、加载状态、错误状态、响应式和可访问性
+- 公共组件抽取规划：页面布局、分页组件、时间段组件、筛选栏、搜索框、表格、表单项、弹窗/抽屉、状态标签等
+- 版本规划：MVP / 二期 / 三期
+- 非功能性要求
+- 外部依赖、内部依赖与风险
+
+生成后必须请用户检查确认。未确认前不进入阶段 4。
+
+### 3.5 阶段 4：生成 `pmdocs/2-task-XXX.md`
+仅在 `pmdocs/1-prd-XXX.md` 确认通过后进行。
+
+任务文档要求：
+- 使用可勾选清单 `- [ ]`。
+- 编号清晰，任务粒度可执行、可验证。
+- 每个任务标注：目标、对应需求 / PRD 条目、验收标准、依赖关系、优先级、阶段。
+- 前后端技术栈、编译、启动、数据库迁移等一旦确认，必须包含创建或更新 `run.md` 的任务。
+- 涉及重大技术决策时，必须包含创建或更新 `pmdocs/adr/*.md` 的任务。
+- 涉及 API 或数据库变更时，必须包含接口契约、迁移、回滚、seed、权限和测试任务。
+- UI 页面开发前，应先识别可复用公共组件，并将页面布局、分页、时间段、筛选、表格、表单、弹窗等抽取任务排在具体页面任务之前。
+- 涉及可复用 UI 组件时，必须包含创建或更新 `pmdocs/ui-components.md` 的任务。
+- 明确测试要求：单元测试、集成测试、端到端测试、构建验证或手工验证。
+- 开发过程中持续更新任务状态和进度记录。
+
+生成后必须请用户确认。未确认前不进入阶段 5。
+
+### 3.6 阶段 5：按任务文档执行开发
+- 仅在 `pmdocs/2-task-XXX.md` 确认通过后开始编码。
+- 严格按确认后的任务文档推进。
+- 每完成一个任务或一组任务：
+  - 做相应验证：linter、构建、单元测试、集成测试或必要的手工验证。
+  - 更新 `pmdocs/2-task-XXX.md`。
+  - 简洁汇报结果、问题和下一步。
+- 若任务执行发现需调整需求或 PRD，必须进入需求变更流程。
+- 不在代码、文档或聊天中硬编码密钥、令牌、密码。
+
+### 3.7 Definition of Done
+
+任务完成标准：
+- 对应 `TASK` 已在 `pmdocs/2-task-XXX.md` 标记完成。
+- 代码实现完成，职责清晰，无复杂度扩散。
+- lint / build / test 或必要手工验证已完成。
+- `run.md` 已同步（若涉及）。
+- 变更文档已闭环，`pmdocs/CHANGELOG.md` 已同步（若涉及）。
+- API / DB / 权限码契约、迁移、回滚、测试已处理（若涉及）。
+- UI 加载、空态、错误、分页、权限状态已覆盖（若涉及）。
+- 无关脏变更未混入。
+
+## 4. 文档管理
+
+- 阶段文档是当前功能的事实来源：`pmdocs/0-req-XXX.md` 管需求，`pmdocs/1-prd-XXX.md` 管产品决策，`pmdocs/2-task-XXX.md` 管执行进度。
+- 不为每个小任务创建重复文档。
+- 项目级文档只在以下情况更新：新增用户可见功能、API 变化、配置格式变化、部署流程变化、重大架构调整、破坏性变更。
+- 文档过大时按模块或层次拆分，并保留导航入口。
+- 优先使用自动化文档：OpenAPI、GraphQL Schema、GoDoc、JSDoc、Sphinx、类型声明等。
+
+### 4.1 `run.md` 运行手册
+
+- 一旦确认前端、后端、数据库、包管理器、运行时或部署方式，必须在项目根目录创建或更新 `run.md`。
+- `run.md` 是项目运行事实来源；后续编译、启动、测试、数据库迁移等操作必须优先读取它，不要每次重新查找和试错。
+- 如果实际命令与 `run.md` 不一致，先验证真实行为，再更新 `run.md`，保持文档与运行时一致。
+- `run.md` 至少包含：
+  - 技术栈：前端、后端、数据库、包管理器、运行时版本。
+  - 本地环境：必要环境变量、配置文件、端口、依赖服务。
+  - 安装命令：依赖安装、初始化步骤。
+  - 开发命令：前端启动、后端启动、全栈启动、后台任务或 worker。
+  - 构建命令：前端构建、后端构建、类型检查、lint。
+  - 测试命令：单元测试、集成测试、端到端测试、覆盖率。
+  - 数据库命令：迁移、回滚、seed、reset、schema 生成。
+  - 常见问题：已验证的坑、报错原因、修复方式。
+- `pmdocs/2-task-XXX.md` 中涉及环境准备、技术栈确认、数据库接入或部署改动时，必须包含更新 `run.md` 的任务。
+
+## 5. Git 与协作
+
+- 不主动提交代码，除非用户明确要求。
+- 不主动 push，除非用户明确要求。
+- 不使用破坏性 Git 操作，例如 `reset --hard`、强制 push、丢弃他人改动，除非用户明确要求并理解风险。
+- 提交粒度应是一个逻辑完整单元。
+- 提交信息优先遵循 Conventional Commits：`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`。
+- 发现无关脏变更时忽略；若与当前任务冲突，先询问用户。
+
+## 6. 特殊场景
+
+### 6.1 Bug 修复
+- 先定位根因，再修复。
+- 说明影响范围。
+- 优先补测试或最小复现。
+- 修复后做回归验证。
+
+### 6.2 性能优化
+- 先测量再优化。
+- 识别瓶颈后再改代码。
+- 给出优化前后对比或可复现验证方式。
+- 说明优化副作用。
+
+### 6.3 重构
+- 先说明重构目标和边界。
+- 保持外部行为不变。
+- 小步推进，保持可回滚。
+- 对遗留代码先理解再修改，必要时先加测试建立安全网。
+
+### 6.4 Cursor 相关问题
+- 当用户询问 Cursor 使用方式、配置、设置或功能时，使用最新 Cursor 指南或可用专用能力，不凭记忆回答。
+
+## 7. 核心原则
+
+1. 用户目标优先，不替用户做关键业务决策。
+2. 架构与模块职责优先，不让复杂度在局部扩散。
+3. 工作流以 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 为主，关键节点必须确认。
+4. 代码必须可维护、可测试、可验证。
+5. 沟通简洁透明，风险和阻塞及时说明。
+6. 不把密钥、令牌、密码放进全局规则或项目源码。
+
+## 8. 相关规则
+
+本规则聚焦工作流主线和核心原则。详细规范请参考：
+
+- `quick-reference.md`：快速参考卡、阶段对照表、禁止行为、紧急降级
+- `architecture-and-design.md`：架构原则、ADR、API/DB 变更约束、代码质量、测试、安全
+- `ui-components-standard.md`：UI/UX 设计原则、公共组件抽取、组件登记表、参数膨胀应对
+- `change-management.md`：需求变更识别、7 维评估、六步流程、文档追加、闭环机制
@@ -0,0 +1,128 @@
+# 架构与设计原则
+
+本规则用于指导架构决策、接口设计、数据库变更和技术选型。
+
+## 核心原则
+
+- 职责分明的模块架构优先于优雅代码，优雅代码优先于功能堆砌。
+- 优先评估模块边界、数据流向、状态机、权限边界、错误边界和扩展点。
+- 出现复杂度扩散、参数爆炸、数据流回溯、状态同步困难时，应优先建议调整模块关系或架构，而不是继续局部补丁。
+- 默认偏好 Functional Programming 和可读的 DSL 化组织方式；除非项目已明确是面向对象架构。
+- 新技术、新依赖、新服务引入前，说明理由、收益、成本、风险和替代方案，并等待确认。
+- 接口设计优先明确契约：输入、输出、错误结构、状态码、幂等性、权限、兼容性。
+
+## ADR 架构决策记录
+
+- 重大技术决策必须写入 ADR，避免决策只存在于聊天或临时说明中。
+- ADR 路径：`pmdocs/adr/YYYY-MM-DD-序号-主题.md`。
+- ADR 触发条件：
+  - 前端技术栈、后端技术栈、数据库或运行时选择。
+  - 认证授权、权限模型、状态管理、路由结构或部署方式选择。
+  - 重大模块边界调整、数据流调整、状态机调整。
+  - 引入会影响长期维护成本的新依赖、新服务或基础设施。
+  - 关键性能、安全、可扩展性方案选择。
+- ADR 必须包含：背景、决策选项、最终选择、选择理由、影响后果、风险和回滚思路。
+- ADR 只记录重要决策；普通实现细节不要过度记录。
+
+### ADR 模板示例
+
+```markdown
+# ADR-001：选择 xxx
+
+## 背景
+为什么需要决策
+
+## 选项
+- A：优点 / 缺点
+- B：优点 / 缺点
+
+## 决策
+选择哪个方案
+
+## 后果
+带来的收益、成本、风险
+```
+
+## API 变更约束
+
+- API 变更必须明确：请求结构、响应结构、错误码、权限要求、幂等性、兼容性和废弃策略。
+- API 变更必须同步到 `pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 或对应变更文档；如果项目已有 OpenAPI / GraphQL Schema / RPC IDL，也必须同步。
+- 涉及权限码的 API 变更，必须同步权限码表、后端校验、前端权限门禁和测试用例。
+- 破坏性 API 变更必须进入需求变更流程，并在 7 维度影响评估表中明确处理动作和状态。
+
+### API 变更检查清单
+
+- [ ] 请求结构（字段、类型、必填、默认值）
+- [ ] 响应结构（字段、类型、状态码、错误码）
+- [ ] 权限要求（角色、权限码、访问边界）
+- [ ] 幂等性（POST / PUT / DELETE 是否幂等）
+- [ ] 兼容性（新增字段 / 废弃字段 / 破坏性变更）
+- [ ] 文档同步（PRD / 任务 / OpenAPI / GraphQL Schema）
+- [ ] 测试覆盖（单元测试 / 集成测试 / 权限测试）
+
+## 数据库变更约束
+
+- 数据库变更必须明确：表、字段、索引、约束、迁移脚本、回滚脚本、seed 是否调整、历史数据兼容策略。
+- 数据库变更必须评估查询性能、索引影响、默认值、空值、唯一约束和线上数据迁移风险。
+- 涉及权限码的 DB 变更，必须同步权限码表、后端校验、前端权限门禁和测试用例。
+- 破坏性 DB 变更必须进入需求变更流程，并在 7 维度影响评估表中明确处理动作和状态。
+
+### 实体唯一代码规范
+
+- 业务主体实体（用户、组织、部门、商品、订单、项目）和配置数据（角色、字典项、模板）必须有唯一业务代码。
+- 唯一代码格式：`{前缀}_{业务含义}` 或 `{模块}_{编号}`，例如：
+  - 用户：`USER_admin001`、`USER_john_doe`
+  - 商品：`PROD_SKU12345`
+  - 订单：`ORDER_20260705001`
+  - 权限：`PERM_USER_CREATE`
+- 唯一代码约束：
+  - 必须有唯一索引
+  - 一旦创建不可修改
+  - 优先可读性，而非简洁性
+- 其他表引用时，优先使用唯一业务代码作为外键，而不是自增 ID。
+- 好处：数据可读、跨系统可追溯、数据库导入导出友好、便于调试。
+- 权衡：查询性能可能略低于整数 ID，必须在唯一代码字段上建立索引。
+- 不需要唯一代码的场景：纯关联表、日志、审计、历史记录、一次性临时数据、只在父实体内部使用的子表。
+
+### 数据库变更检查清单
+
+- [ ] 表、字段、索引、约束变化
+- [ ] 迁移脚本（migration）
+- [ ] 回滚脚本（rollback）
+- [ ] seed 数据是否调整
+- [ ] 历史数据兼容策略（默认值 / 数据填充 / 迁移脚本）
+- [ ] 查询性能影响（索引 / 全表扫描 / 锁表风险）
+- [ ] 空值、唯一约束、外键约束影响
+- [ ] 线上数据迁移风险（停机 / 灰度 / 双写）
+- [ ] 测试覆盖（单元测试 / 集成测试 / 迁移测试）
+
+## 代码质量
+
+- 遵循项目既有代码风格。
+- 保持单一职责、高内聚、低耦合。
+- 避免重复代码，避免过度抽象。
+- 命名必须语义清晰。
+- 注释只解释代码无法自解释的意图、约束和权衡，不写表面行为注释。
+
+## 错误处理
+
+- 不忽略错误。
+- 用户可见错误要友好，内部错误要可诊断。
+- 对关键边界做输入校验、权限校验和异常处理。
+- 错误处理路径应有测试覆盖。
+
+## 测试与验证
+
+- 功能代码和测试代码尽量同步完成。
+- 公共函数、核心业务规则、权限判断、错误处理和边界条件应有测试。
+- 测试优先使用 Arrange-Act-Assert 或 Given-When-Then。
+- 使用 Mock / Stub 隔离外部依赖。
+- 测试应快速稳定，避免不必要的 sleep 或长等待。
+- 完成实质性编辑后，检查 linter 或诊断；若引入错误，应修复。
+
+## 安全
+
+- 不在代码、规则、提交信息或文档中硬编码密钥、令牌、密码。
+- 敏感信息应使用环境变量、密钥管理器或用户指定的安全存储方式。
+- 验证所有用户输入，防止注入、XSS、越权访问等常见问题。
+- 遵循最小权限原则。
@@ -0,0 +1,114 @@
+# 需求变更管理
+
+本规则用于指导需求变更识别、影响评估、文档追加和任务闭环。
+
+## 启用条件
+
+- 当用户提出与已确认的 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md` 或 `pmdocs/2-task-XXX.md` 不一致的要求时，先判断是否属于需求变更。
+- 只有影响以下任一范围时，才启用完整变更机制：需求、PRD、任务、数据库、接口、权限、核心 UI 流程。
+- 小变更不要过度文档化：文案调整、样式微调、明显 bug 修复、无业务含义的配置微调，不需要创建完整变更文档；可在任务记录或回复中简要说明。
+
+## 核心原则
+
+- 每次重要需求变更创建独立变更文档，不覆盖历史内容。
+- 原始 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 只追加版本标注和变更引用，不重写历史决策。
+- 变更必须从"影响评估"进入"任务落地"，最后完成闭环。
+
+## 变更文档命名
+
+- 变更文档路径：`pmdocs/changes/YYYY-MM-DD-序号-主题.md`。
+- 示例：`pmdocs/changes/2026-07-05-001-权限码调整.md`。
+- 每份变更文档必须包含：背景、原因、目标、范围、影响评估、落地任务、状态、完成记录。
+
+## 六步流程
+
+1. 创建变更文档：`pmdocs/changes/YYYY-MM-DD-序号-主题.md`。
+2. 评估影响：使用 7 维度影响评估表。
+3. 更新原文档：在 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 对应章节末尾追加 `v{版本}` 更新标注和变更文档引用。
+4. 更新变更索引：在 `pmdocs/CHANGELOG.md` 追加变更记录。
+5. 开发落地：按 `pmdocs/2-task-XXX.md` 新增任务执行，并关联变更文档。
+6. 完成闭环：任务标记 `[x]`，变更文档状态标注完成，索引状态同步更新。
+
+## 7 维度影响评估表
+
+变更文档必须包含以下表格：
+
+| 维度 | 是否影响 | 影响说明 | 处理动作 | 状态 |
+|---|---|---|---|---|
+| 需求 | 是/否 | 影响哪些 REQ 条目 | 追加版本标注 / 新增需求 | 待处理/已处理 |
+| PRD | 是/否 | 影响哪些产品场景或功能 | 追加版本标注 / 调整优先级 | 待处理/已处理 |
+| 任务 | 是/否 | 新增或调整哪些 TASK | 追加任务 / 调整依赖 | 待处理/已处理 |
+| DB | 是/否 | 表、字段、索引、迁移影响 | 新增 migration / 回滚方案 | 待处理/已处理 |
+| 后端 | 是/否 | API、服务、权限判断影响 | 修改接口 / 服务 / 测试 | 待处理/已处理 |
+| 前端 | 是/否 | 页面、组件、状态、交互影响 | 修改页面 / 公共组件 / 测试 | 待处理/已处理 |
+| 权限码 | 是/否 | 角色、权限码、访问边界影响 | 更新权限表 / 权限校验 | 待处理/已处理 |
+
+## 原文档追加标注格式
+
+在对应章节末尾追加：
+
+```markdown
+📌 v{版本} 更新：见 pmdocs/changes/YYYY-MM-DD-序号-主题.md
+影响范围：REQ-xxx、PRD-xxx、TASK-xxx
+状态：已纳入 / 已完成 / 已废弃
+```
+
+## 确认要求
+
+- 中大型变更执行前说明：影响范围、工作量、风险、回滚方案、需要回归测试的功能。
+- 架构调整、多模块影响、数据结构或 API 破坏性变更，必须获得明确确认。
+- 小规模明确变更可简要说明后直接执行。
+
+## 变更文档模板
+
+```markdown
+# CHG-YYYYMMDD-001：变更主题
+
+## 背景
+为什么要做这个变更
+
+## 原因
+用户需求 / 线上问题 / 技术债 / 架构调整
+
+## 目标
+变更期望达成的目标
+
+## 范围
+影响的功能模块、页面、接口、数据
+
+## 影响评估
+
+| 维度 | 是否影响 | 影响说明 | 处理动作 | 状态 |
+|---|---|---|---|---|
+| 需求 | 是/否 | ... | ... | 待处理/已处理 |
+| PRD | 是/否 | ... | ... | 待处理/已处理 |
+| 任务 | 是/否 | ... | ... | 待处理/已处理 |
+| DB | 是/否 | ... | ... | 待处理/已处理 |
+| 后端 | 是/否 | ... | ... | 待处理/已处理 |
+| 前端 | 是/否 | ... | ... | 待处理/已处理 |
+| 权限码 | 是/否 | ... | ... | 待处理/已处理 |
+
+## 落地任务
+
+- [ ] TASK-xxx：更新需求文档
+- [ ] TASK-xxx：更新 PRD
+- [ ] TASK-xxx：更新任务文档
+- [ ] TASK-xxx：DB migration
+- [ ] TASK-xxx：后端实现
+- [ ] TASK-xxx：前端实现
+- [ ] TASK-xxx：测试
+- [ ] TASK-xxx：更新 CHANGELOG
+
+## 风险与回滚
+
+- 风险：...
+- 回滚方案：...
+- 需要回归测试的功能：...
+
+## 完成记录
+
+- 2026-07-05：创建变更文档
+- 2026-07-06：完成影响评估，更新原文档
+- 2026-07-08：完成开发和测试
+- 2026-07-09：变更闭环
+```
@@ -0,0 +1,89 @@
+# 新项目初始化检查点
+
+本规则用于确保新项目一开始就按照五阶段工作流启动。
+
+## 新项目识别条件
+
+当满足以下任一条件时，判定为新项目：
+
+- 用户明确说"做一个项目""新建项目""开始一个新项目"
+- 项目根目录不存在 `pmdocs/` 目录
+- 项目根目录存在但没有 `pmdocs/0-req-*.md`
+
+## 强制启动流程
+
+一旦识别为新项目，必须执行以下流程，**不得跳过**：
+
+### 第一步：确认项目英文缩写
+
+- 询问用户：项目英文缩写（例如：IPTV、AVCC、BLOG）
+- 用于命名 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md`
+
+### 第二步：创建 pmdocs 目录结构
+
+在项目根目录创建：
+
+```
+pmdocs/
+├── changes/
+└── adr/
+```
+
+### 第三步：进入阶段 1
+
+按照 `ai-coding-workflow.md` 中的"阶段 1：接收需求与目标"开始工作：
+
+- 完整读取和理解用户需求
+- 识别关键缺口：目标用户、使用场景、优先级、性能、安全、数据规模、兼容性、第三方依赖
+- 对模糊、矛盾或高风险信息先澄清
+- 若需求过大，先拆出 MVP
+
+### 第四步：禁止提前编码
+
+在 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 三个文档全部确认前，**严格禁止**：
+
+- 创建源码文件
+- 安装依赖
+- 初始化框架
+- 写任何业务代码
+
+唯一允许的操作：
+
+- 创建 `pmdocs/` 目录和阶段文档
+- 创建 `.gitignore`
+- 创建 `README.md`（只写项目名称和简介）
+
+## 用户试图跳过时的应对
+
+如果用户说"先写代码，文档后补"或类似要求，必须：
+
+1. 明确告知：这违反了项目协作规则
+2. 说明风险：需求不明、架构混乱、返工成本高
+3. 提供选择：
+   - 选项 A：按规则走完五阶段（推荐）
+   - 选项 B：启用紧急降级策略（见 `quick-reference.md`），明确记录技术债和补齐时间点
+
+## 检查点通过条件
+
+只有满足以下条件，才算通过新项目初始化检查点：
+
+- [ ] 项目英文缩写已确认
+- [ ] `pmdocs/` 目录结构已创建
+- [ ] `pmdocs/0-req-XXX.md` 已生成并确认
+- [ ] `pmdocs/1-prd-XXX.md` 已生成并确认
+- [ ] `pmdocs/2-task-XXX.md` 已生成并确认
+- [ ] `run.md` 已创建或计划在任务中创建
+
+通过检查点后，才可以进入"阶段 5：按任务文档执行开发"。
+
+## 已有项目的处理
+
+如果项目已存在代码但缺少 `pmdocs/` 文档：
+
+1. 明确告知：这是一个缺少规范文档的已有项目
+2. 提供选择：
+   - 选项 A：补充 `pmdocs/0-req`、`1-prd`、`2-task`（推荐，但工作量大）
+   - 选项 B：只创建 `run.md` 和当前阶段的 `2-task-XXX.md`，后续按需补充
+   - 选项 C：不补充文档，只用规则指导后续开发（不推荐，可追溯性差）
+
+选择后必须记录在项目根目录的 `README.md` 或 `pmdocs/CHANGELOG.md` 中。
@@ -0,0 +1,106 @@
+# AI Coding 工作流快速参考
+
+用于快速判断当前处于哪个阶段、该产出什么、是否需要用户确认。
+
+## 新项目强制检查点
+
+**识别条件**：用户说"做一个项目"，或项目根目录不存在 `pmdocs/`。
+
+**强制流程**：
+1. 确认项目英文缩写
+2. 创建 `pmdocs/` 目录结构
+3. 进入阶段 1：接收需求
+4. **禁止提前编码**，直到 `0-req`、`1-prd`、`2-task` 全部确认
+
+详见 `new-project-checkpoint.md`。
+
+## 阶段与产出对照表
+
+| 场景 | 应读取 | 应产出 | 必须确认 | 备注 |
+|---|---|---|---|---|
+| 新项目启动 | 用户描述 | `pmdocs/0-req-XXX.md` | ✓ | 理解需求、识别风险、拆 MVP |
+| 需求确认后 | `0-req` | `pmdocs/1-prd-XXX.md` | ✓ | 产品场景、UI/UX、公共组件规划 |
+| PRD 确认后 | `0-req` + `1-prd` | `pmdocs/2-task-XXX.md` + `run.md` | ✓ | 任务拆分、编号、依赖、验收 |
+| 任务确认后 | `run.md` + `2-task` + `changes` + `adr` | 代码 + 测试 + Done 闭环 | - | 按执行前读取顺序 |
+| 需求变更 | 原 `0-req` / `1-prd` / `2-task` | `pmdocs/changes/CHG-*.md` + 7 维评估 | ✓ | 只影响需求/PRD/任务/DB/接口/权限/UI 时启用 |
+| 重大技术决策 | 当前上下文 | `pmdocs/adr/ADR-*.md` | ✓ | 技术栈、认证、模块边界、部署 |
+| 公共组件沉淀 | 页面实现 | `pmdocs/ui-components.md` | - | 登记组件类型、输入输出、使用页面 |
+| 简单任务 | 上下文 | 代码 + 简要说明 | - | 单文件 < 50 行、bug 修复、文案调整 |
+
+## 执行前读取顺序
+
+执行项目任务前，按以下顺序读取上下文：
+
+1. `run.md` → 运行方式
+2. `pmdocs/2-task-XXX.md` → 任务边界
+3. `pmdocs/changes/*.md` → 变更来源
+4. `pmdocs/1-prd-XXX.md` → 产品原因
+5. `pmdocs/0-req-XXX.md` → 原始约束
+6. `pmdocs/adr/*.md` → 技术取舍
+
+## Definition of Ready
+
+允许开始开发的条件：
+
+- [ ] `pmdocs/0-req-XXX.md` 已确认
+- [ ] `pmdocs/1-prd-XXX.md` 已确认
+- [ ] `pmdocs/2-task-XXX.md` 已确认
+- [ ] 当前任务具备 `TASK` 编号、验收标准、依赖、测试要求
+- [ ] 技术栈明确，涉及运行/构建/迁移时 `run.md` 已存在或任务中明确补充
+- [ ] 重大决策已有 ADR 或计划创建
+- [ ] 关键风险、权限边界、数据边界、回滚策略已说明
+
+## Definition of Done
+
+任务完成标准：
+
+- [ ] 对应 `TASK` 已在 `pmdocs/2-task-XXX.md` 标记完成
+- [ ] 代码实现完成，职责清晰，无复杂度扩散
+- [ ] lint / build / test 或必要手工验证已完成
+- [ ] `run.md` 已同步（若涉及）
+- [ ] 变更文档已闭环，`pmdocs/CHANGELOG.md` 已同步（若涉及）
+- [ ] API / DB / 权限码契约、迁移、回滚、测试已处理（若涉及）
+- [ ] UI 加载、空态、错误、分页、权限状态已覆盖（若涉及）
+- [ ] 无关脏变更未混入
+
+## 编号体系速查
+
+- 需求：`REQ-001`
+- PRD 功能：`PRD-FUNC-001`
+- 场景：`SCENE-001`
+- 任务：`TASK-001`
+- 变更：`CHG-YYYYMMDD-001`
+- 架构决策：`ADR-001`
+- 权限码：`PERM_MODULE_ACTION`
+
+编号一旦进入已确认文档，不复用、不重排；废弃项保留编号并标注状态。
+
+## 禁止行为清单
+
+- ❌ 跨阶段抢跑：未确认 `0-req` 就写 `1-prd`，未确认 `2-task` 就开始编码
+- ❌ 文档与代码不同步：`run.md` 过期、`ui-components.md` 不更新、变更未闭环
+- ❌ 编号混乱：`REQ` / `TASK` / `CHG` 编号重复、跳号、随意改动
+- ❌ 过度文档化：明显 bug 修复创建完整变更文档，单文件改动走五阶段
+- ❌ 架构决策口头化：技术栈、认证方案只在聊天里说，未写入 ADR
+- ❌ API / DB 变更无迁移：改表结构不写 migration，改 API 不说明兼容性
+- ❌ 公共组件参数爆炸：把页面路由、接口请求、特定文案硬塞进基础组件
+
+## 紧急情况降级策略
+
+- 线上紧急 bug：可先修复上线，24 小时内补 `pmdocs/changes/CHG-*.md` 和回归测试
+- 技术栈探索期：可先做 POC，技术栈确定后立即补 `run.md` 和 ADR
+- 用户明确"先上后补"：必须在任务或聊天中明确风险、缺失文档清单和补齐时间点
+- 外部不可控因素：在 `0-req` 或 `1-prd` 中标注"假设 X 可用"；若假设失效，进入变更流程
+
+## 文档健康检查清单
+
+定期或阶段结束时验证：
+
+- [ ] `0-req`、`1-prd`、`2-task` 已确认并有版本记录
+- [ ] 所有 `REQ` / `PRD-FUNC` / `TASK` 编号唯一且可追溯
+- [ ] `run.md` 能直接执行，命令无误
+- [ ] 变更文档已闭环，`CHANGELOG.md` 同步
+- [ ] ADR 覆盖所有重大技术决策
+- [ ] `ui-components.md` 与实际组件一致
+- [ ] API / DB 变更有 migration / rollback / 测试
+- [ ] 无关脏变更未混入提交
@@ -0,0 +1,71 @@
+# UI/UX 与公共组件规范
+
+本规则用于指导 UI/UX 设计、公共组件抽取和组件登记管理。
+
+## UI/UX 设计原则
+
+- 禁止使用 emoji 作为 UI 图标。
+- 首选专业图标库：Lucide Icons，其次 Feather Icons；Ant Design 项目可使用 Ant Design Icons。
+- 禁止使用中文拼音缩写表达业务含义；优先使用英文、中文全称或清晰的领域命名。
+- UI 实现应关注一致性、可访问性、响应式布局和错误状态。
+- 页面设计应先确定信息架构，再确定视觉样式：导航、页面标题、主操作区、筛选区、内容区、分页区、反馈区。
+- 表单必须明确必填、校验、错误提示、提交中、提交成功、提交失败和取消路径。
+- 列表和表格必须明确加载、空数据、错误、筛选无结果、分页、排序和批量操作状态。
+- 时间、金额、状态、权限、危险操作等高频模式必须统一呈现，不允许每个页面各自发挥。
+
+## 公共组件抽取原则
+
+- 同一交互或视觉模式在两个及以上页面出现，优先抽取公共组件。
+- 即使只出现一次，但包含复杂状态、权限、时间段、分页、筛选、表格联动等逻辑，也应优先抽取为领域组件或组合组件。
+- 公共组件 API 应表达业务语义，不暴露页面内部状态细节。
+- 公共组件应保持稳定输入输出：`value`、`onChange`、`loading`、`disabled`、`error`、`empty`、`pagination` 等状态显式建模。
+- 不把页面特有文案、接口请求、路由跳转硬塞进基础公共组件；这些应留在页面层或领域组合层。
+
+## 优先沉淀的组件类型
+
+- 页面布局：`PageLayout`、`PageHeader`、`ContentCard`、`ActionBar`。
+- 查询筛选：`FilterBar`、`SearchInput`、`TimeRangePicker`、`DateRangePreset`。
+- 数据展示：`DataTable`、`Pagination`、`EmptyState`、`LoadingState`、`ErrorState`。
+- 表单交互：`FormField`、`FormSection`、`SubmitBar`、`ConfirmDialog`。
+- 反馈与状态：`StatusBadge`、`PermissionGate`、`Toast`、`ResultPanel`。
+- 业务高频组件：根据项目领域沉淀，不提前抽象不存在的业务概念。
+
+## 页面实现顺序
+
+- 先定义页面布局和数据流，再实现页面。
+- 先抽取公共组件，再堆页面细节。
+- 先覆盖加载、空态、错误、分页和权限状态，再补视觉细节。
+- 当组件参数开始膨胀时，优先评估是否应拆成基础组件、领域组件和页面容器三层。
+
+## UI 公共组件登记表
+
+- 一旦项目出现可复用 UI 组件，必须创建或更新 `pmdocs/ui-components.md`。
+- `pmdocs/ui-components.md` 用于记录组件沉淀情况，避免重复造分页、时间段、筛选栏、表格、表单等组件。
+- 组件登记表至少包含：组件名、组件类型、适用场景、输入状态、输出事件、使用页面、维护状态。
+- 推荐格式：
+
+| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
+|---|---|---|---|---|---|---|
+| `Pagination` | 基础组件 | 列表/表格分页 | `page` / `pageSize` / `total` | `onChange` | 用户列表、订单列表 | 稳定 |
+| `TimeRangePicker` | 组合组件 | 时间范围筛选 | `start` / `end` / `preset` | `onChange` | 数据看板、订单筛选 | 稳定 |
+| `FilterBar` | 组合组件 | 列表筛选栏 | `filters` / `onFilterChange` | `onChange` / `onReset` | 用户列表、订单列表 | 稳定 |
+| `DataTable` | 基础组件 | 数据表格 | `columns` / `data` / `loading` / `pagination` | `onPageChange` / `onSort` | 用户列表、订单列表 | 稳定 |
+
+- 公共组件新增、重命名、废弃或职责变化时，必须同步更新组件登记表。
+- 组件登记表只记录复用组件，不记录一次性页面局部元素。
+
+## 组件参数膨胀应对策略
+
+当组件参数超过 10 个，或出现以下情况时，应重新评估组件边界：
+
+- 参数包含页面特定文案、路由、接口请求
+- 参数包含复杂业务规则或权限判断
+- 参数存在互斥或复杂依赖关系
+- 不同使用场景需要不同参数子集
+
+应对策略：
+
+1. 拆成基础组件 + 领域组件 + 页面容器三层
+2. 使用组合模式而不是配置模式
+3. 使用 Render Props 或 Slots 传递复杂逻辑
+4. 使用 Context 或状态管理隔离跨层状态