project-documentation

项目功能文档

编写清晰、非技术性的项目功能文档，说明功能的作用、存在的原因及运作方式，不深入探讨代码细节。文档以 Markdown 文件的形式存放在 docs/ 文件夹中。

目的

这些文档面向两类读者：

1. 非开发人员——产品经理、设计师和利益相关者，他们需要从概念层面了解功能
2. 排查问题的 AI Agent——当 AI 可以访问代码但需要了解预期行为、业务规则和功能间关系时，为其提供背景信息

目标读者

使用非开发人员也能理解的通俗语言，同时提供足够的细节，帮助在代码库中工作的 AI Agent 快速了解预期行为和业务逻辑。

功能索引（推荐）

创建一个 docs/README.md，同时用作功能清单和导航索引。仅在功能文档编写完成后，将其列入索引。

格式示例

# Project Documentation

## Core Features

### [User Authentication](user-authentication.md)
**Related**: User Profile, Session Management
**Summary**: Account creation, login, password reset

### [Payment Processing](payment-processing.md)
**Related**: Order Management, Email Notifications
**Summary**: Stripe integration for payments, refunds, and disputes

### [Dashboard Analytics](dashboard-analytics.md)
**Related**: User Authentication (requires login)
**Summary**: Real-time metrics and reporting

## Secondary Features

### [Email Notifications](email-notifications.md)
**Related**: Most core features
**Summary**: SendGrid integration with queued processing

## Integrations

### [Stripe API](stripe-integration.md)
**Related**: Payment Processing
**Summary**: Payment gateway for transactions and webhooks

索引最佳实践

仅在功能文档编写完成后，才将其添加到索引中。这样可以保持索引整洁，并确保每个列出的功能都有对应文档。

请包含以下字段：

• 功能名称——链接到文档文件
• 相关功能——依赖关系和相互关系
• 摘要——一句话描述

文档结构

每项功能在 docs/ 中都有自己的 Markdown 文件。文件名应具有描述性，并使用小写字母和连字符：

docs/
├── user-authentication.md
├── payment-processing.md
├── email-notifications.md
└── dashboard-analytics.md

哪些内容算作“功能”？

功能指任何重要的面向用户行为或系统能力，包括：

• 面向用户的功能——用户可以执行的操作（登录、提交表单、查看报告）
• 管理工作流——用于管理系统的后台流程（用户管理、内容审核）
• 业务规则和条件逻辑——用于规范行为的规则（审批工作流、资格检查）
• 权限和基于角色的行为——不同类型的用户可以或不可以执行哪些操作
• 与第三方服务的集成——外部 API、支付网关、电子邮件服务
• 后台处理——定时任务、计划任务、排队操作
• 自动化——由事件触发的自动操作（自动通知、数据同步）
• 自定义数据流——信息在系统中的流转方式
• 生命周期行为——状态转换及其触发条件

如果某项内容会影响用户体验或系统行为，就值得记录。

功能文档模板

每项功能都使用以下结构：

# [Feature Name]

## What It Does

