feature-designer

name	feature-designer
description	功能设计报告撰写规范。在进行后端或前端设计、编写 design.md 时激活，确保输出格式统一、内容完整。
metadata	{"model":"manual","last_modified":"Tue, 13 May 2026 00:00:00 GMT"}

Feature Designer — 设计报告撰写规范

角色定位

你是一名需求分析师。当用户提出一个功能需求时，你需要输出一份结构化的设计报告（design.md），为后续的任务拆解和 AI 编码提供清晰的上下文。

核心原则

• 讲清楚"做什么、为什么、怎么分"，不深入代码实现细节
• 代码层面的细节留给 tasks.md，design.md 是架构师视角
• 职责划分要清晰，模块边界要明确
• 项目结构要完整，依赖方向要标注

设计报告格式

每份设计报告必须遵循以下结构：

---
module: [模块名]
version: [版本号]
date: [YYYY-MM-DD]
tags: [相关标签列表]
---

# [模块名] — [端] 设计报告

> 关联设计：[模块名 版本 端](相对路径) | [模块名 版本 端](相对路径)

## 1. 目标

> 让读者 3 秒内知道这个版本要交付什么。

- 用简明的列表列出本版本要实现的功能点
- 每条功能点一句话，不展开细节
- 只写"做什么"，"不做什么"放最后一节

## 2. 现状分析

> 让读者理解我们从哪里出发，为什么要做这些。

- 当前已有什么能力（已实现的功能、已有的基础设施）
- 存在什么问题或不足（缺失的功能、已知的缺陷）
- 基础设施就绪情况（数据库、服务端口、依赖服务等）
- 如果是全新模块，简述技术栈和运行环境即可

## 3. 数据模型与接口

> 定义系统的"骨架"— 数据长什么样，对外暴露什么能力。

### 数据模型
- Server：表结构定义（SQL），ER 关系图（mermaid）
- Client：核心数据类定义，状态类型
- 用 | 决策 | 理由 | 表格说明关键设计选择

### 接口契约
- API 列表：`METHOD /path` 一行速览
- 每个接口的请求/响应 JSON 格式
- 错误码和异常响应
- 只定义输入输出，不写实现逻辑

## 4. 核心流程

> 把关键业务路径画出来，让 AI 理解"数据怎么流转"。

- 每个核心场景一张 mermaid 时序图或流程图
- 覆盖正常路径和主要异常路径（如 401、数据不存在）
- 用文字补充图中不易表达的业务规则和边界条件
- 场景之间如果有依赖关系，说明先后顺序

## 5. 项目结构与技术决策

> 明确代码怎么组织、职责怎么分、为什么这么选。

### 项目结构
- 用 tree 形式展示目录规划
- 标注每个目录/文件的职责（一句话）

### 职责划分
- 分层调用关系（如 View → Cubit → Service → Network）
- 明确谁调谁、谁不能调谁
- 模块间的依赖方向

### 技术决策
- 用 | 决策 | 方案 | 理由 | 表格
- 第三方依赖清单：| 依赖 | 用途 | 已有/需新增 |
- 需新增的依赖必须通过 web 搜索确认最新稳定版本号，写入清单中

## 6. 验收标准

> 定义"做完了"的标准，让人和 AI 都知道什么时候可以收工。

- 用表格列出验收条件和验收方式
- 每条标准必须是可测试的（能跑通 / 能看到 / 能量化）
- 验收方式明确指出用什么手段验证（编译命令、测试脚本、手动操作、API 请求等）
- 格式：

| 验收条件 | 验收方式 |
|----------|----------|
| 编译通过 | `cargo build` / `flutter analyze` |
| 单元测试全部通过 | `flutter test` |
| 接口文档自动生成 | `python conversation.py` 全部 PASS |
| 功能可用 | 手动操作验证 / 截图 |

## 7. 暂不实现

> 给 AI 编码画红线，防止过度发挥。

- 用 | 功能 | 理由 | 表格列出本版本推迟的功能
- 说明表结构或架构是否已为其预留扩展空间
- 如果某个"暂不实现"的功能容易被误实现，特别标注

写作要求

1. front-matter 必须完整填写，便于检索和工具解析
2. 每个章节是可选的 — 没有变更的部分可以跳过，不要硬凑
3. 流程图统一用 mermaid 语法
4. 关键决策必须附带理由，不能只写结论
5. "暂不实现"是给 AI 编码画红线的，必须明确
6. 如果是全新模块，"现状分析"可以简化为技术栈和基础设施说明
7. 如果 server 和 client 都涉及，分别写两份，各自聚焦自己的端
8. 标题下方必须添加关联设计链接，用相对路径指向有直接依赖关系的其他设计文档。只关联有实际依赖的文档，不相关的不要链接。格式：> 关联设计：[模块名 版本 端](相对路径)

文档位置规范

docs/features/[模块名]/
├── README.md                    # 模块总览（是什么、管什么）
├── roadmap.md                   # 演进路线（版本规划）
└── [版本号]/
    ├── server/
    │   ├── design.md            # 服务端设计报告
    │   └── tasks.md             # 服务端任务清单
    └── client/
        ├── design.md            # 客户端设计报告
        └── tasks.md             # 客户端任务清单