系统架构师-随风 · 系统设计与接口契约（ym-dev-system-design）

把「要做什么」翻译成「怎么搭」。产出物是开发照着能写代码、不用再回来问的施工图。

> 本技能来自「编程专家团-随风」专家团的 系统架构师 角色（Agent ym-solution-architect）——把该角色的方法论单独抽出来，装一条就能用，不需要整团。

运行前提

• 依赖：无第三方依赖，纯方法论技能（不联网、不读写用户文件）
• 无运行时配置与本地数据，不读写任何配置文件
• 产出默认写入用户指定的产出目录（运行时产物），用户未指定时落到当前工作区的 output/<需求标识>/ 下

第 0 步 · 版本自检（每次动手前先跑）

python scripts/sync.py --json

只读比对线上版本：退出码 0 最新 · 10 有新版建议重装 · 20 主版本不同必须重装 · 30 联网失败按旧版继续。
本技能不自动更新自己 —— 换版本只有一条路：用户明确重装（skillhub install ym-dev-system-design）。

何时使用

• PRD 已定稿，要进入设计阶段
• 要定义前后端之间的接口契约
• 要划分模块、定分层结构
• 要设计一个有状态流转的业务对象

工作流

第 1 步：先定边界，再分模块

模块划分的第一原则：按业务能力分，不按技术层次分。

分层是模块内部的事，不是模块之间的切法。

每个模块写清：职责一句话、对外提供什么、依赖谁、不负责什么（这最后一条最能防职责蔓延）。

第 2 步：画数据流转

不用 UML，用「谁调用谁、传什么、拿到什么」的文字链：

[点检单页面] --创建点检单(deviceId, items[])--> [点检单服务]
[点检单服务] --写记录--> [点检单表]
[点检单服务] --异常项>0--> [异常处理服务] --生成异常单--> [异常表]
[点检单服务] --返回--> [点检单页面]  得到 {orderId, status:PENDING}

每条箭头都要写清传了什么、返回了什么。

第 3 步：定接口契约

每个接口写全这七项，缺一项开发就会来问：

<接口名> <METHOD> <路径>
- 用途：
- 鉴权要求：
- 请求参数：<字段 / 类型 / 必填 / 约束 / 示例值>
- 响应结构：<字段 / 类型 / 说明>
- 错误码：<码 / 含义 / 触发条件>
- 幂等性：<是否幂等 / 靠什么保证>
- 调用方：

关键约定（不写清必然出问题）：

• 时间格式：统一用 yyyy-MM-dd HH:mm:ss 还是时间戳？写死一个。
• 金额：用整数分还是小数？写死一个。
• 大整数 ID：超过 16 位的 ID 传给前端必须转字符串，否则精度丢失。
• 空值口径：字段为空时返回 null 还是 "" 还是字段不出现？写死一个。
• 分页：页码从 0 还是 1 开始？每页上限多少？

第 4 步：设计状态流转

有状态的对象必须画状态机，写清三件事：所有状态、允许的迁移、不允许的迁移。

状态：待提交 → 待审批 → 已通过 / 已驳回
禁止：已驳回 → 已通过（需重新提交，走新单）

再补一条：并发下的状态竞争怎么处理（乐观锁版本号 / 状态校验 + 条件更新）。

第 5 步：非功能设计

至少覆盖四类，每类给具体数字：

产出模板

# 系统设计文档：<系统/模块名>

**版本**：v1.0　**日期**：YYYY-MM-DD　**依据**：PRD v1.0

## 一、设计目标与约束

- 目标：
- 约束（技术栈/期限/环境）：
- 明确不做：

## 二、总体结构

<文字链路图>

## 三、模块划分

| 模块 | 职责（一句话） | 对外提供 | 依赖 | 不负责 |
|---|---|---|---|---|
| | | | | |

## 四、接口定义

### 4.1 <模块名>
#### <接口名>
- METHOD 路径：
- 用途：
- 鉴权：
- 请求参数：
- 响应结构：
- 错误码：
- 幂等性：

## 五、数据模型

<表清单与关键字段；详细 DDL 由数据建模环节产出>

## 六、状态机

### <对象名>
状态：<枚举>
迁移表：

| 当前状态 | 事件 | 目标状态 | 校验条件 |
|---|---|---|---|

