rd-design git:20261009.a01d3dfA

Immutable. This exact content never changes and is served at /api/v1/blob/43ef3341c161abed.

---
name: rd-design
description: >-
  根据已批准需求和架构决策形成可进入实现阶段的详细设计。当软件或基础设施需要规定
  接口契约、数据模式、关键流程、状态机、配置契约、信任边界、错误、安全、可观测性、
  并发或恢复行为时使用。需求、方案选择、评审、代码实现和运行执行分别路由到其责任工作流。
---

# rd-design

基于已确认需求和技术方案产出**可进入建设阶段的详细设计**——接口定义、数据模型、关键流程、错误处理、安全设计和并发控制。

## 交付物

- 详细设计文档（接口 / 数据模型 / 流程 / 状态机）
- API 契约定义（OpenAPI / Protobuf / GraphQL Schema）
- 数据库 Schema 设计
- 安全、错误处理和可观测性设计章节
- 基础设施或集成相关任务的配置、迁移、核验和回退契约

## 执行步骤

步骤、基线读取和质量门禁仅适用于本次授权的设计范围。不适用维度应简述基于风险的理由，不得为满足清单而新增接口、数据模型或控制。

### 1. 设计输入确认

- 确认已批准需求以及重要技术方案或概要设计（`rd-solution` 产出）
- 提取已确定的：架构决策、技术栈选型、约束条件
- 识别设计范围边界：本次设计覆盖哪些模块/服务
- 确认设计项可追溯到 PRD 或已批准的设计决策
- 修订既有设计时，将每项文字改动分类为已确认的语义澄清或未解决契约；在批准证据支持更具体的责任、顺序、成功条件或恢复行为前，保留来源的抽象层级

**完成标准：** 每个范围内设计项均可追溯到已批准需求或决策；详细契约起草前，缺失的上游决策均已明确；修订工作将每项歧义映射为已批准含义或确切缺失的契约。

### 2. 接口设计

- 定义模块间接口契约（入参、出参、不变式、前置条件、后置条件、错误码、顺序和幂等性要求）
- 内部接口与外部接口分别标注
- API 版本策略说明
- 接口变更的向后兼容性约束

**完成标准：** 每个接口均有归属、输入、输出、不变式、失败行为、适用时的顺序或幂等语义，以及兼容性边界。

### 3. 数据模型设计

- 实体关系图（ER Diagram），标注主键、外键、索引
- 字段级设计：类型、长度、约束、默认值、是否可空
- 数据生命周期：创建 → 更新 → 归档 → 删除
- 数据一致性策略：强一致 / 最终一致 / 补偿

**完成标准：** 每个持久化或交换数据元素均有类型与约束语义、生命周期归属、适用时的关系或索引理由，以及明确的一致性模型。

### 4. 关键流程设计

- 核心业务流程的时序图或流程图
- 每个流程标注：正常路径、异常路径、超时处理
- 并发控制策略：锁类型、乐观/悲观、重试策略
- 幂等性设计：哪些操作必须幂等，如何保证

**完成标准：** 每个关键流程均覆盖成功、失败、超时、重试、并发和幂等行为，尤其是会改变系统状态的边界。

### 5. 状态机设计（如适用）

- 状态定义与合法转换
- 无效转换的处理策略
- 并发状态修改的冲突解决

**完成标准：** 每个状态和合法转换均有触发条件、守卫条件、效果、非法转换处理和并发冲突规则；不适用时已明确说明。

### 6. 安全性设计

通用软件安全设计要点：

| 维度 | 设计内容 |
|------|---------|
| 身份认证 | 认证方式选型、多因素认证需求、Token 过期策略 |
| 授权控制 | 权限模型（RBAC/ABAC）、最小权限原则 |
| 信任边界 | 参与者、区域、数据流、威胁假设和滥用场景 |
| 输入校验 | 校验规则、白名单/黑名单策略、注入防护 |
| 数据保护 | 数据分级、最小化、传输/存储加密、保留和日志脱敏 |
| 接口安全 | 速率限制、签名验证、CORS 策略 |
| 密钥与凭据 | 归属、存储、轮换、吊销和泄露处置 |
| 可审计性 | 审计事件、追踪链路、日志保留、敏感字段脱敏 |

