# DDS 设计细节抽取指南

本文档详细说明如何从 DDS（详细设计说明书）中抽取设计细节，并组织到 reference/ 目录中。

---

## 1. 章节标题提取

### 1.1 标题识别规则（按优先级）

| 优先级 | 格式 | 示例 |
|-------|------|------|
| 1 | Markdown 标题 | `# 系统架构`、`## 接口设计` |
| 2 | 编号标题 | `1 概述`、`2.3 数据库设计` |
| 3 | 中文章标题 | `第一章 总体设计`、`第3章` |
| 4 | 中文小节 | `一、系统概述`、`（二）接口规范` |

### 1.2 提取命令

```bash
# 综合提取（推荐首选）
grep -nE '^(#{1,6}\s+|[0-9]+(\.[0-9]+){0,3}\s+|第[一二三四五六七八九十]+章|第[0-9]+章|[一二三四五六七八九十]+、)' "$DDS_FILE" | head -n 120

# 如果上面匹配不足，尝试更宽松的模式
sed -n '1,200p' "$DDS_FILE" | nl -ba | sed -n '1,120p'
```

### 1.3 降级策略

当标题提取不足（少于 3 个）或 DDS 格式混乱时：

```
reference/00-unknown/
├── 01-apis/
├── 02-events/
├── 03-db/
├── 04-state-machine/
└── 05-security/
```

同时在自检中标记 FAIL：
- **原因**：DDS 标题结构不可识别
- **建议**：提供 Markdown 标题 / 章节目录 / md 格式导出版本

---

## 2. 六类设计要素抽取方法

### 2.1 API/接口

**扫描关键词**：
```bash
grep -nE "API|接口|路径|路由|request|response|错误码|error|handler|endpoint|method" "$DDS_FILE" | head -n 80
```

**抽取内容**：
| 字段 | 说明 |
|------|------|
| 路径 | `/api/v1/users/list` |
| 方法 | POST / GET 等 |
| 请求字段 | 字段名、类型、是否必须、校验规则 |
| 响应字段 | 字段名、类型、说明 |
| 错误码 | code + message + 触发场景 |
| 鉴权要求 | JWT / API Key / 公开 |

**输出格式**：
```markdown
## POST /api/v1/users/list

- **DDS-Section**: 3.2 用户管理接口
- **DDS-Lines**: L120-L168

### Request

| 字段 | 类型 | 必须 | 说明 |
|------|------|------|------|
| page | int | N | 页码，默认 1 |
| page_size | int | N | 每页数量，默认 20 |

### Response

| 字段 | 类型 | 说明 |
|------|------|------|
| list | []User | 用户列表 |
| total | int | 总数 |

### 错误码

| code | message | 触发场景 |
|------|---------|---------|
| 1001 | 参数校验失败 | 字段格式错误 |
```

### 2.2 事件/Topic/消息

**扫描关键词**：
```bash
grep -nE "事件|event|MQTT|topic|outbox|消息|payload|幂等|retry|publish|subscribe|Kafka|RabbitMQ" "$DDS_FILE" | head -n 80
```

**抽取内容**：
| 字段 | 说明 |
|------|------|
| Topic/Queue 名 | `cmii/rmdc/{project_id}/command` |
| 方向 | Publish / Subscribe |
| Payload 字段 | 字段名、类型、说明 |
| QoS / 可靠性 | At-least-once / Exactly-once |
| 幂等键 | 用于去重的唯一标识字段 |
| 重试策略 | 重试间隔、最大次数、死信队列 |

### 2.3 数据库/Schema

**扫描关键词**：
```bash
grep -nE "表|schema|字段|索引|unique|constraint|migration|DDL|PostgreSQL|MySQL|GORM|column|CREATE TABLE" "$DDS_FILE" | head -n 80
```

**抽取内容**：
| 字段 | 说明 |
|------|------|
| 表名 | `users`、`workflows` |
| 字段定义 | 名称、类型、约束、默认值 |
| 索引 | 类型（唯一/普通/组合）、字段 |
| 外键关系 | 引用表、级联策略 |
| 迁移策略 | 向前兼容 / 字段演进方案 |

