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

Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/hooks.json

@@ -0,0 +1,45 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": ".venv\\Scripts\\python.exe .cursor\\hooks\\ai_env_guard.py preToolUse",
+        "matcher": "Read|Glob|Edit|Write|ApplyPatch",
+        "timeout": 5,
+        "failClosed": true
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": ".venv\\Scripts\\python.exe .cursor\\hooks\\ai_env_guard.py beforeReadFile",
+        "matcher": "_archived",
+        "timeout": 5,
+        "failClosed": true
+      }
+    ],
+    "beforeMCPExecution": [
+      {
+        "command": ".venv\\Scripts\\python.exe .cursor\\hooks\\ai_env_guard.py beforeMCPExecution",
+        "matcher": "pg-etl|pg-app",
+        "timeout": 5,
+        "failClosed": false
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": ".venv\\Scripts\\python.exe .cursor\\hooks\\ai_env_guard.py beforeShellExecution",
+        "matcher": "git\\s+(reset|checkout)|--no-verify|psql|mcp-postgres|PG_DSN|APP_DB_DSN",
+        "timeout": 5,
+        "failClosed": false
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": ".venv\\Scripts\\python.exe .cursor\\hooks\\ai_env_guard.py postToolUse",
+        "matcher": "ApplyPatch|Edit|Write",
+        "timeout": 5,
+        "failClosed": false
+      }
+    ]
+  }
+}

.cursor/hooks/ai_env_guard.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+ARCHIVED_RE = re.compile(r"(^|[/\\])_archived([/\\]|$)", re.IGNORECASE)
+PROD_MCP_RE = re.compile(r"\b(pg-etl|pg-app)\b", re.IGNORECASE)
+TEST_MCP_RE = re.compile(r"\b(pg-etl-test|pg-app-test)\b", re.IGNORECASE)
+WRITE_SQL_RE = re.compile(
+    r"\b(insert|update|delete|truncate|drop|alter|create|grant|revoke|merge|copy|call|vacuum|reindex)\b",
+    re.IGNORECASE,
+)
+
+
+def load_input() -> dict:
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return {}
+
+
+def target_text(data: dict) -> str:
+    chunks = [json.dumps(data, ensure_ascii=False)]
+    for key in ("command", "file_path", "path"):
+        value = data.get(key)
+        if isinstance(value, str):
+            chunks.append(value)
+    tool_input = data.get("tool_input")
+    if isinstance(tool_input, dict):
+        chunks.append(json.dumps(tool_input, ensure_ascii=False))
+    return "\n".join(chunks)
+
+
+def allow() -> None:
+    print(json.dumps({"permission": "allow"}, ensure_ascii=False))
+
+
+def before_shell(data: dict) -> None:
+    text = target_text(data)
+    dangerous = [
+        r"git\s+reset\s+--hard",
+        r"git\s+checkout\s+--",
+        r"--no-verify",
+        r"\bPG_DSN\b",
+        r"\bAPP_DB_DSN\b",
+        r"\bpsql\b",
+    ]
+    if any(re.search(pattern, text, re.IGNORECASE) for pattern in dangerous):
+        print(json.dumps({
+            "permission": "ask",
+            "user_message": "命令命中 NeoZQYY 高风险规则：请确认是否需要执行。",
+            "agent_message": "执行前说明风险、目标库/文件、回滚方式；生产库默认不执行。",
+        }, ensure_ascii=False))
+        return
+    allow()
+
+
+def guard_archived(data: dict) -> None:
+    text = target_text(data)
+    if ARCHIVED_RE.search(text):
+        print(json.dumps({
+            "permission": "deny",
+            "user_message": "已阻断：`_archived/` 是废弃归档目录，禁止读取、搜索或作为实现参考。",
+            "agent_message": "改用当前版本文件；如确需考古，请让用户明确授权并说明目的。",
+        }, ensure_ascii=False))
+        return
+    allow()
+
+
+def before_mcp(data: dict) -> None:
+    text = target_text(data)
+    if not PROD_MCP_RE.search(text) or TEST_MCP_RE.search(text):
+        allow()
+        return
+    if WRITE_SQL_RE.search(text):
+        print(json.dumps({
+            "permission": "deny",
+            "user_message": "已阻断：生产库 MCP 写入/DDL 类操作默认禁止。请改用测试库验证，或让用户给出单次明确授权。",
+            "agent_message": "生产库仅允许人工确认后的只读排查；DDL/写入需走单独变更流程。",
+        }, ensure_ascii=False))
+        return
+    print(json.dumps({
+        "permission": "ask",
+        "user_message": "检测到生产库 MCP 只读调用。请确认本次查询目的、SQL 是否只读、是否会暴露敏感数据。",
+        "agent_message": "说明查询目的、目标库、SQL 摘要和风险后等待用户确认。",
+    }, ensure_ascii=False))
+
+
+def post_tool_use(data: dict) -> None:
+    text = target_text(data).replace("\\", "/")
+    hints = []
+    if "/_archived/" in text or text.endswith("/_archived"):
+        hints.append("检测到 `_archived/` 路径：该目录内容已废弃，禁止作为实现参考。")
+    if "apps/demo-miniprogram/" in text:
+        hints.append("检测到 demo-miniprogram：这是 MOCK 标杆目录，修改前需确认目的。")
+    if re.search(r"(db/|docs/database/|migrations/|schemas/)", text):
+        hints.append("检测到数据库相关改动：如影响 schema，需同步 `docs/database/` 并提供 3 条验证 SQL。")
+    if re.search(r"(apps/backend/|apps/etl/|app/ai/|prompts/)", text):
+        hints.append("检测到后端/ETL/AI 逻辑改动：完成后需运行相关测试并写审计记录。")
+    if hints:
+        print(json.dumps({"additional_context": "\n".join(f"[NeoZQYY] {hint}" for hint in hints)}, ensure_ascii=False))
+
+
+def main() -> None:
+    mode = sys.argv[1] if len(sys.argv) > 1 else ""
+    data = load_input()
+    if mode in {"preToolUse", "beforeReadFile"}:
+        guard_archived(data)
+    elif mode == "beforeMCPExecution":
+        before_mcp(data)
+    elif mode == "beforeShellExecution":
+        before_shell(data)
+    elif mode == "postToolUse":
+        post_tool_use(data)
+
+
+if __name__ == "__main__":
+    main()

