tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity

docs: add speckit workflow and capability map guides

Browse Source
This commit is contained in:
tangweijie 2026-03-27 10:12:14 +08:00
parent c85550ffde
commit 6538379f1e
3 changed files with 1228 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/README.md
View File

@ -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. 其他辅助资料
## 维护原则

888
docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md Normal file
View File

@ -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 的输入？
只要这三个问题一直答得清楚，系统级大闭环就会自然长出来。
反过来说，如果这三个问题答不清楚，就算团队一直在干活，也很容易变成“局部热闹，整体失控”。

335
docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md Normal file
View File

@ -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`