root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore(migration): Cursor → Claude Code 反向迁移 + 单轨化（v2）

Browse Source 
- 删除 5 个 AGENTS.md（根 + 4 子模块）与 .cursor/、.cursorignore，全部已备份
- 在 CLAUDE.md 末尾追加 5 节迁移必需内容（CLI/Shell 中文与编码、Claude Code 资产入口、Hook 与权限、不破坏原则、历史追溯），保留用户选定的 226 行项目规则全集
- 用户级 12 个 skills 从 ~/.cursor/skills/ 剥包装回迁到 ~/.claude/skills/（neozqyy-cursor-migration → neozqyy-claude-code-migration）
- docs/ai-env-history/ 顶层 10 文件入仓（含 conversation_index.csv、file_impact_index.csv，已脱敏）；sessions/ 原文继续本地保留
- 新增 tools/claude-code/migrate_ai_environment.py（--check 14/14 通过）
- 新增 docs/claude_code_migration.md 与 docs/audit/changes/2026-05-02__claude_code_migration.md
- .gitignore 调整：开放 2 个 CSV 索引入仓，保留 sessions/ 与 claude-history/ 排除
- 不混入 124 个业务变更（AI 模块重构、runtime_context、sandbox 等保持 unstaged）
- 备份位置：~/.claude/backups/pre-claude-code-migration-2026-05-02/

第二轮迁移（第一轮 commit 6facb2d 已被 git reset 回滚；本轮策略为追加而非重写 CLAUDE.md）
This commit is contained in:
Neo
2026-05-03 21:08:13 +08:00
parent 81e41730ec
commit f2e0de8fab
36 changed files with 15227 additions and 1041 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
apps/backend/AGENTS.md
View File

@@ -1,52 +0,0 @@
# AGENTS.md - Backend (FastAPI)
进入本目录时自动加载。
## 架构模式
### 全局响应包装
`ResponseWrapperMiddleware` 把所有 2xx 响应包为 `{ "code": 0, "data": <payload> }`。
非 2xx 响应保持原样。前端统一通过 `response.data` 解包。
### 序列化
`CamelModel` 基类：snake_case -> camelCase 自动转换（小程序 API 用）。
后端代码始终用 snake_case，JSON 输出自动转驼峰。
### JWT 双认证
| 认证方式 | 用途 | 表 | JWT aud |
|---------|------|-----|---------|
| 用户名+密码 | admin-web 登录 | `auth.admin_users` | `admin` |
| 微信 code | 小程序登录 | `auth.users` | `miniapp` |
| 用户名+密码 | tenant-admin 登录 | `auth.tenant_admins` | `tenant-admin` |
待审核用户有 limited token（仅可访问审核状态接口）。
### AI 集成
8 个千问应用通过 DashScope SDK：
chat / finance / clue / analysis / tactics / note / customer / consolidate
特性：熔断（连续失败自动断路）、限流（每分钟/每日）、预算追踪、对话缓存。
### 后台服务（lifespan）
- `TaskQueue`：按 site_id 消费，FIFO 队列
- `Scheduler`：读 `meta.scheduled_tasks` 自动入队
- 4 个触发器：日结/月结/工资/关系指数
### 数据库访问
- 业务库通过 `APP_DB_DSN` 直连 `zqyy_app`
- ETL 数据通过 FDW 映射的 `app.v_*` RLS 视图访问
- 查询前必须 `SET LOCAL app.current_site_id = :site_id`
## 测试
```bash
cd apps/backend && pytest tests/ -v
```
使用测试库（`TEST_APP_DB_DSN`），禁止连正式库。

18
apps/demo-miniprogram/AGENTS.md
View File

@@ -1,18 +0,0 @@
# AGENTS.md - demo-miniprogram
**禁止删除或移入 `_DEL/`。**
本目录是假数据 MOCK 版小程序，使用硬编码数据驱动所有页面，不连接后端 API。
## 用途
- 页面样式和展示格式的**标杆校对**：开发 `apps/miniprogram/` 时，以本目录的 UI 效果为参考基准
- 快速预览各页面在不同数据状态下的渲染效果，无需启动后端服务
## 与 miniprogram 的关系
| | `apps/miniprogram/` | `apps/demo-miniprogram/` |
|--|---------------------|--------------------------|
| 数据来源 | 后端 API | 硬编码假数据 |
| 用途 | 生产代码 | 样式参考 / UI 校对 |
| 可独立运行 | 需后端 | 可独立运行 |

81
apps/etl/connectors/feiqiu/AGENTS.md
View File

