root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
81 Commits 3 Branches 0 Tags
2dfc926f96681f7e054b01016b15266b3e3ee0ab
Commit Graph

44 Commits

Author SHA1 Message Date
Neo
2dfc926f96 feat(ai): W1-AI-CLOSURE 超级 Sprint — 9 APP 全链路收口 + chat 上下文真激活 
Phase 2.3 chat 上下文捕获链路从未真正激活到完整工作:
- 14 处 ai-float-button 补 sourcePage,chat.ts 三分支同步设 pageFilters.contextId
- 后端 page_context 4 层 BUG 修(列名错位 + RLS site_id 未重设)
- xcx_chat filters.pop 破坏 body.page_context 引用 — dict() 浅拷贝隔离
- chat 流式 markdown 实时解析(表格/标题/列表/加粗 + KPI 富卡)
- reference_card KPI 富卡接入 SSE 路径,db 真写入
- 维客线索 source 显示规则:AI 来源用机器人 icon 替代长文字

数据库:
- public.member_retention_clue 加 emoji + runtime_mode + sandbox_instance_id
- biz.ai_run_logs 加 assistant_id + 复合索引
- chk_ai_cache_type CHECK 约束 8 类应用名
- cache_type / app_type 命名统一(app6_note / app7_customer / app8_consolidation)
- 历史 emoji 抽取脚本 44/44 成功

后端 silent failure 修:
- cleanup_service WHERE app_type → cache_type(90 天清理 + 20K 上限重新生效)
- _build_ai_insight 字段错位修复(app4 → app7 + 字段对齐 prompt schema)
- task_manager talkingPoints 改 app5_tactics + tactics 字段
- task_manager aiSuggestion 改取 one_line_summary
- cache_service.CACHE_EXPIRY_DAYS 加 app2a_finance_area
- WS /ws/ai-cache 加 token + JWT + site_id 校验(P0 信息泄露漏洞)
- internal_ai token 改 hmac.compare_digest

工具/文档:
- main.py 加 RotatingFileHandler logs/backend.log + uvicorn /health 过滤
- 新建 utils/clue_category.py(VI 6 类配色 + emoji fallback + source 显示规则)
- 新建 utils/markdown.ts(轻量 md 转 rich-text 解析 + streaming 容错)
- audit + 数据库变更说明 + backlog §七 #14 收口 + #15-#38 残余子任务
- backlog 追加 §十一 App1 参数/MCP/沙箱审计 + §十二 百炼/SQL MCP 主任务线

实地 MCP 走查:14 入口数据层 + 5 代表入口 sourcePage 注入 + customer-detail 全模块 + chat md 渲染 + reference_card 富卡 都已验证。9 项预先 BUG/UX 登记 §七 #29-#38 后续修复。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 16:39:07 +08:00
Neo
c9c2bce101 docs(audit): W1-AI-CLOSURE Step 1 — AI 9 APP 全链路现状矩阵 
P0 #14 AI 9 APP 全链路 Step 1 调研完成(2 个并行 Explore 子代理 +
Bash 直连测试库实证,~ 1h)。

9 APP × 4 环节(接口/入库/后端处理/前端)矩阵:
- 综合就绪度 ~70/100(后端 78 + 前端 60: admin-web 95 / 小程序 40)
- 后端 9/9 健康,无僵尸 APP(子代理 A Bash 实证 ai_cache / ai_run_logs
  全有真实写入)
- admin-web 管理面板基本完整(95/100)
- 小程序前端 5 APP 展示残缺(app3 / app8 完全无展示;app4 / app5 UI
  占位无数据绑定;app6 notes 页无洞察卡片)
- 8 APP 缺独立 OpenAPI 端点(仅通过 dispatcher 后台调度)

W1-AI-CLOSURE wave 推荐拆分 6 sprint(总 ~ 14h):
- Sprint 1-4: 小程序 5 APP 前端展示补齐(P0)
- Sprint 5: 后端 8 APP 统一 OpenAPI 端点(P1)
- Sprint 6: 收尾对账 + WS 告警推送 + admin-web 缺口(P2)

关键不确定性:
- 8 APP 独立端点 vs 统一 /api/ai/run/{app_type} 端点(待 Neo 拍板)
- 各 APP 小程序展示位置(可能涉及新增页面)
- 沙箱时光机透出标识是否需要

backlog §七 #14 状态: ⏳ 待启动 → 🔄 Step 1 调研完成,等 Neo 确认拆分。

详见 docs/audit/changes/2026-05-06__w1_ai_closure_step1_matrix.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 02:23:15 +08:00
Neo
ffe309e801 docs(audit): 全局收口 P1 #1 #2 完成 + roadmap 合并入 backlog + Wave 0 文档体系登记 
Neo 4 件并行收口指示完成:

P1 #1 — 3 项迁移后功能验证 全部 PASS:
- 5 个 slash 命令文件全在(audit/db-docs/doc-sync/pre-change/spec-close)
- 8 个 subagent 文件全在(本会话已成功调用 Explore 4 次实证)
- 双测试库 SELECT 1 通过(test_etl_feiqiu + test_zqyy_app)
- 详见 2026-05-06__closure_p1_1_migration_post_verification.md

P1 #2 — 2026-04-15~05-02 累积基线 33 项对账(子代理深度对账):
- 23 项已完成(70%)+ 5 项部分完成 + 5 项真正未收口
- 大部分被 W1/F1 sprint 体系接管(F1-5a/5b/F1-6/W1-T2/W1-T7)
- 5 项真正未收口转登记 backlog §七 #9~#13(各自归到具体后续节点)
- 详见 2026-05-06__closure_p1_2_cumulative_baseline_reconciliation.md

docs/roadmap/ 目录合并入 backlog §七:
- BACKLOG.md(2026-03-27 更新,60+ 项 P0-P2 待办)登记 #6
- 2026-02-24__fdw-dwd-to-core-migration-plan.md 登记 #7
- Neo 指示重要:roadmap 大多数任务"乍一看都适用",但很多逻辑细节
  值得再深入调研 — 有些已不适用 / 有些冲突 / 有些被更好方式实现了
- 不批量标已完成或待办,需独立"BACKLOG.md 复核 sprint"逐项细化对账

Wave 0 全栈产品文档体系正式登记 §九:
- 已完成 Wave 0(2026-05-04):01-product-overview.md(380 行) + 02a/02b
  指纹矩阵 + admin-api-prd 151 端点 + 04-doc-conflicts 39 条
- 完整覆盖 WEB + 小程序 + 数据库 + 后端 + AI 应用矩阵
- 与 §八 文档规范化大工程关系:Wave 0 是骨架,§八 是后续精化重构

