architecture-decision-records

架构决策记录

记录重要的技术决策，以便未来的你（和团队）了解做出这些选择的原因。

何时编写 ADR

在做出符合以下条件的决策时，编写一份 ADR：

• 之后难以撤销
• 影响系统的多个部分
• 涉及多个可行选项之间的权衡
• 6 个月后可能会有人提出质疑

示例：选择数据库、采用框架、更改身份验证策略、重构 API、添加构建工具。

模板

在 docs/decisions/（或 adr/）中创建文件，并按顺序编号：

# ADR-001: Use PostgreSQL for primary database

## Status

Accepted | Proposed | Deprecated | Superseded by ADR-XXX

## Date

2026-04-10

## Context

What is the problem or situation that requires a decision?
Include constraints, requirements, and forces at play.

## Options Considered

### Option A: PostgreSQL
- Pros: ACID compliance, JSON support, mature ecosystem, free
- Cons: Requires managing connections, vertical scaling limits

### Option B: MongoDB
- Pros: Flexible schema, horizontal scaling
- Cons: No transactions across collections, eventual consistency issues

### Option C: PlanetScale (MySQL)
- Pros: Serverless, branching, managed
- Cons: Vendor lock-in, no foreign keys in their branching model

## Decision

We chose **PostgreSQL** because:
1. Our data is relational — users, teams, projects with clear relationships
2. We need ACID transactions for billing operations
3. JSON columns give us schema flexibility where needed
4. Prisma/Drizzle have excellent Postgres support

## Consequences

- We need to manage connection pooling (use PgBouncer or Prisma's built-in pool)
- Migrations must be backwards-compatible for zero-downtime deploys
- We accept vertical scaling limits and will shard later if needed

工作流

1. 确定要做出的决策
2. 调研各个选项（至少 2-3 个备选方案）
3. 使用模板编写 ADR
4. 与团队评审（通过 PR 或讨论）
5. 合并并标记为已接受
6. 在相关代码注释中引用：// See ADR-001

文件命名

docs/decisions/
├── 001-use-postgresql.md
├── 002-adopt-trpc-over-rest.md
├── 003-switch-to-pnpm.md
└── template.md

提示

• ADR 应简短，最多 1-2 页
• 使用现在时撰写（“我们选择 X”，而不是“我们选择了 X”）
• 如果决策时忘记编写 ADR，事后补写也没问题
• 被取代的 ADR 应链接到替代它的记录，而不是删除
• ADR 不是设计文档——它记录的是决策，而不是完整设计