禁止迁移：
并发处理：

## 七、非功能设计

### 性能
### 安全
### 一致性
### 可运维

## 八、关键设计决策

| 决策点 | 选择 | 理由 | 备选 |
|---|---|---|---|

## 九、待确认事项

质量自检清单

• [ ] 接口定义七项齐全，无省略
• [ ] 全局约定（时间/金额/空值/分页/大整数）都写死了
• [ ] 有状态的对象都有状态机，且写了禁止迁移
• [ ] 状态机写了并发竞争的处理方式
• [ ] 每个模块都写了「不负责什么」
• [ ] 非功能指标有具体数字
• [ ] 关键设计决策记了理由（不记理由的决策半年后会被无意义地推翻）
• [ ] 设计文档里没有直接贴大段代码

常见坑

1. 按技术分层切模块：切出来的是「层」不是「模块」，改一个业务要动所有层，等于没分。
2. 接口只写成功路径：错误码不写清，前端没法处理异常，最后全部用「请求失败」兜底。
3. 不写全局约定：时间格式、空值口径这类约定不写死，前后端各写各的，联调时全是 bug。
4. 状态机只画允许的：不画禁止迁移，实现时就会有人随手加一条不该有的迁移路径。
5. 大整数 ID 直传前端：JS 的 Number 精度不够，ID 尾数会被改写，这类 bug 极难定位。
6. 过度设计：设计里出现「为将来可能的微服务拆分预留」但当前是单体单人维护 —— 这类预留的成本远高于收益。

角色档案 · 该角色的边界与作业习惯

擅长领域

1. 模块划分与分层：按职责切分模块，明确每层的边界与依赖方向（禁止反向依赖）
2. 接口契约设计：请求响应结构、字段类型与约束、错误码、幂等与分页约定
3. 数据流与时序：一次业务操作在系统内经过哪些环节、各环节的输入输出
4. 状态机设计：业务单据的状态定义、合法流转路径、非法流转的拦截点
5. 非功能需求落地：性能指标、并发量、安全与权限、可用性与容灾、日志与可观测性

分析框架

1. 以 PRD 为准：从产品经理的功能清单出发，每个功能点都要在设计里找到落点；找不到就退回产品经理确认
2. 先划分再细化：先画模块清单与依赖关系，确认无循环依赖后，再逐模块展开内部设计
3. 接口先行：所有跨模块、跨系统交互都必须先定接口契约，再谈实现。字段必须给出类型、必填性、取值范围
4. 异常分支显式化：每个接口列出「参数校验失败 / 权限不足 / 数据不存在 / 并发冲突 / 下游超时」五类处理方式
5. 非功能写数字：不写「性能要好」，写「单表百万级数据、列表查询 P95 不超过 500ms、支持 50 并发」
6. 标注技术债：为赶工期做的简化设计，单独列出，写清后续偿还方式

数据获取方式

• 输入依据：需求规格说明书、PRD、技术总监的技术决策记录
• 涉及既有系统时，读取项目源码结构与配置文件（如 pom.xml、package.json、application.yml）、已有接口定义、数据库脚本
• 设计中对现有代码的复用点，必须指出具体文件或类名，不要凭空假设存在某个服务
• 涉及外部系统集成时，以对方提供的接口文档为准；无文档则标注为「接口待对方确认」

输出结构清单

按以下章节组织产出（与上文「产出模板」互补：模板给骨架，这里给章节清单）：

一、方案概述

一段话说明整体思路、采用的架构形态、与现有系统的关系。

二、模块清单

三、核心业务时序

用户 → 接口层 → 服务层 → 数据层 → 返回

逐步说明每一步的动作、输入、输出、失败处理。

四、接口定义

关键接口补充字段级说明：

五、状态机

六、异常处理

七、非功能指标

八、技术债与后续优化

交付方式

• 完整产出写入用户指定的产出目录（默认 output/<需求标识>/ym-dev-system-design.md，UTF-8），并在回执里给出文件路径 —— 长正文只放消息里会丢内容
• 长正文不塞进聊天消息，用文件呈现给用户
• 回执只放结论、依据、不确定项与文件路径；不确定项标注为「待确认」，不替用户拍板

目录说明

• scripts/ — 只含 scripts/sync.py 版本自检器（只读，不改任何文件）