# 数据持久化设计文档

> **事实纪律**：对象、属性、约束、规模、命令和验证结果必须来自当前项目或真实执行。未知项写“待确认”并说明责任与下一步；合法不适用项写 `N/A（原因）`。
>
> **适用纪律**：关系数据库、文档库、键值存储、对象存储、事件存储或混合方案均可使用本模板。只填写当前方案适用的机制，不得为了模板创建 `schema.sql`、外键、索引或回滚脚本。
>
> **权威纪律**：Markdown 解释决策，但不能替代项目的权威持久化资产。权威资产可以是 migration、schema、模型定义、集合/索引配置、基础设施声明或其组合，路径必须可定位。

## 1. 存储方案与权威资产

### 存储方案表

| 项目 | 当前结论 | 事实来源 |
|---|---|---|
| 存储类型、产品与版本 | | |
| 权威持久化资产及路径 | | |
| 部署与拓扑 | | |
| 一致性与事务能力 | | |
| 备份、保留与恢复能力 | | |
| 上游需求与架构 | | |

- 选择该方案的约束与取舍：
- 不采用其他候选方案的原因：
- 尚待确认的能力及阻塞影响：

## 2. 数据模型与边界

### 数据对象表

| 对象编号 | 对象/集合 | 业务含义 | 所有者 | 来源 | 规模或增长假设 |
|---|---|---|---|---|---|
| | | | | | |

### 关系与引用表

| 关系编号 | 源对象 | 目标对象 | 关系/引用方式 | 一致性要求 | 删除与保留行为 |
|---|---|---|---|---|---|
| | | | | | |

- 分区、聚合或所有权边界：
- 跨边界写入与失败补偿：

## 3. 属性、约束与敏感级别

### 属性定义表

| 对象/集合 | 属性路径 | 类型/格式 | 必需/可空 | 默认或生成规则 | 业务含义 | 敏感级别 | 生命周期 |
|---|---|---|---|---|---|---|---|
| | | | | | | | |

### 不变量与约束表

| 约束编号 | 适用对象 | 不变量/约束 | 执行位置 | 失败语义 | 验证方式 |
|---|---|---|---|---|---|
| | | | | | |

- 租户隔离、授权与审计：
- 加密、脱敏、数据驻留与合规：

## 4. 一致性、访问路径与容量

### 访问路径表

| 场景编号 | 读写场景 | 过滤/分区键 | 排序/聚合 | 一致性与延迟要求 | 支撑机制 | 证据 |
|---|---|---|---|---|---|---|
| | | | | | | |

- 并发冲突、幂等与去重策略：
- 容量、热点、限额与扩缩容边界：
- 缓存、搜索、物化或副本的一致性策略：

## 5. 迁移、兼容与恢复

### 迁移清单表

| 序号 | 变更资产 | 变更类型 | 影响对象 | 前置条件 | 兼容窗口 | 恢复策略 |
|---|---|---|---|---|---|---|
| | | | | | | |

### 恢复验证表

| 变更 | 恢复方式 | 执行命令或步骤 | 验证查询/指标 | 实测结果 |
|---|---|---|---|---|
| | | | | |

- 回填、双写/双读、切换与停止条件：
- 不可逆变更的数据保护与前向修复：

## 6. 消费方与数据映射

### 数据映射表

| 消费方 | 契约字段 | 数据来源 | 转换/派生规则 | 读写方向 | 一致性说明 |
|---|---|---|---|---|---|
| | | | | | |

> 数据来源按当前技术表达，例如 `表.字段`、文档属性路径、键空间、对象元数据、事件字段或外部系统；计算字段和非持久化字段必须说明来源。

## 7. 真实验证证据

### 验证证据表

| 验证项 | 环境与版本 | 命令/步骤 | 预期结果 | 实际结果 | 证据位置 | 状态 |
|---|---|---|---|---|---|---|
| | | | | | | 未执行/通过/失败/阻塞 |

- 未执行或阻塞项及交付影响：
- 性能/容量结论的样本与限制：

## 完成判定

- [ ] 权威持久化资产、版本和路径可定位，文档与其一致。
- [ ] 每个数据对象、属性和不变量都有真实来源、所有者与执行位置。
- [ ] 访问路径、容量和一致性决策有当前项目证据，不靠通用假设。
- [ ] 适用的迁移有兼容窗口、停止条件、恢复方案与真实验证状态；无迁移时写明原因。
- [ ] 消费方数据映射完整，派生或非持久化字段已明确说明。
- [ ] 敏感数据、租户、审计、保留和删除语义已按适用性处理。
- [ ] 未执行、失败、阻塞和待确认项保持真实状态，没有被写成通过。