database-schema-design

数据库架构设计

当主要任务是选择和演进存储模型，而不是堆砌通用 SQL 或 ORM 代码片段时，请使用此技能。

database-schema-design 是后端存储设计的核心，适用于：

• 在关系型优先、文档为主和混合模型之间进行选择
• 将领域实体转化为表、集合、所有权边界和生命周期规则
• 说明约束、索引、租户范围、历史／审计结构以及删除／保留行为的合理性
• 规划分阶段的架构演进，让迁移、回填和清理方案切实可行
• 在后续工作分支到实现、验证、报告或可观测性之前，向下游团队交付一份精简的存储设计方案

处理规模较大或风险较高的工作前，请阅读以下支持文档：

• references/storage-decision-matrix.md
• references/schema-review-checklist.md
• references/intake-packets-and-route-outs.md

何时使用此技能

• 为产品功能、内部工具、管理工作流、客户数据界面或线上运营／游戏后端系统设计新架构。
• 重构现有存储模型，解决约束薄弱、命名不一致、基数建模不佳或索引缺乏可靠性的情况。
• 决定哪些字段必须作为一等列或已索引的文档字段，哪些可以放在灵活的元数据载荷中。
• 规划多租户、审计日志、权限、状态历史、保留或软删除边界。
• 审查迁移是否安全、分阶段方案是否切实可行，以及对回填、兼容窗口和清理的描述是否准确。
• 在开始实现前，或在制定高风险后端变更方案时，产出一份范围明确的存储方案。

何时不使用此技能

• 主要任务是 REST／GraphQL 契约结构、端点行为、Webhook 语义或版本控制 → api-design。
• 主要任务是身份／会话／提供方设置，或由身份验证管理的用户／组织边界 → authentication-setup。
• 主要任务是迁移验证、仓库覆盖率或契约／回归测试 → backend-testing。
• 主要任务是已发布的文档、快速入门指南或面向开发者的架构／API 说明 → api-documentation。
• 主要任务是超出数据完整性范围的全面加固，例如密钥处理、CSRF、Cookie 或滥用防护 → security-best-practices。
• 主要任务是在已建模数据之上进行仪表板／报告展示，或遥测／告警覆盖 → looker-studio-bigquery 或 monitoring-observability。
• 请求尚无明确的领域、访问模式或生命周期背景；此时应返回待补充的问题，而不是假装架构已经确定。

指南

第 1 步：分类一个主要存储设计方案

选择一个主要方向和一个最小但有用的交付物。

schema_packet:
  workload_shape: oltp | analytics-adjacent | event-log | content-heavy | mixed | unknown
  data_lane: relational-first | document-heavy | hybrid | unknown
  change_type: greenfield | incremental | migration | cleanup | scale-fix
  ownership_focus: product-core | internal-ops | marketing-customer-data | game-live-ops | mixed
  durability_needs: basic | transactional | audit-heavy | compliance-sensitive | unknown
  hottest_risk: integrity | queryability | migration-safety | lifecycle-drift | unclear
  output_packet: design-memo | schema-review | migration-rollout | erd-plus-decisions | unknown

先明确以下内容：

1. 实际的业务实体或聚合是什么？
2. 哪些读取、写入、筛选、联接或报告最有价值？
3. 这是从零开始的设计、线上系统变更，还是架构清理？
4. 哪些规则是真正的业务不变量，哪些只是暂时的实现便利？
5. 现有哪些平台约束（数据库引擎、ORM、托管服务、合规要求、规模）？

第 2 步：收集最低限度且可信的依据

不要仅凭感觉设计存储方案。收集足以支持实际决策的最精简材料：

• 产品／领域目标
• 当前架构、模型或具有代表性的记录（如有）
• 已知的读取／写入、筛选、联接、搜索／报告需求和保留规则
• 租户／所有权、审计／历史以及删除方面的预期
• 发布约束：流量、迁移窗口、锁风险、兼容性问题、下游使用方
• 会导致设计只是表面可行的待解问题

如果依据不足，请明确说明，并将方案控制在评审／备忘录级别，不要假装它已可直接实施。

第 3 步：有意识地选择数据路径

使用 references/storage-decision-matrix.md。

• 当完整性、事务、共享不变量、联接或报告最重要时，优先选择关系型。
• 当一个聚合通常会一起读写，且其结构变化足够大、严格的关系型建模会显得刻意追求精确时，优先选择文档型。
• 当事务核心稳定，但部分元数据／内容负载确实需要灵活性时，选择混合型。

用一两句话说明原因。“因为技术栈已经在用它”是有用的背景信息，但不能作为全部理由。

第 4 步：为所有权、生命周期和查询关键字段建模

为每个核心实体／集合／聚合定义：

• 用途和所有权边界
• 标识符策略
• 必需与可选属性
• 生命周期状态和时间戳
• 关系或引用方向
• 相关的租户／组织所有权
• 删除、归档、保留和历史规则
• 必须可查询、唯一或可用于报告的字段
• 哪些字段可以作为灵活元数据保留，而不损害搜索／报告／运维

注意以下陷阱：

