wdh-home
8164eec650
Some checks failed
CI / init (push) Has been cancelled
CI / Frontend node 18.16.0 (push) Has been cancelled
CI / Backend go (1.22) (push) Has been cancelled
CI / devops-test (1.22, 18.16.0) (push) Has been cancelled
CI / release-pr (push) Has been cancelled
CI / release-please (push) Has been cancelled
CI / devops-prod (1.22, 18.x) (push) Has been cancelled
CI / docker (push) Has been cancelled
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# 业务表 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`、迁移和业务代码
|