2. 创建功能设计文档

上下文与触发条件 (Context & Trigger)

此流程在用户已批准功能需求文档 (requirements.md) 后启动。必须确保相关的需求文档已经存在并获得认可。

核心目标 (Core Objective)

基于已批准的需求，创建一份全面、可执行的技术设计文档。这份文档将保存在 .workflow/{feature_name}/design.md 文件中，并作为后续任务规划的基础。

核心工作流程 (Core Workflow)

必须严格遵循以下步骤顺序执行：

1. 强制调研与信息请求 (Mandatory Research & Information Request):

   • 第一步是调研。在产出任何设计细节前，必须先进行技术调研。
   • 主动请求信息：为了使调研更有效，必须首先向用户请求上下文信息。使用如下话术：“为了更好地进行调研和设计，您可以把您认为最相关的代码片段、配置文件或文档附上一部分吗？这将极大地帮助我理解现有架构。”
   • 总结与引用:
     • 基于用户提供的信息和对通用最佳实践的理解，总结关键的调研发现。
     • 必须将调研发现直接融入设计文档的相应部分，而不是创建独立的调研文件。
     • 如果在调研中参考了外部资料（如技术文章、库文档等），必须在对话中引用来源并提供相关链接。

2. 创建设计文档初稿 (design.md):

   • 如果 .workflow/{feature_name}/design.md 文件不存在，则创建它。
   • 依据下文的 “design.md 文档规格”，编写一份包含所有必需部分的设计文档初稿。在适当时，应包含图表或可视化内容（使用 Mermaid 绘制）。
   • 突出设计决策：必须在文档中清晰地突出关键的设计决策及其背后的理由。
   • 征求意见：在设计过程中，可就特定的技术决策向用户征求意见。例如：“关于数据存储，我们可以在现有表中增加字段，也可以创建新表。我倾向于创建新表以实现关注点分离，您觉得呢？”
   • 覆盖所有需求：必须确保最终的设计能够覆盖澄清过程中确定的所有功能需求。
   • 在设计过程中，如果发现需求存在歧义或缺口，必须暂停并向用户提问以澄清，或直接建议返回需求阶段。

3. 口头演练 (Verbal Dry-Run):

   • 在呈现设计文档初稿之后，但在请求正式批准之前，必须进行一次口头的实现路径演练。
   • 使用如下话术：“在您详细审查文档前，让我快速口头描述一下设想的实现路径，以帮助我们提前发现潜在风险：[此处用几句话简要、清晰地描述从用户操作到系统响应的端到端数据流和关键组件交互]。这个流程听起来有什么问题吗？”

4. 互动与批准循环 (Interaction & Approval Loop):

   • 在完成口头演练并根据初步反馈调整后，必须暂停并正式请求用户批准。使用如下确切问句：“这份设计文档怎么样？如果还不错，将进入计划实施阶段。”
   • 如果用户未提供明确批准（如“是”、“批准了”等），则必须根据其反馈修改设计文档。
   • 每一轮修订后，都必须再次征求用户的明确批准，并重复此步骤。
   • 严禁在未获得用户明确批准前，进入或提及“实施计划”阶段。

design.md 文档规格与内容要求

产出的设计文档必须严格遵循以下结构，并突出设计决策及其背后的理由。

• 文件结构: 一份包含以下所有部分的 Markdown 文件。
• 图表示例: 在适当的情况下，使用 Mermaid.js 语法嵌入图表。

示例格式应用

# 设计文档: “记住我”功能

## 1. 概述 (Overview)

### 1.1. 目标 (Goals)

为用户提供“记住我”选项，允许其在关闭浏览器后的一段时间内（例如 30 天）保持登录状态，以提升回访用户的体验。

### 1.2. 范围 (Scope)

- **In-Scope**:
  - 在登录页面提供“记住我”复选框。
  - 用户勾选后，生成长效持久化令牌。
  - 用户下次访问时，通过令牌自动完成登录。
- **Out-of-Scope**:
  - 管理已登录设备或吊销特定令牌的功能。
  - 跨设备同步“记住我”状态。

