---
name: tech-design-review
description: 执行技术设计评审，通过 Jira 获取需求、Confluence 获取设计文档，按 39 项检查清单评审并生成结构化报告，发送钉钉通知，更新项目知识库。当用户请求"技术设计评审"、"评审技术设计"、"review 技术设计"、"帮我评审"时触发。
---

# 技术设计评审

## 评审触发条件

当用户请求进行技术设计评审时触发。关键词：
- "技术设计评审"
- "评审技术设计"
- "review 技术设计"
- "帮我评审"

## 输入信息收集

### 必须信息

1. **Jira Key**（必须）- 格式：`PVS-123`
2. **Confluence 技术设计文档 URL**（必须）
3. **需求类型**（必须）- 新功能开发 / 功能迭代 / 技术优化

### 条件必须信息

当需求类型为"功能迭代"或"技术优化"时：
- **相关表名** - 逗号分隔
- **代码路径** - 相对于项目根目录

### 可选信息
- 历史设计文档 URL
- 系统架构文档 URL
- 需要跳过的检查类别

## 数据获取步骤

### 步骤 0：读取项目知识库（重要！）

**目的**：从历史评审中学习，避免重复犯错

使用 Read 工具读取项目根目录的 `MEMORY.md` 文件：

```
读取项目根目录下的 MEMORY.md 文件
```

**如果文件存在**：
- 提取"常见问题"部分，在本次评审中重点检查
- 提取"设计规范"部分，对照检查本次设计
- 提取"技术债务"部分，检查是否引入新债务

**如果文件不存在**：
- 继续执行评审，在评审完成后创建 MEMORY.md

---

### 步骤 1：获取 Jira 需求信息

使用 `jira_get_issue` 工具：

```
调用 jira_get_issue，参数 issue_key = "{Jira Key}"
```

提取：需求标题、描述、验收标准、状态

### 步骤 2：获取 Confluence 设计文档

使用 `confluence_get_page` 工具：

```
调用 confluence_get_page，参数 page_id = "{从 URL 中提取的 pageId}"
```

提取：设计文档标题、内容、更新时间

### 步骤 3：获取数据库表结构（如需要）

使用 `describe_table` 工具：

```
对每个表名调用 describe_table
```

### 步骤 4：读取本地代码（如需要）

重点关注：
- Controller 类（接口定义）
- Service 类（业务逻辑）
- Entity/DTO 类（数据模型）
- Mapper/Repository 类（数据访问）

## 评审执行流程

### 评审顺序

1. **需求理解**：设计是否覆盖所有需求点
2. **架构设计**：分层是否合理、模块划分是否清晰
3. **接口设计**：接口清单、幂等性、批量限制
4. **数据模型**：表设计、字段规范、索引设计
5. **数据权限**：数据级别的权限隔离
6. **性能设计**：缓存、批量处理、异步
7. **异常处理**：降级、重试、超时
8. **兼容性与迁移**：变更影响、数据迁移（功能迭代时）

**完整检查清单**：参考 [review-checklist.md](review-checklist.md)（共39项）

### 评审判断标准

| 结果 | 说明 |
|------|------|
| **通过** | 设计符合检查项要求 |
| **建议改进** | 设计基本符合，但有优化空间 |
| **需要澄清** | 设计文档中未明确说明 |

## 报告生成

### 文件命名

格式：`{JiraKey}-review-{YYYYMMDD-HHmmss}.md`

### 存储位置

项目的 `reviews/` 目录下（如不存在则创建）

### 报告结构

参考 [review-report-template.md](review-report-template.md)

### 评审结果判定

| 结果 | 条件 |
|------|------|
| **通过** | 无严重问题，无需要澄清的问题 |
| **有条件通过** | 无严重问题，但有需要澄清的问题或重要改进项 |
| **需要修改** | 存在严重问题，需要修改后重新评审 |

## 钉钉通知

评审完成后，**必须**发送钉钉通知到团队群。

### 发送通知

使用 `send_markdown_message` 工具发送评审结果通知：

```
调用 send_markdown_message，参数：
- title: "技术设计评审完成"
- text: {按下方模板生成的 Markdown 内容}
- atAll: false
```

### 通知消息模板

```markdown
## 技术设计评审完成

**基本信息**
- Jira Key: {JiraKey}
- 需求标题: {需求标题}
- 需求类型: {新功能开发/功能迭代/技术优化}
- 评审时间: {YYYY-MM-DD HH:mm}

**评审结果: {通过/有条件通过/需要修改}**

| 统计 | 数量 |
|------|------|
| 通过项 | {n}/39 |
| 改进项 | {n} |
| 澄清项 | {n} |

**主要风险点**
{列出 1-3 个主要风险点，如无则写"无"}

> 详细报告已保存至 reviews/{文件名}
```

