迁移 Claude/Codex/Cursor 开发环境与追溯资产

Co-Authored-By: OpenAI Codex <codex@openai.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-02 03:11:39 +08:00
parent d269ee6401
commit 81e41730ec
33 changed files with 3734 additions and 34 deletions
--- a/.cursor/skills/audit/SKILL.md
+++ b/.cursor/skills/audit/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: audit
+description: /audit — 变更审计。从 Claude Code 命令迁移为 Cursor project skill；用户要求执行 audit、/audit 或相关流程时使用。
+disable-model-invocation: true
+---
+
+# /audit — 变更审计
+
+回顾本次会话中你所做的所有文件变更，结合自动预扫描结果，执行审计落盘。
+
+## 执行步骤
+
+### 第 1 步：运行预扫描脚本（Python，零 token）
+
+运行：
+```bash
+python scripts/audit/prescan.py
+```
+
+该脚本自动完成：
+- 从 git status 获取所有变更文件
+- 分类高风险文件 + 生成 risk_tags
+- 合规检查：代码→文档映射、迁移 SQL 检测、DDL 基线检查
+
+读取输出的 JSON。如果 `audit_required: false`，告知用户"无需审计"并结束。
+
+**备选**：如果 git status 包含大量非本次会话的历史变更，可以用 `--files` 参数只传入本次会话的文件：
+```bash
+python scripts/audit/prescan.py --files "file1.py,file2.sql,..."
+```
+文件列表从你的对话记忆（本次会话的 Edit/Write 工具调用）中提取。
+
+### 第 2 步：补充语义上下文
+
+预扫描脚本能告诉你"哪些文件变了、是否高风险、文档是否缺失"，但它不知道**为什么改**。
+
+从对话记忆中补充：
+- 每个变更文件的修改原因（用户的需求是什么）
+- 改动的技术思路和设计决策
+- 与其他模块的关联影响
+
+将预扫描 JSON + 语义上下文合并，作为第 3 步的输入。
+
+### 第 3 步：委托子代理写审计记录
+
+用 Agent 工具启动子代理，传入：
+1. 预扫描 JSON 结果（完整）
+2. 每个变更的原因和内容概要（你补充的语义上下文）
+
+子代理的任务指令：
+
+> 在 `docs/audit/changes/` 目录下创建审计记录文件，文件名格式 `<YYYY-MM-DD>__<英文短标识>.md`。
+>
+> 使用以下格式：
+>
+> ```markdown
+> # 变更审计记录：<中文标题>
+>
+> | 字段 | 值 |
+> |------|-----|
+> | 日期 | YYYY-MM-DD HH:MM:SS |
+>
+> ## 操作摘要
+> <1-3 段，说清楚做了什么、为什么做>
+>
+> ## 变更文件
+> 按新增/修改/删除分组，每个文件一行，简要说明改动内容。
+>
+> ## 改动注解
+> 对每个变更文件写注解：
+> - 高风险文件（ETL 任务/后端路由/数据库迁移/金额相关）：写详细注解（变更类型、原因、思路、结果）
+> - 普通文件：一行简要说明
+> - 删除的文件：只记录删除原因
+>
+> ## 数据库变更（如有）
+> 列出新建/修改/删除的表、字段、约束、索引。标注迁移执行状态。
+>
+> ## 风险与回滚
+> - 风险点（标注高/中/低）
+> - 回滚要点
+>
+> ## 验证
+> - 至少 1 条可执行的验证方式（测试命令 / SQL / 联调步骤）
+>
+> ## 合规检查
+> - 列出文档同步状态（已同步 / 待补齐 / 不适用）
+> ```
+>
+> 当前北京时间通过 `python -c "from datetime import datetime, timezone, timedelta; print(datetime.now(timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S'))"` 获取。
+>
+> 审计记录语言使用简体中文。
+>
+> 完成后运行 `python scripts/audit/gen_audit_dashboard.py` 刷新审计一览表。
+>
+> 最终只返回：done / files_written / next_step。
+
+### 第 4 步：补齐缺失的文档同步
+
+根据预扫描 JSON 中 `code_without_docs` 列出的不合规项，逐项补齐：
+- 读取对应代码文件当前内容
+- 更新对应文档
+
+如果补齐工作量大（>3 个文档），委托子代理处理。
+
+### 第 5 步：向用户报告
+
+简短回执：
+- 审计记录文件路径
+- 合规检查结果（全部通过 / N 项已补齐 / N 项待用户处理）
+- 下一步建议（如 "commit when ready"）
--- a/.cursor/skills/db-docs/SKILL.md
+++ b/.cursor/skills/db-docs/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: db-docs
+description: /db-docs — 数据库文档同步。从 Claude Code 命令迁移为 Cursor project skill；用户要求执行 db-docs、/db-docs 或相关流程时使用。
+disable-model-invocation: true
+---
+
+# /db-docs — 数据库文档同步
+
+当 PostgreSQL schema/表结构发生变化时，将变更以审计友好的方式落盘到 `docs/database/`。
+
+## 触发条件
+
+- 迁移脚本/DDL 修改（新增/删除/改表、字段、类型、默认值、非空、约束、索引、外键）
+- 手工执行了 DDL
+
+## 执行步骤
+
+### 第 1 步：识别结构性变化
+
+从本次会话的改动中，列出新增/修改/删除的对象：
+- schema / table / column / index / constraint / foreign key
+- 明确变更前后差异（before/after）
+
+### 第 2 步：更新表结构文档
+
+对每张受影响的表，更新 `docs/database/` 下对应的文档：
+- 如果文档已存在：更新字段列表、约束、索引等
+- 如果文档不存在：基于以下模板创建
+
+模板：
+```markdown
+# <schema>.<table_name>
+
+## 概述
+<表的用途说明>
+
+## 字段
+
+| 字段名 | 类型 | 可空 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| ... | ... | ... | ... | ... |
+
+## 约束与索引
+- PRIMARY KEY: ...
+- UNIQUE: ...
+- INDEX: ...
+
+## 关联
+- 上游：<数据来源>
+- 下游：<被哪些模块/表消费>
+```
+
+特别注意金额类字段：标注精度、币种、舍入规则。
+
+### 第 3 步：回滚与验证
+
+写入审计友好的回滚和验证信息：
+- DDL 回滚路径（必要时提供反向迁移 SQL）
+- 至少 3 条验证 SQL（含约束/索引/关键字段检查）
+
+### 第 4 步：DDL 基线检查
+
+检查 `docs/database/ddl/` 下的基线文件是否需要合并更新。如需要，更新基线。
+
+### 第 5 步：输出摘要
+
+- 更新/创建了哪些文档
+- 迁移脚本执行状态（已执行 / 待执行）
+- DDL 基线状态（已合并 / 待合并）
--- a/.cursor/skills/doc-sync/SKILL.md
+++ b/.cursor/skills/doc-sync/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: doc-sync
+description: /doc-sync — 逻辑改动后文档同步。从 Claude Code 命令迁移为 Cursor project skill；用户要求执行 doc-sync、/doc-sync 或相关流程时使用。
+disable-model-invocation: true
+---
+
+# /doc-sync — 逻辑改动后文档同步
+
+检查本次会话中的逻辑改动是否需要同步更新文档，并执行同步。
+
+## 触发条件
+
+修改了以下任一类内容时应执行：
+- 业务规则/计算口径/资金处理（精度、舍入、阈值）
+- ETL/SQL 清洗聚合映射逻辑
+- API 行为（返回结构、错误码、鉴权/权限）
+- 小程序关键交互流程
+- 数据库表结构
+
+## 执行步骤
+
+### 第 1 步：分类
+
+判断本次会话的改动是否属于"逻辑改动"。如果只是纯格式化/拼写修正/注释调整，告知用户"无逻辑改动，无需文档同步"并结束。
+
+### 第 2 步：逐项评估需要更新的文档
+
+根据变更涉及的模块，评估以下文档是否需要更新：
+
+**各级 README.md**（只更新与本次变更相关的）：
+- `README.md`（根目录）：项目总览、快速开始、环境变量、架构概述
+- `apps/backend/README.md`：后端 API 路由、配置、运行方式
+- `apps/etl/connectors/feiqiu/README.md`：ETL 任务清单、开发约定
+- `apps/miniprogram/README.md`：小程序页面结构
+- `apps/admin-web/README.md`：管理后台功能说明
+- `apps/tenant-admin/README.md`：租户管理后台功能说明
+- `packages/shared/README.md`：共享包说明
+- `db/README.md`：Schema 约定、迁移规范
+
+规则：如果"对读者理解系统行为有帮助"就应更新。若某个 README 尚不存在但变更涉及该模块，应创建。
+
+### 第 3 步：执行更新
+
+对每个需要更新的文档：
+1. 读取当前内容
+2. 根据本次变更更新相关段落
+3. 写入更新后的内容
+
+如果更新工作量大（>3 个文档），委托子代理处理。
+
+### 第 4 步：联动检查
+
+- 如果涉及 DB schema 变化：提醒用户执行 `/db-docs`
+- 如果涉及 API 变化：检查 `apps/backend/docs/API-REFERENCE.md` 是否已更新
+
+### 第 5 步：输出摘要
+
+- Changed：改了哪些文档
+- Why：原始原因 + 直接原因
+- Risk：风险点与回归范围
+- Verify：建议的验证步骤
--- a/.cursor/skills/pre-change/SKILL.md
+++ b/.cursor/skills/pre-change/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: pre-change
+description: /pre-change — 逻辑改动前置调研。从 Claude Code 命令迁移为 Cursor project skill；用户要求执行 pre-change、/pre-change 或相关流程时使用。
+disable-model-invocation: true
+---
+
+# /pre-change — 逻辑改动前置调研
+
+对即将修改的模块进行全面调研，输出上下文摘要供用户确认后再动手。
+
+## 适用场景
+
+任何逻辑改动（ETL/业务规则/API/数据模型/前端交互），写代码前执行。
+
+## 执行步骤
+
+### 第 1 步：识别改动范围
+
+从用户需求中提取：
+- 要修改的模块和文件
+- 涉及的数据表/API/页面
+- 预期的行为变化
+
+### 第 2 步：委托 Explore 子代理调研
+
+启动 Explore 子代理（thoroughness: very thorough），调研以下内容：
+
+1. **目标模块文件**：读取要修改的文件及其直接依赖
+2. **历史审计**：搜索 `docs/audit/changes/` 中相关模块的历史变更记录
+3. **相关文档**：README、PRD（`docs/prd/`）、BD 手册（`docs/database/`）、API 参考
+4. **调用关系**：要修改文件的调用方和被调用方
+5. **数据流向**：上游（数据从哪来）→ 当前模块 → 下游（数据到哪去）
+6. **影响范围**：哪些模块/页面/任务可能受影响
+
+### 第 3 步：输出「改动前上下文摘要」
+
+格式：
+
+```
+## 改动前上下文摘要
+
+### 模块职责
+<模块做什么，在系统中的角色>
+
+### 历史变更
+<近期审计记录中的相关改动，特别是踩坑记录>
+
+### 数据流向
+上游: <数据来源>
+当前: <本模块处理>
+下游: <消费方>
+
+### 影响范围
+- <受影响的模块/页面/任务列表>
+
+### 风险点
+- <可能的副作用、边界条件、兼容性问题>
+
+### 建议方案
+<基于调研结果的实施建议>
+```
+
+### 第 4 步：等待用户确认
+
+输出摘要后，等待用户确认或调整方向，确认后再进入编码实施。
+
+## 例外（无需执行此流程）
+
+- 纯格式调整、注释/文档纯文字修改
+- 用户明确说"直接改/跳过调研"
+- 新建文件且不涉及已有逻辑
--- a/.cursor/skills/spec-close/SKILL.md
+++ b/.cursor/skills/spec-close/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: spec-close
+description: /spec-close — Spec 收尾通用流程。从 Claude Code 命令迁移为 Cursor project skill；用户要求执行 spec-close、/spec-close 或相关流程时使用。
+disable-model-invocation: true
+---
+
+# /spec-close — Spec 收尾通用流程
+
+当一个功能 spec 开发完成时，执行此收尾检查清单确保质量闭环。
+
+## 执行步骤
+
+### 步骤 1：最终测试检查点（必选）
+
+- 运行 Monorepo 属性测试：`cd /c/NeoZQYY && pytest tests/ -v`
+- 运行模块单元测试：`cd <模块路径> && pytest tests/ -v`
+- 确保所有测试通过，有问题询问用户
+
+### 步骤 2：前后端联调验证（涉及 API + 前端时必选）
+
+- 启动后端服务，使用测试库验证各端点完整请求-响应链路
+- 验证 JSON 响应结构与 Schema 定义一致（camelCase 序列化）
+- 验证权限校验和数据隔离（`SET LOCAL app.current_site_id`）在真实请求中生效
+- 前端联调验证：确认前端页面能正确调用 API 并渲染数据
+- 验证空数据/降级场景下前端不崩溃
+
+### 步骤 3：数据库变更审计与 DDL 合并（涉及 DB 改动时必选）
+
+- 审计本次实现中对数据库的所有改动（新建表、新增字段、新增索引、FDW 映射变更等）
+- **必须通过 pg MCP 工具实际执行迁移 SQL**（禁止仅标记完成而不执行）
+- 执行后用查询验证表/字段/索引已正确创建
+- RLS 视图双 schema：后端查询 `app.v_*` 视图，新建 DWS RLS 视图时必须同时在原 schema 和 `app` schema 下创建
+- 合并到主 DDL 基线文件（ETL → `docs/database/ddl/etl_feiqiu__<schema>.sql`，业务 → `docs/database/ddl/zqyy_app__<schema>.sql`）
+- 编写回滚脚本（逆序 DROP/ALTER）
+
+### 步骤 4：BD 手册更新（涉及 DB 改动时必选）
+
+- 业务库 → `docs/database/BD_manual_*.md`
+- ETL 库 → `apps/etl/connectors/feiqiu/docs/database/<层级>/main/BD_manual_*.md`
+- FDW → `docs/database/BD_manual_fdw*.md`
+- 每份手册必须包含：字段明细、约束与索引、验证 SQL（≥3 条）、兼容性影响、回滚策略
+
+### 步骤 5：项目文档同步更新（按涉及范围裁剪）
+
+根据改动类型选择需要更新的文档：
+
+| 文档 | 更新条件 |
+|------|----------|
+| 模块 README | 模块内部结构变更时 |
+| `apps/backend/docs/API-REFERENCE.md` | 新增/修改后端路由时 |
+| `docs/contracts/openapi/backend-api.json` | 新增/修改 API 端点时 |
+| `docs/DOCUMENTATION-MAP.md` | 新增任何文档条目时 |
+
+### 步骤 6：变更审计收口（涉及高风险路径时必选）
+
+执行 `/audit` 命令完成审计流程。
+
+### 步骤 7：服务清理（启动了运行时服务时必选）
+
+- 关闭浏览器实例、停止后端和前端服务、清理资源
+
+## 按 Spec 类型裁剪
+
+| 类型 | 必选步骤 |
+|------|---------|
+| ETL 类（ODS/DWD/DWS） | 1, 3, 4, 5, 6 |
+| 后端 API 类 | 1, 2, 5, 6 |
+| 全栈类（前后端 + DB） | 1, 2, 3, 4, 5, 6 |
+| 重构类 | 1, 5, 6 |