---
name: soloforge-database-design
description: 设计适配当前项目的数据模型、持久化约束、迁移兼容与恢复方案。
when: 数据库设计 / 数据持久化设计 / database_design / scope.persistence
---

# 数据持久化设计

## 适用性

任务涉及需要跨进程、跨会话或长期保留的数据时使用。关系数据库、文档库、键值存储、对象存储、事件存储或混合方案都可适用；纯无状态变更应明确不适用，不为填模板引入存储系统。

## 事实输入

- 领域对象、状态机、业务不变量、读写场景、数据规模与增长依据。
- 当前真实的模型定义、schema、migration、集合/索引配置、保留策略及历史数据。
- 存储产品与版本、部署形态、一致性能力、备份恢复能力和消费方。
- 隐私、租户、审计、保留期、数据驻留和合规要求。
- `template.md` 和 `examples.md`。

## 关键决策

- 数据对象和所有权边界，以及选择关系型、文档型、键值、对象、事件或组合模型的理由。
- 数据不变量由哪个层次保证；事务、一致性、幂等、并发冲突和失败语义如何处理。
- 索引、分区、缓存或物化视图必须由真实访问路径与容量事实驱动，并说明写入、成本和一致性代价。
- 迁移恢复方式按风险选择：兼容性演进、可逆变更、expand/contract、备份恢复或前向修复；不能把 down 脚本当万能答案。

## 产出方法

1. 先识别当前项目的权威持久化资产；它可以是 migration、schema、模型定义、集合/索引配置、基础设施声明或它们的组合。
2. 使用 project map 解析后的文档路径；默认文档为 `docs/design/01-数据库设计文档.md`，不强制创建 `schema.sql`。
3. 对每个数据对象记录来源、所有者、属性、敏感级别、不变量、访问路径和生命周期。
4. 对每次变更写前置检查、兼容窗口、执行步骤、数据校验、停止条件和恢复路径。
5. 在目标存储的真实版本或生产等价环境执行适用验证，并记录命令/步骤、环境、结果和证据位置。

## 禁止项

- 不得虚构对象、字段/属性、数据量、访问模式、性能收益或已执行证据。
- 不得把 SQL 表格结构强加给非关系型存储，也不得用 Markdown 替代真实权威资产。
- 不得先实施破坏性迁移再让设计追认。
- 不得要求危险或不可行的 down 脚本；有数据丢失风险时优先安全恢复或前向修复。
- 不得用“加索引/加缓存即可”替代查询计划、容量依据和一致性分析。

## 交付自检

- 文档与当前项目的权威持久化资产一致；资产类型和路径清楚可定位。
- 每个消费方字段能映射到真实数据来源、派生规则或明确的非持久化来源。
- 适用的不变量、一致性、并发、敏感数据、租户和生命周期风险均有执行位置与验证方式。
- 迁移能在目标版本执行，并有与风险匹配、经过验证的恢复方案。
- 所有 `N/A` 均有具体理由，未知事实没有伪装成最终结论。

## 权威验证

编辑后先处理 quick 反馈，再调用 `sf_verify action="full" task_id="当前任务ID" artifact="database_design"`。完整验证证明产物结构与声明式规则满足要求；真实迁移、数据一致性和恢复能力仍须由项目验证命令、演练证据及独立审查共同证明。


## 交付前对抗审查

`sf_verify` 通过只证明结构/编译/测试层；语义质量（承接正确性、异常/并发/权限/边界是否可靠、是否含空话或无法证伪的承诺）须经独立对抗审查。advance/deliver 前用 `sf_review action="start" task_id="当前任务ID" artifact="<本产物 kind>"` 发起 per_artifact 审查，用**独立 session/subagent**（非产出本产物的同一会话）执行返回的 prompt、submit findings，按 next_step 完成 K 次独立采样与闭环。deliver 会阻断未完成/未闭环的审查；活跃豁免与被驳回 error 会被注入审查 focus 供独立复核。