# Proj Analyze Design

> 技术方案设计与确认（阶段二）。基于已确认的需求，设计数据库、接口、代码结构，生成技术方案文档。

- Skill: `zhangloveyan/proj-analyze-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zhangloveyan/proj-analyze-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhangloveyan/proj-analyze-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhangloveyan (https://skillmd.com/u/zhangloveyan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhangloveyan/proj-analyze-design

---


# 技术方案设计（阶段二）

> **前置条件**：用户已确认阶段一（/proj-analyze-req）的需求分析文档，且全流程任务文档已创建
> **目标**：设计技术实现方案，明确数据库、接口、代码结构
> **产出**：技术方案文档（用户确认后进入开发阶段）

---

## 执行流程

```
Step 0: 校验任务文档 → Step 1: 探索现有代码 → Step 2: 设计技术方案 → Step 3: 输出方案文档 → Step 4: 用户确认 → Step 5: 生成任务
```

---

## Step 0: 校验任务文档

- 确认全流程任务文档存在
- 若缺失，先创建任务文档骨架并补齐流程状态与上下文快照

---

## Step 1: 探索现有代码

在设计方案前，先了解项目现状：

| 探索内容 | 目的 |
|----------|------|
| 相关模块代码 | 了解现有实现方式 |
| 类似功能实现 | 参考已有模式 |
| 公共类和工具 | 复用现有组件 |
| 数据库表结构 | 了解关联关系 |

---

## Step 2: 设计技术方案

### 2.1 数据库设计

**表命名规范**：
- 表名：小写下划线，单数（如 `user`, `order_item`）
- 字段名：小写下划线（如 `user_id`, `create_time`）
- 主键：`id BIGINT AUTO_INCREMENT`
- 外键：`{关联表}_id`
- 索引：`idx_{表名}_{字段}`

**通用字段**（每张业务表必须包含）：
```sql
id BIGINT AUTO_INCREMENT PRIMARY KEY,
del_flag TINYINT(1) DEFAULT 0 COMMENT '删除标记',
create_by VARCHAR(64) COMMENT '创建人',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_by VARCHAR(64) COMMENT '更新人',
update_time DATETIME COMMENT '更新时间'
```

### 2.2 接口设计规范

**接口文档要求**：
- **完整参数**：必须包含所有请求参数的类型、是否必填、示例值
- **响应格式**：提供完整的JSON响应示例，包含所有字段
- **错误码**：列出所有可能的错误码和说明
- **业务场景**：说明接口的使用场景和业务含义

### 2.3 枚举类设计规范

**标准枚举格式**：参考模板中的枚举类设计，必须包含getByCode和getMessageByCode方法

### 2.4 技术架构澄清

**按需澄清原则**：只在涉及相关技术时才需要澄清

**常见澄清场景**：
- **消息/通知功能** → 澄清：推送服务 vs 前端轮询？
- **实时数据展示** → 澄清：Redis vs 数据库？
- **历史数据管理** → 澄清：永久保存 vs 定期清理？
- **在线状态功能** → 澄清：实时更新机制？存储位置？

---

## Step 3: 输出方案文档

在充分澄清后，使用模板输出技术方案文档。

**模板文件**：[技术方案模板](templates/design-doc.md)

**保存位置**：`docs/design/{YYYYMMDD}_{中文模块名}_技术.md`

**注意**：技术方案设计时如发现需求遗漏或变更，需同步更新需求文档。

**同步更新任务文档**：
- 将“技术方案”状态标记为进行中/已完成
- 在产物清单中记录技术方案文档路径
- 更新上下文快照与下一步指令

---

## Step 4: 用户确认

### 4.1 确认话术

输出技术方案后，**必须**使用以下话术请求确认：

```
以上是技术实现方案，请确认：
1. 数据库表结构和字段是否符合预期？
2. 接口设计是否满足需求？
3. 是否需要调整？

确认后我将开始编码开发。
```

### 4.2 用户反馈处理

| 用户反馈 | 处理方式 |
|----------|----------|
| "确认"/"没问题"/"可以" | 调用 `/proj-task` 拆分任务，开始开发 |
| "字段需要调整xxx" | 修改表结构设计，再次确认 |
| "接口需要增加xxx" | 补充接口设计，再次确认 |
| "取消"/"不做了" | 结束流程 |

---

## 注意事项

1. **前置检查** - 确保阶段一需求已确认，否则不能开始
2. **参考现有** - 设计前先看项目已有实现，保持风格一致
3. **命名规范** - 严格遵循 CLAUDE.md 命名规范
4. **不要过度设计** - 按需求来，不主动加功能
5. **确认再开发** - 方案确认前禁止创建/修改任何代码文件

---

## Step 5: 生成任务（用户确认后）

用户确认技术方案后：

1. **保存方案文档**（中等/复杂需求）：`docs/design/{YYYYMMDD}_{中文模块名}_技术.md`
2. **生成任务清单**：调用 `/proj-task` 创建任务
3. **开始开发**：按顺序 SQL → Entity → Mapper → DTO → Service → Controller
4. **开发完成**：调用 `/proj-review` 自检

**同步更新任务文档**：
- 标记“方案确认”状态为已完成
- 更新“下一步指令”为进入任务拆分