# /db-docs — 数据库文档同步

当 PostgreSQL schema/表结构发生变化时，将变更以审计友好的方式落盘到 `docs/database/`。

## 触发条件

- 迁移脚本/DDL 修改（新增/删除/改表、字段、类型、默认值、非空、约束、索引、外键）
- 手工执行了 DDL

## 执行步骤

### 第 1 步：识别结构性变化

从本次会话的改动中，列出新增/修改/删除的对象：
- schema / table / column / index / constraint / foreign key
- 明确变更前后差异（before/after）

### 第 2 步：更新表结构文档

对每张受影响的表，更新 `docs/database/` 下对应的文档：
- 如果文档已存在：更新字段列表、约束、索引等
- 如果文档不存在：基于以下模板创建

模板：
```markdown
# <schema>.<table_name>

## 概述
<表的用途说明>

## 字段

| 字段名 | 类型 | 可空 | 默认值 | 说明 |
|--------|------|------|--------|------|
| ... | ... | ... | ... | ... |

## 约束与索引
- PRIMARY KEY: ...
- UNIQUE: ...
- INDEX: ...

## 关联
- 上游：<数据来源>
- 下游：<被哪些模块/表消费>
```

特别注意金额类字段：标注精度、币种、舍入规则。

### 第 3 步：回滚与验证

写入审计友好的回滚和验证信息：
- DDL 回滚路径（必要时提供反向迁移 SQL）
- 至少 3 条验证 SQL（含约束/索引/关键字段检查）

### 第 4 步：DDL 基线检查

检查 `docs/database/ddl/` 下的基线文件是否需要合并更新。如需要，更新基线。

### 第 5 步：输出摘要

- 更新/创建了哪些文档
- 迁移脚本执行状态（已执行 / 待执行）
- DDL 基线状态（已合并 / 待合并）