### 2.4 状态机/流程

**扫描关键词**：
```bash
grep -nE "状态机|state|transition|流转|工单|workflow|回调|补偿|lifecycle|FSM|guard" "$DDS_FILE" | head -n 80
```

**抽取内容**：
| 字段 | 说明 |
|------|------|
| 状态枚举 | 名称、值、描述 |
| 转换规则 | from → to、触发动作、守卫条件 |
| 角色权限 | 谁可以触发哪些转换 |
| 回调/副作用 | 状态变更后执行的操作 |
| 补偿机制 | 转换失败时的回滚策略 |

### 2.5 授权模型

**扫描关键词**：
```bash
grep -nE "RBAC|DAC|鉴权|JWT|claim|授权|TOTP|权限|auth|token|session|role|permission" "$DDS_FILE" | head -n 80
```

**抽取内容**：
| 字段 | 说明 |
|------|------|
| 认证方式 | JWT / Session / OAuth |
| JWT Claims | 包含的字段（tenant_id, role 等） |
| 角色定义 | 角色名、权限描述 |
| 权限矩阵 | 角色 × 资源 × 操作 |
| 层级设计 | 一级授权 / 二级授权 |

### 2.6 依赖关系

**扫描关键词**：
```bash
grep -nE "模块|module|service|依赖|dependency|import|gateway|调用|集成|protocol" "$DDS_FILE" | head -n 80
```

**抽取内容**：
| 字段 | 说明 |
|------|------|
| 源模块 | 调用方 |
| 目标模块 | 被调用方 |
| 协议 | HTTP / gRPC / MQTT / 内部调用 |
| 关键接口 | 跨模块调用的接口清单 |
| 失败处理 | 超时、重试、熔断策略 |

---

## 3. reference 目录组织

### 3.1 命名规范

```
reference/
├── 01-architecture-overview/     # 章节序号 + slug
│   └── dependencies.md
├── 02-api-design/
│   ├── apis.md
│   └── error-codes.md
├── 03-data-model/
│   └── db-schema.md
├── 04-message-system/
│   └── events-topics.md
├── 05-workflow-engine/
│   └── state-machine.md
└── 06-security/
    └── security-model.md
```

**Slug 生成规则**：
1. 全小写
2. 非字母数字字符替换为 `-`
3. 连续 `-` 合并为单个
4. 截断到 48 字符以内
5. 序号来自 DDS 中的章节顺序

### 3.2 SKILL.md 中的引用方式

```markdown
## Pitfalls

1. **MQTT Topic 命名冲突**：新增 topic 前必须检查
   `reference/04-message-system/events-topics.md` 中的 topic 清单

## Related References

| 需要了解... | 查阅... |
|------------|--------|
| API 完整定义 | `reference/02-api-design/apis.md` |
| 数据库表结构 | `reference/03-data-model/db-schema.md` |
```

### 3.3 扁平化兼容

当 DDS 章节结构不明显时，也可以采用扁平 reference，但需在自检中说明：

```
reference/
├── apis.md
├── db-schema.md
├── events-topics.md
├── state-machine.md
├── security-model.md
└── dependencies.md
```

---

## 4. TBD 标注规范

当 DDS 中某个设计要素不完整或不清晰时：

```markdown
## 消息重试策略

- **DDS-Section**: 4.3 消息可靠性
- **DDS-Lines**: L245-L260

### Extract

| 配置项 | 值 |
|-------|---|
| 最大重试次数 | [TBD - DDS 未明确指定] |
| 重试间隔 | [TBD - DDS 未明确指定] |
| 死信队列 | [TBD - DDS 仅提及概念，未给出配置] |

### 最小补充信息清单

1. 重试次数上限（建议 3~5 次）
2. 重试间隔策略（固定 / 指数退避）
3. 死信队列名称与消费策略
```
