# ER 图与业务图规范(mermaid)

> 用途:docs/02-design/database/ER-图.md、docs/02-design/architecture/泳道图与时序图。所有图统一用 mermaid 写在 markdown 中,禁止使用外部工具导出的静态图片(无法随文档维护)。

## 一、ER 图规范(表结构)

- 文件位置:`docs/02-design/database/ER-图.md`(fmode 平台项目亦可直接以 `docs/schema/` PlantUML 范式为准)
- 与 FmodeSchema 建表脚本保持同步(脚本与范式是单一事实源,ER 图是同步视图)
- 表名与字段名与数据库一致;主键/外键关系用关系线标注

```mermaid
erDiagram
    USER ||--o{ ORDER : "下单"
    ORDER ||--|{ ORDER_ITEM : "包含"
    USER ||--o{ COURSE : "拥有"

    USER {
        string objectId PK
        string username
        string displayName
        string role
        boolean isDeleted
        date createdAt
        date updatedAt
    }
    ORDER {
        string objectId PK
        string userPointer FK
        string status
        number totalAmount
        boolean isDeleted
    }
    ORDER_ITEM {
        string objectId PK
        string orderPointer FK
        string coursePointer FK
        number price
    }
```

## 二、业务泳道图规范(跨角色流程)

- 文件位置:`docs/02-design/architecture/`
- 泳道 = 角色/系统;用于展示多角色协作流程

```mermaid
sequenceDiagram
    participant 学员
    participant 销售
    participant 系统
    participant 财务

    学员->>系统: 提交报名
    系统->>销售: 推送待审核任务
    销售->>系统: 审核通过
    系统->>财务: 生成账单
    财务->>系统: 确认收款
    系统->>学员: 报名成功通知
```

## 三、时序图规范(系统内部交互)

```mermaid
sequenceDiagram
    participant UI
    participant API
    participant Service
    participant Parse

    UI->>API: POST /api/v1/orders
    API->>Service: createOrder(payload)
    Service->>Parse: saveAll(orderItems)
    Parse-->>Service: saved
    Service-->>API: order
    API-->>UI: { code:0, data: order }
```

## 四、流程图规范(业务逻辑)

```mermaid
flowchart TD
    A[开始] --> B{是否已登录?}
    B -- 否 --> C[跳转登录页]
    B -- 是 --> D[加载列表]
    D --> E{是否有权限}
    E -- 否 --> F[提示无权限]
    E -- 是 --> G[渲染页面]
    G --> H[结束]
```

## 五、绘图要点

1. 图必须表达真实实现(与代码一致),不画"理想状态";
2. 每次实现/数据结构变更,同步更新对应图(属变更传播链一环);
3. 图内文字使用中文;实体/表名用英文与代码一致;
4. 大图拆多张小图,避免一张图塞全部细节。