• 镜像 UI 对象，而不是业务概念
• 在 JSON 数据块或临时数组中隐藏多对多关系或历史记录
• 将可变状态、审计历史和派生／缓存数据合并到同一张表／同一个文档中
• 让身份验证／个人资料／会话的所有权与不相关的产品实体混淆
• 当分析、遥测或活动属性已经用于筛选、报告或实时运营决策时，仍将其存储在不透明的负载中

第 5 步：一并设计完整性和访问规则

架构的质量取决于它能否保障不变量。

明确列出：

• 键和所有权规则
• 唯一性／可空性／默认值／状态约束
• 最常用的读取、写入、筛选、联接或聚合查询
• 索引及其存在的原因
• 有意进行的反规范化或灵活字段，以及保持灵活的原因

如果说不清主要查询模式，那么索引建议很可能是空谈。

第 6 步：规划上线和分流

对于增量变更或线上系统变更，请定义：

• 增量式还是破坏性变更
• 是否需要扩展与收缩、回填、双重读／写或影子读取阶段
• 何时可以安全地强制执行索引／约束
• 回滚或停止条件
• 清理旧列／表／文档字段的条件

然后使用 references/intake-packets-and-route-outs.md 明确分流相邻工作：

• api-design：依赖该模型的接口或契约变更
• authentication-setup：身份／会话／提供方所有权
• backend-testing：迁移验证和回归测试覆盖
• looker-studio-bigquery：主要工作是基于整理后的数据制作利益相关方仪表板／报告
• monitoring-observability：主要工作是遥测时效性、告警覆盖或运行时可见性
• security-best-practices：关注点超出数据完整性，涉及更广泛的应用／Web 加固

第 7 步：执行边界检查

完成定稿前，使用 references/schema-review-checklist.md。

验证：

1. 已选择一条数据路径和一个输出包。
2. 已明确所有权、生命周期和查询关键字段。
3. 灵活元数据有充分理由，不是在转移建模欠债。
4. 对线上系统而言，迁移安全方案可信。
5. API／身份验证／测试／报告／可观测性工作已分流，而非被默默纳入。
6. 输出包以明确的下一步行动收尾。

输出格式

## Storage Design Packet: [System or Feature]

### Packet framing
- Workload shape:
- Chosen data lane:
- Change type:
- Ownership focus:
- Why this lane fits:

### Evidence used
- Current artifacts:
- Query/reporting needs:
- Lifecycle or retention constraints:
- Assumptions / gaps:

### Entity / collection map
| Entity | Purpose | Key fields | Relationships / ownership | Lifecycle notes |
|--------|---------|------------|----------------------------|-----------------|
| ... | ... | ... | ... | ... |

### Integrity and access rules
- Required constraints:
- Uniqueness / nullability notes:
- Indexes and why:
- Flexible metadata that stays flexible:

### Rollout / migration plan
- Sequence:
- Backfill / compatibility notes:
- Cleanup conditions:
- Stop / rollback signals:

### Route-outs
- API / contract:
- Auth / identity:
- Verification:
- Reporting / observability:

### Recommended next move
- draft migration plan | review with owners | hand off to API/auth/testing/reporting | defer until missing evidence is gathered

示例

示例 1：SaaS 核心模型

输入：“我们需要为一款 B2B SaaS 应用设计数据库模式，涉及用户、组织、成员关系、订阅、发票和审计日志。我们使用 Postgres，需要可直接用于实现的方案。”

良好的输出方向

• 选择 relational-first
• 清晰地区分用户、组织、成员关系、订阅和不可变的发票记录
• 将审计／历史记录与可变的实体状态分开处理
• 将会话／提供商细节交由 authentication-setup 处理

示例 2：灵活元数据迁移

输入：“我们的交易平台将商品元数据存储在一个 JSON 列中，但现在搜索、审核和筛选都依赖稳定字段。请规划一次安全的迁移。”

良好的输出方向

• 选择 hybrid
• 确定哪些字段必须从 JSON 中独立出来，成为一等列或索引字段
• 提出分阶段发布、回填和清理条件
• 将验证工作交由 backend-testing 处理

示例 3：游戏实时运营边界

输入：“我们需要为一款在线运营游戏设计玩家库存、季节性活动进度和遥测数据模型，同时避免将报表需求塞进不透明的数据块中。”

良好的输出方向

• 将玩家拥有的事务性状态与遥测／报表需求分开
• 让一个存储方案聚焦于状态完整性和生命周期
• 将仪表板／遥测后续工作交由 looker-studio-bigquery 或 monitoring-observability 处理

最佳实践

1. 从业务不变量和访问模式入手，而不是纠结于表的外观。
2. 将迁移安全性视为数据库模式设计的一部分，而非之后才处理的运维杂事。
3. 如实对待灵活元数据：确有需要时很有用，但如果它掩盖了查询所需的关键字段，就会带来风险。
4. 将可变状态、历史／审计数据以及派生／报表数据分开。
5. 将相关的 API／身份验证／测试／报表工作交由其他工具处理，避免把这里变成通用的后端超级技能。
6. 优先采用经久耐用的方案，而不是堆砌大量特定于供应商的示例。

参考资料

• PostgreSQL 数据定义文档
• Prisma 数据指南——建立连接
• MongoDB 数据建模文档
• Firestore 数据结构指南