### 1.3. 关联需求 (Related Requirements)

- (关联需求: F-Auth-05, NF-SEC-02)

## 2. 整体架构 (System Architecture)

### 2.1. 架构图 (Diagram)

[此处应嵌入一个高层级的架构图，用于清晰地展示新功能将如何融入现有系统，以及关键组件间的交互关系。**推荐使用序列图 (Sequence Diagram) 来描述交互流程，或使用组件图 (Component Diagram) / C4 模型来展示系统结构。**]

### 2.2. 设计决策与权衡 (Design Decisions & Trade-offs)

- **决策**: 采用独立的持久化令牌，而非延长会话(session)有效期。
  - **理由**: 增强安全性。长效会话更容易被劫持，而持久化令牌可以设计为一次性使用或与特定设备/IP 绑定，且不直接暴露会话 ID。
  - **权衡**: 实现逻辑比简单延长会话略复杂，需要额外的数据表和验证逻辑。

## 3. 数据模型 (Data Model)

**决策**: 新建`persistent_tokens`表来存储令牌信息，以实现关注点分离。

[如果需要修改数据库，应在此处描述表结构变更。**推荐使用实体关系图 (ER Diagram) 来清晰地展示数据模型。**]

## 4. API 接口设计 (API Design)

[对于每个新增或修改的 API 端点，都应提供详细的定义。]

### `[HTTP 方法] /api/path/to/endpoint`

- **描述**: [清晰地描述此端点的功能和用途。]
- **请求体 (Request Body)**:
  ```json
  {
    "key": "value_type",
    "another_key": "another_value_type"
  }
  ```

• 成功响应 (Success Response):
  • 状态码: 200 OK
  • 响应头 (Headers): [可选。列出关键的响应头，如 Set-Cookie。]
  • 响应体 (Body):

    {
      "status": "success",
      "data": {}
    }
    

• 失败响应 (Error Response):
  • 状态码: 4xx/5xx
  • 响应体 (Body):

    {
      "error": "A descriptive error message."
    }
    

5. 核心逻辑实现 (Core Logic)

• 令牌验证中间件 verify_persistent_token:
  1. 在常规会话验证失败后触发。
  2. 从请求的Cookie中提取remember_token。
  3. 如果令牌不存在，则流程结束。
  4. 使用SHA-256对令牌进行哈希计算。
  5. 在persistent_tokens表中查找该哈希值。
  6. 若找到且expires_at未过期，则为该user_id创建一个新的会话(session)，并删除当前使用的持久化令牌（增强安全性，每次都换新令牌）。
  7. 若未找到或已过期，则清除客户端的无效remember_token Cookie。

6. 非功能性需求 (Non-Functional Requirements)

• 安全性 (Security):
  • 令牌在数据库中必须使用强哈希算法（如 SHA-256）存储，绝不能明文存储。
  • remember_token Cookie 必须设置为HttpOnly以防止 XSS 攻击，设置为Secure以确保只在 HTTPS 下传输。
• 性能 (Performance):
  • 令牌验证的数据库查询（基于主键）必须在50ms内完成。

7. 测试策略 (Testing Strategy)

• 单元测试:
  • generate_secure_token()函数的随机性和唯一性。
  • hash_token()函数的正确性。
• 集成测试:
  • POST /api/auth/login接口在rememberMe为 true/false 时，响应头的Set-Cookie是否正确。
  • verify_persistent_token中间件能否在有/无/无效/过期令牌的情况下正确处理。
• 端到端测试:
  • 模拟用户勾选“记住我”并登录，关闭浏览器，30 分钟后再打开，应能自动登录。
  • 模拟令牌过期后，用户需要重新手动登录。

8. 风险与缓解措施 (Risks & Mitigation)

• 风险: 用户的物理设备被盗，导致账户被非授权访问。

  • 缓解措施: 在用户修改密码或手动“登出所有设备”时，必须清空该用户在persistent_tokens表中的所有记录。

• ⚠️ 若在设计过程中发现需求存在缺口，模型应主动建议返回功能需求澄清阶段