chore(migration): CLAUDE.md 去重精简（v3）

减少根 CLAUDE.md 每次会话 token 消耗：267 行 → 211 行（-21%）/ 14.4KB → 12.5KB（-13%）。预计每次会话节省 ~700 tokens。精简项： - 删除 ## 常用命令整节（IDE 用户不直接用 CLI；命令存在于子模块 CLAUDE.md / package.json / pyproject.toml） - 删除 ## 已废弃整节（git 历史可考古） - 精简 ## 架构模式：4 个子节合并为顶层概要 + 子模块 pointer；保留 RLS 双 schema 关键规则（高频踩坑） - 精简 ## 数据库 Schema 变更规则（要点 + pointer 到 db/CLAUDE.md） - 合并 ## 项目概览中"两个管理后台的区别"到子系统表注脚新增： - ## Claude Code 资产入口下添加"子模块 CLAUDE.md（按需自动加载，避免在根级重复）"导航表不动（核心强制规则）： - 语言、CLI/Shell 编码、3 段工作流（审问/调研/验证）、测试环境、脚本规范、子代理、审计、资产入口、Hook、不破坏原则、历史追溯 - 飞球 4 条速查（高频陷阱，全局都要知道）校验：python tools/claude-code/migrate_ai_environment.py --check → 14/14
2026-05-03 21:15:22 +08:00
parent f2e0de8fab
commit 2010034840
1 changed files with 19 additions and 75 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,8 +39,8 @@ NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店
 | `apps/etl/connectors/feiqiu/` | 飞球 Connector：API → ODS → DWD → DWS |
 | `apps/backend/` | FastAPI 后端（JWT 双认证、WebSocket、AI 集成） |
 | `apps/miniprogram/` | 微信小程序（C 端，Donut + TDesign） |
-| `apps/admin-web/` | 系统管理后台（React+Vite+AntD）— 开发/运维视角，操作 ETL 库 |
-| `apps/tenant-admin/` | 租户管理后台（React+Vite+AntD）— 门店管理员视角，操作业务库 |
+| `apps/admin-web/` | 系统管理后台（开发/运维视角，操作 ETL 库；ETL 配置 / 数据质量 / 系统监控） |
+| `apps/tenant-admin/` | 租户管理后台（门店管理员 `site_admin`/`tenant_admin`；用户审核 / Excel 上传 / 维客线索，门店隔离视角） |
 | `apps/mcp-server/` | MCP Server（PostgreSQL 只读，AI 工具集成） |
 | `packages/shared/` | 跨项目共享包（enums, money, datetime_utils） |
 | `apps/demo-miniprogram/` | MOCK 小程序（假数据驱动，页面样式/展示格式标杆校对） |
@@ -48,11 +48,6 @@ NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店
 | `tools/` | 通用工具（db/reporting/health/h5-to-mp-checker） |
 | `scripts/ops/` | 日常运维脚本（ETL 监控、数据回填、导出等） |

-### 两个管理后台的区别
-
- `admin-web`：开发/运维用，ETL 配置、数据质量、系统监控，全局视角
- `tenant-admin`：门店管理员用（`site_admin`/`tenant_admin`），用户审核/管理、Excel 上传、维客线索，门店隔离视角
-
 ## 技术栈

 - Python 3.10+，uv workspace（4 成员：etl/connectors/feiqiu、backend、mcp-server、shared）
@@ -61,63 +56,14 @@ NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店
 - DSN：`PG_DSN`（ETL）、`APP_DB_DSN`（业务），根 `.env` 定义
 - 配置分层：`.env` < `.env.local` < 环境变量 < CLI 参数

-## 常用命令
+## 架构模式（顶层）