### 通知失败处理

如果钉钉通知发送失败：
1. 向用户提示通知发送失败
2. 不影响评审报告的保存
3. 建议用户检查钉钉机器人配置

## 错误处理

| 错误场景 | 处理方式 |
|----------|----------|
| jira_get_issue 失败 | 提示检查 Jira Key 是否正确，Token 是否有效 |
| confluence_get_page 失败 | 提示检查页面 URL 是否正确，是否有访问权限 |
| describe_table 失败 | 提示检查表名是否正确，数据库连接是否配置 |
| 必须信息缺失 | 列出缺失项，请求用户补充 |
| send_markdown_message 失败 | 提示钉钉通知发送失败，建议检查机器人配置 |

## 进度反馈

在评审过程中向用户反馈进度：

1. "正在获取 Jira 需求信息..."
2. "正在获取 Confluence 设计文档..."
3. "正在读取项目知识库 MEMORY.md..."
4. "正在获取数据库表结构..."
5. "正在读取相关代码..."
6. "正在进行评审..."
7. "正在生成评审报告..."
8. "评审完成，报告已保存至 reviews/{文件名}"
9. "正在发送钉钉通知..."
10. "正在更新项目知识库 MEMORY.md..."
11. "知识库更新完成"

---

## 知识库更新（闭环关键）

评审完成后，**必须**更新项目的 `MEMORY.md` 文件，实现知识积累。

### 闭环流程

```
设计 → 评审 → 问题 → MEMORY.md → 下一次设计（参考历史问题）
```

### 文件位置

项目根目录：`MEMORY.md`

### 更新内容

从本次评审中提取以下信息，追加到 MEMORY.md：

#### 1. 新增问题

```markdown
### {问题类别}

**问题**：{问题描述}
**检查项ID**：{REQ-001 / ARCH-002 / API-003 等}
**首次发现**：{JiraKey} - {日期}
**影响**：{严重/重要/一般}
**建议**：{改进建议}
```

#### 2. 设计规范（从优秀设计中提炼）

```markdown
### {规范类别}

**规范**：{规范描述}
**来源**：{JiraKey} - {日期}
**示例**：{具体示例}
```

#### 3. 技术债务

```markdown
### {债务描述}

**类型**：{性能/安全/架构/代码}
**来源**：{JiraKey} - {日期}
**建议处理时机**：{建议}
```

### MEMORY.md 模板（首次创建）

```markdown
# 项目技术设计知识库

本文件记录项目技术设计评审过程中积累的知识，包括常见问题、设计规范、技术债务等。
由 AI 技术设计评审助手自动维护。

---

最后更新：{YYYY-MM-DD HH:mm}
评审次数：{n}

## 常见问题

> 从历次评审中发现的重复出现或高影响问题

### 需求理解
### 架构设计
### 接口设计
### 数据模型
### 性能设计
### 安全设计

## 设计规范

> 从优秀设计中提炼的规范和模式

### 架构模式
### 接口规范
### 数据模型规范

## 技术债务

> 评审中识别出需要后续处理的技术债务

### 待处理
### 已处理

## 项目上下文

> 项目特定的技术信息

### 技术栈
### 中间件
### 关键表
```

### 更新流程

1. **提取本次评审的关键信息**
   - 需要修改的问题（严重、重要）
   - 建议改进项（有代表性的）
   - 优秀设计实践
2. **分类整理**
   - 按检查项 ID 归类（如 ARCH-002、API-004）
   - 检查是否重复（同一问题不重复记录）
3. **追加/更新文件**
   - 首次创建：使用模板创建 MEMORY.md
   - 追加内容：在对应类别下添加新条目
   - 更新元数据：最后更新时间、评审次数
4. **提示用户**
   - "已更新项目知识库 MEMORY.md，新增 X 条问题，X 条规范"

---

## 参考资料

- **文档模板**：[doc-template.md](doc-template.md) - 技术设计文档标准模板
- **安全清单**：[security-checklist.md](security-checklist.md) - 安全自查清单（OWASP Top 10 + 业务安全）
- **检查清单**：[review-checklist.md](review-checklist.md) - 完整39项检查清单
- **提示词模板**：[review-prompts.md](review-prompts.md) - 不同场景的评审模板
- **报告模板**：[review-report-template.md](review-report-template.md) - 评审报告格式
- **接口规范**：[standards/api-design-standards.md](standards/api-design-standards.md)
- **数据库规范**：[standards/database-design-standards.md](standards/database-design-standards.md)
- **编码规范**：[standards/java-coding-standards.md](standards/java-coding-standards.md)
- **示例报告**：[examples/sample-review-report.md](examples/sample-review-report.md)