软件设计编写范式

核心原则

范式与数据分离 — skill 定义的是设计范式（模板结构+拆分策略+质量标准），
领域知识从需求规格文件和 _metadata.md 动态读取，不写死在 skill 中。

大文档拆分，小批量处理 — 单次调用只处理一个系统的一个阶段（概要或详细），
详细设计按子模块拆分，每次只处理 1 个子模块（通常 2-6 个功能点），
确保输入和输出都在可控范围内。

从需求到设计的可追溯 — 每个设计产物必须标注对应的需求编号（S0N-XXX），
每张数据库表必须追溯到业务对象编码（BO-0N-XXX），
每个API必须追溯到用例编码（U-0N-XXX-XX）。

三阶段架构

┌─────────────────────────────────────────────────────────┐
│  Phase 0: 设计元数据生成（每个项目执行一次）               │
│                                                           │
│  输入：_metadata.md + 扫描各系统需求规格（只读摘要）        │
│      ↓                                                    │
│  分析：技术选型 → 设计规范 → 公共组件 → 拆分计划           │
│      ↓                                                    │
│  输出：_design_metadata.md + 00-公共设计/*.md               │
│      ↓                                                    │
│  用户确认 & 调整                                          │
└───────────────────────────┬─────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│  Phase 1: 概要设计（每个系统执行一次）                     │
│                                                           │
│  输入：_design_metadata.md + 该系统需求规格                 │
│      ↓                                                    │
│  处理：读取汇总表 → 架构设计 → 数据模型概要 → API清单       │
│      ↓                                                    │
│  输出：{系统编号}/概要设计.md                               │
└───────────────────────────┬─────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│  Phase 2: 详细设计（每个子模块执行一次）                   │
│                                                           │
│  输入：_design_metadata.md + 概要设计 + 子模块需求          │
│      ↓                                                    │
│  处理：DDL生成 → API详设 → 业务逻辑 → 页面设计             │
│      ↓                                                    │
│  输出：{系统编号}/{子模块编号}-{名称}-详细设计.md            │
└─────────────────────────────────────────────────────────┘

工作模式

创建模式（默认）

• 触发： 用户要求编写软件设计，且 项目文档/02-软件设计/ 目录为空
• 行为： 执行 Phase 0，然后逐系统执行 Phase 1 + Phase 2

修复模式

• 触发： 用户要求修复/补充设计文档
• 行为： 执行修复工作流程（R1-R4）

自动模式

• 触发： 上下文包含 AUTO_MODE=true
• 行为： 跳过确认步骤，自动按拆分计划逐系统执行

---

Phase 0: 设计元数据生成

目标： 从需求元数据中提取技术决策信息，建立全局设计规范，规划拆分方案。

0.1 定位数据源

扫描需求分析输出目录：

文件	读取方式	提取内容
_metadata.md	全量读取	行业领域、角色、术语、数据类型约定、外部系统、合规要求
S0N-*.md	只读标题和汇总表	系统名称、功能点数、子模块数、业务对象汇总、接口汇总

关键：Phase 0 不读取各功能点的详细展开内容，只扫描摘要信息。

0.2 系统分级与拆分规划

根据每个系统的规模，确定拆分策略：

## 系统拆分计划

| 系统编号 | 系统名称 | 功能点数 | 子模块数 | 分级 | Phase 1 输出 | Phase 2 输出 |
|---------|---------|---------|---------|------|-------------|-------------|
| S01 | 油库任务管理 | 5 | 0 | 小型 | 概要+详细合并 | 跳过 |
| S02 | 油料供应管理 | 18 | 5 | 中型 | 概要设计 | 5个详细设计文件 |
| S05 | 质量计量管理 | 61 | 16 | 大型 | 概要设计 | 16个详细设计文件 |
| ... | ... | ... | ... | ... | ... | ... |

分级规则：

• 小型：功能点 ≤ 6 且无子模块 → Phase 1 输出合并文件（概要+详细）
• 中型：功能点 7-20 → Phase 1 概要 + Phase 2 按子模块拆分
• 大型：功能点 > 20 或子模块 > 5 → Phase 1 概要 + Phase 2 每子模块独立

0.3 技术架构决策

从 _metadata.md 的行业领域和部署要求推导：

## 技术架构

| 决策项 | 选择 | 依据 |
|--------|------|------|
| 架构风格 | {微服务/模块化单体/云边协同} | {从部署要求推导} |
| 后端框架 | {Spring Boot/Django/...} | {从技术栈推导} |
| 前端框架 | {Vue/React/...} | {从兼容性要求推导} |
| 数据库 | {从_metadata.md读取} | |
| 消息队列 | {RabbitMQ/Kafka/RocketMQ} | {从集成需求推导} |
| 缓存 | {Redis} | |
| 对象存储 | {MinIO/本地文件} | {从文件存储需求推导} |

0.4 数据库设计规范

基于 _metadata.md 的数据类型约定，扩展为完整的数据库设计规范：

## 数据库设计规范

### 命名规范
- 表名：`t_{系统缩写}_{业务对象}` 全小写下划线
- 字段名：全小写下划线（如 `oil_height`, `tank_no`）
- 索引名：`idx_{表名}_{字段}` 或 `uk_{表名}_{字段}`
- 外键名：`fk_{表名}_{关联表}`

### 公共字段（每张表必须包含）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键，雪花算法 |
| create_by | VARCHAR(50) | 创建人 |
| create_time | DATETIME | 创建时间 |
| update_by | VARCHAR(50) | 最后修改人 |
| update_time | DATETIME | 最后修改时间 |
| del_flag | TINYINT | 逻辑删除 0=正常 1=删除 |
| tenant_id | BIGINT | 租户ID（如需多租户） |

### 索引策略
- 主键自动创建聚簇索引
- 外键字段必须创建普通索引
- 状态+时间的组合查询创建联合索引
- 编号/编码字段创建唯一索引

0.5 API设计规范

## API设计规范

### URL规范
- 基础路径：`/api/v1/{系统缩写}/{模块}`
- 资源命名：名词复数，如 `/api/v1/supply/vouchers`
- 操作用HTTP方法表达：GET查询 POST新增 PUT修改 DELETE删除

### 请求/响应格式
- Content-Type: application/json
- 统一响应体：`{ "code": 200, "message": "success", "data": {...} }`

### 错误码体系
| 范围 | 含义 |
|------|------|
| 200 | 成功 |
| 400-499 | 客户端错误（参数校验、权限不足等） |
| 500-599 | 服务端错误 |
| 1000-1999 | 业务错误（按系统分段） |

### 认证方式
- JWT Token 认证
- 请求头：`Authorization: Bearer {token}`

0.6 公共组件设计

从所有系统需求中抽取公共服务：

## 公共组件清单

| 组件 | 职责 | 依赖系统 |
|------|------|---------|
| 统一认证服务 | JWT签发/验证、SSO | S12 系统管理 |
| 权限管理服务 | RBAC权限控制、数据权限 | S12 系统管理 |
| 文件服务 | 上传/下载/预览 | 所有系统 |
| 消息通知服务 | 站内信/推送/邮件 | 所有系统 |
| 审批流引擎 | 通用审批流程管理 | S01,S02,S04,S05 |
| 日志服务 | 操作日志/审计日志 | 所有系统 |
| 数据字典服务 | 编码/枚举/主数据 | 所有系统 |
| 导出服务 | Excel/PDF导出 | 所有系统 |
| 定时任务服务 | 日清/月结/数据采集 | S02,S03 |
| 云边协同组件 | 数据同步/任务下发 | S11 |

0.7 系统间交互矩阵

从各系统需求的接口汇总表中提取：

## 系统交互矩阵

| 调用方 → 被调方 | 交互方式 | 数据内容 |
|----------------|---------|---------|
| S01 → S04 | REST | 任务分配至收发作业 |
| S02 → S04 | REST/Event | 获取已完成作业数据 |
| S02 → S05 | REST | 获取化验结果 |
| S03 → EXT-02 | MQTT | 实时采集物联数据 |
| ... | ... | ... |

0.8 输出

输出到 项目文档/02-软件设计/ 目录：

1. _design_metadata.md — 设计元数据（含拆分计划）
2. 00-公共设计/技术架构总览.md
3. 00-公共设计/数据库设计规范.md
4. 00-公共设计/API设计规范.md
5. 00-公共设计/公共服务设计.md

必须向用户展示拆分计划并等待确认。

---

Phase 1: 概要设计

目标： 为指定系统生成概要设计文档。

1.1 加载上下文

读取以下文件：

1. _design_metadata.md — 全局设计规范
2. 目标系统需求规格文件 — 只读以下部分：
   • 系统概述（定位、业务范围、角色、边界）
   • 业务对象汇总表
   • 接口汇总表
   • 需求追溯矩阵

不读取各功能点的详细展开（留给 Phase 2）。

1.2 概要设计模板

# {系统编号} {系统名称} — 概要设计

## 文档信息
| 项目 | 内容 |
|------|------|
| 需求规格 | {系统编号}-{系统名称}.md |
| 功能点数 | {N} |
| 设计日期 | {YYYY-MM-DD} |

## 一、系统架构

### 1.1 分层架构
{描述该系统的分层结构：展现层→应用层→领域层→基础设施层}
{标注各层使用的技术组件}

### 1.2 模块划分
| 模块 | 职责 | 对应需求 |
|------|------|---------|
| {模块名} | {职责描述} | S0N-XXX ~ S0N-XXX |

### 1.3 部署视图
{该系统的部署位置：本地/云端/边缘}
{与其他系统的网络拓扑关系}

## 二、数据模型概要

### 2.1 核心实体关系
{用文字描述 ER 关系，如"供应凭证(1) → 收发油信息(N)"}
{每个实体对应一张表，标注业务对象编码}

### 2.2 数据库表清单
| 表名 | 业务对象 | 说明 | 预估数据量 |
|------|---------|------|-----------|
| t_{缩写}_{对象} | BO-0N-XXX | {说明} | {日增/总量} |

## 三、API清单

### 3.1 API总览
| 方法 | URL | 用途 | 对应用例 |
|------|-----|------|---------|
| GET | /api/v1/{模块}/{资源} | {说明} | U-0N-XXX-XX |
| POST | ... | ... | ... |

### 3.2 系统间接口
| 接口编码 | 方向 | 对接系统 | 说明 |
|---------|------|---------|------|
| IF-0N-XXX | 输入/输出 | {系统/外部} | {说明} |

## 四、安全设计

### 4.1 权限矩阵
| 功能 | R01 库领导 | R02 保管员 | ... |
|------|-----------|-----------|-----|
| {功能名} | 查看/审批 | 新增/编辑 | ... |

### 4.2 审计策略
{关键操作审计日志记录策略}

## 五、设计追溯

| 设计产物 | 对应需求 |
|---------|---------|
| 表 t_xxx | BO-0N-XXX {业务对象名} |
| API /xxx | U-0N-XXX-XX {用例名} |

1.3 小型系统合并输出

当系统分级为"小型"时，Phase 1 输出合并概要+详细设计：

在概要设计模板基础上，直接追加：

## 六、数据库详细设计
{各表的完整DDL}

## 七、API详细设计
{各API的请求/响应/错误码}

## 八、业务逻辑设计
{状态机/流程/算法}

---

Phase 2: 详细设计

目标： 为指定系统的指定子模块生成详细设计文档。

2.1 加载上下文

读取以下文件：

1. _design_metadata.md — 数据库规范、API规范
2. 该系统的概要设计 — 表清单、API清单
3. 该子模块在需求规格中的详细展开部分 — 业务对象数据字典、用例描述、业务规则

只读取当前子模块的需求内容，不读取其他子模块。

2.2 详细设计模板

# {系统编号}-{子模块编号} {子模块名称} — 详细设计

## 文档信息
| 项目 | 内容 |
|------|------|
| 所属系统 | {系统编号} {系统名称} |
| 功能点范围 | S0N-XXX ~ S0N-XXX |
| 业务对象 | BO-0N-XXX ~ BO-0N-XXX |

## 一、数据库表设计

### 1.1 表 t_{缩写}_{对象名}

**追溯：** BO-0N-XXX {业务对象名}

```sql
CREATE TABLE t_{缩写}_{对象名} (
    id              BIGINT          NOT NULL COMMENT '主键ID',
    {字段名}        {类型}({长度})  {NOT NULL} COMMENT '{说明}',
    -- 公共字段
    create_by       VARCHAR(50)     NOT NULL COMMENT '创建人',
    create_time     DATETIME        NOT NULL COMMENT '创建时间',
    update_by       VARCHAR(50)     DEFAULT NULL COMMENT '修改人',
    update_time     DATETIME        DEFAULT NULL COMMENT '修改时间',
    del_flag        TINYINT         NOT NULL DEFAULT 0 COMMENT '删除标志',
    PRIMARY KEY (id),
    {索引定义}
) COMMENT='{表注释}';

索引设计：

索引名	字段	类型	用途
uk_{表}_{字段}	{字段}	UNIQUE	{说明}
idx_{表}_{字段}	{字段}	NORMAL	{说明}

1.2 表 t_{下一张表}...

{重复以上结构}

二、API详细设计

2.1 {API名称}

追溯： U-0N-XXX-XX {用例名}

项目	内容
方法	POST
URL	/api/v1/{模块}/{资源}
认证	需要
权限	{角色编码列表}

请求参数：

参数	类型	必填	说明
{参数名}	{类型}	{Y/N}	{说明}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "{字段}": "{值}"
  }
}

错误码：

错误码	说明	处理建议
1001	{说明}	{建议}

2.2 {下一个API}...

三、业务逻辑设计

3.1 状态机（如适用）

{状态A} --[{事件}]--> {状态B}
{状态B} --[{事件}]--> {状态C}

当前状态	事件	目标状态	前置校验	后置动作
{状态}	{事件}	{状态}	{校验}	{动作}

3.2 核心算法（如适用）

伪码描述：
1. {步骤}
2. {步骤}

3.3 定时任务（如适用）

任务名	触发规则	处理逻辑	超时策略
{名称}	{cron表达式}	{描述}	{策略}

四、前端页面设计

4.1 页面清单

页面	路由	功能	对应用例
{页面名}	/{路由}	{功能}	U-0N-XXX-XX

4.2 页面交互说明

{关键页面的交互逻辑描述}

### 2.3 功能原型展开策略

不同功能原型的详细设计侧重点不同：

#### 原型 A：数据录入/维护
- **数据库**：完整CRUD表结构，校验规则用COMMENT标注
- **API**：标准REST五件套（list/get/create/update/delete）+ 批量操作
- **逻辑**：字段校验规则清单、级联更新逻辑

#### 原型 C：文书/报告/表单
- **数据库**：模板表 + 实例表 + 审批记录表
- **API**：模板管理 + 表单渲染 + 签名 + 打印
- **逻辑**：模板渲染引擎对接、电子签名流程

#### 原型 D：统计/分析/报表
- **数据库**：统计视图（VIEW）或物化视图、预计算表
- **API**：查询条件组合 + 聚合结果 + 导出接口
- **逻辑**：数据聚合SQL、缓存策略、图表数据格式

#### 原型 E：流程/闭环/审批
- **数据库**：流程定义表 + 节点表 + 操作记录表 + 状态变迁日志
- **API**：流程启动/推进/回退/挂起/终止
- **逻辑**：完整状态机定义（状态×事件矩阵）

#### 原型 G：集成/同步/对接
- **数据库**：同步日志表 + 数据映射配置表
- **API**：适配器接口 + 同步触发 + 状态查询
- **逻辑**：消息队列消费者、重试策略、幂等设计

#### 原型 H：移动端
- **数据库**：与PC端共用 + 离线缓存策略
- **API**：轻量查询接口 + 数据同步接口 + 推送注册
- **逻辑**：离线存储方案、冲突解决策略

#### 原型 I：监控/预警
- **数据库**：规则配置表 + 预警记录表 + 阈值配置表
- **API**：规则管理 + 预警查询 + 处理反馈
- **逻辑**：规则引擎设计、阈值判定算法、通知分发策略

---

## 修复模式工作流程

### R1. 读取反馈

读取用户提供的评审反馈或问题清单：
- 按严重程度分组：缺失 / 错误 / 不完整 / 建议
- 按产物类型分组：DDL问题 / API问题 / 逻辑问题 / 追溯问题

### R2. 加载上下文

读取 `_design_metadata.md` + 目标系统的概要设计 + 对应需求规格。

### R3. 逐项修复

| 问题类型 | 修复方式 |
|---------|---------|
| DDL字段缺失 | 从需求BO数据字典补充字段 |
| DDL类型不匹配 | 参照 _design_metadata.md 数据类型约定修正 |
| API缺失 | 从需求用例推导并补充 |
| 状态机不完整 | 从需求业务规则补充状态转换 |
| 追溯缺失 | 补充需求编号引用 |
| 索引缺失 | 根据查询场景补充索引 |

### R4. 修复后验证

重新执行自检清单，输出修复摘要。

---

## 自检清单

### Phase 0 自检
- [ ] 技术架构决策有明确依据
- [ ] 数据库命名规范完整
- [ ] API设计规范完整
- [ ] 公共组件清单覆盖所有共性需求
- [ ] 系统拆分计划与需求规格一致（系统数、功能点数匹配）

### Phase 1 自检（每系统）
- [ ] 数据库表数 ≥ 业务对象数（含关联表可能更多）
- [ ] 每张表都追溯到业务对象编码
- [ ] API数量覆盖所有用例
- [ ] 每个API都追溯到用例编码
- [ ] 权限矩阵覆盖所有角色×功能组合
- [ ] 系统间接口与需求接口汇总一致

### Phase 2 自检（每子模块）
- [ ] DDL字段与需求BO数据字典完全对应
- [ ] 数据类型与 _design_metadata.md 约定一致
- [ ] 公共字段（create_by, create_time等）齐全
- [ ] 必要索引已定义
- [ ] API请求参数覆盖BO必填字段
- [ ] API响应包含完整业务数据
- [ ] 状态机覆盖所有需求中定义的状态枚举
- [ ] 错误码无重复

---

## 编号规则

### 数据库表

t_{系统缩写}_{业务对象}
例: t_supply_voucher, t_stock_tank_realtime, t_quality_lab_task

### API路由

/api/v1/{系统缩写}/{模块}/{资源}
例: /api/v1/supply/vouchers, /api/v1/stock/tanks/{id}/realtime

### 错误码

{系统编号}00{序号}
例: S01→1000110099, S02→2000120099

---

## 输出格式

所有文件输出到 `项目文档/02-软件设计/` 目录，Markdown 格式。

目录结构：

项目文档/02-软件设计/
├── _design_metadata.md
├── 00-公共设计/
│ ├── 技术架构总览.md
│ ├── 数据库设计规范.md
│ ├── API设计规范.md
│ └── 公共服务设计.md
├── S01-油库任务管理/
│ └── 概要设计.md (小型系统：合并输出)
├── S02-油料供应管理/
│ ├── 概要设计.md
│ ├── 01-供应凭证-详细设计.md
│ └── ...
└── ...

**注意**：如单个文件超过 300 行，应考虑进一步拆分。

---

## 完成状态

### Phase 0 完成

--- BID-SOFTWARE-DESIGN PHASE0 COMPLETE ---
项目名称: {项目名称}
技术架构: {架构风格}
数据库: {数据库类型}
系统总数: {N}
小型系统: {N} 个（合并输出）
中型系统: {N} 个（拆分输出）
大型系统: {N} 个（子模块独立）
输出文件: _design_metadata.md + 00-公共设计/*.md
状态: SUCCESS
--- END ---

### Phase 1 完成（每系统）

--- BID-SOFTWARE-DESIGN PHASE1 COMPLETE ---
系统编号: {编号}
系统名称: {名称}
系统分级: {小型/中型/大型}
数据库表数: {N}
API数: {N}
输出文件: {文件路径}
状态: SUCCESS
--- END ---

### Phase 2 完成（每子模块）

--- BID-SOFTWARE-DESIGN PHASE2 COMPLETE ---
系统编号: {编号}
子模块: {子模块名}
DDL表数: {N}
DDL字段总数: {N}
API数: {N}
状态机数: {N}
输出文件: {文件路径}
状态: SUCCESS
--- END ---