System Design Doc

---
name: system-design-doc
description: 为后端系统编写或更新系统设计文档，包含系统上下文图与系统结构图（Mermaid），说明系统与用户、外部系统、内部模块和中间件之间的关系。用户说「画架构图」「上下文图」「系统结构图」「写系统设计」「架构文档」，或新系统立项、系统依赖发生变化时使用。只设计单个模块的数据库或缓存时改用 db-schema-design 或 cache-design。
---

# 系统设计文档

目的是让研发、测试、产品、运维对同一个系统有一致的认识。文档随需求迭代更新，依赖关系变化时必须同步修改两张图。

文件位置：`docs/design/<系统>-architecture.md`。图用 Mermaid 写在 Markdown 中，便于随代码评审与版本管理。

## 1. 收集信息

从代码（`go.mod`、配置文件、客户端初始化代码、路由注册）中查出实际依赖，查不到的再问用户：

- 系统的使用者：C 端用户、B 端用户、内部运营人员等
- 调用本系统的外部系统，以及本系统调用的外部系统；每条依赖的协议（HTTP/JSON、gRPC、消息队列）和同步或异步
- 系统内部的进程或模块、各自的职责与技术栈，以及使用的数据库、缓存、消息队列
- 依赖的公共服务：日志、配置中心、调度、告警等

## 2. 系统上下文图

描述当前系统与其用户以及所依赖系统之间的关系。当前系统画成一个整体，不展开内部。

```mermaid
flowchart TB
  cu([C 端用户]) -->|HTTP/JSON| x
  bu([B 端用户]) -->|HTTP/JSON| x
  a[系统 A] -->|HTTP/JSON| x
  x[["当前系统<br/>一句话职责"]]
  x -->|HTTP/JSON| f[系统 F]
  x -.->|RabbitMQ/JSON| d[系统 D]
```

约定：

- 实线箭头为同步依赖，虚线箭头为异步依赖；箭头方向表示调用方向（A → B 表示 A 调用 B）。
- 每条线标注「协议/数据格式」。
- 每个节点写系统名和一句话职责。

## 3. 系统结构图

描述系统内部的进程、模块与中间件之间的组成关系。

```mermaid
flowchart TB
  web["前台<br/>Node.js"] -->|HTTP/JSON| gw["网关<br/>Go"]
  gw -->|HTTP/JSON| sa["订单服务<br/>Go / FiberHouse"]
  gw -->|gRPC| sb["库存服务<br/>Go / Gin"]
  sa --> mysql[(MySQL)]
  sa --> redis[(Redis)]
  sb --> mongo[(MongoDB)]
  sa -.->|Kafka| sb
  subgraph 公共服务
    log[日志] --- conf[配置中心] --- alarm[告警]
  end
```

约定：

- 每个模块节点写名称、职责和技术栈（语言 / 框架）；子模块要标出所属的父模块（用 `subgraph`）。
- 数据库、缓存、消息队列用圆柱节点 `[(...)]`，并标出连接方式。
- 用 `subgraph` 区分前台、后台、公共支撑服务等层次。

## 4. 文档其他内容

两张图之后依次写：模块职责表、关键流程（必要时用时序图）、数据存储（链接到 `db-schema-design` 产出的文档）、非功能需求（容量、可用性、监控）、待决问题。重大选型另写 ADR：`docs/adr/NNNN-<标题>.md`。

写完后核对：图中每条依赖在代码或配置中都能找到对应；代码中的每个外部依赖在图中都有体现。