# SDD · MVCP 总览

> SDD（System Design Document）用 **MVCP 四象限**组织：**M**odel · **V**iew · **C**ontrol · **P**rocess。每个象限是一篇独立页，每个定义带 **name / path / shape / contract / tests** 五字段。Claude Code 用 cheerio 即可机械抽取。

## 为什么是 MVCP 而不是 MVC

传统 MVC 三分对一个有大量「长进程 / 异步循环」的系统不够用。DevLoop 系统里：

- L1/L2/L3 是**长时运行的状态机**
- 每个 Agent 是**长寿子进程**（ACP session 复用）
- SSE Broker 是**持续推送通道**

这些都不属于 Controller（即时响应请求），也不属于 Model（数据）。给它们一个独立象限 **Process** 才有归处。

## 四象限

<!-- 图见原 HTML -->

## 每个定义的「五字段标准」

所有 MVCP 页里的每条定义都强制遵循下表结构，便于 Claude Code 用同一套抽取器处理：

| 字段 | 类型 | 含义 | 抽取选择器 |
| --- | --- | --- | --- |
| **name** | string · 必填 | 唯一标识符 · 命名空间.对象名 | `section[data-def-name]` |
| **path** | string · 必填 | 预期落盘路径或文件位置 | `[data-def-name] code.path` |
| **shape** | code · 必填 | TypeBox / TS interface / Vue defineProps / SQL DDL | `[data-def-name] pre.shape` |
| **contract** | list · 选填 | 前置 / 后置条件 / 不变式 | `[data-def-name] ul.contract li` |
| **tests** | list · 选填 | 验收用例（Tester Agent 直接转 vitest） | `[data-def-name] ul.tests li` |

### HTML 模板示例

```js

  
### DocStore.writePRD(pid, html)

  `server/services/doc-store.js`

  
```
async function writePRD(pid: string, html: string): Promise<{rev: number}>
```

  
- 前置：html 必须包含顶级 article[data-doc="prd"]
- 后置：旧版本归档到 history/prd-rev-{rev}.html

  
- tests: 写入后 readPRD 能读回完全一致内容
- tests: 非法 HTML 抛 ValidationError

```

> _本套文档因美观需要不完全遵守这个最严格的 HTML 模板，但每条定义至少含 name + path + shape。完全机械化版会在 P1 实施时由 Architect Agent 产出。_

## 抽取流程

```js
// Claude Code 抽取 build-manifest 的伪代码
const manifest = { model: [], view: [], control: [], process: [] };
for (const mvcp of ['model', 'view', 'control', 'process']) {
  const html = await fetch(`sdd-${mvcp}.html`).then(r => r.text());
  const $ = cheerio.load(html);
  $('[data-def-name]').each((_, el) => {
    manifest[mvcp].push({
      name:     $(el).attr('data-def-name'),
      path:     $(el).find('code.path').first().text(),
      shape:    $(el).find('pre.shape').text(),
      contract: $(el).find('ul.contract li').map((_,li) => $(li).text()).get(),
      tests:    $(el).find('ul.tests li').map((_,li) => $(li).text()).get(),
    });
  });
}
fs.writeFileSync('build-manifest.json', JSON.stringify(manifest, null, 2));
```

结果是一份 `build-manifest.json`，能直接喂给 Architect Agent 生成 units.json + Unit spec 文件。

## 四象限对应 Agent

| 象限 | 谁负责写 | 谁负责消费 |
| --- | --- | --- |
| Model | Architect | Coder（读 schema 生成数据访问代码）· DocStore（自身实现） |
| View | Architect | Coder（fe 类 Unit 直接对应） |
| Control | Architect | Coder（be 类 Unit）· Integrator（跑端点） |
| Process | Architect | 所有 Agent 都要读懂 Process 才知道自己在生命周期哪一步 |