# 业务表 SQL 规范

## 适用范围

- 当任务是新增/修改 `.ai-specs/doc-sql/*.md` 时，先读本文件。
- 当前项目关系型数据库默认是 `PostgreSQL`，`doc-sql` 的 `建议 SQL` 默认输出 `PostgreSQL` 写法。
- 涉及状态、类型、级别、来源、模式、分类等值域字段时，必须先读 `.ai-specs/sys-specs/business-dictionary-spec.md`，并先补 `.ai-specs/doc-dict/<dict-code>.md`。

## 强制输出

- 文档路径固定：`.ai-specs/doc-sql/<table_name>.md`
- 文档结构固定只保留：`# 标题`、`## 基本信息`、`## 建议 SQL`
- `## 基本信息` 固定顺序：`模块` → `表名` → `模型` → `迁移接入` → 按需补 `字典` 行 → `职责`
- 有字典字段时，每个字典单独占一行：`- <字段中文名>字典：\`<dict-code>\``
- `## 建议 SQL` 前的说明固定写为：`> 以下 SQL 以当前项目 PostgreSQL 为准，主要表达字段、约束和索引语义；实际落库以 \`GORM Model\` 和 \`initialize/gorm_biz.go\` 为准。`
- `SQL` 代码块固定按这个顺序组织：`CREATE TABLE` → `COMMENT ON TABLE` → `COMMENT ON COLUMN` → `CREATE UNIQUE INDEX` / `CREATE INDEX`
- 表名、字段名、索引名统一使用 `snake_case`
- 唯一索引命名固定：`uk_<table_name>_<field>`
- 普通索引命名固定：`idx_<table_name>_<field>`
- 字典字段只存字典项 `Value`，禁止存 `Label`
- 文档只写已确认字段、约束、索引；禁止再补 `字段设计`、`索引设计`、`关联关系`、`删除与兼容`、`自检` 等重复章节

## PostgreSQL 写法

- 主键自增优先写 `bigserial PRIMARY KEY`
- 时间字段优先写 `timestamp with time zone`
- 注释统一写 `COMMENT ON TABLE`、`COMMENT ON COLUMN`
- 索引统一单独写 `CREATE UNIQUE INDEX`、`CREATE INDEX`
- 禁止混入 `AUTO_INCREMENT`、反引号、`ENGINE=InnoDB`、行内 `COMMENT`、`UNIQUE KEY`、`KEY ...` 等 `MySQL` 方言

## 输出模板

````md
# <表中文名>

## 基本信息

- 模块：<module>
- 表名：`<table_name>`
- 模型：`model/<module>/<file>.go`
- 迁移接入：`initialize/gorm_biz.go`
- <字段中文名>字典：`<dict-code>`
- 职责：<一句话职责>

## 建议 SQL

> 以下 SQL 以当前项目 PostgreSQL 为准，主要表达字段、约束和索引语义；实际落库以 `GORM Model` 和 `initialize/gorm_biz.go` 为准。

```sql
CREATE TABLE <table_name> (
  id bigserial PRIMARY KEY,
  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
  <field_1> <type> <constraint>,
  <field_2> <type>
);

COMMENT ON TABLE <table_name> IS '<表中文名>';
COMMENT ON COLUMN <table_name>.id IS '主键';
COMMENT ON COLUMN <table_name>.created_at IS '创建时间';
COMMENT ON COLUMN <table_name>.updated_at IS '更新时间';
COMMENT ON COLUMN <table_name>.<field_1> IS '<字段说明>';
COMMENT ON COLUMN <table_name>.<field_2> IS '<字段说明>';

CREATE UNIQUE INDEX uk_<table_name>_<field_1> ON <table_name> (<field_1>);
CREATE INDEX idx_<table_name>_<field_2> ON <table_name> (<field_2>);
```
````

- 没有字典字段，就删除对应“字典”行
- 没有唯一索引或普通索引，就删除对应 SQL 行
- 如果字段默认值来自字典，直接写字典项 `Value`，例如 `DEFAULT 'enabled'`

## 复刻目标

- 只看本文件，应能直接写出类似 `.ai-specs/doc-sql/book_author.md` 的文档
- 先定字典，再写 `doc-sql`，再进入 `Model`、迁移和业务代码