# SQL 目录规则

## 目录定位

`sql/` 是数据库模式、迁移脚本和持久化约束的真源之一。这里的改动默认高风险，因为它们会影响已有数据、运行时兼容性、回滚能力和跨服务契约。

SQL 不是附属文档，而是生产行为的一部分。

## 第一原则

1. 数据兼容性优先。
新增、修改、删除表结构前，先考虑已有数据、旧代码、灰度过程和回滚路径。

2. 模式变更必须服务真实运行主链路。
不要在 SQL 里提前铺大量“未来可能需要”的字段和表。

3. DDL、代码、文档要同步。
字段、索引、约束、枚举、默认值变更，必须同步检查对应存储模型、接口输出和文档说明。

4. 显式优于隐式。
约束、索引、检查条件、唯一性要求应尽量在 schema 中表达，不要把关键一致性只留在应用代码里。

## 变更前必须先回答

- 这是新增表、补丁、兼容性修复，还是破坏性变更？
- 现网数据是否已经存在？
- 应用层是否已经能理解新字段/新约束？
- 如果发布失败，如何回滚或向前修复？

## 编写要求

- 文件名要体现语义和版本，不要使用含糊命名
- 注释要说明边界、用途和与其他 schema 的关系
- 对 authority、audit、outbox、账务、结算类表要特别谨慎
- Patch 脚本必须说明它修复的具体问题，不要变成长期主 schema 的隐性替代

## 验证要求

- 检查 DDL 是否可重复执行或明确说明一次性前提
- 检查约束是否与应用层枚举/状态机一致
- 索引变更要有明确查询场景，不做无根据加索引
- 涉及高并发更新时，要考虑锁、唯一键和冲突语义

## 风险重点

- 状态枚举漂移
- 乐观锁/悲观锁语义失配
- audit 字段缺失或不一致
- token / settlement / order / usage 这类关键表的唯一性与时间字段设计
- patch 覆盖正式 schema 但未同步主文档

## 禁止事项

- 不要在未评估兼容性的情况下直接改列语义
- 不要把应用层 bug 临时补丁长期固化进 schema 却不回收
- 不要让 SQL 成为代码真实行为的“另一个版本”