-```bash
-# 依赖安装
-uv sync                              # Python 全量安装
-cd apps/admin-web && pnpm install    # 前端（admin-web / tenant-admin 各自独立）
-
-# 开发服务器
-cd apps/backend && uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
-cd apps/admin-web && pnpm dev        # port 5173
-cd apps/tenant-admin && pnpm dev
-
-# ETL
-cd apps/etl/connectors/feiqiu
-python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
-python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"
-
-# 测试
-cd apps/etl/connectors/feiqiu && pytest tests/unit         # ETL 单元测试
-cd apps/etl/connectors/feiqiu && pytest tests/integration --with-db  # ETL 集成测试
-cd apps/backend && pytest tests/                           # 后端测试
-cd /c/NeoZQYY && pytest tests/ -v                          # Monorepo 属性测试（hypothesis）
-cd apps/admin-web && pnpm test                             # 前端 Vitest
-cd apps/admin-web && pnpm e2e                              # Playwright e2e
-cd apps/admin-web && pnpm lint                             # TypeScript 检查
-cd apps/miniprogram && npm test                            # 小程序 Jest
-```
-
-## 架构模式
-
-### 数据库
-
- 六层 Schema：`meta` → `ods`（原始）→ `dwd`（规范化）→ `core`（聚合）→ `dws`（业务汇总）→ `app`（RLS 视图）
- 跨库访问：`zqyy_app` 通过 FDW 只读映射 `etl_feiqiu.app` schema
- 多门店隔离：`site_id` + RLS，`app` schema 视图层通过 `app.current_site_id` 会话变量过滤
-
-### RLS 视图双 Schema 规则（踩坑 2026-03-29）
-
-新建 DWS/DWD 表的 RLS 视图必须同时在原 schema（如 `dws`）和 `app` schema 创建。后端通过 `app.v_*` 访问。只在 `dws` 创建会导致后端查询失败。迁移模板：先 `CREATE VIEW dws.v_xxx`，再 `CREATE VIEW app.v_xxx`，WHERE 条件相同。回滚需逆序 DROP。
-
-### ETL
-
-> 完整规则见 `apps/etl/connectors/feiqiu/CLAUDE.md`
-
- 任务模式：继承 `BaseTask`（Extract → Transform → Load），在 `orchestration/task_registry.py` 注册
- 加载器模式：每张目标表一个 Loader，`upsert()` + 冲突处理
- SCD2 处理：`scd/` 模块
- Flow：`--pipeline` 参数指定（如 `api_full`）
-
-### 后端
-
-> 完整规则见 `apps/backend/CLAUDE.md`
-
- 全局响应包装：`ResponseWrapperMiddleware` → `{ "code": 0, "data": <payload> }`
- JWT 双认证：admin（用户名密码）+ miniapp（微信 code）+ tenant-admin（用户名密码）
- AI 集成：8 个千问应用（DashScope SDK），带熔断、限流、预算追踪
- 后台服务：TaskQueue + Scheduler + 4 个触发器
+- **数据库六层 Schema**：`meta` → `ods` → `dwd` → `core` → `dws` → `app`（RLS 视图）；`zqyy_app` 通过 FDW 只读映射 `etl_feiqiu.app`；多门店通过 `site_id` + `app.current_site_id` 会话变量过滤
+- **RLS 双 Schema 强制规则（踩坑 2026-03-29）**：新建 DWS/DWD 表的 RLS 视图必须**同时**在原 schema（如 `dws`）和 `app` schema 创建。后端走 `app.v_*`。只在 `dws` 创建会让后端查询失败；回滚需逆序 DROP
+- 详细子模块架构（响应包装、JWT、AI 集成、ETL Loader/SCD2/Flow、DDL）见对应 `CLAUDE.md`（自动加载）：
+  - `apps/backend/CLAUDE.md` — FastAPI 后端
+  - `apps/etl/connectors/feiqiu/CLAUDE.md` — 飞球 ETL（含 12 条 DWD 强制规则）
+  - `db/CLAUDE.md` — DDL / 迁移 / RLS 双 schema 模板

 ## 文件归属规则

@@ -178,11 +124,7 @@ cd apps/miniprogram && npm test                            # 小程序 Jest

 ## 数据库 Schema 变更规则

-修改任何影响 PostgreSQL schema 的内容（迁移/DDL/表定义/ORM 模型）时，必须同步更新 `docs/database/`：
- 变更说明：新增/修改/删除的表、字段、约束、索引
- 兼容性：对 ETL、后端 API、小程序字段映射的影响
- 回滚策略：如何撤销
- 验证步骤：至少 3 条校验 SQL
+修改 PostgreSQL schema（迁移/DDL/表/ORM）时**必须**同步 `docs/database/`：变更说明 + 兼容性影响（ETL/后端/小程序）+ 回滚策略 + ≥3 条校验 SQL。详细模板见 `db/CLAUDE.md`。

 ## 测试与验证环境规范

@@ -218,13 +160,6 @@ cd apps/miniprogram && npm test                            # 小程序 Jest

 预扫描脚本支持 `--files` 参数：当 git status 包含大量历史未提交变更时，可只传入本次会话涉及的文件列表。

-已废弃（不再使用）：
-
- Prompt-ID 溯源、`docs/audit/prompt_logs/` — Claude Code 原生 session 日志已覆盖
- AI_CHANGELOG 文件内标记 — git blame 替代
- CHANGE 块级代码标记 — git blame 替代
- Session 日志 (`docs/audit/session_logs/`) — Claude Code 原生 session 存储已覆盖
-
 ## Claude Code 资产入口

 | 资产 | 位置 |
@@ -238,6 +173,15 @@ cd apps/miniprogram && npm test                            # 小程序 Jest
 | 用户级 rules（自动加载） | `~/.claude/rules/{python,typescript,web,zh}/` |
 | 自动记忆 | `~/.claude/projects/c--Project-NeoZQYY/memory/` |

+### 子模块 CLAUDE.md（按需自动加载，避免在根级重复）
+
+| 子模块 | CLAUDE.md 内容 |
+|------|------|
+| `apps/backend/` | FastAPI 全局响应包装、CamelModel、JWT 三类 aud、AI 集成、TaskQueue/Scheduler、FDW 访问 |
+| `apps/etl/connectors/feiqiu/` | DWD-DOC 标杆、12 条 DWD 强制规则、DWS 权威规范（幂等/课程定价/绩效/会员分层/调度窗口/指数参数/台桌分类） |
+| `apps/demo-miniprogram/` | MOCK 标杆禁改、UI 校对基准、与 `apps/miniprogram/` 关系 |
+| `db/` | Schema 变更模板、RLS 双 schema 模板、目录结构、DDL 刷新、测试规范 |
+
 ## Hook 与权限

 项目已注册的 hooks（见 `.claude/settings.json`）：