chore: 文档与 IDE 配置整理
- .kiro/specs/ → docs/specs/（41 个历史需求 spec 迁移，移除 .config.kiro） - CLAUDE.md 三层拆分：根文件精简 + apps/backend/CLAUDE.md + .claude/commands/ - 新增 /spec-close、/pre-change 两个工作流命令 - DDL 基线刷新（从测试库重新导出 11 个文件，dws 35→38 表，biz 18→21 表） - BD_Manual → BD_manual 命名统一（48 个文件） - 修复 3 处文档与数据库不一致（auth.users.status 默认值、scheduled_tasks 字段、RLS 视图数） - 新增 BD_manual_public_rbac_tables.md（public schema 8 张 RBAC/工作流表） - 合并 biz.trigger_jobs 文档（10→12 字段，归档独立文档） - docs/database/README.md 索引更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
72
CLAUDE.md
72
CLAUDE.md
@@ -1,6 +1,21 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
本文件为 Claude Code (claude.ai/code) 在本仓库工作时的指导规范。
|
||||
|
||||
## 语言（强制）
|
||||
|
||||
始终使用中文，覆盖所有场景：
|
||||
|
||||
- 对话回复、解释、提问、状态更新 → 中文
|
||||
- 代码注释 → 中文
|
||||
- Git commit message → 中文描述 + 英文 Co-Authored-By 签名行
|
||||
- PR 标题与正文 → 中文
|
||||
- 审计记录、文档、变更说明 → 中文
|
||||
- 错误提示、日志说明 → 中文
|
||||
- 变量名/函数名/类名 → 保持英文（编程惯例）
|
||||
- 第三方 API 字段名、CLI 命令 → 保持原文
|
||||
|
||||
禁止在回复中使用英文段落或英文标题（技术术语、代码片段、专有名词内嵌除外）。
|
||||
|
||||
## 项目概览
|
||||
|
||||
@@ -18,6 +33,8 @@ NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店
|
||||
| `apps/mcp-server/` | MCP Server（PostgreSQL 只读，AI 工具集成） |
|
||||
| `packages/shared/` | 跨项目共享包（enums, money, datetime_utils） |
|
||||
| `db/` | DDL / 迁移 / 种子数据 |
|
||||
| `tools/` | 通用工具（db/reporting/health/h5-to-mp-checker） |
|
||||
| `scripts/ops/` | 日常运维脚本（ETL 监控、数据回填、导出等） |
|
||||
|
||||
### 两个管理后台的区别
|
||||
|
||||
@@ -74,6 +91,8 @@ cd apps/miniprogram && npm test # 小程序 Jest
|
||||
|
||||
### ETL
|
||||
|
||||
> 完整规则见 `apps/etl/connectors/feiqiu/CLAUDE.md`
|
||||
|
||||
- 任务模式：继承 `BaseTask`（Extract → Transform → Load），在 `orchestration/task_registry.py` 注册
|
||||
- 加载器模式：每张目标表一个 Loader，`upsert()` + 冲突处理
|
||||
- SCD2 处理：`scd/` 模块
|
||||
@@ -81,11 +100,12 @@ cd apps/miniprogram && npm test # 小程序 Jest
|
||||
|
||||
### 后端
|
||||
|
||||
- 全局响应包装：`ResponseWrapperMiddleware` 把所有 2xx 响应包为 `{ "code": 0, "data": <payload> }`
|
||||
- `CamelModel` 基类：snake_case → camelCase 自动转换（小程序 API 用）
|
||||
- JWT 双认证：用户名密码（admin）+ 微信 code（小程序）；待审核用户有 limited token
|
||||
- AI 集成：8 个千问应用通过 DashScope SDK（chat/finance/clue/analysis/tactics/note/customer/consolidate），带熔断、限流、预算追踪
|
||||
- 后台服务（lifespan）：`TaskQueue`（按 site_id 消费）、`Scheduler`（读 scheduled_tasks 自动入队）、4 个触发器
|
||||
> 完整规则见 `apps/backend/CLAUDE.md`
|
||||
|
||||
- 全局响应包装：`ResponseWrapperMiddleware` → `{ "code": 0, "data": <payload> }`
|
||||
- JWT 双认证：admin（用户名密码）+ miniapp（微信 code）+ tenant-admin（用户名密码）
|
||||
- AI 集成：8 个千问应用（DashScope SDK），带熔断、限流、预算追踪
|
||||
- 后台服务：TaskQueue + Scheduler + 4 个触发器
|
||||
|
||||
## 文件归属规则
|
||||
|
||||
@@ -96,9 +116,11 @@ cd apps/miniprogram && npm test # 小程序 Jest
|
||||
| 只验证本模块逻辑的测试 | 模块内 `tests/` |
|
||||
| 守护 monorepo 结构/约定的测试 | 根 `tests/` |
|
||||
| 只操作本模块数据的脚本 | 模块内 `scripts/` |
|
||||
| 运维/全局工具脚本 | 根 `scripts/` |
|
||||
| 日常运维脚本（回填/导出/种子/初始化） | `scripts/ops/` |
|
||||
| 可复用通用工具（健康检查/数据库/报表/分析） | `tools/`（按类型分子目录） |
|
||||
| 审计记录（任何模块的变更） | 根 `docs/audit/` — 禁止写入子模块 |
|
||||
| 数据库文档（全局 schema 视角） | 根 `docs/database/` |
|
||||
| 归档/待删除内容 | `_DEL/`（保持原路径结构，用户定期手动清理） |
|
||||
|
||||
审计产物路径：
|
||||
- 变更记录：`docs/audit/changes/<YYYY-MM-DD>__<slug>.md`
|
||||
@@ -106,38 +128,12 @@ cd apps/miniprogram && npm test # 小程序 Jest
|
||||
|
||||
## 飞球数据规范
|
||||
|
||||
权威文档：`docs/reports/DWD-DOC/`（DWD 12 条）+ 同目录 DWS 权威规范。与 BD 手册、ETL 文档、DDL 注释冲突时以 DWD-DOC 为准。
|
||||
> 完整规则见 `apps/etl/connectors/feiqiu/CLAUDE.md`（进入 ETL 目录时自动加载）。
|
||||
|
||||
### 硬规则速查
|
||||
|
||||
1. `consume_money` 禁止直接计算 → 用 `items_sum = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money`
|
||||
2. 助教费用拆分：`assistant_pd_money`（陪打）+ `assistant_cx_money`（超休），禁止用 `service_fee` / `ASSISTANT_BASE` / `ASSISTANT_BONUS`
|
||||
3. 支付恒等式：`balance_amount = recharge_card_amount + gift_card_amount`，三者不可重复计算
|
||||
4. `settle_type` 过滤：正向交易 `IN (1, 3)`，本表无 `is_delete` 字段
|
||||
5. 会员信息通过 `member_id` JOIN 维度表（`scd2_is_current=1`），结算单冗余字段不可靠（DQ-6/DQ-7）
|
||||
6. 支付方式拆分来源是 `dwd_payment` 表（DQ-8）：`payment_method=2` 现金，`payment_method=4` 扫码。`dwd_settlement_head_ex.cash_amount/online_amount` 不可靠
|
||||
7. 散客：`member_id ≤ 0`，全链路过滤入口加 `member_id > 0`
|
||||
8. 课程类型/定价/绩效档位/奖金/指数权重 → 配置表读取，禁止硬编码
|
||||
9. DWS 汇总表 delete-before-insert，库存表 upsert
|
||||
10. 折扣互斥：`discount_manual` + `discount_other` = `adjust_amount`
|
||||
11. 现金流互斥：`platform_settlement_amount` 与 `groupbuy_pay_amount` 互斥
|
||||
12. 废单判断：`dwd_assistant_service_log_ex.is_trash`
|
||||
|
||||
### 取数优先级
|
||||
|
||||
DWS > DWD（明细+维度表）> 禁止 ODS（API 快照表，同一 id 有 100+ 行重复，JOIN 会行膨胀）
|
||||
|
||||
### 参考优先级
|
||||
|
||||
DWD-DOC > DWS 权威规范 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释
|
||||
|
||||
## 废弃对象黑名单（禁止引用）
|
||||
|
||||
- `dwd_assistant_trash_event` / `_ex`（2026-02-22 DROP）→ 用 `dwd_assistant_service_log_ex.is_trash`
|
||||
- `ods.assistant_cancellation_records`（2026-02-22）→ 无需独立链路
|
||||
- `ODS_ASSISTANT_ABOLISH` / `ASSISTANT_ABOLISH`（2026-02-22）→ 无
|
||||
- `BILLIARD_VIP`（2026-03-07）→ V1-V4 归 `BILLIARD`，V5 归 `SNOOKER`
|
||||
- `dws_member_recall_index` / `v_dws_member_recall_index`（2026-03-20）→ WBI + NCI
|
||||
**核心速查**：
|
||||
- `consume_money` 禁止直接计算 → 用 `items_sum` 拆分字段
|
||||
- 取数优先级：DWS > DWD > 禁止 ODS
|
||||
- 参考优先级：DWD-DOC > DWS 权威规范 > BD 手册 > ETL 任务文档 > DDL 注释
|
||||
- 所有 `_archived/` 目录禁止读取或参考
|
||||
|
||||
## 编码前需求审问（强制）
|
||||
|
||||
Reference in New Issue
Block a user