服务端

server/.ai-specs/sys-specs/business-table-spec.md

@@ -0,0 +1,77 @@
+# 业务表 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`、迁移和业务代码