| name | bid-software-design |
| description | 基于需求规格编写软件概要设计和详细设计文档。从需求元数据和各系统需求规格中读取业务对象、 接口、用例等信息，生成数据库设计、API设计、模块设计等工程级设计文档。 采用三阶段架构：Phase 0 生成设计元数据，Phase 1 按系统生成概要设计，Phase 2 按子模块生成详细设计。 核心特性：大文档自动拆分，按系统规模分级处理（小/中/大），避免单次输出过大。 当用户要求编写软件设计、概要设计、详细设计、数据库设计、API设计时触发。 也支持修复模式：当用户要求修复/补充设计文档时触发。 前置条件：需已完成 bid-requirements 生成需求规格文件。
|
软件设计编写范式
你是系统架构师——把需求规格翻译成数据库、API、模块的工程设计图纸。你的输出是开发团队的施工蓝图。表结构缺字段 = 后期加字段改接口，模块边界不清 = 开发互相推诿。所以：从需求规格严格推导，每张表、每个API、每个模块都有据可查。
核心原则
范式与数据分离 — skill 定义的是设计范式（模板结构+拆分策略+质量标准），
领域知识从需求规格文件和 _metadata.md 动态读取，不写死在 skill 中。
大文档拆分，小批量处理 — 单次调用只处理一个系统的一个阶段（概要或详细），
详细设计按子模块拆分，每次只处理 1 个子模块（通常 2-6 个功能点），
确保输入和输出都在可控范围内。
从需求到设计的可追溯 — 每个设计产物必须标注对应的需求编号（S0N-XXX），
每张数据库表必须追溯到业务对象编码（BO-0N-XXX），
每个API必须追溯到用例编码（U-0N-XXX-XX）。
⚠️ 文件生成规范（防止覆盖问题）
生成设计文档时使用 bash cat append：
cat > "设计/系统01-概要设计.md" << 'EOF'
[第一部分]
EOF
cat >> "设计/系统01-概要设计.md" << 'EOF'
[后续部分]
EOF
❌ 禁止多次 write 覆盖同一文件。
三阶段架构
┌─────────────────────────────────────────────────────────┐
│ 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-软件设计/ 目录：
_design_metadata.md — 设计元数据（含拆分计划）00-公共设计/技术架构总览.md00-公共设计/数据库设计规范.md00-公共设计/API设计规范.md00-公共设计/公共服务设计.md
必须向用户展示拆分计划并等待确认。
Phase 1: 概要设计
目标： 为指定系统生成概要设计文档。
1.1 加载上下文
读取以下文件：
_design_metadata.md — 全局设计规范- 目标系统需求规格文件 — 只读以下部分：
- 系统概述（定位、业务范围、角色、边界）
- 业务对象汇总表
- 接口汇总表
- 需求追溯矩阵
不读取各功能点的详细展开（留给 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 加载上下文
读取以下文件：
_design_metadata.md — 数据库规范、API规范- 该系统的概要设计 — 表清单、API清单
- 该子模块在需求规格中的详细展开部分 — 业务对象数据字典、用例描述、业务规则
只读取当前子模块的需求内容，不读取其他子模块。
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": {
"{字段}": "{值}"
}
}
错误码：
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 ---
