---
id: <ID>
kind: design
title: <标题> · 设计与说明
prd: docs/process/prd/<ID>.md
status: draft # draft / confirmed / terminated
gate1: pending
---

# <ID> <标题> · 设计与说明

> **本文件是什么**：把需求**逐条 `R-NN`** 翻译成设计 —— 落在哪个实体 / 字段 / 端点 / 页面 / 交互，用来在进 Gate1 之前拦住「初始偏差」。
> **本文件不是什么**：不是 PRD（判据在 PRD 的 `AC`）、不是契约（字段与签名在 `contracts/<ID>.md`）；**不写实现细节、不写技术选型、不写 SQL / DDL / 迁移方案**。
> **权威来源**：需求核对件的裁定表（`R-NN`）。**不得在此发明新业务口径** —— 需要新口径时回流 PRD 待确认事项，由人裁定。
> `status` 是 design 自有的次级状态位（`confirmed` = Gate1 已过 / 本件已定稿），**不是** PRD 状态机的值；权威状态位只在 `prd/<ID>.md`。

## 当前状态一览

> 一屏内可读完，只写"现在是什么状态"，不留沿革；随每次交付就地更新。

- 对齐进度：`R-NN` 已落实 __ / 偏差 __ / 未落实 __
- 本轮结论：<一句话>
- 阻塞项：<有则列出 / 无>
- 最后更新轮次：<rN>

---

## 一、裁定对齐表（必填，Gate1 逐条核）

> 核对件里的**每一条** `R-NN` 都要出现在此表，**一条不漏**。

| `R-NN` | 裁定（一句话） | 设计如何落实（实体 / 字段 / 端点 / 页面 / 交互） | 状态 |
| --- | --- | --- | --- |
| `R-01` | <一句话> | <落实点> | 已落实 / 偏差 / 未落实 |
| `R-02` | <一句话> | <落实点> | 已落实 / 偏差 / 未落实 |

---

## 二、偏差与未落实项

> **落实不了、或与裁定有出入的，必须在此单列并说明** —— 不得静默略过、不得默默按自己判断改口径。
> 需要改口径时，其裁定必须回流 PRD 待确认事项，由人裁定；本表只登记事实与建议。

| # | 对应 `R-NN` | 偏差 / 未落实内容 | 原因 | 影响面 | 建议处置 |
| --- | --- | --- | --- | --- | --- |
| `D-1` | <R-NN> | <内容> | <原因> | <影响面> | <建议> |

---

## 三、方案与取舍

> 这一段回答「**为什么这样设计**」：在若干可行设计之间选了什么、放弃了什么、代价是什么。
> 只写**设计与契约层**的取舍（形态 / 边界 / 归属 / 兼容性），**不写技术选型**，也不写实现步骤。

| # | 议题 | 候选方案 | 选定与理由 | 放弃项的代价 |
| --- | --- | --- | --- | --- |
| `T-1` | <设计议题> | A / B / C | **选定 X** —— <理由> | <代价> |

### 3.1 端到端主流程

> 「谁 → 在什么场景 → 做什么」逐步写，作为验收的预期对照。

1. <步骤>
2. <步骤>

### 3.2 前端交互

> 各端（`<app-a>` / `<app-b>` / `<app-c>` / 智能体）各自的入口、组件、跳转、空态与异常态。

- `<app-a>`：<入口 / 交互 / 空态 / 异常态>
- `<app-b>`：<…>
- `<app-c>`：<…>

---

## 四、数据 / 接口影响

> 只描述**契约层影响**并与契约互指，**不复制判据字面、不写 SQL / DDL / 索引实现 / 迁移方案**。

### 4.1 数据模型影响

| 实体 | 字段 | 类型 | 约束 / 取值 | 影响（新增 / 修改 / 复用） |
| --- | --- | --- | --- | --- |
| <实体> | <字段> | <类型> | <约束> | 新增 / 修改 / 复用 |

> 若触及数据层（schema 变更）：在此写明**列变更 / 是否需数据补偿 / 回滚方式**，并在 Gate 摘要里显式提请人点头。

### 4.2 接口形态影响

| 端点 | 方法 | `alignment` | 影响说明 |
| --- | --- | --- | --- |
| `<路径>` | `<METHOD>` | `keep` / `change` / `new` | <出入参要点；复用字段须与现行 schema 命名一致> |

### 4.3 权限与数据范围

> 权限码、鉴权口径、数据可见范围（组织 / 区域 / 个人）分别写清；引用 PRD §8 的权限码清单。

- 权限码：<逐条>
- 鉴权口径：<…>
- 数据可见范围：<…>

---

## 五、非目标

> 与需求核对件的「明确不做」保持一致；**本文件新增的不做项须注明原因**。

| # | 不做项 | 来源（核对件 / 本文件新增） | 原因 |
| --- | --- | --- | --- |
| `N-1` | <不做项> | 核对件 / 本文件 | <原因> |

---

## 六、风险与回退

> 每条风险必须给**回退方式**：出问题时回到哪个已知良态、由谁执行、要多久。只写风险不给回退 = 未完成。

| # | 类型 | 内容 | 触发条件 | 回退 / 缓解 |
| --- | --- | --- | --- | --- |
| `R-1` | 风险 | <内容> | <触发条件> | <回退方式> |
| `D-1` | 依赖 | <内容> | — | <影响> |

---

## 七、变更记录

| 版本 | 日期 | 修改人 | 修改内容 | 状态流转 |
| --- | --- | --- | --- | --- |
| 1 | <YYYY-MM-DD> | <角色> | 初稿 | — → draft |
