chore(repo): reinitialize repository

2026-03-18 11:29:54 +08:00
commit 24871e213a
288 changed files with 44369 additions and 0 deletions
@@ -0,0 +1,380 @@
+# Inbox V2 P1
+
+本文档定义 `inbox v2` 的 `P1` 范围。  
+`P1` 只包含“独立模块”。
+
+这里的独立模块，不是指“所有包彼此完全隔离”，而是指：
+
+- 不依赖 `store`、`runtime`、`agent runner`、`HTTP route`、`app service`
+- 可以单独实现、单独测试
+- 可以作为后续 `HTTP`、`app service`、`store`、`client` 的公共基础
+- 允许按分层方向依赖更底层的 `P1` 模块
+
+换句话说：
+
+- `P1` 要先固定“底层规则和模型”
+- `P1` 不要先混入“流程装配和基础设施”
+- `P1` 内部允许存在清晰的自底向上依赖
+
+`P1` 的目标不是先把服务跑起来，而是先把最底层、最稳定、最可复用的规则和模型固定下来。
+
+数据库设计草案见 [docs/inbox-v2-database.md](./inbox-v2-database.md)。
+
+## 背景
+
+`inbox v2` 的主线已经明确：
+
+- `HTTP` 是唯一业务入口
+- `server` 是唯一正式启动入口
+- `CLI` 只是给 AI 使用的 `HTTP` 封装
+- `clarifier` 角色移除
+- `product` 接管需求整理，并继续输出：
+  - `PRD`
+  - `Decision Log`
+- `discovery` 保留
+- 交互路径暂时保持：
+  - discovery
+  - 需求整理
+  - pool
+  - workflow
+
+在这条主线下，最先该实现的不是 server，也不是 client，而是底层独立模块。
+
+## P1 设计原则
+
+1. `P1` 模块必须独立于基础设施层，但允许依赖更底层的 `P1` 模块。
+2. `P1` 模块优先承载“稳定规则”，而不是“流程编排”。
+3. `P1` 模块一旦定型，后续 `P2/P3` 都应复用它们，而不是复制一份。
+4. `P1` 模块必须有单元测试。
+5. `P1` 不实现 HTTP route、不实现 runtime 装配、不实现数据库。
+
+## P1 分层
+
+为了让后续实现可落地，`P1` 采用下面这套分层：
+
+| 层级 | 类型 | 可以依赖 |
+| --- | --- | --- |
+| `L0` | 基础工具 | Go 标准库 |
+| `L1` | 文档规范 | `L0` + Go 标准库 |
+| `L2` | 核心领域 | `L0/L1` + Go 标准库 |
+| `L3` | 领域组合规则 | `L0/L1/L2` + Go 标准库 |
+
+约束只有一条：
+
+- 依赖只能向下，不能横向乱连，更不能回依赖 `P2/P3`
+
+## P1 模块清单
+
+下面这些是 `inbox v2` 第一阶段应先落下的独立模块。
+
+| 模块 | 建议路径 | 作用 | 说明 |
+| --- | --- | --- | --- |
+| 时间模块 | `internal/base/timeutil` | UTC 时间、标准时间格式、可注入 clock | 给记录、文档更新时间、事件时间统一格式 |
+| 标识符模块 | `internal/base/idgen` | topic / message / requirement / merge request 等 ID 生成规则 | 先固定命名和生成策略 |
+| slug 模块 | `internal/base/slug` | topic、workspace、project 的 slug 规范化 | 这是所有上层都会复用的基础规则 |
+| HTTP 通用模块 | `internal/base/httpx` | 状态错误、JSON 编解码、通用响应封装 | 只做 transport 基础工具，不做具体业务 |
+| 文档模板模块 | `internal/domain/docspec` | `PRD`、`Decision Log`、Discovery request/result 的模板与渲染规则 | `product` 将直接依赖它 |
+| 消息模块 | `internal/domain/message` | message envelope、front matter 解析、渲染、收件人规则 | 统一所有消息文档格式 |
+| Topic 模块 | `internal/domain/topic` | topic 的 space/status 生命周期规则 | 明确 clarify/pool/workflow/discovery 的推进规则 |
+| Role 模块 | `internal/domain/role` | 角色分类、角色定义、角色能力边界 | 包括 `product`、`backend`、`frontend`、`reviewer`、discovery 系列 |
+| Requirement 模块 | `internal/domain/requirement` | requirement 的结构、状态、优先级与验证规则 | pool 的结构化实体先独立出来 |
+| Discovery 模块 | `internal/domain/discovery` | discovery 提案、投票、共识计算、结果文档规则 | 保留 discovery 的核心领域逻辑 |
+| Workflow 模块 | `internal/domain/workflow` | workflow 阶段枚举、阶段合法流转、角色协作规则 | 只管规则，不管看板聚合 |
+| Merge 模块 | `internal/domain/merge` | merge request 状态、元数据结构、状态流转规则 | 只管领域规则，不管 git 命令 |
+
+## P1 依赖关系
+
+下面是建议的依赖方向。
+
+| 模块 | 层级 | 可依赖模块 |
+| --- | --- | --- |
+| `timeutil` | `L0` | 无 |
+| `slug` | `L0` | 无 |
+| `idgen` | `L0` | `timeutil`, `slug` |
+| `httpx` | `L0` | 无 |
+| `docspec` | `L1` | `timeutil` |
+| `role` | `L2` | 无 |
+| `topic` | `L2` | `slug` |
+| `workflow` | `L2` | `role`, `topic` |
+| `requirement` | `L2` | `slug` |
+| `merge` | `L2` | `timeutil`, `idgen`, `slug` |
+| `message` | `L3` | `role`, `topic`, `workflow`, `slug`, `timeutil` |
+| `discovery` | `L3` | `role`, `docspec`, `idgen`, `timeutil`, `slug` |
+
+这张表的意义是：
+
+- `P1` 仍然是独立模块集合
+- 但不是人为禁止复用
+- 后续实现时可以从 `L0` 往上逐层推进
+
+## P1 模块详细职责
+
+### 1. `timeutil`
+
+负责：
+
+- `NowUTC()`
+- RFC3339 / RFC3339Nano 格式化
+- 可注入 clock
+
+不负责：
+
+- 调度
+- 轮询
+- timeout 策略
+
+### 2. `idgen`
+
+负责：
+
+- message ID 规则
+- requirement ID 规则
+- merge request ID 规则
+- discovery round ID / candidate ID 规则
+
+不负责：
+
+- 数据库存储
+- 去重查询
+
+### 3. `slug`
+
+负责：
+
+- topic slugify
+- workspace slugify
+- project slugify
+- 安全截断规则
+
+不负责：
+
+- 校验是否重名
+- 路径解析
+
+### 4. `httpx`
+
+负责：
+
+- `WriteJSON`
+- `WriteError`
+- `ErrorWithStatus`
+- 通用 JSON decode 辅助
+- CORS 等通用 transport helper
+
+不负责：
+
+- route 注册
+- 业务 request/response
+
+### 5. `docspec`
+
+这是 `P1` 里非常关键的模块。
+
+负责：
+
+- `PRD` 模板
+- `Decision Log` 模板
+- Discovery request 文档格式
+- Discovery result 文档格式
+- 文档 front matter 规范
+- 文档固定章节顺序
+
+不负责：
+
+- 文档存储
+- 文档版本管理
+- 文档归属权限
+
+这里要明确：
+
+- 第二版中 `product` 会直接使用 `PRD` 和 `Decision Log`
+- 模板沿用当前澄清模板，但所有权从 `clarifier` 转到 `product`
+
+### 6. `message`
+
+负责：
+
+- message envelope 结构
+- YAML front matter 解析
+- markdown 渲染
+- `from / to / type / topic / stage / reply_to / round` 规则
+- 收件人解析
+- 基础合法性校验
+- 面向消息文档的稳定结构定义
+
+不负责：
+
+- 消息存储
+- mailbox 查询
+- HTTP handler
+
+### 7. `topic`
+
+负责：
+
+- topic `space`
+  - `clarify`
+  - `pool`
+  - `workflow`
+  - `discovery`
+- topic `status`
+- space/status 的默认值
+- 合法推进规则
+- “能升不能降”之类的基础约束
+
+不负责：
+
+- topic record 存储
+- topic 列表聚合
+
+注意：
+
+虽然 v2 去掉 `clarifier` 角色，但 `clarify` 这个对话整理阶段可以在兼容期继续存在；只是它背后的角色从 `clarifier` 变成 `product`。
+
+### 8. `role`
+
+负责：
+
+- 角色枚举和分类
+- 角色合法性校验
+- 角色阶段边界
+- 哪些角色属于 discovery
+- 哪些角色属于 workflow
+- `product` 的正式职责定义
+
+不负责：
+
+- role 存储
+- role 技能绑定
+
+### 9. `requirement`
+
+负责：
+
+- requirement 结构
+- requirement 状态
+  - `pending`
+  - `dispatched`
+  - `completed`
+  - `archived`
+- 优先级范围和校验
+- requirement 文本字段校验
+
+不负责：
+
+- requirement 查询
+- requirement dispatch 执行
+
+### 10. `discovery`
+
+负责：
+
+- discovery candidate 结构
+- vote 结构
+- 共识判断
+- result markdown 生成
+- discovery request 文本格式规则
+- discovery 阶段的固定角色集合规则
+
+不负责：
+
+- 并发执行
+- codex 调用
+- round 持久化
+
+### 11. `workflow`
+
+负责：
+
+- workflow 阶段枚举
+  - `plan`
+  - `review`
+  - `execution`
+  - `verification`
+- workflow 阶段流转规则
+- workflow 角色协作边界
+- workflow 消息的基础规则
+
+不负责：
+
+- workflow board 聚合
+- dispatch 查询
+
+### 12. `merge`
+
+负责：
+
+- merge request 结构
+- merge request 状态流转
+- merge metadata 规则
+
+不负责：
+
+- git diff
+- merge 命令执行
+
+## P1 明确不做的东西
+
+下面这些不属于 `P1`：
+
+- `server`
+- `client`
+- `http route`
+- `app service`
+- `store`
+- `runtime`
+- `agent runner`
+- `workflow board`
+- `pool dispatch`
+- `merge` 的 git 执行
+
+这些模块都依赖更高层或外部设施，不属于独立底层模块。
+
+## P1 实现顺序
+
+建议顺序如下：
+
+1. `timeutil`
+2. `slug`
+3. `idgen`
+4. `httpx`
+5. `docspec`
+6. `role`
+7. `topic`
+8. `workflow`
+9. `requirement`
+10. `merge`
+11. `message`
+12. `discovery`
+
+原因很简单：
+
+- 先做通用基础能力
+- 再做文档规范
+- 再做核心领域规则
+- 最后做组合型领域模块
+- 最后才进入 `P2` 的 `server/app/store`
+
+## P1 输出结果
+
+`P1` 完成后，应该得到这些结果：
+
+1. 一组独立于基础设施的底层模块。
+2. 一组稳定的领域结构、模板和状态流转规则。
+3. 第二版可以明确复用的文档标准：
+   - `PRD`
+   - `Decision Log`
+   - Discovery request
+   - Discovery result
+4. 一套从 `L0 -> L3` 的清晰依赖方向。
+5. 后续 `P2` 实现 `HTTP server` 和 `app services` 时，不再需要重新发明这些规则。
+
+## P1 完成标准
+
+满足下面条件，`P1` 才算完成：
+
+1. 上述每个模块都有明确目录。
+2. 每个模块都有单元测试。
+3. 每个模块都只依赖下层 `P1` 模块，不依赖任何 `P2/P3` 模块。
+4. 文档模板和领域规则已经固定。
+5. `product` 接管需求文档这一决策已经在底层模型中可以表达。