[1-2 paragraph overview of what this feature accomplishes from the user's perspective]

## Why We Built It

[Explain the problem this solves or the need it fulfills]

## How It Works

[Step-by-step explanation of the feature's behavior and logic, without code details]

### Key Components

- **[Component 1]**: What it does
- **[Component 2]**: What it does
- **[Component 3]**: What it does

### Data Flow

[What information enters the feature, how it's transformed, and what comes out]

## User Experience

[Describe what users see and how they interact with this feature]

## Expected Behavior

### Success Scenarios
- **Scenario 1**: [Input] → [Expected Result]
- **Scenario 2**: [Input] → [Expected Result]

### Error Scenarios
- **When [condition]**: [Expected behavior/message]
- **When [condition]**: [Expected behavior/message]

## Business Rules

[Critical validation rules, constraints, and logic that must always be enforced]

**Examples:**
- Passwords must be 8+ characters with 1 number and 1 special character
- Users cannot delete items that are currently in use
- Refunds are only allowed within 30 days of purchase

## Dependencies

### Required Features/Systems
- [Feature/System]: Why it's needed

### Affected Features
- [Feature]: How this feature impacts it

### External Services
- [Service]: What it's used for

## Common Issues & Edge Cases

[Document known edge cases, gotchas, or areas that commonly cause confusion]

**Examples:**
- When the external API times out, the system should queue and retry
- If a user has multiple sessions, changes in one should reflect in all
- Empty state: what happens when there's no data to display

## Future Considerations

[Optional: Known limitations or planned enhancements]

写作指南

应该：

• 使用通俗语言——避免行话和技术术语
• 聚焦行为——说明会发生什么，而不是代码如何实现
• 解释“原因”——说明业务逻辑和决策依据
• 使用具体示例——提供包含预期结果的具体场景
• 描述用户流程——“用户执行 X 时，系统会执行 Y”
• 记录边界情况——说明在异常或错误情况下会发生什么
• 明确说明规则——包括验证逻辑、业务限制和必要条件
• 提及集成——说明涉及哪些外部服务或系统
• 列出依赖项——说明此功能依赖什么，以及哪些内容依赖此功能
• 记录预期错误——说明出现错误时应显示哪些错误消息

不应该：

• 引用代码——不要写函数名、类名或文件路径
• 包含实现细节——不要写数据库架构、API 端点或技术架构
• 使用开发者行话——不要使用“中间件”“ORM”“序列化”等术语
• 臆作假设——解释缩写和领域术语
• 含糊其辞——避免只说“处理各种情况”，却不具体说明

对 AI 故障排查至关重要：

• 记录“正常流程”——一切正常时应该发生什么
• 记录错误流程——出现问题时应该发生什么
• 阐明业务规则——必须始终遵守的约束
• 注明功能边界——一个功能的结束位置和另一个功能的开始位置
• 解释不明显的逻辑——任何看起来像 Bug、但实际上是有意为之的行为
• 描述隐式行为——自动分配、默认值、隐藏触发条件
• 记录依赖配置的行为——设置或用户属性变化时，行为会如何改变

仅靠代码还不够时

有些功能的行为无法仅通过阅读代码看出来：

• 历史背景——作出某些决策的原因
• 业务规则——基于利益相关方要求的逻辑
• 隐式假设——未在代码中明确写出的默认行为
• 边缘情况处理——对异常场景的处理决策
• 配置驱动的行为——在不同情境下的不同表现

记录文档时遇到不明确的行为：

1. 记录不明确之处——写下需要解答的问题
2. 询问用户/SME——向了解业务背景的人请求澄清
3. 记录答案——将澄清后的行为补充到文档中
4. 明确说明——在文档中清楚写明隐式行为

向 SME 提出的问题示例：

• “用户有多个角色时，哪些权限优先？”
• “结账期间外部 API 不可用时，应该怎么处理？”
• “为什么要将用户自动分配到 Team A，而不是 Team B？”
• “退款期限限制为 30 天的业务原因是什么？”

文档示例

好的示例：

# User Authentication

## What It Does

Allows users to create accounts and securely log in to access their personalized dashboard. Users can also reset their password if they forget it.

## Why We Built It

We needed a secure way to identify users and protect their personal data. Each user has unique settings and history that should only be accessible to them.

## How It Works

### Registration
When someone signs up, they provide an email address and create a password. The system checks that the email isn't already in use and that the password meets security requirements (at least 8 characters, one number, one special character). We send a verification email to confirm they own the email address.

### Login Process
Users enter their email and password. The system verifies these credentials match what's stored. If correct, they get access to their account. After 3 failed attempts, the account is temporarily locked for 15 minutes to prevent unauthorized access attempts.

### Password Reset
If a user forgets their password, they can request a reset link via email. The link is valid for 1 hour. Clicking it allows them to set a new password.

### Data Flow
Email + Password → Validation → Password Security Check → Store Account → Send Verification Email → User Clicks Link → Account Activated

## User Experience

- Registration form with email and password fields
- Validation messages appear in real-time (e.g., "Password too short")
- Verification email arrives within 1-2 minutes
- Login page with "Forgot Password?" link
- Error messages are helpful but don't reveal whether an email exists in the system

## Expected Behavior

### Success Scenarios
- **Valid registration**: User receives verification email within 2 minutes, can click link and access account
- **Valid login**: User enters correct credentials, immediately redirected to dashboard
- **Password reset request**: User receives reset link within 2 minutes, link works for 1 hour

### Error Scenarios
- **Duplicate email**: Show "An account with this email already exists" message
- **Weak password**: Show specific requirements not met (e.g., "Password must include a number")
- **Failed login (1-2 attempts)**: Show "Invalid email or password" message
- **Failed login (3 attempts)**: Show "Account locked for 15 minutes due to too many failed attempts"
- **Expired reset link**: Show "This reset link has expired. Please request a new one."
- **Unverified account login**: Show "Please verify your email before logging in" with option to resend

## Business Rules

- Email addresses must be unique across all accounts (case-insensitive: [email protected] = [email protected])
- Passwords must be at least 8 characters with 1 number and 1 special character (!@#$%^&*)
- Passwords expire after 90 days and users must create a new one
- New password cannot match previous 3 passwords
- Verification emails expire after 24 hours
- Users can't register with disposable email services (list maintained separately)
- Account lockout after 3 failed attempts lasts exactly 15 minutes
- Password reset links expire after 1 hour
- Only one active reset link per account - requesting new one invalidates previous

## Dependencies

### Required Features/Systems
- **Email delivery service**: For verification and password reset emails. If service is down, registration/reset will fail gracefully with "Unable to send email, please try again later"
- **Session management**: Required to maintain logged-in state

### Affected Features
- **User profile**: Cannot be accessed without authentication
- **Dashboard**: Requires active session
- **Settings**: Changes require password re-confirmation

### External Services
- **Email service**: SendGrid for transactional emails
- **Disposable email checker**: API to validate email domains

## Common Issues & Edge Cases

**Multiple tabs/sessions**: If user logs out in one tab, all other tabs should immediately reflect logged-out state. Currently handled via session token validation on each request.

**Email service downtime**: System will retry sending 3 times over 10 minutes. If all fail, user sees error message but account is created - they can request verification resend from login page.

**Case sensitivity**: Email addresses are stored lowercase and compared case-insensitively. "[email protected]" and "[email protected]" are treated as same user.

**Timing attacks**: Login error messages deliberately don't distinguish between "email not found" and "wrong password" to prevent account enumeration.

**Clock skew**: Reset links use server time, not user device time, to prevent timezone issues.

## Future Considerations

- Add two-factor authentication option
- Support social login (Google, GitHub)
- Add "Remember me" option for extended sessions

不好的示例：

# Authentication

Uses JWT tokens with bcrypt hashing. The AuthController handles login() and register() methods. Password validation uses regex pattern /^(?=.*[0-9])(?=.*[!@#$%^&*])/.

Database schema includes users table with email, password_hash, and created_at columns.

这过于技术化，关注的是实现方式，而不是从用户角度说明做什么、为什么做以及如何做。

工作流：记录新功能

功能完成后：

1. 确定功能范围——从用户角度看，哪些内容构成这个“功能”？
2. 创建文档文件——在 docs/ 中使用清晰、描述性强的名称
3. 从“是什么”开始——用简单的语言描述该功能的作用
4. 解释“为什么”——它解决了什么问题？
5. 详细说明“如何做”——逐步介绍其行为和逻辑
6. 记录预期行为——通过具体示例说明成功和错误场景
7. 列出业务规则——所有必须执行的验证和约束
8. 梳理依赖关系——该功能需要什么，以及哪些功能依赖它
9. 记录边缘情况——异常场景及其处理方式
10. 添加到索引——在 docs/README.md 中添加条目，并附上摘要和关联关系
11. 检查清晰度——非开发人员能看懂吗？AI Agent 能知道预期行为吗？

工作流：记录现有项目

为没有现有文档的完整项目编写文档时：

1. 识别所有功能——检查项目，或利用你对其功能的了解
2. 确定功能优先级——先记录核心功能，再记录辅助功能
3. 记录每项功能——遵循上面的模板
4. 添加到索引——记录每项功能后，将其添加到 docs/README.md 中（模板请参见上文的“功能索引”部分）
5. 关联相关功能——在每份文档中交叉引用存在交互的功能

编写高质量文档的技巧

具体明确

• ❌ “系统会处理各种错误情况”
• ✅ “如果邮件服务不可用，系统会将消息加入队列，并每隔 5 分钟重试一次，最多持续 2 小时”

使用场景

• ❌ “支持批量操作”
• ✅ “用户可以选择多个项目并一次性删除。如果某个项目已锁定或正在使用，系统会显示无法删除的项目及原因”

解释决策

• ❌ “密码必须至少包含 8 个字符”
• ✅ “密码必须至少包含 8 个字符，以兼顾安全性和易用性：长度足以抵御常见攻击，又不至于难以记忆”

描述边缘情况

• ❌ “处理支付”
• ✅ “支付过程中，如果支付网关超时，系统会等待 30 秒，然后直接查询支付状态。这可以防止重复扣款”

维护文档

• 行为发生变化时更新——不是代码发生变化时，而是面向用户的行为或业务逻辑发生变化时
• 保持内容最新——删除已弃用的功能，或明确标记它们已弃用
• 记录重要变更的版本——注明何时新增或修改了主要功能
• 定期审查——确保文档仍准确反映产品

总结清单

在完成功能文档前：

核心内容

• 从用户角度说明功能的作用
• 说明该功能存在的原因（问题／需求）
• 不引用代码，描述功能的工作方式
• 包含数据流概述

预期行为（对 AI 故障排查至关重要）

• 使用具体的输入和输出记录成功场景
• 记录错误场景及预期的错误消息
• 涵盖边缘情况和异常情形
• 说明依赖项故障时应发生什么

业务规则（对 AI 故障排查至关重要）

• 列出所有验证规则并提供具体示例
• 记录必须始终强制执行的约束
• 解释那些看起来像 Bug 的非显而易见逻辑

集成与依赖项

• 列出必需的功能／系统并加以说明
• 列出受此功能影响的功能
• 记录外部服务及其用途
• 说明依赖项不可用时会发生什么

常见问题

• 记录已知的边缘情况
• 解释容易出错之处或令人困惑的行为
• 涵盖常见故障模式

质量

• 使用非开发者也能理解的通俗语言
• 提供具体示例，而非抽象描述
• 能帮助 AI Agent 快速理解预期行为
• 文件保存在 docs/ 中，且文件名清晰