Neo
e60cfc037c
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>
7.9 KiB
7.9 KiB
架构演进 Backlog(长远)
创建日期:2026-05-06 状态:backlog,等优先级排期(不在当前 F1-6 范围) 记录人:Neo + Claude(F1-6 Sprint 2 #3 调研触发)
一、核心方向
DWD 层孤立 + Core 做连接器中间件,Core 之上的全部上游(DWS / 指数 / RLS 视图等)在所有连接器之间统一规范。
二、目标
- 后期可能接入多个连接器(与
feiqiu平行的其他平台,不同字段/不同设计) - DWD 层归属于各连接器自身(字段/口径可异),保留为各连接器原始数据落地层
- Core 层作为中间件:
- 下游对接各连接器的 DWD 层(吸收差异)
- 上游输出统一规范的字段/语义
- Core 之上的所有层(DWS、指数计算、RLS 视图、ETL 任务输出表等)结构、字段、设计、设置在所有连接器之间完全一致
- 后端 / 小程序 / 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 反思,逐项收口)
触发背景
Neo 发现"项目全局的控制度不够,有很多东西被漏了,到处都没有收口"。 经 5 问追溯调研(子代理 + Bash 实证),发现以下 5 个未收口洞口。
收口清单
| # | 洞口 | 来源证据 | 状态 | 优先级 | 处理方式 |
|---|---|---|---|---|---|
| 1 | 3 项迁移后功能验证未做 | docs/audit/changes/2026-05-02__claude_code_migration.md L111-113 标"待用户后续验证" |
⏳ 待验 | P1 | (a) IDE 中输入 /audit 等 5 个 slash 命令是否能加载;(b) 8 个 subagent 通过 Agent 工具调用是否正常;(c) MCP 测试库 pg-etl-test / pg-app-test SELECT 1 通过 — 各自 ~ 2 分钟,出补做 audit |
| 2 | 2026-04-15 ~ 05-02 累积基线 17 天工作待验证 | docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md 文件名即"待验证",commit caf179a 把 17 天工作打包成 1 个 commit |
⏳ 待验 | P1 | 读该 audit 文档列举的待验证项,逐项验证或推迟到具体 wave 验证(F1-5a/F1-5b 走查实际已部分覆盖,需对账) |
| 3 | F1-6 Sprint 3 范围描述误导 | F1-6-tasks.md §4 把 MP-2 单项 ETL 依赖错误暗示成 Sprint 3 整体不可做,导致 Claude 推荐"跳过 Sprint 3 直推 Sprint 4" | ⏳ 待修订 | P0 | 修订 F1-6-tasks.md §4,明确 5 个 P1 指标(#6~#10)可独立做,仅 MP-2 依赖 ETL 配合 |
| 4 | etl-coupon-detail 30+ "待调研"标注 4 个月未定 | docs/specs/etl-coupon-detail/ design.md + requirements.md(package_services / coupon_details_list 等) |
⏳ 灰色 | P2 | 由 Neo 评估是否在 Wave 1 解决;若是登记到 W1 任务清单,若否明确推迟到指定阶段 |
| 5 | Sprint 3 / 4 衔接判断错误 | Claude 在 Sprint 2 收尾时推荐"跳过 Sprint 3"是错误判断 | 已识别 | P0 | 本次反思已纠正,Sprint 2 收尾后正确顺序 = Sprint 3 (5/6 项可做) → Sprint 4 |
收口原则
- 每项洞口完成后,出对应 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 定义)
- 规范化:项目内所有文档按类型和作用归类
- 归档:过期内容统一归档(不删除)
- 对账:不符合项目实时状态的文档,逐一对比分析原因
- 去重 + 合并:多文档同主题/重叠内容,合并去重
- 重构:目录结构按"类型 + 作用"重新组织
- 零信息损失 (关键约束):不损失任何精度,即使整理过程也保留原文留底
范围估算(初步,详细 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 收尾后启动)