fmode-app/templates/er-diagram-guide.md

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 图是同步视图)

• 表名与字段名与数据库一致;主键/外键关系用关系线标注

  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/

• 泳道 = 角色/系统;用于展示多角色协作流程

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

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

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 }

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

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

五、绘图要点

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