backlog §七 13 项洞口现状:
- ✅ 已收口 5 项(#1 #2 #3 #5 #8)
- ⏳ 待 Neo 评估 1 项(#4 etl-coupon-detail)
- ⏳ 待独立 sprint 1 项(#6 BACKLOG.md 复核)
- ⏳ 待对照 1 项(#7 fdw migration plan)
- ⏳ 累积基线遗留 5 项(#9~#13 各归后续节点)

dev 分支领先 origin/dev 9 commit(本会话累计)。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 02:11:04 +08:00
Neo
e60cfc037c docs(audit): 全局收口反思 — 5 问追溯 + 洞口登记 + 文档规范化大工程立项 
Neo 在 F1-6 Sprint 2 收尾后反思"项目全局控制度不够,到处没收口"。
经 5 问追溯调研(2 个子代理 + Bash 实证),识别 5 个未收口洞口 + 1 个
未明确登记的大工程,本次完成"登记 + 修订",实际收口动作待逐项推进。

5 个未收口洞口(已登记 backlog §七):
- P0 #3 F1-6 Sprint 3 范围描述误导(本次已修订 F1-6-tasks.md §4 拆分 3a/3b)
- P0 #5 Sprint 3/4 衔接判断错误(本次已纠正)
- P1 #1 3 项迁移后功能验证未做(IDE slash / 8 subagent / MCP 测试库)
- P1 #2 2026-04-15~05-02 累积基线 17 天工作待验证
- P2 #4 etl-coupon-detail 30+ 待调研 4 个月未定

文档规范化大工程立项(已登记 backlog §八):
- Neo 明确目标:规范化 / 归档 / 对账 / 去重 / 重构 / 零信息损失
- 范围 11 个 docs/ 子目录 + 各模块本地 docs
- 工程量 L+(数十小时,需多 sprint)
- 状态:立项,详细 spec 待 Neo 调度时立

落地修订:
- docs/_overview/architecture-evolution-backlog.md 追加 §七 §八
- docs/_overview/wave1-findings/F1-6-tasks.md §4 Sprint 3 拆分 3a/3b
- docs/audit/changes/2026-05-06__global_closure_reflection.md 反思全文

承认:Claude 在跨 sprint 衔接判断上有盲区,本次反思已纠正,未来 sprint 转换
前必须读完整 §4 范围描述,不靠记忆推断。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 01:58:18 +08:00
Neo
3164c23168 docs(audit): F1-6 sprint1 UI 走查补做证据 (daysSinceVisit 双截图) 
补做 sprint 1 当时偷工的 UI 实地走查(当时只调 wx.request 验 JSON,未做
navigate_to + screenshot)。Neo 提醒后立即归档到 sprint 1 audit 文档。

UI 实地展示位置: customer-detail.wxml 顶部 stat 卡条第 4 格"距今到店"
- 4a live(today=2026-05-05): 32天(黄先生 last_consume=2026-04-03)
- 4b sandbox=2026-04-20: 31天(walkthrough 测试快照 last_consume=2026-03-20)

双截图归档:
- _DEL/walkthrough_f1_6/sprint1_4a_live_days_since_visit.png
- _DEL/walkthrough_f1_6/sprint1_4b_sandbox_days_since_visit.png

测试快照已清理(DELETE 1 行 stat_date=2026-04-15),sandbox 已切回 live。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 01:36:51 +08:00
Neo
c446920c9e feat(backend): F1-6 sprint2 #5 累计 GMV 加入 sandbox_replay (门店级) 
Sprint 2 收尾指标:门店级累计 GMV(与 #1-#4 会员级粒度不同),新建
sandbox_replay/finance_replay.py 模块。无原 fdw_queries.get_total_gmv
函数(0 现有调用方),不写 thin wrapper(spec §5.5 决策原则)。

数据源 dws_finance_daily_summary.gross_amount(门店日度财务汇总,daily 累计)。
SQL 模式 SUM(gross_amount) WHERE stat_date <= ctx.business_date,与 #1-#4
取最新单行不同,是多行累计 SUM。SQL 层 COALESCE(SUM(...), 0) 兜底,无数据
返回 Decimal('0')(开店前累计 GMV = 0,业务语义)。

口径 gross_amount = table_fee + goods + assistant_pd + assistant_cx,**不含
electricity_money**(与会员级 items_sum 略有差异,docstring 明确防止交叉验证)。

双口径数值验证 PASS(直接 Python,site=2790685415443269 朗朗桌球):
- 4a live(today=2026-05-05): ¥5,725,837.51
- 4b sandbox=2026-04-20: ¥5,653,063.37(差异 ¥72,774,即 4-21~4-27 七天合计)

新增防御性回归测试 test_get_total_gmv_no_member_ids_param 阻断未来误加
member_id 参数(门店级粒度强约束)。

unit test sprint1+sprint2 累计 28/28 PASS,无回归。

Sprint 2 收尾(4 项迁移 + #3 推迟 Sprint 3 等 ETL 配合)。

详见 docs/audit/changes/2026-05-06__f1_6_sprint2_total_gmv.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 01:32:14 +08:00
Neo
7b1cfadc2e feat(backend): F1-6 sprint2 #4 储值卡余额迁移 sandbox_replay (SCD2 时光机) 
新建 sandbox_replay/balance_replay.py 模块,迁移 fdw_queries.get_member_balance,
fdw_queries 改 thin wrapper 保持 5 处现有调用(chat/coach/customer x2/task_manager)
透明兼容。

数据源 dim_member_card_account 是 SCD2 维度表(原生支持时光机),sandbox 改造
关键是替换 scd2_is_current=1 过滤为 scd2_start_time + scd2_end_time 时间过滤
(ref_date+1day 边界 = 当天结束时仍 active 的版本,timestamptz 比较稳定)。

双口径 UI 走查 PASS(member=2799207363643141 葛先生,SCD2 历史余额变化样本):
- 4a live(today=2026-05-05): 储值余额 ¥6,602
- 4b sandbox=2026-04-20: 储值余额 ¥18,080(差异 1.1w+,时光机效果显著)

unit test sprint1+sprint2 累计 24/24 PASS,无回归。

附带本次 sprint 2 触发的架构级登记:
- 新建 docs/_overview/architecture-evolution-backlog.md(DWD 孤立 + Core 中间件 +
  库重组,长远架构演进 backlog)
- F1-6-tasks.md 登记 #3 累计交易笔数推迟 Sprint 3(ETL 配合新增
  total_open_table_count,因现有 total_visit_count 实算 COUNT(settle_type IN (1,3))
  含商城订单,不符 Neo "开台次数"业务语义)
- sandbox-replay-engine-spec §5.5 thin wrapper 决策原则(已在 #2 commit)

详见 docs/audit/changes/2026-05-06__f1_6_sprint2_member_balance.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 01:26:18 +08:00
Neo
32716bc71a feat(backend): F1-6 sprint2 #2 累计消费总额加入 sandbox_replay 
新增指标(无 fdw_queries 原查询 + 0 现有调用方 + 无 thin wrapper),沿用
sprint 1/sprint2 #1 模式 @trace_service + @runtime_aware decorator + 显式
stat_date <= ctx.business_date 上界 + dws_member_consumption_summary
.total_consume_amount 字段 items_sum 口径。

双口径数值验证 PASS(member=2799207087163141 黄先生,直接 Python 调用):
- 4a live(today=2026-05-05): get_total_consume_amount=1252.65
- 4b sandbox=2026-04-20: get_total_consume_amount=999.99(walkthrough 测试快照)

unit test sprint1+sprint2 累计 19/19 PASS,无回归。

记录 thin wrapper 决策原则到 spec §5.5(迁移辅助层,非常态架构;
fdw_queries 长远退化纯 ETL 物理访问层,清理放收尾 sprint)。

注:#3 累计交易笔数因 spec §4 字段未明确(dws_order_summary vs
total_visit_count)暂停,等 Neo 决断后继续。

详见 docs/audit/changes/2026-05-06__f1_6_sprint2_total_consume_amount.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 00:52:08 +08:00
Neo
d418621951 feat(backend): F1-6 sprint2 #1 60d 消费迁移到 sandbox_replay 
迁移 fdw_queries.get_consumption_60d 到 sandbox_replay.consumption_replay,
沿用 sprint 1 模式: @trace_service + @runtime_aware decorator + 显式
stat_date <= ctx.business_date 上界(与视图过滤双保险),fdw_queries 改
thin wrapper 保持 customer_service 2 处调用兼容。

双口径走查 PASS(member=2799207087163141 黄先生):
- 4a live(today=2026-05-05): 小程序 stat 卡条 60天消费 ¥115(consume_amount_60d=115.36)
- 4b sandbox=2026-04-20: 小程序 stat 卡条 60天消费 ¥89(walkthrough 测试快照 88.88)

unit test sprint1+sprint2 累计 15/15 PASS,无回归。

详见 docs/audit/changes/2026-05-06__f1_6_sprint2_consumption_60d.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-06 00:27:13 +08:00
Neo
9f1e35d71a feat(backend): F1-6 sprint1 sandbox_replay 模块脚手架 + get_last_visit_days 迁移试点 (W1) 
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>
 2026-05-05 23:53:19 +08:00
Neo
5d4da0ae8c docs(spec): F1-5b D1-D4 P20 SPEC 同步 + audit dashboard 刷新 (W1) 
F1-5b 大量代码改动落地后,同步 P20 SPEC 反映现状,防止文档与代码偏差。

D1 §6 与 ETL 影子衔接:
- 新增 §6.1 "F1-5b 收益":app 视图业务日上界裁剪范围 + 后端读取层
  + 写入层 sandbox 隔离 + 业务架构边界(zqyy_app 永不建 RLS) + 跨连接器扩展性

D2 §10 跨模块覆盖矩阵更新:
- §10.1 后端服务层:5 个 ? 项核实更新为 X 或 —,各项补 commit 引用
  * task_generator / coach_service / customer_service / dispatcher / admin_service
- §10.2 AI 提示词:app8_consolidate ? 标"F1-5b 范围外,Wave 2 / F1-6 audit"
- §10.3 小程序页面:新增 coach-service-records 行(MP-5);board-* 系列
  ? → —(后端走 board_service);customer-detail 备注补 MP-3 + MP-4

D3 §11 已知遗漏:
- §11.1 设计共识:新增 zqyy_app 永不建 RLS(A4) + batch_id 命名规约(A5)
- §11.2 已知 hack:补 F1-5b T3 间接覆盖说明
- 新增 §11.3 F1-5b 已收口的 11 项遗留 hack ✓
- 新增 §11.4 推迟到 F1-6 沙箱时光机阶段 B 的 4 项 ⏳
- 新增 §11.5 推迟到 F1-7+ 阶段 C 的 3 项 ⏳

D4 §15 变更记录 + §15.1 收益总结 + §12 任务清单:
- §15 新增 4 行(F1-5a 走查 / F1-5b Wave A / Wave B / 沙箱时光机 spec)
- 新增 §15.1 F1-5b 收益总结:7 大类已落地 + 业务价值 + 未落地指引
- §12 任务清单:T11/T12/T13 F1-5b 三批次摘要 + T18/T19 F1-6/F1-7+ 排期
- audit dashboard 自动刷新(scripts/audit/gen_audit_dashboard.py)
  扫描 165 条审计记录(含本次 F1-5b 全部 commit)

无代码改动,纯文档同步。F1-6 启动可直接引用 sandbox-replay-engine-spec
+ P20 SPEC §11.4/§11.5 排期登记。

审计:docs/audit/changes/2026-05-05__wave1_f1_5b_d1234_spec_sync.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 22:21:24 +08:00
Neo
1e803e23cd feat(db,docs): F1-5b MP-2 prep + 沙箱时光机模块 spec (W1) 
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>
 2026-05-05 22:12:22 +08:00
Neo
16c6fb0d3b fix(backend): F1-5b A6 ETL 连接显式 client_encoding=UTF8 防御 GBK (W1) 
Windows GBK 环境下 psycopg2/libpq 在拼接连接字符串时,会读取系统
用户名 / 计算机名,若含中文(0xd6 是 GBK 首字节)会触发
UnicodeDecodeError。admin_db_health.py:105-115 已用显式 DSN +
PGCLIENTENCODING 修过,但 database.py 中的 4 个 connect 函数遗漏。

变更:
- apps/backend/app/database.py
  - 新增 _CONN_KWARGS = {**_KEEPALIVE_KWARGS, "client_encoding": "UTF8"}
  - 4 处 psycopg2.connect 调用从 **_KEEPALIVE_KWARGS 改为 **_CONN_KWARGS:
    * get_connection(zqyy_app 业务库)
    * get_etl_global_readonly_connection(ETL 全局只读)
    * get_etl_readonly_connection(ETL RLS 只读)
    * get_etl_write_connection(ETL 可写)

业务影响:
- 影响 75+ 调用点(grep 统计),Windows GBK 环境下未来出现
  UnicodeDecodeError 概率大幅降低
- Linux UTF-8 环境无影响
- ETL RLS / FDW 链路无逻辑变化(client_encoding 是协议层)

验证:
- 后端 reload + /health 200 OK
- /api/admin/db-health 测试库 connected(test_zqyy_app + test_etl_feiqiu)
- BE-3 / T3 unit test 5/5 PASS,间接证明 ETL 连接链路无破坏

§3.3 标"sandbox 无关",4b 跳过(client_encoding 是协议层,与 sandbox
业务时钟无关)。

未加 feature flag ETL_FORCE_UTF8(§8.3 兜底建议):client_encoding=UTF8
是 PostgreSQL 默认安全设置,无需 flag 控制。若未来出现特殊业务字段
含非 UTF-8 字节再考虑加 flag。

审计:docs/audit/changes/2026-05-05__wave1_f1_5b_a6_etl_conn_utf8.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 22:11:43 +08:00
Neo
6df02f8efe docs(audit): F1-5b BE-3 + T3 测试回归覆盖 (W1) 
补强 F1-5a runtime_context 落地后的测试覆盖,防止未来 PR 回归。
测试文件本地通过,因 .gitignore:71 不入仓(同 T1 / T2 / af02446 处理)。

BE-3 ai_run_logs runtime 写入回归(5 case,本地 PASS):
- apps/backend/tests/test_ai_run_logs_runtime.py
- 覆盖 AIRunLogService.create_log() 在 live / sandbox 模式下分别写入
  正确的 runtime_mode + sandbox_instance_id 字段
- 边界:prompt 截断、INSERT 失败 rollback、bind_to_session=True 调用

T3 dispatcher runtime 单测(5 case,本地 PASS):
- apps/backend/tests/test_dispatcher_runtime.py
- 覆盖 AIDispatcher._run_step 在 4 条路径(circuit_open / rate_limited
  / budget_exceeded / 正常)下都把 context["site_id"] 正确传给
  run_log_svc.create_log
- 防御目标:dispatcher 内部不该意外丢失 site_id,否则 sandbox 切换
  在 dispatcher 路径上失效

依赖 F1-5b A3(commit af02446)的 RuntimeContext 接口契约。
两份测试与 T2(test_admin_ai_batch_runtime,af02446 已 PASS)互补,
一起构成 F1-5a 落地后的回归守护网。

审计:
- docs/audit/changes/2026-05-05__wave1_f1_5b_be3_run_log_runtime_regression.md
- docs/audit/changes/2026-05-05__wave1_f1_5b_t3_dispatcher_runtime.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 19:17:19 +08:00
Neo
3916085063 fix(miniprogram): F1-5b MP-4 coach-detail id 边界保护 (W1) 
走查发现 pages/coach-detail 在某种入口下 data.coachId 为 undefined /
空字符串,导致后端 /api/xcx/coaches/undefined 请求 422,体现为助教
详情页加载失败。后端日志多次出现该 422 记录。

变更:
- apps/miniprogram/miniprogram/pages/coach-detail/coach-detail.ts:247
  onLoad 加 guard(参考 coach-service-records.ts 同款模式):
  - 检查 options.id 非空 + 非字面 'undefined'
  - 数字格式校验 (^\d+$)
  - 失败时 wx.showToast("缺少助教标识") + 1s 后 navigateBack
    (失败时 fallback switchTab board-finance)

双口径验证(weixin-devtools-mcp):
- 缺参入口 /pages/coach-detail/coach-detail(无 query) → guard 触发,
  toast 显示 + 退回 board-finance,不再发出 422 请求
- 正常入口 ?id=3148987180059141 → 通过 guard,pageState=normal 加载成功

§3.3 标"sandbox 无关",4b 跳过(权限/参数路径与 sandbox 无关联)。

审计:docs/audit/changes/2026-05-05__wave1_f1_5b_mp4_coach_detail_id_guard.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 19:17:02 +08:00
Neo
c43375734a feat(admin-web,backend): F1-5b Wave B UI-3 + UI-5 admin-web sandbox 透出补强 (W1) 
UI-3 AIDashboard sandbox 提示 + today_calls 分组:
- 后端 schemas/admin_ai.py DashboardResponse 加 today_live_calls / today_sandbox_calls 字段(默认 0,向后兼容)
- 后端 services/ai/admin_service.py _get_range_stats SELECT 加 2 个 FILTER COUNT 表达式
- 前端 api/adminAI.ts DashboardResponse 类型补 2 字段
- 前端 pages/AIDashboard.tsx
  - 顶部加 sandbox Alert 提示条,选中 site sandbox 模式下显示业务日 + 实例 ID
  - today_calls 卡片下方加分组 Tag(实时 X / 沙箱 Y),feature flag 控制
  - import fetchRuntimeContext + useEffect 拉 RuntimeContext
- apps/admin-web/.env.example 新建,加 VITE_AI_RUNTIME_GROUPING=false 默认值说明

UI-5 AITriggerJobs runtime 列:
- 后端 schemas/admin_ai.py TriggerJobItem 加 runtime_mode / sandbox_instance_id 可选字段
- 后端 admin_service.py list_trigger_jobs / get_trigger_job 各加 SELECT 列
- 前端 adminAI.ts TriggerJobItem 类型补 2 字段
- 前端 pages/AITriggerJobs.tsx 列表 columns 加运行模式 + 沙箱实例(同 UI-1 模式),详情 Modal 加 2 项(同 UI-2 模式)

双口径验证(Playwright + DB 直查):
- UI-3 4a live: 选中默认门店,无 Alert,today_card 仅显示总数(flag off)
- UI-3 4b sandbox=4-20: Alert 显示"沙箱 + 业务日 + sbx_…",today_calls=93(sandbox 当日)
- UI-5 4a/4b: SQL INSERT 注入 walkthrough 测试行(id=9 live, id=10 sandbox),列表正确渲染 Tag + 短哈希

trend_7d 双线 / app_distribution 堆叠分布等更深入分组改造延后到 Wave C(§8.3 风险:破坏图表)。

审计:
- docs/audit/changes/2026-05-05__wave1_f1_5b_ui3_aidashboard_sandbox.md
- docs/audit/changes/2026-05-05__wave1_f1_5b_ui5_aitriggerjobs_runtime.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 19:16:47 +08:00
Neo
87a5e3b08e docs(audit): F1-5b MP-1 储值卡充值字段语义复核 (false alarm) (W1) 
走查发现 board-finance "储值卡充值实收" 66000 vs ETL 直查 ~132000
2 倍差异,怀疑前后端字段错位。

复核结论:链路完全正确,无代码改动。
- 小程序 board-finance.ts L409 'recharge.actualIncome' ← 后端 actual_income
- 后端 fdw_queries:2825 SELECT SUM(recharge_cash) AS actual_income
- 用的是 recharge_cash(现金口径),非 recharge_total(全口径=cash+gift)

DB 直查 site=2790685415443269 / 2026-04 月度:
- recharge_cash  = 66998
- recharge_gift  = 66998
- recharge_total = 133996(= cash + gift,刚好 2 倍)

走查时 132000 = recharge_total(全口径),66000 = recharge_cash
(现金实收),两者本就不同语义。recharge_cash 是"实收"应有的现金
口径(赠送非真实现金流入,业务上不算"实收"),后端字段使用正确。

端到端验证(weixin-devtools-mcp + DB):
- sandbox=4-20: 小程序 actualIncome=66000(SQL stat_date<=4-20)
- 与 DB 全月 SUM(recharge_cash) 66998 差额 998 = 4-21 之后被
  sandbox 业务日上界裁剪(F1-5b T1/A1 收益,跨任务交叉验证)

留给 Wave B 的改进建议(非本次任务范围):
- 小程序 helpKey 'rechargeActual' 文案补充"现金口径(不含赠送)"
- DWS 视图列注释明确 cash/gift/total 三字段语义

审计:
- docs/audit/changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 18:43:54 +08:00
Neo
18fbb2fddf refactor(auth): F1-5b BE-1 manager 角色移除 view_tasks 权限 (W1) 
走查发现 manager(店长)进入小程序"任务"tab 收到 403 "权限不足"。
根因不在 require_permission(权限校验通过,missing=set()),而在
task_manager._get_assistant_id() 因 user_assistant_binding 无有效绑定
抛 403 "权限不足"(detail 与权限错误同名,误导走查方向)。

设计层冲突:task-list 是助教个人工作台业务概念,manager 没有"我自己
的任务"业务场景,监督需求由 board-coach 等汇总看板覆盖。

Neo 决策(2026-05-05):
> "任务的 tab 只有助教身份的用户可以进入并查看,让管理身份的用户
> 进入没有意义。因为他们使用业务场景中不存在任务方面的场景。"

→ 选 B 方案:权限矩阵层移除 manager 的 view_tasks。

变更:
- db/zqyy_app/migrations/20260505__remove_manager_view_tasks.sql
  DELETE FROM auth.role_permissions WHERE role_id=manager AND permission_id=view_tasks
- docs/database/changes/2026-05-05__remove_manager_view_tasks.md
  完整变更说明 + 兼容性 + 4 条校验 SQL + 幂等回滚

测试库执行 + 4 条校验全 PASS:
- manager 改前 5 项权限,改后 4 项(view_board* 保留)
- view_tasks 现绑定到 [coach, head_coach](manager 已剥离)
- coach / head_coach 助教工作台不受影响
- 典型 manager 用户 Neo (8778) 实际权限不再含 view_tasks

双口径走查(weixin-devtools-mcp):
- 4a live: relaunch 后 visibleTabs 从 [task, board, my] → [board, my]
  小程序 tabBar"任务"tab 自动隐藏(getVisibleTabs 基于权限自动重算)
- 强制调 GET /api/xcx/tasks 仍 403,但根因从 _get_assistant_id 错位
  转为 require_permission 正确拦截,语义清晰

不改的部分:
- task_manager._get_assistant_id() 不动(仍用于 coach/head_coach)
- require_permission("view_tasks") 路由保护不动(仍合理)
- 前端 auth-guard.ts 不改(getVisibleTabs 已基于 permissions 自动)

正式库同步说明:
- 本次仅在测试库执行,生产环境同步时 psql 执行 migration + 跑校验 SQL

审计:
- docs/audit/changes/2026-05-05__wave1_f1_5b_be1_task_list_403_root_cause.md
  含完整证据链 + 三方案 ABC 业务影响对比 + B 实施记录

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 18:43:35 +08:00
Neo
96dae0c778 fix: F1-5b MP-3 + MP-5 沙箱业务日小程序适配 (W1) 
MP-3 customer-detail coachTasks.lastService 业务日上界裁剪:
- apps/backend/app/services/customer_service.py
  - import as_runtime_today_param 从 late import 提至模块顶部
  - _build_coach_tasks 开头取 ref_date,供两段 SQL 共用
  - 第一条直查 biz.coach_tasks 加 `AND updated_at < (%s::date + INTERVAL '1 day')::timestamptz`
  - 删除原方法内重复 ref_date 调用
- 业务影响:sandbox=2026-04-20 时,customer-detail 的"上次服务"
  时间不再展示 sandbox 业务日之后的助教任务更新(沙箱不读未来)
- 测试:apps/backend/tests/test_customer_detail_mp3_lastservice.py
  本地通过,因 .gitignore:71 不入仓(同 T1 / af02446 处理方式)

MP-5 coach-service-records 接入 getBusinessClock:
- apps/miniprogram/miniprogram/pages/coach-service-records/coach-service-records.ts
  - import getBusinessClock + data 加 clockYear/clockMonth/clockDay 字段
  - onLoad 改 async,await getBusinessClock() 取 business_year/month/date
  - loadData / switchMonth 4 处 new Date() → clockYear/Month/Day
- 业务影响:sandbox=2026-04-20 时,coach-service-records 默认显示
  "2026 年 4 月"业绩(而非 today 月),canGoNext=false 阻止翻到 5 月,
  "前 5 日预估金额"规则按 sandbox business_date 判断

双口径验证(weixin-devtools-mcp + DB 直查):
- MP-3 4a live: lastService 最大 04-19(无未来时间)
- MP-3 4b sandbox=4-20: 5-01 任务 task_id=8348/8347 完全消失
- MP-5 4a live: clockYear/Month/Day=2026/5/5,monthLabel="2026年5月"
- MP-5 4b sandbox=4-20: monthLabel="2026年4月" + 35 笔/¥4,657
   first group=2026-04-20(后端 SQL 上界裁剪生效)

审计:
- docs/audit/changes/2026-05-05__wave1_f1_5b_mp3_lastservice_upper_bound.md
- docs/audit/changes/2026-05-05__wave1_f1_5b_mp5_coach_service_records_clock.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 18:43:08 +08:00
Neo
3c8d72edd4 feat(ai): F1-5b Wave A admin-web sandbox 透出 UI-1/2/4 (W1) 
完成 F1-5b Wave A admin-web 改造:

UI-1 AIRunLogs 列表加 runtime_mode + sandbox_instance_id 列
- 后端 schema RunLogItem 补 runtime_mode / sandbox_instance_id 字段
- 后端 SQL list_run_logs SELECT 加这两列
- 前端 columns 加"运行模式"(orange/blue Tag) + "沙箱实例"(短哈希 + tooltip)

UI-2 AIRunLogs 详情 Drawer 加 runtime 字段
- 后端 SQL get_run_log SELECT 加 runtime 列
- 前端 Descriptions 加"运行模式" + "沙箱实例"两项

UI-4 全局 sandbox 徽章(覆盖所有 admin-web 页面)
- App.tsx Footer 三段式: 左 sandbox 徽章 / 中 任务状态 / 右 占位
- 30s 轮询 fetchRuntimeContext(userSiteId)
- sandbox: 橙色"沙箱"+ 业务日 + 短哈希实例 ID(monospace)
- live: 绿色"实时"+ 真实今天

双口径 4a/4b 验证(MCP Playwright 实地走查):
- UI-1 4a live: 列表全行 live 蓝 Tag
- UI-1 4b sandbox: SQL INSERT walkthrough_ui12 → 列表显示 sandbox 橙 Tag + 短哈希
- UI-2 4b: Drawer 详情 runtime_mode='sandbox' 橙 Tag + sandbox_instance_id monospace 全 ID
- UI-4 4a: footer 左侧绿"实时"+ 2026-05-05
- UI-4 4b: 切 sandbox=2026-04-20 后 footer 显示橙"沙箱"+ 业务日 + sbx_e7a7e5c5...
- 截图归档 docs/audit/changes/screenshots/2026-05-05_f1_5b_wave_a/

剩余 Wave A: MP-3/5 小程序 sandbox / MP-1 board-finance 字段复核 / BE-1 task-list 403

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 15:14:29 +08:00
Neo
af02446740 feat(ai): F1-5b Wave A 中段 沙箱业务日全栈架构主体收口 (W1) 
完成 F1-5b 任务:
- T1 RuntimeContext unit 测试基础(36 case PASS,本地不入仓走 .gitignore:71)
- A1 admin_service.py 4 处 CURRENT_DATE → business_date 改造
  - _get_range_stats / _get_7d_trend / _get_app_distribution
  - 上下界双全(下界 - 6 days + 上界 < + 1 day,Step 4b 暴露原 PR
    上界缺失,sandbox=4-20 时 trend_7d 漏 4-21~5-01 数据 → 修补)
  - 全局聚合 list_trigger_jobs / get_budget 保留 CURRENT_DATE
    (Neo D 决策选 A: 多 site 时全局无单一业务日)
- A2 fdw_queries:113 / 2552 异常分支兜底 + 三层 fallback + warning
  - conn=None 也尝试 get_runtime_context(自开 conn)
  - RuntimeContext 不可用降级真实 today + logger.warning
- A3 _fdw_context docstring 显式登记唯一 ETL 入口架构契约
  (D2 完整且统一: 所有 ETL 视图查询通过 _fdw_context 自动 SET 三个
   GUC: site_id / business_date / runtime_mode)
- 防御 hook post_edit_business_date_check.py
  Wave 2 后续 PR 引回 CURRENT_DATE / date.today() 即提醒

双口径验证(§3.1 4a + 4b):
- 4a live: dashboard trend_7d 2 条 4-30~5-01 (真实今天)
- 4b sandbox=2026-04-20: trend_7d 1 条仅 4-20 (业务日上界生效硬证据)
- pytest test_runtime_context 36/36 全过

未完(下一批 Wave A): T2 integration / UI-1/2/4 / MP-3/5 / MP-1 / BE-1
F1-5b-tasks.md 新增 + audit 记录已就位

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 15:01:51 +08:00
Neo
95a4500c75 chore(ops): reload 卡死三层预防 + F1-5a 完整走查报告 
reload 卡死三层预防(走查中遭遇 uvicorn graceful shutdown 死等触发):
- Layer 1 (apps/backend/start_uvicorn.py 新): 把 reload-excludes
  封装在 Python 字符串内,ps1 命令行只有字面路径,根治 PowerShell
  PSNativeCommandArgumentPassing 在不同 profile 下 wildcard 展开
  行为差异(数组 splatting 和 --% 都不稳)。同时显式设
  timeout-graceful-shutdown=5,5 秒强杀防死等
- Layer 2 (scripts/ops/backend-watchdog.ps1 新): 自主 socket 探针
  (TcpClient + 手写 HTTP/1.1 GET,Connection: close)规避 .NET
  HttpClient pool 复用 + 系统代理误报;3s × 3 = 9s 触发重启;
  进程链 kill 至 pwsh 后端窗口(关闭原窗口);3 次/小时上限自停
- Layer 3 (scripts/ops/start-admin.ps1): 启动时拉起 watchdog,
  菜单 [4] 仅重启后端选项,主菜单退出时一并 kill 看门狗

CLAUDE.md: 新增"后端 reload 卡死预防(强制)"章节,
分级文件风险表 + SOP + 启动菜单速查

走查报告(应查尽查严肃版):
- 后端 6 个改造点 PASS(P1-P4 + GUC + ai_run_logs runtime 字段)
- admin-web 7 页 Playwright 实地走查 → 5 项 UI 不完整登记 F1-5b
- 小程序看板 tab 7 页 weixin-devtools-mcp 实地 + DB 数据核对 →
  board-finance 5/6 项上界裁剪吻合;board-customer 业务日生效;
  board-coach 月度聚合表设计盲区;5 项 sandbox 覆盖盲区登记 F1-5b
- 8 张走查截图归档 docs/audit/changes/screenshots/2026-05-05_f1_5a_walkthrough/

audit_dashboard 刷新到 153 条审计

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-05 11:53:08 +08:00
Neo
421e193041 fix(ai): F1-5a 沙箱 batch-run 接入 runtime_context (W1 / 阶段 A 主体) 
Neo F1-5 反馈: "让沙箱起到其真正的作用. 真正的模拟日期, 仅能看到沙箱设定日期
及之前日期的数据, 并运行 AI 的各个业务."

调研发现 (4 个并行子代理): batch-run 端点 _run_batch 是空壳 stub
(只 logger.info, 实际不跑 AI), GUC apply_runtime_session_vars 0 处调用
(dead code), 7 张业务表 6 张有 runtime 复合索引唯独 ai_run_logs 漏建,
App2/2a 3 行 _calc_date_range 漏传 ref_date.

本 commit (F1-5a 阶段 A 主体, F1-5b 后续完整 zqyy_app RLS 视图层):

后端核心:
- admin_service.py: _run_batch 真实化 (Semaphore(5)+asyncio.gather+
  return_exceptions=True+ctx_snapshot 防漂移); estimate 入口抓
  RuntimeContext 快照, confirm 取出传给 worker
- admin_ai.py: confirm_batch_run lazy 注入 dispatcher
- admin_service.retry_trigger_job: INSERT 落 runtime_mode +
  sandbox_instance_id 列 (用 runtime_insert_columns helper)
- runtime_context.py: get_runtime_context 加 bind_to_session 参数,
  激活 GUC app.current_business_date / app.current_runtime_mode
- run_log_service.create_log: 启用 bind_to_session=True 试点

App2/2a 3 行 ref_date 修复:
- app2_finance_prompt.py:817 储值卡余额变化板块
- app2_finance_prompt.py:841 日粒度 series + 异常检测窗口
- app2a_finance_area_prompt.py:466 区域日粒度 series

DB:
- migrations/20260505__ai_run_logs_runtime_index.sql:
  补 (site_id, runtime_mode, sandbox_instance_id, created_at DESC) 复合索引

前端:
- AIOperations.tsx: 顶部加 sandbox 模式提示条 (Alert 显示 sandbox_date +
  sandbox_instance_id + 影响范围 + 切回 live 入口)

未做 (留 F1-5b 完整 zqyy_app RLS 视图层一并):
- B1 admin_service 6 处 CURRENT_DATE -> business_date
- B2 fdw_queries 异常分支兜底
- GUC 完整传递 (fdw_queries / page_context 等)
- 测试 3 套 (.gitignore:71 排除, F2-2 入仓时 commit)
- P20 SPEC \xa76/\xa710/\xa711/\xa715 (F1-5b 完整收口后同步更准确)

Neo 决策: docs/_overview/wave1-findings/F1-5-impl-decisions.md

详见 docs/audit/changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md
 2026-05-05 03:01:48 +08:00
Neo
a99bbd9a74 chore(hooks): OpenAPI 抓取 + Prompt 同步 提醒 hook (W1 / F2-1B) 
历史教训 (F2-1A): OpenAPI 抓取脚本 2026-04-06 commit 779b2f6 被
Claude Opus 4.6 在批量清理 1155 个废弃文件时误归档到
_DEL/_DEL/scripts/ops/, 导致 docs/contracts/openapi/backend-api.json
28 天 stale (137 paths -> 实际 167 paths, 缺 30 端点)。
Neo 反馈: 建立机制不要让类似事件再发生。

F3-2C 配套需求: 建立 docs/ai/system-prompts/ 独立 MD 体系后,
维护流程依赖 3 步同步 (元信息日期 / 同步历史 / _INDEX.md 状态表),
容易遗漏造成漂移。

新增 2 个 PostToolUse hook (Edit|Write matcher, timeout 5s):
- post_edit_openapi_reminder.py: 改 apps/backend/app/routers/*.py
  提醒重抓 OpenAPI 具体命令
  (.venv/Scripts/python.exe scripts/ops/_export_openapi.py)
- post_edit_prompt_sync_reminder.py: 改 docs/ai/system-prompts/app*.md
  提醒 3 步同步 (元信息 / 同步历史 / _INDEX.md 状态表)

settings.json 注册 2 个 hook 条目 (PostToolUse 末尾追加)。

spec-close.md 步骤 5 文档同步表:
- OpenAPI 行升级为具体命令 (避免手工同步漂移描述)
- 新增 docs/ai/system-prompts/app*.md 同步行

验证: stdin 模拟测试 3 场景全部符合预期 (匹配 router 输出 OpenAPI 提醒;
匹配 system-prompts MD 输出 prompt 同步提醒; 不匹配静默)。

详见 docs/audit/changes/2026-05-05__wave1_f2_1b_defense_hooks.md
 2026-05-05 02:03:43 +08:00
Neo
b3ad4b8325 docs(ai-prompt): 9 APP system prompt 独立 MD 目录 + ai-app-prompts.md 瘦身改造 (W1 / F3-2C) 
Neo 反馈: 我把百炼 8 APP 的 system prompt 更新到了 ai_system_prompt_by_app.md,
帮我整理成单独 8+1 个文件, 加说明, 放合适目录, 妥善保管。

新增 docs/ai/system-prompts/ 目录:
- _INDEX.md (关系图 + APP ID 映射 + 同步状态表 + SOP)
- 9 份独立 MD: app1_chat / app2_finance / app2a_finance_area /
  app3_clue / app4_analysis / app5_tactics /
  app6_note / app7_customer / app8_consolidation
- 每份带元信息表 + 场景 + 提示词参数 + system prompt 全文 +
  协作关系 + 同步历史 (用 4 反引号 ````text 避免内部 ```json 冲突)

App2a 厘清 (状态 A):
- 与 App2 是两个独立百炼 APP, APP_ID 0ae965029bc54706bcff44f511ac716b
- 显示名 ZQYY-APP2a-指定区域财务洞察, env DASHSCOPE_APP_ID_2A_FINANCE_AREA
- prompt 是 App2 5/5 版本的精细化扩充: H6 新增'助教成本特殊规则'+
  板块 D 新增'助教字段缺失业态判断'(麻将/KTV 缺失=业态正常 /
  大厅/VIP/斯诺克 缺失=业态异常)

改名 + Banner:
- docs/ai/ai_system_prompt_by_app.md
  -> docs/ai/system-prompts/_snapshot-20260505-source.md
  (git mv 保留历史; 文件头加 Banner 说明已被拆分)

A 处置 docs/prd/ai-app-prompts.md (Neo 同意):
- 727 行 -> 110 行 (减 84.9%)
- 标题改为 '百炼平台 AI 应用集成实现规范'
- 删 8 APP system prompt 章节 (已迁移)
- 留 NS2 实现要点 + APP ID 映射 (补 App2a 行) + 前端消费方式 (补 App2a 行) + 附录代码审计对照表

修正认知错误:
- 5/4 F3-2-prompt-files-list.md 给的对照逻辑 (对照 .py 与云端) 是错的
- .py 是 user message 拼装代码, 不是 system prompt 备份
- 5/5 重写该文件: 对照对象改为 docs/ai/system-prompts/*.md

详见 docs/audit/changes/2026-05-05__wave1_f3_2c_system_prompts_split.md
 2026-05-05 02:03:20 +08:00
Neo
f92f2d98f3 fix(tools): 恢复 OpenAPI 抓取脚本 + 重抓 backend-api.json (W1 / F2-1A) 
历史: 2026-04-06 commit 779b2f6 大批量清理时被 Claude Opus 4.6
误归档到 _DEL/_DEL/scripts/ops/_export_openapi.py, 28 天 stale。

恢复:
- cp _DEL/_DEL/scripts/ops/_export_openapi.py scripts/ops/
- 跑脚本重抓: 137 -> 167 paths (新增 30) / 194 -> 234 schemas
- 0 个 removed (后端无废弃)

新增 30 端点分布: admin-ai 5 + runtime-context 3 + task-engine 7 +
triggers 1 + db-health 1 + execution/internal/trigger-jobs 5 + xcx 5

附 F3-2B prompt 文件清单 (本地 8 个 + App1 缺本地副本):
docs/_overview/wave1-findings/F3-2-prompt-files-list.md
Neo 决策 B 云端权威, 用清单对照云端 prompt 检查/更新本地副本。

详细 diff 见审计:
docs/audit/changes/2026-05-04__wave1_f2_1_openapi_script_restored.md
 2026-05-05 00:30:10 +08:00
Neo
c58599d29b docs(prd): admin-web API 全景总览 + 批 1 PRD (W1-T7 / P1-7) 
Wave 1 Day 4 admin-web 后端 API PRD 批 1 撰写。

00-overview.md (338 行):
- 151 端点 / 34 标签全清单(实际 vs P1-7 估算 80,多 71 个)
- 5 批 PRD 拆分映射
- OpenAPI 与代码不同步告警(本批缺 10+ 端点,Wave 5 修复抓取脚本)

batch1-runtime-context-and-ai.md (924 行):
- 23 端点 PRD: admin-ai 17 + runtime-context 5 + triggers 1
- 41 评估发现: P0x8 / P1x20 / P2x13
- 每端点带 file:line 引用 + 调用方定位

工作量修正: P1-7 估算 60-65h -> 实际 100-130h (按 5 批分散到 Wave 1-5)。

参考: docs/audit/changes/2026-05-04__wave1_t7_admin_api_prd_batch1.md
 2026-05-04 09:54:35 +08:00
Neo
e74ce4242f docs(audit): Day 4 测试现状 + 补 W1-T4 audience 单测 (本地) 
- 跑测试: jwt 15/15 + db_viewer_properties 2/2 + ETL 4 视图 smoke PASS
- 补 W1-T4 audience 7 单测 (admin/miniapp 写入 + 旧 token 兼容 + jose silent pass)
- 修 db_viewer_properties.py: _WRITE_KEYWORDS -> _DENY_KEYWORDS (W1-T5 重命名)
- pre-existing 26 个 db_viewer_router fail 与本 Wave 无关 (留 Wave 5)

注: .gitignore:71 'tests/' 排除测试代码不入仓 (项目级决策),
    测试改动仅在本地工作树,本审计记录改动清单 + 跑通结果。

参考:
- 审计: docs/audit/changes/2026-05-04__wave1_day4_test_coverage.md
- 待治理: tests/ 不入仓 -> CI 缺失 -> 测试可能 rot,留 Wave 5 决策
 2026-05-04 09:46:27 +08:00
Neo
3673090582 docs(audit): W1-T6 chat 多入口后端契约已就位 (P1-11 关闭) 
Day 3 实地走读确认 CHAT-2b 端点已实现:
- 后端 xcx_chat.py:GET /api/xcx/chat/messages (contextType + contextId)
- 前端 chat.ts:6 分支 (historyId / taskId / customerId / coachId / sourcePage / general)
- 前后端字段契约 + chatId 归属验证均一致

E-2 调研当时只读到前端标 "待核",本次走读确认后端早已实现。
无代码改动,本审计文件作为"已就位"标记,避免后续误判。

参考: docs/audit/changes/2026-05-04__wave1_t6_chat_context_already_in_place.md
 2026-05-04 08:12:12 +08:00
Neo
b0340349bd feat(etl): cfg_* 视图入口统一 + NULL 兼容 + 3 处 _load_* 历史 Bug (W1-T2 / P0-1) 
Wave 1 Day 3 沙箱配置参数切片。

DB 迁移 (20260504__cfg_views_null_compatible.sql):
- 4 个 v_cfg_* 视图 WHERE 加 NULL 兼容
  (effective_to IS NULL OR effective_to >= ...)
- 顺手清理 v_cfg_assistant_level_price / v_cfg_performance_tier
  WHERE 重复一次的 bug
- 测试库已执行,4 校验 PASS

ETL 代码 (4 处 SQL):
- base_index_task.py: FROM dws.cfg_index_parameters -> app.v_cfg_index_parameters
- base_dws_task.py 3 处 _load_* (performance_tier / level_price / bonus_rules)
  改 FROM app.v_cfg_*,顺手修历史 Bug:原 SQL 不带 effective_from/to WHERE

效果:
- 修复视图 NULL 行被过滤问题(SPI 27 行原本读到 0)
- 沙箱模式回放历史日期时,参数自动按 sandbox_date 切片
- _load_* 直接得到当前生效行(原 12/9 行历史 Python 挑)

参考:
- docs/audit/changes/2026-05-04__wave1_t2_scd2_view_unify.md
- docs/database/changes/2026-05-04__cfg_views_null_compatible.md
 2026-05-04 08:10:57 +08:00
Neo
9eb495686f feat(miniprogram): board-finance isCurrentMonthFilter 接入业务时钟 (W1-T1 / P0-3) 
Wave 1 Day 2 看板沙箱接入。

调研修正:
- xcx_board.py + board_service.py 服务层已接入 runtime_context (L264/L712)
- board-customer.ts / board-coach.ts 0 处使用 new Date(),无需改
- 唯一遗漏: board-finance.ts isCurrentMonthFilter 用 new Date().getDate()
  沙箱回放历史日期会判错"本月前 5 天预估"提示

修复:
- import getBusinessClock from utils/runtime-clock
- isCurrentMonthFilter 接收可选 businessDate 参数;空值降级 new Date()
- data 加 businessDate: ''
- onShow 拉业务时钟 + 修正 isCurrentMonth
- onTimeChange 用 this.data.businessDate

参考: docs/audit/changes/2026-05-04__wave1_t1_board_sandbox_clock.md
 2026-05-04 07:42:51 +08:00
Neo
17f045a89e fix(backend): Wave 1 Day 1 三个 P0 D Bug 修复 
- W1-T3 修 4 处 fdw_etl.* 必坏残留 → app.* (P0-5 致命 1)
  · tenant_users.py L431/L456-457: v_dim_assistant + v_dim_staff(_ex)
  · tenant_excel.py L394/L411: v_dim_assistant + v_dim_staff
  · tenant_clues.py L119: v_dim_member
  · 修复后 tenant-admin 用户审核 / Excel 上传 / 维客线索恢复正常

- W1-T4 JWT aud sign 端写入 (P0-5 致命 2 最小止血)
  · jwt.py 全部 token 创建/解码函数加 audience 参数
  · auth.py admin 端加 audience="admin"
  · xcx_auth.py miniapp 端加 audience="miniapp" (8 处调用)
  · 18 router 切强制 aud 校验留 Wave 2

- W1-T5 DBViewer 白名单 + 黑名单双保险 (P0-8)
  · 白名单: SELECT/WITH/EXPLAIN/SHOW 开头
  · 黑名单: 17 关键词覆盖全 DML/DDL/DCL
  · 注释剥离避免误伤;15/15 单测 PASS

参考: docs/audit/changes/2026-05-04__wave1_day1_d_bug_triple_fix.md
 2026-05-04 07:36:20 +08:00
Neo
caf179a5da feat: 2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复 
涵盖（每条对应已存的审计记录）：
- AI 模块拆分：apps/backend/app/ai/apps -> prompts/（8 个 APP + app2a 派生）
  audit: 2026-04-20__ai-module-complete.md
- admin-web AI 管理套件：AIDashboard / AIOperations / AIRunLogs / AITriggers / TriggerManager
  audit: 2026-04-21__admin-web-ai-management-suite.md
- App2 财务洞察 prompt v3 -> v5.1 + 小程序 AI 接入（chat / board-finance）
  audit: 2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md
- App2 prewarm 全过滤器 + AI 触发器 cron reschedule
  audit: 2026-04-21__app2-finance-prewarm-all-filters.md
  migration: 20260420_ai_trigger_jobs_and_app2_prewarm.sql / 20260421_app2_prewarm_cron_reschedule.sql
- AppType 联合类型对齐 + adminAiAppTypes.test.ts
  audit: 2026-04-30__admin_web_ai_app_type_alignment.md
- DashScope tokens_used 提取修复
  audit: 2026-04-30__backend_dashscope_tokens_used_extraction.md
- App3 线索完整详情 prompt
  audit: 2026-05-01__backend_app3_full_detail_prompt.md
- Runtime Context 沙箱（5-1~5-2 主线）：
  - 后端 schema/service + admin_runtime_context / xcx_runtime_clock 两个 router
  - admin-web RuntimeContext.tsx + miniprogram runtime-clock.ts
  - migration: 20260501__runtime_context_sandbox.sql
  - tools/db/verify_admin_web_sandbox.py + verify_sandbox_end_to_end.py
  - database/changes: 7 份 sandbox_* 验证报告
- 飞球 DWS 修复：finance_area_daily 区域汇总 + task_engine 调整
  + RLS 视图业务日上界（migration 20260502 + scripts/ops/gen_rls_business_date_migration.py）

合规：
- .gitignore 启用 tmp/ 排除
- 不入仓：apps/etl/connectors/feiqiu/.env（API_TOKEN secret，本地修改保留）

待验证清单：
- docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md
  每个主题的功能完整性 / 上线验证几乎都未收口，按优先级 P0~P3 逐一处理
 2026-05-04 02:30:19 +08:00
Neo
f2e0de8fab chore(migration): Cursor → Claude Code 反向迁移 + 单轨化（v2） 
- 删除 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）
 2026-05-03 21:08:13 +08:00
Neo
81e41730ec 迁移 Claude/Codex/Cursor 开发环境与追溯资产 
Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-05-02 03:11:39 +08:00
Neo
d269ee6401 docs(ai): app2a v1.2 system prompt + 多 APP 派生设计 v2 + 审计 + A/B 脚本 
1. docs/ai/app2a_finance_area_system_prompt_20260422_v1.md (新建 · v1.2 生产版):
   - 基于 app2_finance V5.1 派生
   - 板块 C 改"业态收入结构" · 板块 E 改"业态定位与对比"
   - 新增 H7 硬约束：业态特征引用必须紧跟 payload 真实数据
   - H6 扩展区域级 6 类字段缺失降级（储值卡/分渠道现金流/现金流出/会员占比/按星期/日异常）
   - 经 3 次修正：v1"稀疏" → v1.1 纠正为业务真实 0/非 0 → v1.2 纠正为字段存在/整块缺失
   - 已同步百炼控制台 APP ID 0ae965029bc54706bcff44f511ac716b

2. docs/ai/app2_finance_multi_app_design.md (新建 · v2 定稿):
   - 6 章 + 3 附录 · Q1-Q7 全部决策 · 6 阶段 28 项 checklist
   - 72 组合数据源支持度三档梳理（必须 / 业务级全店 / 字段存在 vs 整块缺失）
   - 2 套 prompt 拼接方案 · 2 个派生百炼 APP 策略

3. docs/audit/changes/2026-04-23__app2a_finance_area_integrated.md (新建):
   - 完整审计记录 · 13 高风险文件逐项注解
   - 数据库变更 + 风险与回滚 + 验证方式 + 合规检查

4. docs/audit/audit_dashboard.md (刷新 · 135 条记录)

5. scripts/ab_test_app2a_area.py (新建):
   - 8 业态 × 3 轮 = 24 次采样评估含金量
   - 自动检测 H1/H2/H3/H7 硬约束通过率 + seq11 三色灯分布

6. scripts/ab_to_cache.py (新建):
   - 复用 A/B 结果直接写 ai_cache · 绕开百炼预算验证 UI 端到端

A/B 实测 24/24 成功 · 12 条齐整率 100% · H1/H3/H7 100% · 达生产级。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-22 21:56:46 +08:00
Neo
b44096600d chore(cleanup): 清理历史会话遗留未跟踪产物 — gitignore 追加 + 文件归位 
- .gitignore: 追加 .playwright-mcp/ 与 apps/miniprogram/.font_patch_tmp/ 两条忽略规则
- apps/miniprogram/scripts/: 新建目录, 迁入 TDesign BOM 修复脚本 inspect-wechat-font.ps1 及其检查报告
- 根目录 excel_analysis_report.txt / sheet_structure.txt 归位 tmp/, 修正 root-file 风险标签
- 审计记录 2026-04-20__legacy-untracked-cleanup-review.md, 含实际执行段与回滚路径
- audit_dashboard.md 由 gen_audit_dashboard.py 刷新至 130 条

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-20 06:48:27 +08:00
Neo
95dd1fa6b9 chore(audit): 修正审计文件命名 — 单下划线补为双下划线 
2026-03-24_fix_cfg_skill_type_missing_records.md
  → 2026-03-24__fix_cfg_skill_type_missing_records.md

该文件源自 audit-gap-recovery 阶段 1 补追的 96 份 D 类孤本之一，原命名采用单
下划线分隔日期与 slug，与 gen_audit_dashboard.py 期望的双下划线格式不符而被
脚本忽略。补齐下划线后 dashboard 记录数从 128 升至 129，与主目录 md 文件
数一致。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-20 06:39:13 +08:00
Neo
14a12342b5 chore(audit): 补追 96 份未入仓审计孤本 — 覆盖 2026-02-26 ~ 2026-04-08 
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。

按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。

涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
   召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
   DDL 基线合并 / Kiro 到 Claude Code 迁移

阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-20 06:35:42 +08:00
Neo
80bda9b991 chore(audit): 2026-04-20 历史批次预审 + 文档同步 + .gitignore 修正 
- 新增 docs/audit/changes/2026-04-20__historical-batch-pre-audit.md
  157 文件分批盘点审计（7 条主线 + 10 项高/中风险 + 2 份迁移 SQL DDL 清单）
- 补追 docs/audit/changes/2026-04-15__meituan-settle-core-sync.md
  原审计产物因 .gitignore 屏蔽长期未入仓，本次一并追回
- 刷新 docs/audit/audit_dashboard.md（33 条审计记录）
- .gitignore 白名单放行 docs/audit/changes/*.md 与 audit_dashboard.md
  同时屏蔽 changes/changes/ 嵌套误产物目录
- 新增 docs/specs/audit-gap-recovery/tasks.md
  扫描嵌套目录发现 96 份 D 类孤本（从未入过 git history），
  生成独立 PRD 供单开任务清理与补追
- 文档同步（高风险项）：
  - apps/backend/docs/API-REFERENCE.md (+69)
  - apps/miniprogram/README.md (+50)
  - apps/etl/connectors/feiqiu/docs/architecture/data_flow.md (+52/-2)
  - apps/etl/connectors/feiqiu/docs/architecture/system_overview.md (+5/-3)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-20 06:32:58 +08:00
Neo
2a7a5d68aa feat: 2026-04-15~04-20 累积变更基线 — 多主线合流 
主线 1: rns1-customer-coach-api + 04-miniapp-core-business 后端实施
  - 新增 GET /xcx/coaches/{id}/banner 轻量接口
  - performance/records 加 coach_id 参数 + view_board_coach 权限分流
  - coach/customer/performance/board/task 服务层重构
  - fdw_queries 结算单粒度聚合 + consumption_summary 视图统一
  - task_generator 回访宽限 72h + UPSERT 替代策略 + Step 5 保底清理
  - recall_detector settle_type=3 双重限制 + 门店级 resolved

主线 2: 小程序权限分流 + 新增 coach-service-records 管理者视角业绩明细页
  - perf-progress 共享模块去重 task-list/coach-detail 动画逻辑
  - isScattered 散客标记端到端
  - foodDetail/phoneFull/creator* 字段透传

主线 3: P19 指数回测框架 Phase 1+2
  - 3 个指数表 stat_date 日快照模式
  - 新增 DWS_INDEX_BACKFILL / DWS_TASK_SIMULATION 工具任务
  - task_engine 升级 HTTP 实时 + 推演回测双模式

主线 4: Core 维度层启用
  - 新增 CORE_DIM_SYNC 任务（DWD → core 4 维度表）
  - 修复 app 视图空查询问题

主线 5: member_project_tag 改为 LAST_30_VISITS 消费次数窗口

主线 6: 2 个迁移 SQL 已执行（stat_date + member_project_tag 新窗口）
  - schema 基线与 DDL 快照同步

主线 7: 开发机路径迁移 C:\NeoZQYY → C:\Project\NeoZQYY（约 95% 改动量）

附带: 新建运维脚本（churned_customer_report / simulate_historical_tasks /
      backfill_index_snapshots）+ tools/task-analysis/ 任务分析工具

合计 157 文件。未包含中间产物（tmp/ .playwright-mcp/ inspect-* excel/sheet 分析 txt）。
审计记录见下一个 commit。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-20 06:32:07 +08:00
Neo
f65c1d038b chore: 审计记录 + 修复 repo_root.py 仓库根检测 
- 审计记录：2026-04-06__v1-cleanup-ddl-consolidation.md
- 刷新审计一览表（125 条记录）
- 修复 repo_root.py：.kiro 已删除后改用 pyproject.toml + CLAUDE.md 检测

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 2026-04-06 01:05:06 +08:00
Neo
4eac07da47 在准备环境前提交次全部更改。 2026-02-19 08:35:13 +08:00
Neo
ded6dfb9d8 init: 项目初始提交 - NeoZQYY Monorepo 完整代码 2026-02-15 14:58:14 +08:00