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

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

AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md
+
+NeoZQYY Monorepo 顶层规则。子模块详细规范见各自 `apps/*/AGENTS.md`、`docs/database/`、`apps/etl/connectors/feiqiu/AGENTS.md`。
+
+## 语言（强制）
+
+始终中文：对话、解释、代码注释、commit message（中文描述 + 英文 Co-Authored-By 签名）、PR、审计、文档、错误日志。
+保持原文：变量/函数/类名、第三方 API 字段名、CLI 命令、技术术语。
+禁止英文段落或英文标题。
+
+## CLI / Shell 中文处理
+
+- Python `encoding="utf-8"` / `PYTHONUTF8=1`；CSV 给 Excel 用 `utf-8-sig`；PowerShell/Node 不依赖系统 ANSI。
+- 终端中文乱码时，不当作事实；先调编码重跑，或说明"终端编码异常，结果需复核"。
+- Shell 路径含中文/空格/特殊字符必须加引号；复杂中文输出走脚本或结构化 API。
+
+## 项目概览
+
+NeoZQYY = 台球门店全栈数据平台。多门店隔离（`site_id` + RLS），中文领域语言，CNY，金额 `numeric(2)`。
+
+| 目录 | 用途 |
+|------|------|
+| `apps/etl/connectors/feiqiu/` | 飞球 ETL：API → ODS → DWD → DWS |
+| `apps/backend/` | FastAPI（JWT 双认证 + WebSocket + AI） |
+| `apps/miniprogram/` | 微信小程序 C 端（Donut + TDesign） |
+| `apps/admin-web/` | 系统管理后台（开发/运维视角，操作 ETL 库） |
+| `apps/tenant-admin/` | 租户管理后台（门店管理员视角，操作业务库） |
+| `apps/demo-miniprogram/` | MOCK 标杆小程序（样式校对，禁改） |
+| `apps/mcp-server/` | MCP Server（PostgreSQL 只读） |
+| `packages/shared/` | 跨项目共享包 |
+| `db/` | DDL（`schemas/`）+ 迁移 + FDW |
+| `tools/` | 通用工具 |
+| `scripts/ops/` | 日常运维脚本 |
+
+技术栈：Python 3.10+ uv workspace、React+Vite+AntD、PostgreSQL 四库（`etl_feiqiu`/`test_etl_feiqiu`/`zqyy_app`/`test_zqyy_app`，DSN `PG_DSN`/`APP_DB_DSN`）。配置分层 `.env` < `.env.local` < env < CLI。
+
+## 数据库
+
+- 六层 Schema：`meta` → `ods` → `dwd` → `core` → `dws` → `app`（RLS 视图）
+- 跨库：`zqyy_app` 通过 FDW 只读映射 `etl_feiqiu.app`
+- RLS：`site_id` + `app.current_site_id` 会话变量
+- **RLS 双 Schema 踩坑**：DWS/DWD 表的 RLS 视图必须同时建在 `dws` 和 `app` schema，后端走 `app.v_*`。只建 `dws` 会让后端查询失败。回滚需逆序 DROP。
+
+## 飞球数据规范（速查）
+
+- `consume_money` 禁止直接计算 → 用 `items_sum` 拆分字段
+- 取数优先级：DWS > DWD > 禁止 ODS
+- 参考优先级：DWD-DOC > DWS 权威规范 > BD 手册 > ETL 任务文档 > DDL 注释
+- `_archived/` 目录禁止读取或参考
+- 完整规则见 `apps/etl/connectors/feiqiu/AGENTS.md`
+
+## 文件归属
+
+| 类型 | 位置 |
+|------|------|
+| 模块内文档/测试/脚本 | 模块内 `docs/`、`tests/`、`scripts/` |
+| 跨模块文档 | 根 `docs/` |
+| Monorepo 守护测试 | 根 `tests/` |
+| 日常运维脚本 | `scripts/ops/` |
+| 通用工具 | `tools/`（按类型分子目录） |
+| 审计记录 | 根 `docs/audit/changes/<YYYY-MM-DD>__<slug>.md`（禁止写子模块） |
+| 数据库文档 | 根 `docs/database/` |
+| 归档/待删 | `_DEL/`（保持原路径，定期清理） |
+
+`docs/audit/audit_dashboard.md` 由 `scripts/audit/gen_audit_dashboard.py` 生成，勿手动编辑。
+
+## 编码前需求审问（强制）
+
+新建功能/接口、重构、多模块联动、需求模糊时：
+1. 不立即动手，先提问循环（每轮 3-5 个问题）
+2. 必问：用户角色、核心操作、数据写入/展示/来源、错误/成功反馈、认证权限、存储（哪库/新表）、终端适配、边界（并发/幂等/超时）
+3. 输出「需求确认摘要」，用户确认后实施
+
+例外：用户说"直接改/跳过审问"、Bug 有明确复现步骤、纯格式调整、已有 spec
+
+## 逻辑改动前置调研（强制）
+
+任何逻辑改动（ETL/业务规则/API/数据模型/前端交互）：
+1. 委托 Explore 子代理调研：目标模块、`docs/audit/changes/` 历史、调用方/被调用方、数据流向、影响范围
+2. 输出「改动前上下文摘要」，用户确认后实施
+
+流程：需求审问 → 确认 → 前置调研 → 确认 → 编码
+
+例外：纯格式/注释/文档修改、用户说"直接改/跳过调研"、新建独立文件
+
+## 改动后验证（强制）
+
+1. 运行相关测试（单元/集成/lint），不能运行需说明原因
+2. 输出 diff 摘要（文件清单 + 每个改动要点）
+3. 列出未覆盖风险点（未测路径、副作用、需人工验证场景）
+
+例外：纯格式/文档/注释、用户说"跳过验证"
+
+## 数据库 Schema 变更
+
+修改 PostgreSQL schema（迁移/DDL/表定义/ORM）时，必须同步 `docs/database/`：变更说明、兼容性影响、回滚策略、≥3 条校验 SQL。
+
+## 测试环境
+
+1. `load_dotenv` 加根 `.env`；必需变量缺失立即报错，禁止静默回退空串
+2. cwd 与正式一致：ETL → `apps/etl/connectors/feiqiu/`、后端 → `apps/backend/`
+3. 配置走 `AppConfig.load()`，不得为测试构造简化配置
+4. 用测试库（`TEST_DB_DSN`），禁止连正式库
+5. 属性测试分组执行（`-k` 筛选），禁止一次性全跑；hypothesis 默认 `max_examples=100`
+
+例外：用户指定简化环境、纯单元测试用 FakeDB/FakeAPI、`--dry-run` CLI 验证
+
+## 脚本规范
+
+- 复杂操作写 Python 脚本，避免复杂 shell
+- 一次性运维 → `scripts/ops/`；模块专属 → 模块内 `scripts/`
+- `scripts/ops/` 不在 uv workspace 内，导入 ETL 纯函数用 `importlib.util` + stub（参考 `scripts/ops/backfill_finance_area_daily.py`）
+
+## 子代理
+
+- 委托：批量读 ≥3 文件、大范围搜索、不熟悉模块探索、多步 shell
+- 主流程直接处理：单文件、单命令、小范围精确搜索
+
+## 审计
+
+任何逻辑改动必须可追溯、可验证、可回滚。
+
+完成一轮后用 `/audit`：
+1. `python scripts/audit/prescan.py` 预扫描（自动识别+分类+合规，零 token）
+2. 补充语义上下文（从对话提取每变更原因）
+3. 委托子代理写 `docs/audit/changes/`
+4. 补齐文档同步
+5. `python scripts/audit/gen_audit_dashboard.py` 刷新一览表
+
+`prescan.py --files` 参数：git status 含大量历史未提交时，只传本次会话文件列表。