Neo
9f1e35d71a
F1-5b 完成后启动 F1-6 沙箱时光机阶段 B,Sprint 1 范围: 1. 建立 sandbox_replay 模块脚手架 2. 实现 @runtime_aware decorator(自动注入 RuntimeContext) 3. 试点迁移 1 个指标:get_last_visit_days(P1-4 距上次到店天数) 4. MCP 端到端 4a/4b 双口径走查 新增文件: - apps/backend/app/services/sandbox_replay/__init__.py(模块入口 + re-export) - apps/backend/app/services/sandbox_replay/_decorator.py(@runtime_aware 实现) - apps/backend/app/services/sandbox_replay/consumption_replay.py(get_last_visit_days 试点) - docs/_overview/wave1-findings/F1-6-tasks.md(F1-6 任务清单 4 个 sprint) - docs/audit/changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md(Sprint 1 审计) 修改: - apps/backend/app/services/fdw_queries.py:218-238 get_last_visit_days 改 thin wrapper,委托 sandbox_replay.consumption_replay 保持 75+ 现有调用点无感兼容 关键 bug 修复:@trace_service + @runtime_aware 嵌套 sig.bind 失败 - 现象:仅 FastAPI 请求 + 有活跃 TraceContext 时复现 (直接 Python 脚本 get_current_trace 返回 None,跳过 _build_params_dict) - 根因:functools.wraps 设置 __wrapped__ 让 inspect.signature 追溯原函数 → bind 时缺 keyword-only 必传 ctx → TypeError - 修复:_decorator.py 不用 functools.wraps,手动复制元信息但不设 __wrapped__,inspect.signature 看到 wrapper 自身 (*args, **kwargs) 测试: - unit test 10/10 PASS(本地 .gitignore:71 不入仓) - 直接 customer_service.get_customer_detail PASS(独立诊断脚本) - etl_conn 复用模式 PASS MCP 双口径(member=2799207087163141 黄先生): - 4a live (today=2026-05-05): daysSinceVisit=32(05-05 - 04-03) - 4b sandbox=2026-04-20: daysSinceVisit=31(04-20 - 03-20) 通过插 walkthrough 测试快照 stat_date=2026-04-15 演示 (测试库 dws_member_consumption_summary 仅 stat_date=2026-05-01 一行, sandbox=4-20 时被视图层 stat_date <= business_date_now() 过滤) - 测试快照已清理,sandbox 已切回 live Sprint 2-4 待启动(见 F1-6-tasks.md): - Sprint 2:5 个会员 P1 指标(余额/60d 消费/累计交易/GMV/累计服务客户数) - Sprint 3:5 个助教/门店 P1 + MP-2 完整(含 ETL 改造) - Sprint 4:5 个 P2 算法重算指标 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）