diff --git a/docs/README.md b/docs/README.md index eeecbe0..84236fc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,9 +18,11 @@ ## 推荐阅读顺序 -1. `guides/BACKEND_CURRENT_STATUS.md` -2. `guides/BACKEND_TABLE_MAPPING.md` -3. 其他辅助资料 +1. `guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md` +2. `guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md` +3. `guides/BACKEND_CURRENT_STATUS.md` +4. `guides/BACKEND_TABLE_MAPPING.md` +5. 其他辅助资料 ## 维护原则 diff --git a/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md b/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md new file mode 100644 index 0000000..119099c --- /dev/null +++ b/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md @@ -0,0 +1,888 @@ +# Speckit 工作流的人类友好教学文档 + +## 1. 先说结论 + +`Speckit` 的理论基础,不是“先写一堆文档”,而是先把一个需求拆成一连串可验证的小闭环,再让每个闭环都留下明确工件。 + +在这个工作区里,它本质上是在解决四个老问题: + +1. 需求很容易一开始就说大了,最后越做越散。 +2. 文档、代码、验证和台账经常各说各话。 +3. 多仓协作时,大家都在干活,但没人能准确回答“现在到底做到哪了”。 +4. 交付时只能靠口头解释,缺少稳定的追溯链。 + +所以 `Speckit` 不是“文档优先”这么简单,它更准确的说法是: + +**用规格驱动的方式,把需求澄清、方案收敛、任务拆解、实现验证、结论回写做成一个个可追溯闭环。** + +--- + +## 2. 它基于什么理论 + +结合本仓库的 `constitution`、模板和工作流说明,`Speckit` 的底层思想主要来自以下几类工程方法。 + +### 2.1 单一真源 + +核心思想是:正式结论必须有唯一归属,不能让多个版本并行竞争。 + +在本仓库里,这被明确成: + +- 正式内容优先回写主文档 +- `specs/` 是过程工件和治理工件 +- `Archive` 是来源,不是正式结论 +- backend/frontend 负责实现,不负责定义正式规格 + +这对应的是经典的软件工程思想:**single source of truth**。 + +### 2.2 逐步求精 + +同一个需求,不在一开始就展开到代码细节,而是逐层收敛: + +1. 先确认到底要解决什么问题 +2. 再确认边界和约束 +3. 再确认要怎么拆 +4. 再进入实现和验证 + +这对应的是:**stepwise refinement**,也就是逐步求精。 + +### 2.3 需求到交付的可追溯性 + +每个阶段都要能回答两个问题: + +- 你这个结论是从哪里来的? +- 你这个结果后来落到哪里去了? + +所以它天然要求: + +- spec 能追到 source of truth +- plan 能追到 spec +- tasks 能追到 user story / requirement +- implementation / evidence 能追到 tasks +- 最终结论能回写正式文档和台账 + +这对应的是:**traceability**。 + +### 2.4 小步闭环,而不是大步推进 + +很多团队的问题,不是不会做,而是喜欢一次推进太多内容,导致: + +- 范围没锁住 +- 任务没拆清 +- 验证没前置 +- 回写没人做 + +`Speckit` 的做法是把系统构建看成多个连续闭环,而不是一个大瀑布。 + +这更接近:**iterative delivery** 和 **feedback loop**。 + +--- + +## 3. 它到底怎么通过一个个闭环构建系统 + +可以把 `Speckit` 理解成 6 个连续闭环。 + +前一个闭环的输出,是后一个闭环的输入。 + +### 闭环 1:范围闭环 + +目标:先回答“这次到底做什么,不做什么”。 + +输入: + +- 用户意图 +- 主文档 +- Archive 历史资料 +- 当前代码现状 + +输出: + +- `spec.md` +- 明确的纳入范围 +- 明确的排除范围 +- 明确的验收口径 + +闭环成功的标志: + +- 评审者只看 `spec.md` 就能判断是否超范围 +- 团队不会把“以后可能做”误当成“这轮必须做” + +这一步解决的是“方向漂移”。 + +### 闭环 2:决策闭环 + +目标:把范围内仍然模糊的关键问题收敛成可执行决策。 + +输入: + +- `spec.md` +- 现有设计文档 +- 冲突来源 +- 需要裁决的问题 + +输出: + +- `research.md` +- 一组关键决策和理由 + +闭环成功的标志: + +- 后续规划不再反复争论同一个问题 +- 每个重要选择都能说清“为什么这样定” + +这一步解决的是“大家都觉得自己理解对,但没有正式裁决”。 + +### 闭环 3:设计闭环 + +目标:把“需求”转成“可落地结构”。 + +输入: + +- `spec.md` +- `research.md` + +输出: + +- `plan.md` +- `data-model.md` +- `contracts/*` +- `quickstart.md` + +闭环成功的标志: + +- 已经知道涉及哪些文档、哪些仓、哪些接口、哪些数据对象 +- 已经知道最小验证动作是什么 +- 已经知道正式主文档后续该怎么回写 + +这一步解决的是“知道要做什么,但还不知道怎么组织”。 + +### 闭环 4:任务闭环 + +目标:把设计转成可分配、可执行、可检查的任务。 + +输入: + +- `plan.md` +- `data-model.md` +- `contracts/*` +- `quickstart.md` + +输出: + +- `tasks.md` + +闭环成功的标志: + +- 每个任务都能映射到具体文件、具体仓、具体验证动作 +- 每个 user story 都可以独立评审 +- 任务不是“继续完善一下”这种抽象话,而是明确动作 + +这一步解决的是“设计有了,但执行还是靠临场发挥”。 + +### 闭环 5:实现与验证闭环 + +目标:把任务变成实际改动,并证明改动有效。 + +输入: + +- `tasks.md` +- docs/backend/frontend 各 lane 的执行结果 + +输出: + +- 正式文档修改 +- 代码改动 +- 校验结果 +- evidence / final verdict + +闭环成功的标志: + +- 改动完成后有对应验证 +- 验证结果能追溯到具体基线 +- 不是“我本地看起来可以”,而是有可复核证据 + +这一步解决的是“做了,但没人能确定真的完成了什么”。 + +### 闭环 6:治理回写闭环 + +目标:把阶段结果沉淀回正式体系,而不是停留在聊天记录或临时分支里。 + +输入: + +- 已完成的文档和代码结果 +- 验证结果 +- feature 基线 + +输出: + +- 主文档回写 +- `01_Project_Progress.md` +- `03_Task_Checklist.md` +- 必要的 evidence 与最终结论 + +闭环成功的标志: + +- 别人不看聊天记录,也能知道当前状态 +- 后续 feature 可以直接站在当前结论上继续推进 + +这一步解决的是“这次做完了,但组织记忆没有留下来”。 + +--- + +## 4. 一个需求是怎么一步步长成系统的 + +可以把整个过程理解成下面这条链: + +```text +用户问题 +-> spec 锁范围 +-> research 锁关键决策 +-> plan 锁实施结构 +-> tasks 锁执行清单 +-> implementation 锁实际改动 +-> verification 锁完成证据 +-> ledger/main docs 锁组织记忆 +``` + +这条链最重要的地方在于: + +**每一步都不是为了“写文档”,而是为了减少下一步的不确定性。** + +举例: + +- `spec` 不是为了写需求书,而是为了防止做着做着变成另一个项目 +- `plan` 不是为了写方案书,而是为了让任务拆解有稳定骨架 +- `tasks` 不是为了列清单,而是为了让 lane 执行可分配、可验收 +- `verification` 不是为了走流程,而是为了把“我觉得好了”变成“证据表明好了” + +--- + +## 5. 为什么它适合复杂系统,而不只是适合写文档 + +因为复杂系统最怕的不是工作量大,而是下面这四种失控: + +1. 需求失控:边界不清,越做越大 +2. 结构失控:模块、接口、数据口径互相冲突 +3. 执行失控:任务拆不稳,协作互相阻塞 +4. 认知失控:做完后没人说得清当前状态 + +`Speckit` 的价值,就在于它把这四种失控分别放进不同闭环里处理: + +- `spec` 管需求失控 +- `plan` / `contracts` / `data-model` 管结构失控 +- `tasks` 管执行失控 +- `verification` / `ledger sync` 管认知失控 + +所以它不是“文档流程”,而是一个 **复杂系统治理流程**。 + +--- + +## 6. 在这个仓库里,Speckit 的真实落地方式 + +在 `water-workspace` 里,`Speckit` 不是独立于实现的平行世界,而是正式治理层。 + +职责边界是: + +- `water-docs`:负责正式 `spec/plan/tasks/evidence` 和主文档回写 +- `water-backend`:负责后端实现与后端验证 +- `water-frontend`:负责前端实现与前端验证 +- `tmux + worktree`:负责并行执行现场 + +也就是说: + +```text +Speckit 定义“应该做什么、如何验收” +lane 执行“具体怎么做出来” +water-docs 负责“最终正式结论落到哪里” +``` + +这就是为什么仓库里一直强调: + +- `.specify/` 只保留在 `water-docs` +- backend/frontend 不复制第二套 spec-kit +- 正式工件统一回到 `water-docs` + +--- + +## 7. 人最容易误解的几个点 + +### 误解 1:Speckit 就是先写文档再开发 + +不准确。 + +更准确的说法是:**先把决策和验收条件固定,再进入开发。** + +如果一个需求很小,完全可以不走完整流程。 + +### 误解 2:有了 spec,就等于已经设计好了 + +不对。 + +`spec` 主要回答“做什么”和“做到什么算完成”。 + +真正回答“怎么组织、怎么拆、怎么验证”的,是 `plan`、`data-model`、`contracts` 和 `tasks`。 + +### 误解 3:tasks 只是项目管理清单 + +不对。 + +`tasks` 在这里是执行接口,作用是把规格层结论翻译成 lane 可以直接消费的动作。 + +### 误解 4:验证是收尾动作 + +不对。 + +在 `Speckit` 里,验证条件应该从 `spec` 和 `plan` 阶段就开始定义,而不是等实现完才临时想。 + +--- + +## 8. 对新人最实用的理解方式 + +如果你不想一上来记所有命令,可以只记下面四句话: + +1. `spec`:先把边界锁住。 +2. `plan`:再把结构和依赖锁住。 +3. `tasks`:再把执行动作锁住。 +4. `verify + 回写`:最后把结果锁进正式系统。 + +把它翻成更口语的话就是: + +```text +先确认做什么 +再确认怎么做 +再确认谁去做 +最后确认做完没有,并把结论留下来 +``` + +这就是 `Speckit` 最朴素、也最重要的本质。 + +--- + +## 9. 一张总图 + +```text +用户需求 + ↓ +specify / clarify + 产出:范围、边界、验收口径 + 闭环:范围闭环 + ↓ +plan + 产出:方案、决策、模型、合同、最小验证 + 闭环:决策闭环 + 设计闭环 + ↓ +tasks + 产出:可执行任务、lane 映射、独立验收切片 + 闭环:任务闭环 + ↓ +implement / verify + 产出:代码、文档、验证证据 + 闭环:实现与验证闭环 + ↓ +ledger sync / main docs update + 产出:正式结论、项目进度、任务状态、基线 + 闭环:治理回写闭环 +``` + +--- + +## 10. 推荐给团队的教学方式 + +如果你要拿这套流程教别人,建议不要从命令开始讲,而是按下面顺序讲: + +1. 先讲为什么团队会失控:范围、结构、执行、认知四种失控。 +2. 再讲 `Speckit` 用哪些闭环分别处理这四种失控。 +3. 再讲 `spec -> plan -> tasks -> verify -> 回写` 的工件链。 +4. 最后才讲仓库里具体怎么落地到 `water-docs`、`water-backend`、`water-frontend`。 + +这样新人先理解“为什么”,再理解“怎么做”,吸收速度会快很多。 + +--- + +## 11. 与本仓库口径对应的参考来源 + +本说明基于以下仓内材料整理: + +- `water-docs/.specify/memory/constitution.md` +- `water-docs/.specify/templates/spec-template.md` +- `water-docs/.specify/templates/plan-template.md` +- `water-docs/.specify/templates/tasks-template.md` +- `docs/TMUX_WORKTREE_TEAM_WORKFLOW.md` +- `water-docs/AGENTS.md` +- 现有 `water-docs/specs/*` 工件样例 + +如果这些基础材料后续更新,本教学文档也应同步修订。 + +--- + +## 12. Speckit 与工程控制论的关系 + +如果从方法论上看,`Speckit` 和钱学森提出的工程控制论确实很接近。 + +但要说得准确一些,不是“完全一样”,而是: + +**`Speckit` 可以理解为一种面向软件研发治理的工程控制论实践。** + +### 12.1 相似之处 + +两者都关心同一件事: + +**怎样让一个复杂系统朝目标稳定演化,而不是边做边失控。** + +在 `Speckit` 里,这种相似性主要体现在下面几项。 + +#### 1. 都先定义目标状态 + +工程控制论强调,控制之前必须先明确目标。 + +`Speckit` 里对应的是: + +- `spec` 定义目标 +- `spec` 定义边界 +- `spec` 定义完成条件 + +也就是说,系统不是“先干起来再说”,而是先定义希望到达什么状态。 + +#### 2. 都强调观测当前状态 + +控制不能脱离观测。 + +`Speckit` 在进入规划和实施前,都会先看: + +- 主文档现状 +- Archive 来源 +- backend / frontend 当前实现 +- 验证结果 +- 台账状态 + +这相当于先观察系统当前状态,而不是只看目标。 + +#### 3. 都依赖偏差分析 + +控制的核心不是“下命令”,而是发现偏差、修正偏差。 + +`Speckit` 实际上一直在比较: + +- 目标和现状是否一致 +- 文档和代码是否一致 +- 接口、数据、设计之间是否一致 +- 任务完成状态和验收标准是否一致 + +只要不一致,就说明存在偏差,需要继续修正。 + +#### 4. 都通过反馈回路持续校正 + +这和传统“一路写到最后再看结果”的思路不同。 + +`Speckit` 的典型反馈方式是: + +- 范围不清,回到 `spec` +- 关键决策冲突,回到 `research` 或 `plan` +- 设计与接口不一致,回到 `contracts` / `data-model` +- 验证不过,回到任务或实现 +- 结论未沉淀,回到主文档和台账 + +这本质上就是反馈控制。 + +#### 5. 都有分层控制结构 + +工程控制论往往不是单层控制,而是多层协同。 + +`Speckit` 也一样: + +- `spec` 控目标层 +- `plan` 控结构层 +- `tasks` 控执行层 +- `verify` 控结果层 +- `ledger sync` 控组织记忆层 + +每一层控制的对象不同,但共同服务于整体稳定性。 + +### 12.2 不同之处 + +两者也有明显区别。 + +钱学森的工程控制论,更多研究的是: + +- 物理工程系统 +- 工业过程 +- 技术系统运行中的控制规律 + +而 `Speckit` 控制的不是设备本身,而是: + +- 需求如何收敛 +- 设计如何对齐 +- 任务如何拆解 +- 实现如何验证 +- 结论如何沉淀 + +所以它控制的是: + +**研发过程和交付过程。** + +不是狭义的设备控制,而是过程治理。 + +### 12.3 为什么这个类比有价值 + +把 `Speckit` 理解成“工程控制系统”,会比把它理解成“文档流程”更准确。 + +因为这样你会自然意识到: + +1. `spec` 不是装饰品,而是目标设定器。 +2. `plan` 不是空洞方案,而是结构控制器。 +3. `tasks` 不是待办清单,而是执行调度器。 +4. `verify` 不是收尾动作,而是反馈传感器。 +5. `ledger` 不是行政记录,而是组织状态记忆。 + +这样一来,团队就不会把每个工件当成独立文件,而会把它们看成控制链上的不同节点。 + +### 12.4 一个更贴切的理解 + +可以把 `Speckit` 理解成下面这个模型: + +```text +目标设定 +-> 状态观测 +-> 偏差识别 +-> 方案校正 +-> 执行调节 +-> 结果验证 +-> 组织回写 +-> 下一轮控制 +``` + +这条链本身就是一个闭环控制系统。 + +而 `Speckit` 的价值,正是在于它把软件研发从“经验驱动、口头协调、事后补救”,变成了“目标明确、过程可观测、偏差可修正、结果可追溯”的受控过程。 + +### 12.5 教学时可以怎么讲 + +如果要对团队解释这层关系,建议直接用这句话: + +**`Speckit` 不是让大家多写文档,而是用工程控制论的思路,把复杂研发过程变成一个有目标、有反馈、有校正的闭环系统。** + +这句话通常比单纯讲命令和模板更容易让人真正理解它的价值。 + +--- + +## 13. 小闭环是怎么组织成大闭环的 + +这是理解 `Speckit` 最关键的一步。 + +很多人会以为: + +- `spec` 是一个闭环 +- `plan` 是一个闭环 +- `tasks` 是一个闭环 +- `implement` 是一个闭环 + +然后这些闭环只是顺序排开。 + +其实不是。 + +更准确的理解是: + +**小闭环是分层嵌套的,前一个闭环的输出会变成后一个闭环的控制输入;很多 feature 闭环继续累积,才会形成系统级大闭环。** + +### 13.1 先看四层结构 + +在这个工作区里,可以把闭环分成四层。 + +#### 第一层:动作闭环 + +这是最小闭环,通常是一组非常具体的动作: + +```text +修改 +-> 校验 +-> 修正 +-> 记录结果 +``` + +例如: + +- 改 `12_REV_Detailed.md` +- 执行 `make validate-file` +- 如有链接变更再跑 `make check-links` +- 结果写入 quickstart 或最终结论 + +这一层解决的是“这一个动作到底有没有做实”。 + +#### 第二层:用户故事闭环 + +这是把多个动作闭环拼成一个可以独立评审的能力片段: + +```text +一个用户故事 +-> 若干文档动作 +-> 若干代码动作 +-> 独立验证 +-> 形成局部结论 +``` + +这一层解决的是“这一个业务片段是否已经独立成立”。 + +#### 第三层:feature 闭环 + +这是把多个用户故事闭环拼成一个 feature 的完成链: + +```text +spec +-> plan +-> tasks +-> implement +-> verify +-> ledger sync +``` + +这一层解决的是“这个 feature 是否已经成为系统中的稳定能力单元”。 + +#### 第四层:系统交付闭环 + +这是最大的闭环: + +```text +需求池 +-> feature 闭环 1 +-> feature 闭环 2 +-> feature 闭环 3 +-> 主文档与台账持续更新 +-> 系统能力版图逐步收敛 +``` + +这一层解决的是“整个系统是否在有秩序地长出来”。 + +### 13.2 最重要的一句话 + +可以把这四层关系记成一句话: + +**动作闭环保证局部真实,故事闭环保证片段成立,feature 闭环保证能力落地,系统闭环保证整体演进。** + +--- + +## 14. 用你当前系统做案例讲解 + +下面直接用你仓库里的 `REV-004` 和 `REV-005` 来讲。 + +### 14.1 系统目标不是一次性实现,而是逐块实现 + +你现在这个营收系统,不是靠“一次大开发”完成的,而是靠多个 feature 闭环逐步长成。 + +从当前仓库可以看到几个典型能力块: + +- `REV-004`:账务处理一期 +- `REV-005`:发票业务流 +- `REV-006`:催缴与通知 +- `REV-007`:统计分析 + +这四个 feature 不是平行孤岛,而是在共同补齐营收系统的核心业务版图。 + +也就是说,系统级大闭环大致是: + +```text +营收系统目标 +-> 一个个 feature 进入 Speckit +-> 每个 feature 形成可控闭环 +-> 每轮闭环结果回写主文档和台账 +-> 系统整体能力逐步成形 +``` + +### 14.2 先看 `REV-004`:它在补什么系统能力 + +`REV-004` 的本质,不是“写一份账务说明”,而是在给系统补一块能力底座: + +- 明确账务处理一期边界 +- 统一 `IF-REV-007` +- 统一留痕、原始依据、结果状态 +- 再按场景拆到账务调整、退款、冲正、坏账申请 + +这意味着 `REV-004` 的价值不是单一功能点,而是: + +**先把账务处理域里的共性控制骨架搭起来。** + +如果这块不闭合,后面的退款、冲正、坏账等就会各自长成不同口径。 + +所以 `REV-004` 这个 feature 闭环,本质上是在给系统建立: + +- 账务场景边界 +- 账务接口边界 +- 账务留痕边界 +- 账务状态边界 + +这是一块“平台型能力闭环”。 + +### 14.3 再看 `REV-005`:它在补什么系统能力 + +`REV-005` 的计划更接近实现闭环。 + +从 [002-rev005-invoice-flow/plan.md](/Volumes/Dpan/github/water-workspace/water-docs/specs/002-rev005-invoice-flow/plan.md) 可以看出,它要补的是: + +- 后台发票申请 +- 后台单笔/批量开票 +- `SYS-008` 异步申请与查询兜底 +- 发票结果回写 +- 账单与发票关联 +- 客户侧查询/下载/推送 + +这说明 `REV-005` 不是一个接口修补,而是在补一个完整业务结果链: + +```text +收费账单 +-> 发票申请 +-> 外部发票服务协同 +-> 查询补偿 +-> 结果回写 +-> 客户消费结果 +``` + +这是一块“流程型能力闭环”。 + +### 14.4 为什么 `REV-004` 和 `REV-005` 能拼成更大的闭环 + +因为它们不是随机 feature,而是在系统业务链上前后衔接。 + +可以这样理解: + +- `REV-004` 负责账务处理域中的调整、退款、冲正、坏账等控制逻辑 +- `REV-005` 负责收费后发票结果的业务闭环 + +两者共同服务的是“营收处理全过程”的可控性。 + +举个直白例子: + +如果系统里发生退款或冲正,账务状态一定会影响后续发票状态、发票可用性、结果展示和客户消费体验。 + +所以: + +- 没有 `REV-004`,`REV-005` 可能会缺失上游账务一致性约束 +- 没有 `REV-005`,`REV-004` 的结果又无法完整延伸到发票交付链 + +它们拼起来,才更接近真实的营收业务闭环。 + +### 14.5 从小闭环拼成大闭环的真实过程 + +下面用更接近执行的方式来描述。 + +#### 第一步:先闭合 `REV-004` 内部的小闭环 + +例如先闭这些: + +1. 范围闭环 +2. `IF-REV-007` 统一合同闭环 +3. 留痕与结果状态统一闭环 +4. 退款/冲正原交易校验闭环 +5. 正式文档与执行手册回写闭环 + +这些闭完后,`REV-004` 才算从“讨论账务”变成“系统已有一套稳定账务处理骨架”。 + +#### 第二步:再闭合 `REV-005` 内部的小闭环 + +例如继续闭这些: + +1. 发票申请闭环 +2. `SYS-008` 查询兜底闭环 +3. 发票结果回写闭环 +4. 账单-发票关联闭环 +5. 客户侧查询/下载/推送闭环 +6. backend 编译与文档回写闭环 + +这些闭完后,`REV-005` 才算从“发票规划”变成“系统已有一条稳定发票结果链”。 + +#### 第三步:再把 feature 闭环在系统层面接起来 + +这一步不是再写一份大而全的总方案,而是靠以下机制自然接起来: + +- 主文档持续回写 +- 接口设计持续统一 +- 数据库承接口径持续统一 +- 项目进度与任务台账持续记录 +- 新 feature 继续站在前一轮闭环结论上推进 + +这就形成了系统级大闭环: + +```text +账务闭环稳定 +-> 发票闭环接入 +-> 通知闭环接入 +-> 统计闭环接入 +-> 各能力通过主文档、接口、数据、台账不断统一 +-> 营收系统形成整体受控结构 +``` + +### 14.6 为什么主文档和台账这么重要 + +很多团队的大闭环之所以拼不起来,不是因为他们没有做 feature,而是因为: + +- 每个 feature 的结论只留在聊天记录里 +- 代码改了但主文档没回写 +- 台账不更新,没人知道当前真实状态 +- 下一个 feature 启动时,又重新猜一遍现状 + +这样 feature 虽然一个个做了,但系统级大闭环拼不起来。 + +而你这个仓库里一直强调: + +- 主文档单一真源 +- 重要结果回写 `01_Project_Progress.md` +- 任务闭环更新 `03_Task_Checklist.md` + +它的真正作用就是: + +**让上一个 feature 的输出,成为下一个 feature 的稳定输入。** + +这正是大闭环成立的关键条件。 + +--- + +## 15. 一个更贴近实现目标的系统级示意图 + +如果你的最终目标是“把营收系统真实实现出来”,可以把当前过程理解成下面这张图: + +```text +系统目标:形成可交付、可实现、可验证的营收系统 + ↓ +Feature A:REV-004 账务处理一期 + - 闭合范围 + - 闭合接口 + - 闭合留痕与状态 + - 闭合账务场景控制骨架 + ↓ +Feature B:REV-005 发票业务流 + - 闭合申请 + - 闭合查询兜底 + - 闭合结果回写 + - 闭合客户消费链路 + ↓ +Feature C:REV-006 催缴与通知 + - 闭合任务生成 + - 闭合消息协同 + - 闭合结果回写 + ↓ +Feature D:REV-007 统计分析 + - 闭合统计口径 + - 闭合指标来源 + - 闭合输出与追溯 + ↓ +主文档 / 接口设计 / 数据库设计 / 台账 / evidence 持续统一 + ↓ +系统级大闭环:各业务域能力逐步收敛成一个整体系统 +``` + +这张图里最重要的是: + +不是先有“大闭环设计”,再去硬塞小闭环。 + +而是每个 feature 先形成稳定能力块,再通过统一主文档、统一接口、统一数据库口径、统一台账回写,把这些能力块拼成系统级闭环。 + +--- + +## 16. 给当前实施目标的直接建议 + +如果你现在的目标是“以系统实现为目的继续推进”,那最实用的策略不是问“什么时候整个系统才算闭环”,而是每一轮都问下面三个问题: + +1. 当前这个 feature,补的是系统里的哪一块能力? +2. 这块能力内部还有哪些小闭环没闭? +3. 这轮闭合后的结果,会通过哪些主文档、接口、数据和台账,变成下一个 feature 的输入? + +只要这三个问题一直答得清楚,系统级大闭环就会自然长出来。 + +反过来说,如果这三个问题答不清楚,就算团队一直在干活,也很容易变成“局部热闹,整体失控”。 diff --git a/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md b/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md new file mode 100644 index 0000000..99a59ea --- /dev/null +++ b/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md @@ -0,0 +1,335 @@ +# 营收系统能力地图与闭环进度图 + +## 1. 文档目的 + +本文用于回答三个实际问题: + +1. 当前 `REV-004`、`REV-005`、`REV-006`、`REV-007` 分别在补系统的哪一块能力? +2. 这些 feature 当前各自走到了 `spec / plan / tasks / implement / verify / 回写` 的哪一步? +3. 如果目标是“继续把系统实现出来”,下一轮最应该优先闭哪一块? + +这份图不是替代 `specs/`,而是把多个 feature 的局部闭环放到同一张系统视角里,帮助统一判断整体推进顺序。 + +--- + +## 2. 一张总图 + +```text +福建水务营收系统 + ↓ +收费与账单主链 + - REV-002 开账计费与账单生成 + - REV-003 收费核销处理 + ↓ +账后控制与结果链 + - REV-004 账务处理一期 + - REV-005 发票业务流 + - REV-006 催缴与通知 + - REV-007 营收统计查询 + ↓ +主文档 / 接口设计 / 数据库设计 / 台账 / evidence 持续统一 + ↓ +系统级大闭环 +``` + +这条链的意思不是“后面的 feature 必须等前面的全做完才能动”,而是: + +- `REV-004`、`REV-005`、`REV-006`、`REV-007` 都属于收费后处理与经营结果链条 +- 它们既可以分阶段推进,也必须最终回到统一的主文档、接口、数据库和治理台账上 + +--- + +## 3. 当前能力地图 + +### 3.1 feature 与系统能力的对应关系 + +| Feature | 系统能力类型 | 核心目标 | 当前角色 | +| --- | --- | --- | --- | +| `REV-004` | 账后控制能力 | 统一账务调整、退款、冲正、坏账申请的一期边界、接口、留痕和状态口径 | 底座型闭环 | +| `REV-005` | 发票结果链能力 | 打通发票申请、外部协同、查询兜底、结果回写与客户侧消费 | 流程型闭环 | +| `REV-006` | 催缴协同能力 | 打通催缴对象生成、通知协同、结果回写、停复水边界和历史查询口径 | 协同型闭环 | +| `REV-007` | 经营观察能力 | 明确统计主题、指标口径、查询维度、接口边界和数据承接口径 | 观察型闭环 | + +### 3.2 这四块能力在业务链上的位置 + +```text +账单 / 收费结果 + ├─ REV-004:账后调整与异常处理 + ├─ REV-005:发票申请、开具、回写、客户消费 + ├─ REV-006:欠费提醒、通知协同、结果承接 + └─ REV-007:经营统计、收费统计、欠费统计、渠道分析 +``` + +因此这四个 feature 不是平级替代关系,而是共同围绕“收费后的业务控制、结果消费、消息协同、经营观察”形成系统后半段。 + +--- + +## 4. 闭环进度图 + +## 4.1 统一阶段定义 + +为了避免“已经做了很多”但说不清做到哪,下面统一用六段来标识每个 feature 的阶段: + +1. `spec`:范围和验收口径已锁定 +2. `plan`:结构、依赖、接口/数据设计已组织 +3. `tasks`:任务拆解已能直接指导执行 +4. `implement`:文档或代码已进入实际落地 +5. `verify`:已有验证证据或待补证据边界已明确 +6. `ledger sync`:主文档、进度台账、任务台账已统一回写 + +## 4.2 当前 feature 闭环进度 + +| Feature | spec | plan | tasks | implement | verify | ledger sync | 当前判断 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `REV-004` | 已完成 | 已完成 | 已完成 | 文档 implement 已完成 | 文档校验已完成 | 已完成 | 文档闭环完成,代码闭环未启动 | +| `REV-005` | 已完成 | 已完成 | 已完成 | 已进入 backend implement 并完成 US1~US4 | Verification Pending | 已完成 | 实现态闭环基本完成,运行态证据待补 | +| `REV-006` | 已完成 | 已完成 | 已完成 | implement 阶段文档收口已完成 | 文档校验已完成 | 已完成 | 治理闭环完成,backend 仍未见明确实现 | +| `REV-007` | 已完成 | 已完成 | 已完成 | implement 阶段正式文档收口推进中 | 文档校验与治理校验为主 | 已完成 | 设计闭环已建立,代码入口未见明确实现 | + +### 4.3 用符号再看一遍 + +```text +REV-004: spec ✓ -> plan ✓ -> tasks ✓ -> implement(文档) ✓ -> verify(文档) ✓ -> ledger ✓ +REV-005: spec ✓ -> plan ✓ -> tasks ✓ -> implement(代码+文档) ✓ -> verify(运行态待补) △ -> ledger ✓ +REV-006: spec ✓ -> plan ✓ -> tasks ✓ -> implement(文档) ✓ -> verify(文档) ✓ -> ledger ✓ +REV-007: spec ✓ -> plan ✓ -> tasks ✓ -> implement(文档) ✓ -> verify(设计/治理) ✓ -> ledger ✓ +``` + +最关键的区别是: + +- `REV-004 / REV-006 / REV-007` 当前主要是“文档与治理闭环” +- `REV-005` 已经进入“代码实现闭环” + +这决定了后续系统推进的优先级不能一刀切。 + +--- + +## 5. 依赖关系图 + +## 5.1 业务依赖 + +```text +REV-002/REV-003 产出账单与收费结果 + ↓ +REV-004 处理账后调整、退款、冲正、坏账 + ↓ +REV-005 消费收费/账单结果形成发票闭环 + ↓ +REV-006 基于欠费/催缴对象形成通知协同闭环 + ↓ +REV-007 对账单、收费、欠费、渠道、客户结果做统计观察 +``` + +## 5.2 方法依赖 + +```text +REV-004 先统一账务状态、留痕、原交易校验口径 + ↓ +有助于 REV-005 / REV-006 / REV-007 在状态、日志、追溯上保持一致 +``` + +因此: + +- `REV-004` 更像后续 feature 的控制骨架 +- `REV-005` 更像当前最接近真实交付的结果链 +- `REV-006` 更像待转实现的协同链 +- `REV-007` 更像待转实现的观察链 + +--- + +## 6. 从“小闭环”到“系统大闭环”的拼接方式 + +## 6.1 feature 内部怎么闭 + +每个 feature 先把自己内部的小闭环闭起来。 + +### `REV-004` + +- 范围闭环:五类场景收敛 +- 合同闭环:`IF-REV-007` +- 共性能力闭环:留痕、原始依据、结果状态、审批边界 +- 治理闭环:执行手册、项目进度、任务清单回写 + +### `REV-005` + +- 申请闭环:后台发票申请与校验 +- 协同闭环:`SYS-008` 异步申请与查询兜底 +- 回写闭环:发票状态、账单关联、客户侧消费 +- 二期入口闭环:作废与红冲最小入口 +- 验证闭环:实现态证据已补,运行态样本待补 + +### `REV-006` + +- 设计闭环:催缴对象、通知事件、结果状态四态、停复水边界 +- 接口闭环:`IF-REV-013` 与 `IF-EXT-008` +- 治理闭环:implement 阶段文档收口与台账回写 + +### `REV-007` + +- 设计闭环:统计主题、维度、指标与排除项 +- 接口闭环:`IF-REV-010` +- 数据闭环:聚合来源与承接口径 +- 治理闭环:实现评估与正式台账回写 + +## 6.2 feature 之间怎么拼 + +系统大闭环不是再额外建一个“超级文档”,而是依靠四类统一机制把它们接起来: + +1. 主文档统一 +所有结论最终回到 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` + +2. 台账统一 +重要动作回写 `01_Project_Progress.md`、`03_Task_Checklist.md` + +3. 接口统一 +各 feature 都落到同一套 `IF-*` 体系中 + +4. 数据承接口径统一 +不让每个 feature 各自发明自己的状态、日志、承接模型 + +这四类统一机制的作用就是: + +**让上一个闭环的输出,自动成为下一个闭环的稳定输入。** + +--- + +## 7. 当前系统视角下的真实判断 + +### 7.1 哪些 feature 已经是“稳定能力块” + +- `REV-004`:是,文档与治理层面已稳定 +- `REV-005`:是,已形成实现态稳定能力块 +- `REV-006`:是,设计与治理层面已稳定 +- `REV-007`:是,设计与治理层面已稳定 + +### 7.2 哪些 feature 还不是“完整业务闭环” + +- `REV-004`:还不是完整实现闭环,因为代码侧尚未启动 +- `REV-006`:还不是完整实现闭环,因为 backend 仍未见明确实现 +- `REV-007`:还不是完整实现闭环,因为代码入口仍未见明确实现 +- `REV-005`:最接近完整业务闭环,但仍缺运行态样本、联调统计与物理 DDL 风险闭合 + +### 7.3 当前系统最大的断点在哪里 + +当前最大的断点不是设计断点,而是: + +**设计闭环与实现闭环之间的转换断点。** + +换句话说: + +- `REV-006` 和 `REV-007` 都已经具备进入实现的前置条件 +- 但还没有真正转成 backend 可验证的实现链 + +这说明现在系统推进的主矛盾,已经不是“要不要继续补文档”,而是: + +**哪一块设计基线应当最先转成实现闭环。** + +--- + +## 8. 面向“系统实现”为目标的优先级建议 + +## 8.1 第一优先级:完成 `REV-005` 的 verify 收口 + +原因: + +- 它是四个 feature 里唯一已经深入到 backend implement 的 +- 再补少量运行态证据,就能形成最完整的一条真实业务闭环 +- 这会给后续 feature 提供一个“设计如何转实现、实现如何转验证”的标准样板 + +建议优先补: + +- 运行态联调样本 +- `T055`、`T060 ~ T063` 对应的验证记录 +- `biz_invoice` 物理 DDL / migration 风险的最终判断 + +## 8.2 第二优先级:启动 `REV-006` 的 backend 最小实现闭环 + +原因: + +- `REV-006` 已完成 `spec -> plan -> tasks -> implement(文档)` 全链条 +- 它适合作为“从设计闭环转实现闭环”的下一块 +- 相比 `REV-007`,它更直接落在业务控制与消息协同链上,更贴近真实业务运行 + +最小切入建议: + +- 先做催缴对象生成 +- 再做通知事件触发 +- 再做结果回写 +- 最后做停复水边界联动 + +## 8.3 第三优先级:评估 `REV-004` 二期还是 `REV-007` 实现入口 + +这一步要看你的系统目标偏哪边: + +- 如果更偏“业务控制完善”,优先 `REV-004` +- 如果更偏“经营观察与管理看板”,优先 `REV-007` + +当前从系统运行价值看,我更建议: + +**`REV-004` 优先于 `REV-007`。** + +原因是: + +- `REV-004` 会影响退款、冲正、坏账、账务状态与留痕一致性 +- 这是多个后续流程共享的控制骨架 +- `REV-007` 的价值也高,但它更偏“看清系统”,不是“先让系统可控” + +--- + +## 9. 一个可以直接执行的推进顺序 + +如果以“尽快把系统大闭环往前推”为目标,建议按下面顺序推进: + +```text +第一步:补完 REV-005 verify 收口 + 目标:形成第一条最完整的实现态业务闭环 + +第二步:启动 REV-006 backend 最小实现 + 目标:把设计闭环成功转成协同实现闭环 + +第三步:启动 REV-004 二期实现 + 目标:把账务控制骨架从文档闭环转成实现闭环 + +第四步:启动 REV-007 最小查询实现 + 目标:让经营观察能力从“设计已定义”进入“查询可验证” +``` + +这条顺序的逻辑是: + +- 先拿 `REV-005` 固化“实现闭环样板” +- 再拿 `REV-006` 证明“设计闭环可转实现闭环” +- 再拿 `REV-004` 固化系统控制骨架 +- 最后拿 `REV-007` 打开经营观察能力 + +--- + +## 10. 结论 + +当前仓库已经不是“还在摸索 feature 是什么”,而是已经形成了四块明确的系统能力板块。 + +真实状态可以概括为: + +- `REV-004`:账务控制骨架已闭合,待转实现 +- `REV-005`:实现链最完整,待补运行态证据 +- `REV-006`:协同设计已闭合,待转实现 +- `REV-007`:统计设计已闭合,待转实现 + +因此,从系统大闭环视角看,下一阶段最重要的事情不是继续横向铺更多 spec,而是: + +**把已经完成设计闭环的能力块,逐步转成实现闭环。** + +这就是当前从“文档治理阶段”走向“系统实现阶段”的真正分水岭。 + +--- + +## 11. 参考依据 + +本文基于以下仓内工件整理: + +- `specs/001-rev004-accounting/` +- `specs/002-rev005-invoice-flow/` +- `specs/003-rev006-reminder-event-design/` +- `specs/004-rev007-revenue-statistics-design/` +- `docs/design/00_Management/01_Project_Progress.md` +- `docs/design/00_Management/03_Task_Checklist.md` +- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`