@@ -1,81 +0,0 @@
# AGENTS.md - ETL Feiqiu Connector
进入本目录时自动加载。包含 DWD 和 DWS 层的强制业务规则。
## DWD-DOC 标杆文档（权威数据源）
`docs/reports/DWD-DOC/` 是业务模型与财务数据的权威标杆文档。所有涉及金额口径、支付渠道、消费链路、账务公式、字段语义的开发工作，必须以此目录为第一参考源。
### 文档清单
| 文件 | 内容 | 关键规则 |
|------|------|----------|
| `01-business-panorama.md` | 消费链路 + 优惠机制 + 消费场景 | settle_type 枚举、助教费用拆分、团购券三层价格 |
| `02-accounting-panorama.md` | 支付渠道 + 对账公式 + consume_money 口径 | 支付渠道恒等式、F2 三期公式 |
| `03-financial-panorama.md` | 收入构成 + 储值卡资金流 + 对账矩阵 | 平台结算互斥关系 |
| `04-dimension-panorama.md` | 维度表与主数据全景 | SCD2 维度取值规则 |
| `05-f2-balance-audit.md` | F2 收支平衡公式专项 | 三期公式 + 139 笔失败根因 |
| `06-calibration-checklist.md` | 校准清单 + 验证 SQL | 全部验证公式集中 |
| `consume/consume-money-caliber.md` | consume_money 口径变化时间线 | 三种口径(A/B/C)定义与切换时间点 |
### DWD 强制规则（12 条）
1. **consume_money 禁止直接用于计算**：存在三种历史口径(A/B/C)混合，DWS 层及下游统一使用 `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`（`service_fee` 仅在平台结算表中表示"平台服务费"，语义不同）
3. **支付渠道恒等式**：`balance_amount = recharge_card_amount + gift_card_amount`（100% 成立），三者不可重复计算
4. **settle_type 过滤**：正向交易取 `IN (1, 3)`，本表无 `is_delete` 字段
5. **电费未启用**：`electricity_money` 全为 0，`gross_amount` 不含电费是正确的
6. **折扣互斥**：`discount_manual`（大客户优惠）与 `discount_other` 互斥，两者之和 = `adjust_amount`
7. **现金流互斥**：`cash_inflow_total` 中 `platform_settlement_amount` 和 `groupbuy_pay_amount` 互斥
8. **废单判断**：使用 `dwd_assistant_service_log_ex.is_trash`，`dwd_assistant_trash_event` 已废弃
9. **储值卡字段命名**：DWS 层使用 `balance_pay`/`recharge_card_pay`/`gift_card_pay`；财务日报用 `recharge_card_consume`
10. **会员字段断档（DQ-6）**：`settlement_head.member_phone/member_name` 自 2025-12 起全为 NULL -> 通过 `member_id` LEFT JOIN `dwd.dim_member`（`scd2_is_current=1`）
11. **会员卡字段断档（DQ-7）**：`settlement_head.member_card_type_name` 自 2025-07-21 起全为 NULL -> 通过 `member_id` LEFT JOIN `dwd.dim_member_card_account`（`scd2_is_current=1`）。通用规则：结算单上所有会员冗余字段均不可靠
12. **支付方式拆分（DQ-8）**：`dwd_settlement_head_ex.cash_amount`/`online_amount` 不可靠。正确来源是 `dwd_payment` 表：`payment_method=2` 现金，`payment_method=4` 扫码。通过 `relate_type=2` + `relate_id` 关联结算单
## DWS 层权威规范
> DWD 12 条在 DWS 层同样生效。冲突时以 DWD-DOC 为准。
### 幂等更新策略
- 汇总表默认 delete-before-insert（按日期范围 + site_id 先删后插）
- 库存表使用 upsert（`ON CONFLICT DO UPDATE`）
- 禁止 TRUNCATE
### 课程类型与定价
- 课程类型通过 `cfg_skill_type` 映射（`skill_id` -> `course_type_code`：BASE/BONUS/ROOM），禁止硬编码
- 定价通过 `cfg_assistant_level_price` 按 SCD2 生效期 as-of join，禁止硬编码价格
- 包厢课统一 138 元/小时（`dws.salary.room_course_price`）
### 绩效档位与工资
- 绩效档位通过 `cfg_performance_tier` 按有效业绩小时数匹配 `[min_hours, max_hours)` 区间
- 新入职折算：入职日期在当月 1 日后按日均 × 30 定档；> 25 日最高 T2
- 奖金通过 `cfg_bonus_rules`：SPRINT 不累计取最高档，TOP_RANK 按排名（1000/600/400 元）
- 排名使用 `calculate_rank_with_ties()`，相同业绩并列
### 会员与散客
- 散客：`member_id <= 0`，不计入会员统计（但计入助教业绩）
- 客户分层：高价值（90 天 >= 3 次且 >= 1000 元）-> 中等 -> 低活跃 -> 流失
- 会员信息一律通过 ID 关联维度表
### 时间窗口与调度
- 滚动窗口标准集：7/10/15/30/60/90 天
- 月度任务宽限期：月初前 5 天可处理上月数据
- 工资计算周期：月初前 5 天运行
### 指数参数
- 所有权重和阈值通过 `cfg_index_parameters` 按 `index_type`（WBI/NCI/RS/OS/MS/ML/SPI）加载，禁止硬编码
### 台桌分类
- `cfg_area_category` 仅精确匹配 + 兜底：BILLIARD/SNOOKER/OTHER。`BILLIARD_VIP` 已废弃
### 参考优先级
DWD-DOC > DWS 权威规范 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释