Neo-ZQYY/docs/_overview/architecture-evolution-backlog.md

架构演进 Backlog(长远)

创建日期:2026-05-06 状态:backlog,等优先级排期(不在当前 F1-6 范围) 记录人:Neo + Claude(F1-6 Sprint 2 #3 调研触发)

一、核心方向

DWD 层孤立 + Core 做连接器中间件,Core 之上的全部上游(DWS / 指数 / RLS 视图等)在所有连接器之间统一规范。

二、目标

1. 后期可能接入多个连接器(与 feiqiu 平行的其他平台,不同字段/不同设计)
2. DWD 层归属于各连接器自身(字段/口径可异),保留为各连接器原始数据落地层
3. Core 层作为中间件:
   • 下游对接各连接器的 DWD 层(吸收差异)
   • 上游输出统一规范的字段/语义
4. Core 之上的所有层(DWS、指数计算、RLS 视图、ETL 任务输出表等)结构、字段、设计、设置在所有连接器之间完全一致
5. 后端 / 小程序 / admin-web / tenant-admin 仅依赖 Core 之上的统一层,不感知具体连接器

三、牵连(待逐一决断)

记录所有触发的牵连项,推进时逐一对齐:

#	牵连项	说明	当前状态
1	库结构重组(连接器粒度)	当前每店铺一个 ETL 库(etl_feiqiu / test_etl_feiqiu),Neo 指示至少每连接器一个库,Core 后的全部上游应统一到一个共享库集中管理	待设计
2	DWS 字段名 vs 实算口径不一致	F1-6 Sprint 2 #3 调研发现 dws_member_consumption_summary.total_visit_count 字段名"累计到店次数",实算是 COUNT(settle_type IN (1,3)) 即结算单数(含商城订单);BD manual / dws_tasks.md 描述误导	待修订(随 #3 推到 Sprint 3)
3	F1-6 #3 累计交易笔数	按 Neo 业务语义"开台次数"(不含 settle_type=3 商城订单),需 ETL 在 DWS 新增 total_open_table_count = COUNT(settle_type=1) 字段	推迟 Sprint 3(ETL 配合)
4	DWD 不可被后端 / 应用层直读	F1-6 Sprint 2 #3 调研发现 app7_customer AI prompt 当前直接读 app.v_dwd_settlement_head COUNT(*),违反"DWD 孤立"原则	待重构(随大架构演进)
5	后端 fdw_queries.py 中所有 app.v_dwd_* 直读点	需要梳理全部,逐一改走 Core / DWS 统一接口	待清单化
6	F1-7+ thin wrapper 收尾 sprint	F1-6 全部迁完后清理 fdw_queries 的 thin wrapper(详见 sandbox-replay-engine-spec.md §5.5)	与本演进同步

四、不属于本 backlog

• F1-6 沙箱时光机阶段 B(Sprint 1-4)— 仍按现有 ETL 库结构推进,不等本演进。Sprint 推进过程中遇到本 backlog 第 2-5 项的具体问题,各自登记到对应 Sprint 任务清单。
• 架构设计细节(Core 层 schema 定义、库迁移策略、连接器适配 SDK 等)— 本文件仅做需求登记,详细设计待优先级到位时另起 spec。

五、关联

• F1-6 Sprint 3 任务清单:docs/_overview/wave1-findings/F1-6-tasks.md §4
• 沙箱时光机模块 spec:docs/_overview/sandbox-replay-engine-spec.md §5.5(thin wrapper)+ §11(远期目标)
• DWD 强制规则:apps/etl/connectors/feiqiu/CLAUDE.md §DWD 强制规则(12 条)

六、决策与变更记录

日期	决策 / 变更	触发
2026-05-06	创建本 backlog	F1-6 Sprint 2 #3 累计交易笔数调研发现 DWS 字段名与实算口径矛盾 + app7 直读 DWD 违规,Neo 决定将 DWD 孤立 + Core 中间件目标提上任务表
2026-05-06	追加 §七 全局收口洞口清单 + §八 文档规范化整理大工程	Neo 反思项目全局控制度,5 问追溯调研后立项
2026-05-06	§七 收口 #1 #2 完成 + 追加 #6~#13 + 新增 §九 全栈产品文档体系登记	docs/roadmap/BACKLOG.md 60+ 项发现 + Wave 0 全栈文档体系实证 + 累积基线 33 项对账

---

七、全局收口洞口清单(2026-05-06 反思,逐项收口)

触发背景

Neo 发现"项目全局的控制度不够,有很多东西被漏了,到处都没有收口"。 经 5 问追溯调研(子代理 + Bash 实证),发现以下 5 个未收口洞口。

收口清单

#	洞口	来源证据	状态	优先级	处理方式
1	3 项迁移后功能验证	docs/audit/changes/2026-05-02__claude_code_migration.md L111-113	✅ 2026-05-06 已收口	P1	实测 PASS:5 slash 命令文件 + 8 subagent 文件 + 双测试库 SELECT 1 全通过;详见 2026-05-06__closure_p1_1_migration_post_verification.md
2	2026-04-15 ~ 05-02 累积基线 33 项对账	docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md	✅ 2026-05-06 已对账	P1	子代理对账:23 完成(70%)+ 5 部分 + 5 真正未收口(转登记 #9~#13);详见 2026-05-06__closure_p1_2_cumulative_baseline_reconciliation.md
3	F1-6 Sprint 3 范围描述误导	F1-6-tasks.md §4 把 MP-2 单项 ETL 依赖错误暗示成 Sprint 3 整体不可做	✅ 2026-05-06 已修订	P0	F1-6-tasks.md §4 已修订:Sprint 3a(5 个 P1 可独立做)+ Sprint 3b(MP-2 + #11 等 ETL)
4	etl-coupon-detail 30+ "待调研"标注 4 个月未定	docs/specs/etl-coupon-detail/	⏳ 灰色	P2	待 Neo 评估是否 Wave 1 解决
5	Sprint 3 / 4 衔接判断错误	Claude 在 Sprint 2 收尾时推荐"跳过 Sprint 3"是错误判断	✅ 2026-05-06 已纠正	P0	Sprint 2 收尾后正确顺序 = Sprint 3 (5/6 项可做) → Sprint 4
6	docs/roadmap/BACKLOG.md 60+ 项 P0-P2 待办	docs/roadmap/BACKLOG.md(2026-03-27 更新,258 行)	⏳ 乍一看适用,但需细化对账	P1	Neo 指示:大多数任务"乍一看都适用",但很多逻辑细节值得再深入调研 — 有些已不适用 / 有些与现状冲突 / 有些被更好方式实现了。不能简单"批量标已完成"或"批量标待办"。需逐项做细化对账(可能与 Wave 1/F1 工作有大量交叠)。本身是一个独立的中等工作量任务(~ 2-3h),建议作为独立"BACKLOG.md 复核 sprint"启动
7	docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md FDW 迁移方案	docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md	⏳ 待对照	P2	与 backlog §一 "DWD 孤立 + Core 中间件"目标完全一致,实际是同一目标的更早期 spec。需对照本 backlog §一确认是否仍代表当前方向,或已被本 backlog 取代
8	Wave 0 全栈产品文档体系(已完成,但需登记并纳入 §八文档规范化范围)	docs/_overview/01-product-overview.md 等 5 篇	✅ Wave 0 完成	—	详见 §九新增登记;文档规范化大工程(§八)是其下一阶段,即"对完整体系进一步精化和重构,零信息损失"
9	(累积基线遗留)缓存分桶 + EventBus 生产观察	累积基线 3.1.3	⏳ 未收口	P2	F1-6 sprint 3 完成后补 audit
10	(累积基线遗留)WebSocket 消费稳定性	累积基线 3.1.7	⏳ 未收口	P2	上线灰度期(5-7 ~ 5-15)长期观察
11	(累积基线遗留)ETL 库完整 GUC 传递 26 视图	累积基线 3.5.5	⏳ 未收口	P1	推迟 F1-5b Wave C(已规划)
12	(累积基线遗留)finance_area_daily 会员分桶 vs DWS 规范	累积基线 3.7.2	⏳ 未收口	P1	数据质量 Review,上线灰度期
13	(累积基线遗留)RLS 视图 pg_get_viewdef 全量重建	累积基线 3.7.3	⏳ 未收口	P1	数据质量 Review + 视图清单专题 audit

收口原则

• 每项洞口完成后,出对应 audit 文档(docs/audit/changes/2026-05-XX__closure_*.md)
• 完成后标 ✅ 并补 commit 引用
• 不再让"待验证 / 待调研"在文档中无限期挂着

---

八、文档规范化整理(大工程,长期立项)

触发背景

Neo:"项目中的文档又多又零碎,分支理不清,只能逐一处理并全部文档按类型和作用 重构合并去重等。但我不想损失任何的信息精度。这是一个很重很大的工程。"

调研背景(子代理 2 实证 2026-05-06):没有找到明确的"2026-01-01 至今文档整理" 任务记录,只有零散的局部整理痕迹(2026-02-13 BD manual 整理 / 2026-02-15 docs/database 合并 / 2026-04-06 v1 整理 1155 文件)。本立项即明确该任务正式登记。

工程目标(Neo 定义)

1. 规范化:项目内所有文档按类型和作用归类
2. 归档:过期内容统一归档(不删除)
3. 对账:不符合项目实时状态的文档,逐一对比分析原因
4. 去重 + 合并:多文档同主题/重叠内容,合并去重
5. 重构:目录结构按"类型 + 作用"重新组织
6. 零信息损失 (关键约束):不损失任何精度,即使整理过程也保留原文留底

范围估算(初步,详细 spec 待立)

• docs/_overview/(产品全景索引)
• docs/audit/(审计记录,200+ 篇 audit 文档)
• docs/prd/(PRD + 决策卡 + 反馈)
• docs/database/(BD manual + DDL)
• docs/specs/(spec 文档,含 etl-coupon-detail 等)
• docs/ai/(AI prompt 体系)
• docs/contracts/(OpenAPI 契约)
• docs/guides/(开发指南)
• docs/miniprogram-dev/(小程序开发)
• docs/architecture/(架构总览)
• docs/ai-env-history/(迁移历史)
• 各模块内 docs/(模块本地文档)

工程量初判

• 大概率 L+ 工作量(数十小时,需要分多个 sprint)
• 必须有明确 spec 设计(类型分类标准 / 归档约定 / 去重原则 / 信息损失防护)
• 不在 F1-6 阶段 B 做,作为独立任务在 F1-6 完成后或并行启动

执行原则

• 先 spec 后施工(不做无规划重构)
• 每次提交 1 个目录或 1 个主题,不批量乱动
• 整理前留下 git 备份点(全文档 tar 归档 _DEL/ )
• 整理后做信息精度核对(diff 比对关键内容)

状态

• ⏳ 立项(2026-05-06 由 Neo 在反思时正式登记)
• 详细 spec 待 Neo 调度时立(可能与 F1-6 阶段 B 收尾后启动)

---

九、Wave 0 全栈产品文档体系(已完成,登记并纳入 §八后续重构范围)

触发背景

Neo 反思时问:"WEB 小程序 数据库 后端等项目全局的一个文档的任务,是否也规划了, 还是已经完成了?"经子代理调研:已完成 Wave 0(2026-05-04),但当时缺乏明确登记, 本次正式登记并标注后续与 §八 文档规范化大工程的关系。

Wave 0 完成清单

文档	完整度	内容	引用方
docs/_overview/01-product-overview.md	95%	380 行产品全景脑图,角色到 4 端映射,8 大章节	F1-* sprint 引为标杆
docs/_overview/02a-miniprogram-page-matrix.md	90%	21 页小程序业务指纹矩阵(498 行)	W1-T1 / F1-5b MP-3/4/5
docs/_overview/02b-adminweb-page-matrix.md	85%	19 路由 admin-web 业务指纹矩阵(280 行)	F1-5b UI-1/2/3/4/5
docs/_overview/admin-api-prd/00-overview.md	90%	151 端点 API 全景(拆 5 批 PRD,W1-T7 批 1 完成)	W1-T7 P1-7
docs/_overview/04-doc-conflicts.md	90%	39 条文档冲突清单(已拍板)	W1 P0/P1/P2 反馈调研
docs/_overview/00-index.md	—	主索引 + 维护协议	全 W1/F1 sprint

完整覆盖范围

• WEB 端(admin-web 19 路由 + tenant-admin)
• 小程序端(21 页业务指纹)
• 数据库端(docs/_overview/01-product-overview.md §四 数据流 + docs/database/ BD manual)
• 后端端(admin-api-prd 151 端点 + 后端架构)
• AI 应用矩阵(8 个千问 APP 汇总)

当前状态

• ✅ 已规划 + 已完成(Wave 0,2026-05-04)
• 🔄 持续优化中(W1/F1 sprint 推进时持续引用 + 增量更新)
• ⏳ 待精细化(§八 文档规范化大工程是其下一阶段,目标"对完整体系进一步规范化、去重、零信息损失重构")

与 §八 的关系

Wave 0 文档体系是 §八 文档规范化大工程的起点(已有的全景索引体系),不是 §八 的目标产物。§八 的目标是把整个 docs/ 目录(11+ 子目录,200+ 篇 audit + N 篇 spec/PRD)按 统一的"类型 + 作用"分类标准重构,Wave 0 已建立的全景索引体系是其规范的"骨架", 具体规则、归档约定、信息精度防护待 §八 详细 spec 时立。