**完成标准：** 每个信任边界和受保护资产均映射到适用的认证、授权、校验、保护、密钥或凭据、滥用场景和审计控制；未采用的控制已有基于风险的理由。

### 7. 错误处理设计

- 错误分类：可恢复 / 不可恢复 / 需人工介入
- 错误码体系设计
- 错误传播策略：向上传播 / 本层处理 / 降级
- 监控与告警触发条件

**完成标准：** 每类重要故障均有归属、传播或降级行为、用户或调用方可见性、可观测性，以及恢复或升级语义。

### 8. 配置与变更设计（如适用）

- 定义配置归属、唯一权威来源、模式、默认值、校验规则、环境差异和优先级
- 将密钥与普通配置分离，并定义凭据提供、轮换、吊销和脱敏边界
- 定义迁移阶段、兼容窗口、回退条件、恢复点和状态对账
- 规定预期观察和核验标准，但不把设计文档写成执行操作手册

**完成标准：** 配置与变更行为具有唯一权威来源、优先级和校验规则、凭据边界、兼容与回退条件，以及可观察的核验标准；不适用时已明确说明。

### 9. 设计验证说明

- 定义评审方如何验证设计：追踪矩阵、检查清单、走查、原型或外部标准核验
- 未决设计项必须标注决策依赖、核验动作，以及已知负责人或目标日期；未知时标记为待指定或待确认
- 标出进入实现前必须验证的假设

**完成标准：** 评审方能够核验每项重要契约和追踪关系；所有未决事项均有分配状态、依赖和核验动作。

## 上下文与基线检查

仅阅读下列约束本次范围内设计的基线：
- 项目设计规范和命名约定
- 已有的接口设计规范和 API 风格指南
- 数据库设计规范（命名、索引、分区策略）
- 已固化的架构决策
- 安全、隐私、合规或标准规范对设计的约束

## 工具选择

- 优先检查已批准需求、架构决策、数据模式和本地约定
- 仅当外部标准或当前技术事实的重要证据缺口需要专门研究时，使用 `rd-research`；复用已检查且仍具时效性和适用性的证据，常规来源核对留在设计流程内
- 仅在核实当前框架、库、SDK 或 API 行为时使用 Context7 或同类文档检索能力
- 外部仓库设计只能作为示例，必须结合本系统约束验证适用性

## 质量门禁

交付前核查：

- [ ] 接口契约完整（入参/出参/错误码/幂等性）
- [ ] 数据模型的规范化或反规范化选择有理由说明
- [ ] 关键流程覆盖正常/异常/超时路径
- [ ] 并发和幂等需求已处理
- [ ] 适用的安全控制已覆盖，包括相关的认证、授权、输入校验和数据保护；未采用的控制有基于风险的理由
- [ ] 错误处理策略明确
- [ ] 适用时已明确配置、迁移、恢复和回退契约
- [ ] 设计可追溯到需求（每个模块可关联到需求项）
- [ ] 未决设计项具有分配状态、依赖、核验动作，以及已知负责人或目标日期
- [ ] 文本使用明确的领域术语，并在影响实现或评审时显式说明因果、条件、转折和时序关系；结合上下文修改含混、口语化或比喻性表达，且不改变约定术语、标识符、引文、规范强度或追踪关系；搜索可用于定位和复核，机械替换仅用于所有受影响位置均已确认语义等价的情形；上下文不能确定预期含义时，保留已确认内容的抽象层级，只记录确切缺失的契约或决策依赖
- [ ] 文档细度足以支持评审方判断可行性和一致性

## 不做

- 只有缺少的上游决策会使关键设计契约必须猜测时才暂停。不存在重要架构选择时，已批准需求可以作为充分输入；非阻塞未知项应记录负责人和核验动作，并继续可独立确定的设计工作
- 不留下无核验动作、无明确分配状态的“待定”
- 不设计不会用到的抽象层
- 不写实现代码、测试、部署命令或运维操作手册