/design

description: 技术设计（doc 文档框架 / checklist 质量检查）
argument-hint: "[doc|checklist] 功能描述"

根据参数选择设计模式：

• `/design doc [功能]` → 生成技术设计文档框架
• `/design checklist [功能]` → 生成设计质量检查清单
• `/design [功能]` → 默认生成文档框架（同 doc）

参数值：「$ARGUMENTS」

---

模式 1：doc（默认）

根据以下信息，生成技术设计文档框架。

请按照以下模板结构生成，根据实际需求填充内容：

---

[功能名称] 设计文档

作者：wwj 版本：v1.0 日期：[当前日期] 状态：草稿

---

一、需求背景

[简要描述功能的业务背景和目标]

---

二、核心原则

<!-- [注释] 列出 3-5 条设计原则，指导后续设计决策 -->

1. **原则1**：[说明] 2. **原则2**：[说明] 3. **原则3**：[说明]

---

三、术语定义（如需要）

| 术语 | 定义 | 说明 | |------|------|------| | [术语1] | [定义] | [说明] |

---

四、数据库设计

4.1 新增/修改表

-- [表名] - [说明]
CREATE TABLE / ALTER TABLE ...

4.2 字段说明

| 字段 | 类型 | 位置 | 说明 | |------|------|------|------| | [字段名] | [类型] | [表名] | [说明] |

---

五、功能设计

5.1 [功能模块1]

功能概述

[功能描述]

界面设计

| 操作 | 元素 | 说明 | |------|------|------| | 新增 | [元素] | [说明] |

处理逻辑

[流程说明或伪代码]

---

六、接口设计

6.1 [接口名称]

[METHOD] /api/[path]

请求参数：
{
  "field1": "type - 说明"
}

响应：
{
  "code": 200,
  "message": "成功",
  "data": { ... }
}

**实现位置**：

• Controller: `[文件路径]`
• Service: `[文件路径]`

---

七、前端设计

7.1 组件结构

[目录结构]

7.2 页面实现

**文件位置**：`[文件路径]`

// 关键代码片段

---

八、影响范围评估

8.1 代码改动范围

| 模块 | 文件 | 改动类型 | 说明 | |------|------|---------|------| | [模块] | [文件] | 新增/修改 | [说明] |

8.2 风险评估

| 风险 | 影响 | 缓解措施 | |------|------|---------| | [风险] | [影响] | [措施] |

---

九、测试要点

9.1 功能测试清单

• [ ] [测试点1]
• [ ] [测试点2]

9.2 测试用例

| 测试用例 | 输入 | 预期结果 | |---------|------|---------| | [用例1] | [输入] | [预期] |

---

十、部署/迁移说明（如需要）

10.1 数据库迁移

-- 迁移脚本

10.2 配置变更

| 配置项 | 变更 | 说明 | |-------|------|------| | [配置] | [变更] | [说明] |

---

**文档版本历史**

| 版本 | 日期 | 作者 | 说明 | |------|------|------|------| | v1.0 | [日期] | wwj | 初稿 |

---

模式 2：checklist

基于 S-Tier SaaS 设计标准（参考 Stripe、Airbnb、Linear），进行设计质量检查。

检查清单

一、核心设计原则

• [ ] **用户优先**：界面是否以用户任务为中心设计
• [ ] **简洁清晰**：信息层次是否清晰，无冗余元素
• [ ] **一致性**：颜色、字体、组件是否与现有系统一致
• [ ] **可访问性**：对比度是否达标（WCAG AA 4.5:1）

二、视觉设计

**颜色**

• [ ] 主色调使用是否克制（不超过 3 种主色）
• [ ] 语义色是否正确（成功=绿、错误=红、警告=黄、信息=蓝）
• [ ] 深色模式是否考虑（如需要）

**字体**

• [ ] 标题层级是否清晰（H1 > H2 > H3 > Body）
• [ ] 正文字号是否舒适（14-16px）
• [ ] 行高是否合适（1.5-1.7）

**间距**

• [ ] 是否使用 8px 基准网格
• [ ] 元素间距是否一致
• [ ] 留白是否充足

三、交互设计

• [ ] 按钮状态是否完整（默认、悬停、激活、禁用）
• [ ] 表单验证反馈是否及时
• [ ] 加载状态是否有提示
• [ ] 空状态是否有引导
• [ ] 错误状态是否有恢复建议

四、响应式

• [ ] 桌面端（1440px）布局是否正常
• [ ] 平板端（768px）是否适配
• [ ] 移动端（375px）是否可用
• [ ] 无水平滚动条

五、可访问性（WCAG 2.1 AA）

• [ ] Tab 键导航顺序是否合理
• [ ] 焦点状态是否可见
• [ ] 图片是否有 alt 文本
• [ ] 表单标签是否关联

六、性能

• [ ] 图片是否优化（WebP、懒加载）
• [ ] 动画是否流畅（60fps）
• [ ] 首屏加载是否快速

输出格式

### 设计检查报告：[功能名称]

**总体评分**：⭐⭐⭐⭐☆ (X/5)

#### ✅ 通过项
- [列出通过的检查项]

#### ⚠️ 建议改进
- [问题描述] → [改进建议]

#### ❌ 必须修复
- [问题描述] → [修复方案]

#### 截图/示意（如有）
[相关截图或 ASCII 示意]