Development
文档与架构决策记录
记录决策和文档。在进行架构决策、修改公开 API、发布功能或记录背景信息时使用。
记录决策，而不仅仅是代码。最有价值的文档记录的是背后的原因。
ADR 记录了重大技术决策背后的推理过程。
将 ADR 存放在 docs/decisions/ 目录中，按顺序编号：
# ADR-001：使用 PostgreSQL 作为主数据库
## 状态
已接受 | 被 ADR-XXX 替代 | 已废弃
## 日期
2025-01-15
## 背景
我们需要为任务管理应用选择主数据库。关键要求：
- 关系型数据模型（用户、任务、团队之间的关联）
- 任务状态变更需要 ACID 事务支持
- 支持任务内容的全文搜索
- 提供托管服务
## 决策
使用 PostgreSQL 搭配 Prisma ORM。
## 考虑过的备选方案
### MongoDB
- 优点：灵活的 Schema，上手容易
- 缺点：我们的数据本质上是关系型的；需要手动管理关联关系
- 否决原因：在文档存储中处理关系型数据会导致复杂的连接或数据重复
### SQLite
- 优点：零配置、嵌入式、读取速度快
- 缺点：并发写入支持有限，无生产环境托管服务
- 否决原因：不适合生产环境中的多用户 Web 应用
## 影响
- Prisma 提供类型安全的数据库访问和迁移管理
- 可以使用 PostgreSQL 的全文搜索，无需额外引入 Elasticsearch
- 团队需要掌握 PostgreSQL 知识（标准技能，风险较低）
已提议 → 已接受 → （已替代 或 已废弃）
注释为什么，而不是是什么：
// 不好：复述代码
// 计数器加 1
counter += 1;
// 好：解释非显而易见的意图
// 速率限制使用滑动窗口——在窗口边界重置计数器，
// 而不是在固定时间点，以防止窗口边缘的突发攻击
if (now - windowStart > WINDOW_SIZE_MS) {
counter = 0;
windowStart = now;
}
// 不要注释自解释的代码
function calculateTotal(items: CartItem[]): number {
return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
// 不要为应该立即完成的事情留 TODO 注释
// TODO: 添加错误处理 ← 直接添加即可
// 不要保留被注释掉的代码
// const oldImplementation = () => { ... } ← 删除它，git 有历史记录
/**
* 创建一个新任务。
*
* @param input - 任务创建数据（title 必填，description 可选）
* @returns 创建的任务，包含服务器生成的 ID 和时间戳
* @throws {ValidationError} 如果 title 为空或超过 200 个字符
* @throws {AuthenticationError} 如果用户未通过认证
*
* @example
* const task = await createTask({ title: 'Buy groceries' });
* console.log(task.id); // "task_abc123"
*/
export async function createTask(input: CreateTaskInput): Promise<Task> {
// ...
}
每个项目都应有一个涵盖以下内容的 README：
# 项目名称
一段话描述本项目的作用。
## 快速开始
1. 克隆仓库
2. 安装依赖：`npm install`
3. 配置环境：`cp .env.example .env`
4. 启动开发服务器：`npm run dev`
## 命令
| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm test` | 运行测试 |
| `npm run build` | 生产构建 |
| `npm run lint` | 运行代码检查 |
## 架构
简要概述项目结构和关键设计决策。
详见 ADR 文档。
## 贡献指南
如何参与贡献、编码规范、PR 流程。
已发布功能的记录格式：
# 变更日志
## [1.2.0] - 2025-01-20
### 新增
- 任务分享：用户可以将任务分享给团队成员 (#123)
- 任务分配的邮件通知 (#124)
### 修复
- 快速点击创建按钮时出现重复任务的问题 (#125)
### 变更
- 任务列表每页加载数量从 20 条调整为 50 条，提升用户体验 (#126)
针对 AI 智能体的特殊考虑：
文档编写完成后检查：