Neo
1e803e23cd
MP-2 经 4 轮调研 + Neo 反馈,采纳方案 C(推迟到 F1-6 沙箱时光机阶段 B): - 第 1 轮原方案 D(双口径) → 第 2 轮 D'(单口径) - 第 3 轮 Neo 架构纠正:不读 DWD,走 Core/DWS/app - 第 4 轮 DWS 视图靠谱性审计:dws_assistant_daily_detail 是计费明细 (ledger_amount),不是助教工资(gross_salary 需等级时薪 + 抽成 + 罚分),且缺 effective_hours / work_days - 结论:MP-2 真正实施需要新建 dws_assistant_daily_salary 表(ETL 改造),跟其他 14 个 P1 指标一起做更高效 → 推迟到 F1-6 本次 Wave B 只做 prep:DB schema + 模块 spec + tasks.md 状态调整。 DB 迁移(zqyy_app): - db/zqyy_app/migrations/20260505__add_effective_date_for_excel_adjustments.sql - 3 张 Excel 暂存表(全空,Neo 确认尚无 Excel 上传)ADD COLUMN effective_date DATE NOT NULL(无 DEFAULT,强制未来 Excel 上传必须带): * biz.salary_adjustments(助教薪资扣款/奖励) * biz.stg_finance_expense(月度支出) * biz.stg_platform_income(平台结算收入) - 3 个复合索引 (site_id, effective_date) 支持后续 daily 截断查询 - biz.stg_recharge_commission 已有 recharge_date,无需改造 测试库执行 + 5/5 校验 PASS: - 字段存在(NOT NULL DATE 无 default) - 复合索引存在 + 列序正确 - 字段注释含 'F1-5b MP-2 prep' - INSERT 不带 effective_date 触发 NotNullViolation docs/database/ 同步: - docs/database/changes/2026-05-05__add_effective_date_for_excel_adjustments.md 完整变更说明 + 兼容性 + 回滚 + 5 条校验 SQL + 正式库执行说明 沙箱时光机模块 spec(主干任务排期登记): - docs/_overview/sandbox-replay-engine-spec.md - 22 个相关指标分 P1/P2/P3 优先级: * P1 14 项(daily 视图已有,后端切换) * P2 5 项(算法重算,含 MP-2 完整 daily salary) * P3 3 项(状态算法 + sandbox_audit_log 用户行为) - 4 阶段实施路径: * 阶段 0(本次 prep) * 阶段 A(F1-5a/b 已完成) * 阶段 B(F1-6,2-3 周)— MP-2 真正实施在此 * 阶段 C(F1-7+,1-2 周) - sandbox_replay 模块结构 + runtime_aware decorator 接口契约 - 性能 + 测试 + 前置依赖清单 F1-5b-tasks.md 状态调整: - §4.3 顺序 15:MP-2 从"待开始/C4" → "延期 F1-6" - §6 进度表 MP-2 行同步标"延期 F1-6 + 改方向说明" - 关联到 mp2_prep.md 审计 业务影响: - board-coach sandbox 行为暂遗留(F1-6 解决) - 旧 Excel 模板上传将因 NOT NULL 失败,需 F1-6 同期 ETL UI 改造 + 操作员培训 - 跨页面已 audit:board-finance / customer-records / coach-service-records / customer-service-records 等已合规(F1-5b A1/A3 + MP-1/3/5 收益) 审计:docs/audit/changes/2026-05-05__wave1_f1_5b_mp2_prep.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
NeoZQYY Monorepo
台球门店运营助手一体化平台，整合 ETL 数据 Connector、微信小程序后端、小程序前端与管理后台。
项目结构
| 目录 | 说明 | 文档 |
|---|---|---|
apps/etl/connectors/feiqiu/ |
飞球 Connector（API → ODS → DWD → DWS） | docs/ |
apps/backend/ |
FastAPI 后端（13 个路由 · JWT 双认证 · WebSocket） | README · API 参考 |
apps/miniprogram/ |
微信小程序（Donut + TDesign + TypeScript） | README |
apps/admin-web/ |
管理后台（React + Vite + Ant Design） | README |
apps/mcp-server/ |
MCP Server（AI 工具集成，PostgreSQL 只读查询） | README |
packages/shared/ |
共享包（枚举、金额精度、时间工具） | README |
db/etl_feiqiu/ |
ETL 数据库（6 层 Schema：meta/ods/dwd/core/dws/app） | README |
db/zqyy_app/ |
业务数据库（auth 认证 + 任务队列 + 调度） | README |
docs/ |
项目文档中心（架构、数据库、部署、审计） | README |
scripts/ |
运维/工具脚本 | — |
tests/ |
Monorepo 级属性测试 | — |
快速开始
# 安装全部依赖（需要 uv）
uv sync
# 运行 ETL
cd apps/etl/connectors/feiqiu
python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"
# 启动后端 API
cd apps/backend
uvicorn app.main:app --reload
# 运行 ETL 单元测试
cd apps/etl/connectors/feiqiu
pytest tests/unit
配置
配置采用分层叠加：根 .env -> 应用 .env.local -> 环境变量 -> CLI 参数。
参见 .env.template 了解可用配置项。
技术栈
- Python 3.10+, uv workspace（4 个成员：etl、backend、mcp-server、shared）
- PostgreSQL 四库：
etl_feiqiu/test_etl_feiqiu（ETL）、zqyy_app/test_zqyy_app（业务） - FastAPI + Uvicorn（后端 API）
- React 19 + Vite 6 + Ant Design 5（管理后台，独立 pnpm）
- 微信小程序原生 + Donut + TDesign + TypeScript（C 端）
- JWT 双认证（管理后台用户名密码 + 小程序微信登录）
- 多门店隔离（
site_id+ RLS）