.cursor/rules/admin-web.mdc

@@ -0,0 +1,12 @@
+---
+description: admin-web 规则：React/Vite/AntD、AI 管理套件与前端验证。
+globs: apps/admin-web/**
+alwaysApply: false
+---
+
+# admin-web 规则
+
+- `admin-web` 是开发/运维后台，不是租户后台。
+- 遵循 React + Vite + Ant Design 现有页面和 API 封装风格。
+- AI 管理相关改动先查 2026-04-21、2026-04-30 审计记录。
+- 前端逻辑改动后优先运行 `pnpm test` / `pnpm lint`，无法运行需说明原因。

.cursor/rules/audit-history.mdc

@@ -0,0 +1,11 @@
+---
+description: 历史追溯规则：优先使用精简索引、审计记录和当前代码。
+globs: docs/**
+alwaysApply: false
+---
+
+# 历史追溯规则
+
+- 日常追溯先查 `docs/ai-env-history/README.md`、`docs/claude-history/`、`docs/audit/changes/`。
+- 历史摘要只解释来龙去脉，编码前仍以当前文件、当前 diff、当前测试为准。
+- 原始 JSONL 可用于追查细节，但不要把密钥、DSN、token 原文写入仓库文档。

.cursor/rules/backend-fastapi.mdc

@@ -0,0 +1,14 @@
+---
+description: FastAPI 后端规则：响应包装、认证、AI 集成、RLS 与测试库。
+globs: apps/backend/**
+alwaysApply: false
+---
+
+# 后端规则
+
+- 2xx 响应经 `ResponseWrapperMiddleware` 包装为 `{ "code": 0, "data": <payload> }`。
+- 后端内部使用 snake_case，JSON 输出通过 `CamelModel` 转 camelCase。
+- admin、miniapp、tenant-admin 三类 JWT aud 不可混用。
+- 访问 ETL FDW/RLS 视图前必须设置 `app.current_site_id`。
+- AI 集成涉及 DashScope、熔断、限流、预算、缓存和运行日志，改动后必须查审计历史。
+- 后端验证默认在 `apps/backend` 下运行，使用测试库，禁止连正式库。

.cursor/rules/database.mdc

@@ -0,0 +1,13 @@
+---
+description: 数据库规则：schema 变更、RLS 双 schema、文档同步和验证 SQL。
+globs: db/**,docs/database/**
+alwaysApply: false
+---
+
+# 数据库规则
+
+- 任何 PostgreSQL schema/迁移/DDL/ORM 结构变更必须同步 `docs/database/`。
+- 新建 DWS/DWD RLS 视图必须同时创建原 schema 和 `app` schema 视图。
+- 回滚需逆序 DROP/ALTER，并提供至少 3 条验证 SQL。
+- 默认使用 `TEST_DB_DSN` / `TEST_APP_DB_DSN`，禁止连正式库。
+- DDL 基线变更后运行 `tools/db/gen_consolidated_ddl.py` 并同步权威 DDL。

.cursor/rules/demo-miniprogram-protect.mdc

@@ -0,0 +1,11 @@
+---
+description: demo-miniprogram 保护规则：假数据标杆，不删除不迁移到 _DEL。
+globs: apps/demo-miniprogram/**
+alwaysApply: false
+---
+
+# demo-miniprogram 保护
+
+- 本目录是假数据 MOCK 版小程序，用于页面样式和展示格式标杆校对。
+- 禁止删除、移入 `_DEL/` 或改造成真实 API 驱动。
+- 只有在用户明确要求校正 demo 标杆时才修改。

.cursor/rules/etl-feiqiu.mdc

@@ -0,0 +1,14 @@
+---
+description: 飞球 ETL 规则：DWD-DOC 优先、金额口径、DWS 优先、禁止归档目录。
+globs: apps/etl/connectors/feiqiu/**
+alwaysApply: false
+---
+
+# ETL 飞球规则
+
+- 金额、支付、消费链路、字段语义优先参考 `apps/etl/connectors/feiqiu/docs/reports/DWD-DOC/`。
+- `consume_money` 禁止直接用于计算，使用 `items_sum` 拆分字段。
+- 助教费用必须区分 `assistant_pd_money` 和 `assistant_cx_money`。
+- 正向结算使用 `settle_type IN (1, 3)`，禁止随意读取 ODS 做业务计算。
+- DWS/DWD 汇总默认保持幂等，禁止 `TRUNCATE`。
+- 所有 `_archived/` 目录禁止读取或参考。

.cursor/rules/miniprogram.mdc

@@ -0,0 +1,12 @@
+---
+description: 微信小程序规则：生产小程序、Donut/TDesign、demo 标杆对齐。
+globs: apps/miniprogram/**
+alwaysApply: false
+---
+
+# 小程序规则
+
+- `apps/miniprogram` 是生产小程序，数据来自后端 API。
+- UI 样式和展示格式需要参考 `apps/demo-miniprogram` 的 MOCK 标杆。
+- 改动关键交互、鉴权、API 字段或页面跳转后必须说明验证路径。
+- 涉及微信开发者工具时优先使用 `weixin-devtools-mcp` 或记录手工验证步骤。

.cursor/rules/neozqyy-core.mdc

@@ -0,0 +1,18 @@
+---
+description: NeoZQYY 核心工作规范：中文、调研、验证、审计、dirty tree 保护。
+alwaysApply: true
+---
+
+# NeoZQYY 核心规范
+
+- 始终使用中文交流、解释、审计和文档；命令、API 字段、变量名保持原文。
+- 以 `AGENTS.md` 为权威规则；历史 `CLAUDE.md` 已并入 `AGENTS.md`，需考古时查 git 历史或 `docs/ai-env-history/`。
+- 逻辑改动前先做需求审问和前置调研；用户明确跳过时除外。
+- 逻辑改动后运行相关验证，输出 diff 摘要和未覆盖风险。
+- 不回滚用户已有改动，不使用破坏性 git 命令，除非用户明确要求。
+- 审计记录统一写入 `docs/audit/changes/`，`docs/audit/audit_dashboard.md` 只由脚本生成。
+- 历史追溯优先查 `docs/ai-env-history/`、`docs/claude-history/`、`docs/audit/`，再查原始对话。
+- 用户偏好模型为 GPT 5.5 与 Claude 4.7；模型选择由 Cursor UI/会话设置控制，规则只保留偏好。
+- CLI / Shell 中文处理必须优先确保 UTF-8：Python 用 `encoding="utf-8"` / `PYTHONUTF8=1`，CSV 给 Excel 用 `utf-8-sig`，PowerShell/Node 避免依赖系统默认 ANSI 编码。
+- 遇到中文乱码时，不要把乱码输出当作事实；先调整编码重跑，或明确说明终端编码异常并转述可确认的信息。
+- Shell 路径和参数含中文、空格或特殊字符时必须正确加引号；复杂中文输出优先用脚本或结构化 API，避免手写脆弱转义。

.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"）

.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 基线状态（已合并 / 待合并）

.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：建议的验证步骤

.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 步：等待用户确认
+
+输出摘要后，等待用户确认或调整方向，确认后再进入编码实施。
+
+## 例外（无需执行此流程）
+
+- 纯格式调整、注释/文档纯文字修改
+- 用户明确说"直接改/跳过调研"
+- 新建文件且不涉及已有逻辑

.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 |