服务端

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

@@ -0,0 +1,53 @@
+# 业务字典规范
+
+## 适用范围
+
+- 当任务是新增业务状态、类型、级别、来源、模式、分类等值域时，先读本文件。
+- 本文件只规定新增业务字典怎么写，不重复说明系统字典实现细节。
+
+## 强制规则
+
+- 业务枚举就是业务字典。禁止在代码中脱离字典单独发明枚举值域。
+- 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
+- 具体业务字典必须写到 `.ai-specs/doc-dict/` 下。
+- 一个 `.md` 文件只能写一个字典。
+- 字典文件名必须等于字典编码，推荐路径：`.ai-specs/doc-dict/<dict-code>.md`。
+- 字典编码使用 `snake_case`，固定格式 `<module>_<field>`，例如 `device_status`。
+- `<dict-code>` 就是 `<module>_<field>`。
+- 字典项 `Value` 使用稳定 machine value；代码常量值必须与字典项 `Value` 完全一致。
+- 代码判断统一使用字典项 `Value`；禁止使用 `Label` 做逻辑分支。
+- 已上线字典的编码和字典项 `Value` 默认不可变；下线优先禁用，不直接删除。
+- 禁止出现数据库存 `1/2/3`，但没有对应字典文档说明语义。
+- 禁止代码新增枚举值，但未同步字典文档和字典数据。
+
+## MD 模板
+
+.ai-specs/doc-dict/<dict-code>.md
+```md
+# <字典中文名>
+
+- 模块：<module>
+- 字典编码：`<module>_<field>`
+
+| Label | Value | Sort | Status | Desc |
+|:---|:---|:---|:---|:---|
+| <中文名> | `<machine_value>` | 10 | true | <说明> |
+```
+
+## 代码模板
+
+```go
+package <module>
+
+type <TypeName> string
+
+const (
+	<TypeName><Item1> <TypeName> = "<value_1>"
+	<TypeName><Item2> <TypeName> = "<value_2>"
+)
+```
+
+## 与 SQL 的关系
+
+- 值域字段先有字典定义，再进入表设计。
+- 值域字段如何落库，按 `.ai-specs/sys-specs/business-table-spec.md` 执行。

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`、迁移和业务代码

server/.ai-specs/sys-specs/module-naming-spec.md

@@ -0,0 +1,20 @@
+# 模块命名规范
+
+## 适用范围
+
+- 当任务涉及新增/修改业务模块命名、中英文对照、目录命名、表前缀、字典编码时，先读本文件。
+
+## 强制规则
+
+- 模块中文名与英文名的映射统一登记在本文件；禁止同一业务出现多个英文命名。
+- 同一业务模块在 `router`、`api`、`service`、`model`、表名、字典编码、接口路径中必须使用同一英文词根；禁止混用近义词或复数变体。
+- 模块英文名统一使用小写登记值；需要拼接时，按目标位置使用既有规范展开，不单独发明新缩写。
+- 新增模块词汇时，必须先更新本文件，再进入代码实现。
+- 已登记模块命名默认视为稳定约束；如需改名，必须先更新本文件并评估受影响目录、表、接口、字典和文档。
+
+## 模块词汇
+
+| 中文 | 英文 | 说明 |
+|:---|:---|:---|
+| 书籍 | book | 书籍与章节相关业务模块 |
+| 设备 | device | 设备管理模块 |