基础项目

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

@@ -3,39 +3,63 @@
 ## 适用范围
 
 - 当任务是新增业务状态、类型、级别、来源、模式、分类等值域时，先读本文件。
-- 本文件只规定新增业务字典怎么写，不重复说明系统字典实现细节。
+- 本文件规定业务字典怎么写，统一分为 `固定值域字典` 和 `动态值域字典` 两类；不重复说明系统字典底层实现细节。
 
 ## 强制规则
 
-- 业务枚举就是业务字典。禁止在代码中脱离字典单独发明枚举值域。
+- 业务字典是值域定义来源；禁止在代码中脱离字典单独发明枚举值域。
 - 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
 - 具体业务字典必须写到 `.ai-specs/doc-dict/` 下。
+- 新增/修改业务字典时，必须同步维护初始化数据和当前版本升级 SQL；初始化数据覆盖新库，升级 SQL 覆盖老库。
 - 一个 `.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` 默认不可变；下线优先禁用，不直接删除。
+- 字典只分两类：`固定值域字典` 和 `动态值域字典`。
+- `固定值域字典`：当前业务已确认值域，字典项必须在文档中完整定义，并与代码枚举、接口校验、默认值、状态流转和展示映射保持同步。
+- `动态值域字典`：当前业务不固化值域，必须保留对应 `.md` 文档，但文档只说明字典编码、类型、来源、业务用途和逻辑边界，不要求在业务文档里枚举全部值项。
+- `固定值域字典` 通常需要同步代码枚举或常量定义；`动态值域字典` 默认不新增固定枚举常量。
+- `固定值域字典` 的字典项 `Value` 使用稳定 machine value；代码常量值必须与字典项 `Value` 完全一致。
+- 代码判断统一使用 `固定值域字典` 的字典项 `Value`；禁止使用 `Label` 做逻辑分支。
+- `固定值域字典` 必须同步写入 `source/system` 初始化数据和 `.ai-transition/database-upgrade-doc/<version>.sql` 的 `sys_dictionaries`、`sys_dictionary_details` 数据。
+- `动态值域字典` 必须同步写入 `source/system` 初始化数据和 `.ai-transition/database-upgrade-doc/<version>.sql` 的 `sys_dictionaries` 主字典；默认不写固定字典项。
+- `动态值域字典` 禁止为了占位在文档或代码中伪造临时 `Value`、伪造枚举常量或伪造默认值。
+- 已上线 `固定值域字典` 的编码和字典项 `Value` 默认不可变；下线优先禁用，不直接删除。
+- `动态值域字典` 如果后续参与默认值、状态流转、业务分支、稳定接口 contract 或展示映射，必须升级为 `固定值域字典` 并补齐字典项定义。
 - 禁止出现数据库存 `1/2/3`，但没有对应字典文档说明语义。
 - 禁止代码新增枚举值，但未同步字典文档和字典数据。
 
 ## MD 模板
 
 .ai-specs/doc-dict/<dict-code>.md
+固定值域字典模板：
 ```md
 # <字典中文名>
 
 - 模块：<module>
 - 字典编码：`<module>_<field>`
+- 字典类型：`固定值域字典`
 
 | Label | Value | Sort | Status | Desc |
 |:---|:---|:---|:---|:---|
 | <中文名> | `<machine_value>` | 10 | true | <说明> |
 ```
 
+动态值域字典模板：
+```md
+# <字典中文名>
+
+- 模块：<module>
+- 字典编码：`<module>_<field>`
+- 字典类型：`动态值域字典`
+- 数据来源：`系统字典`
+- 业务用途：<筛选 / 展示 / 聚合 / 其他>
+- 逻辑约束：<不参与业务状态流转、默认值判断和分支逻辑等约束>
+```
+
 ## 代码模板
 
+固定值域字典代码模板：
 ```go
 package <module>
 
@@ -47,7 +71,12 @@ const (
 )
 ```
 
+- `动态值域字典` 默认不在业务代码里新增固定枚举常量；如需独立封装，优先封装查询、存在性校验和展示转换入口。
+
 ## 与 SQL 的关系
 
-- 值域字段先有字典定义，再进入表设计。
+- `固定值域字典` 字段先有值项定义，再进入表设计。
+- `动态值域字典` 字段先有字典说明文档，再进入表设计。
+- `动态值域字典` 字段进入 `doc-sql` 时，只记录字典编码、是否必填、索引和通用结构约束；禁止伪造固定值项、伪造默认值或伪造 `CHECK IN (...)`。
 - 值域字段如何落库，按 `.ai-specs/sys-specs/business-table-spec.md` 执行。
+- 字典数据升级 SQL 按 `.ai-specs/sys-specs/database-upgrade-doc-spec.md` 执行，必须考虑重复执行、人工已建数据和部分明细缺失。

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

@@ -2,51 +2,61 @@
 
 ## 适用范围
 
-- 当任务是新增/修改 `.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/*.sql` 时，先读本文件。
+- 当前项目关系型数据库默认是 `PostgreSQL`，`doc-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`
+- 文档路径固定：`.ai-specs/doc-sql/<table_name>.sql`
+- 文件必须是可执行 SQL，不再使用 Markdown 包裹 SQL。
+- 文件头部必须使用 SQL 注释声明基本信息，注释后直接输出 SQL 主体。
+- 基本信息固定顺序：`# 标题` → `## 基本信息` → `模块` → `表名` → `模型` → `迁移接入` → `删除策略` → 按需补 `字典` 行 → `职责`
+- 每张业务表必须显式声明删除策略，只允许两种：`软删表`、`硬删表`
+- `软删表`：`Model` 应使用 `global.GVA_MODEL` 或显式包含 `DeletedAt`；`doc-sql` 必须包含 `deleted_at` 字段和对应索引
+- `硬删表`：`Model` 不应因沿用默认基类而隐式带出 `DeletedAt`；`doc-sql` 不写 `deleted_at`
+- `硬删表` 建模时禁止直接嵌入 `global.GVA_MODEL`；应显式定义 `ID`、`CreatedAt`、`UpdatedAt`，或使用不包含 `DeletedAt` 的硬删基类
+- `硬删表` 的 `Service` 删除逻辑必须执行物理删除；禁止依赖 `GORM` 软删行为或查询侧隐式过滤 `deleted_at`
+- `硬删表` 如果后续需要保留删除痕迹，必须先把 `doc-sql` 删除策略改为 `软删表`，再同步修改 `Model`、索引和删除逻辑
+- 当 `doc-sql` 声明为 `硬删表` 时，后续生成 `model/<module>/*.go` 必须按 `doc-sql` 字段逐项建模；即使项目默认模型带软删，也不得自动补 `DeletedAt`
+- 当 `doc-sql` 声明为 `硬删表` 时，后续生成 `initialize/gorm_biz.go` 迁移只注册该硬删模型；迁移结果不得比 `doc-sql` 多出 `deleted_at`
+- 当 `doc-sql` 声明为 `硬删表` 时，唯一索引直接按业务唯一性生成；不得为了兼容软删把 `deleted_at` 拼入唯一索引
+- `book` 模块当前所有 `doc-sql/book*.sql` 均按 `硬删表` 处理；生成 `model/book/*.go` 时必须使用硬删建模规则
+- 有字典字段时，每个字典单独占一行：`-- <字段中文名>字典：<dict-code>`
+- 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`
-- 文档只写已确认字段、约束、索引；禁止再补 `字段设计`、`索引设计`、`关联关系`、`删除与兼容`、`自检` 等重复章节
+- `固定值域字典` 字段如果默认值来自字典，直接写稳定字典项 `Value`。
+- `动态值域字典` 字段在 `doc-sql` 中只表达字段本身的结构约束、是否必填和索引；禁止伪造默认值、伪造固定值项或伪造 `CHECK IN (...)`。
+- 文件只写已确认字段、约束、索引；禁止再补 `字段设计`、`索引设计`、`关联关系`、`删除与兼容`、`自检` 等重复章节
+- 仅修改 SQL 注释说明且不改变字段、约束、索引、默认值、注释等落库语义时，不需要补数据库升级 SQL。
 
 ## PostgreSQL 写法
 
 - 主键自增优先写 `bigserial PRIMARY KEY`
 - 时间字段优先写 `timestamp with time zone`
+- `软删表` 的软删字段统一写 `deleted_at 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
+-- # <表中文名>
+--
+-- ## 基本信息
+--
+-- 模块：<module>
+-- 表名：<table_name>
+-- 模型：model/<module>/<file>.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- <字段中文名>字典：<dict-code>
+-- 职责：<一句话职责>
+
 CREATE TABLE <table_name> (
   id bigserial PRIMARY KEY,
   created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -65,13 +75,15 @@ 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>);
 ```
-````
 
-- 没有字典字段，就删除对应“字典”行
+- `软删表` 参考上面的硬删模板，在 `updated_at` 后追加 `deleted_at timestamp with time zone`，并同步补 `COMMENT ON COLUMN <table_name>.deleted_at IS '删除时间';` 与 `CREATE INDEX idx_<table_name>_deleted_at ON <table_name> (deleted_at);`
+- `硬删表` 按模板直接输出，不追加 `deleted_at`
+- 没有字典字段，就删除对应“字典”注释行
 - 没有唯一索引或普通索引，就删除对应 SQL 行
-- 如果字段默认值来自字典，直接写字典项 `Value`，例如 `DEFAULT 'enabled'`
+- 如果字段默认值来自 `固定值域字典`，直接写字典项 `Value`，例如 `DEFAULT 'enabled'`
+- 如果字段引用 `动态值域字典`，就删除默认值示例，按业务真实规则只保留结构约束和索引
 
 ## 复刻目标
 
-- 只看本文件，应能直接写出类似 `.ai-specs/doc-sql/book_author.md` 的文档
+- 只看本文件，应能直接写出类似 `.ai-specs/doc-sql/book_author.sql` 的文件
 - 先定字典，再写 `doc-sql`，再进入 `Model`、迁移和业务代码

server/.ai-specs/sys-specs/database-upgrade-doc-spec.md

@@ -0,0 +1,59 @@
+# 数据库升级文档规范
+
+- **当前数据库表结构版本**：`v1`
+
+## 适用范围
+
+- 当任务新增/修改 `.ai-specs\doc-sql\*.sql` 并导致数据库结构、字段、索引、约束、默认值或注释变化时，必须先读本文件。
+- 当任务新增/修改 `.ai-specs\doc-dict\*.md` 并导致系统字典主数据或字典项变化时，必须先读本文件。
+- 数据库升级 SQL 固定存放在 `.ai-transition\database-upgrade-doc`。
+- 当前升级版本固定读取本文件中 `当前数据库表结构版本` 的值。
+
+## 强制规则
+
+- 升级 SQL 文件命名固定为 `<version>.sql`，例如 `v1.sql`、`v2.sql`、`v3.sql`。
+- 当前数据库表结构版本声明为 `v1` 时，兼容变更 SQL 必须写入 `.ai-transition\database-upgrade-doc\v1.sql`。
+- 默认版本文件为 `v1.sql`；不存在时，首次产生数据库结构变更必须创建。
+- 修改 `.ai-specs\doc-sql\*.sql` 时，禁止只改文档；必须同步检查并补充当前版本 SQL 文件。
+- 修改 `.ai-specs\doc-dict\*.md` 时，禁止只改文档；必须同步检查初始化数据和当前版本 SQL 文件。
+- SQL 只记录从既有数据库升级到当前 `doc-sql` 目标结构所需的兼容变更，不重复粘贴完整建表基线。
+- 同一次业务变更涉及多张表时，必须写在同一个当前版本 SQL 文件中，并按表分组。
+- 修改字段名、类型、默认值、非空约束、唯一约束、普通索引、软硬删字段、注释时，都必须写对应升级 SQL。
+- 新增/修改固定值域字典时，必须写入 `sys_dictionaries` 和 `sys_dictionary_details` 的幂等升级 SQL。
+- 新增/修改动态值域字典时，必须至少写入 `sys_dictionaries` 的幂等升级 SQL；无固定值项时不写 `sys_dictionary_details`。
+- 仅修改文档表述且不改变实际落库语义时，可以不写 SQL，但必须在最终说明中明确原因。
+
+## SQL 要求
+
+- SQL 默认使用 `PostgreSQL` 写法。
+- 优先使用 `ALTER TABLE`、`CREATE INDEX`、`DROP INDEX`、`COMMENT ON TABLE`、`COMMENT ON COLUMN`、`UPDATE` 回填语句。
+- 数据类升级 SQL 必须幂等，禁止裸 `INSERT`；必须使用 `WHERE NOT EXISTS`、`UPDATE ... FROM` 等方式兼容重复执行。
+- 新增 `NOT NULL` 字段必须先给默认值或先回填历史数据，再追加 `NOT NULL` 约束。
+- 新增唯一约束或唯一索引前，必须考虑历史重复数据；不能直接写会必然失败的 SQL。
+- 索引创建应使用项目统一命名：唯一索引 `uk_<table_name>_<field>`，普通索引 `idx_<table_name>_<field>`。
+- 字典主表重复判断固定使用 `sys_dictionaries.type`。
+- 字典明细重复判断固定使用 `sys_dictionary_details.sys_dictionary_id + value`。
+- 固定值域字典项变更时，先 `UPDATE` 已有 `value` 的 `label`、`sort`、`status`、`updated_at` 等展示字段，再 `INSERT` 缺失项。
+- 字典主表或明细表命中已存在数据时，若表包含 `deleted_at`，恢复启用数据必须同步置空 `deleted_at`。
+- 固定值域字典项废弃时，优先将 `status` 改为 `false`，禁止直接删除历史值项。
+- 禁止混入 `MySQL` 方言，例如反引号、`AUTO_INCREMENT`、`ENGINE=InnoDB`、行内 `COMMENT`。
+
+## 文件格式
+
+```sql
+-- <业务说明> / <表名> / <YYYY-MM-DD>
+
+ALTER TABLE <table_name>
+  ADD COLUMN <field_name> <type>;
+
+COMMENT ON COLUMN <table_name>.<field_name> IS '<字段说明>';
+
+CREATE INDEX idx_<table_name>_<field_name> ON <table_name> (<field_name>);
+```
+
+## 联动关系
+
+- 改 `doc-sql`：同步改 `Model`、`Service`、`initialize/gorm_biz.go`，并补当前版本升级 SQL。
+- 改 `doc-dict`：同步改代码枚举/校验/展示逻辑、`source/system` 初始化数据，并补当前版本升级 SQL。
+- 改当前版本升级 SQL：同步确认 `doc-sql`、`Model`、迁移注册与业务读写逻辑一致。
+- 版本升级：先修改本文件的 `当前数据库表结构版本`，再在 `.ai-transition\database-upgrade-doc` 新增对应 `<version>.sql`。

server/.ai-specs/sys-specs/requirements-stage-spec.md

@@ -1,107 +0,0 @@
-# 需求草案阶段规范
-
-## 适用范围
-
-- 新增/修改 `.ai-specs/requirements/*.md` 前必须先读本文件。
-- 本文件只约束 `requirements` 文档，不替代 `doc-dict`、`doc-sql`、`doc-api` 和代码实现规范。
-
-## 阶段目标
-
-- `制定需求草案阶段`：只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档。
-- `归档阶段`：需求草案已稳定，可作为下游文档和实现依据；新增需求或未确认变更必须退回 `制定需求草案阶段`。
-- 两个阶段正文结构一致：涉及表时先写 `## 表`，再写 `## 需求描述`；不涉及表时只写 `## 需求描述`。
-
-## 强制规则
-
-- 文档路径固定：`.ai-specs/requirements/<topic>.md`
-- 文档标题固定：`# <主题> 需求草案`
-- 标题下方空一行后必须紧跟两行阶段元信息，格式固定为 `- **阶段** <阶段说明>` 和 `- **要求** <阶段要求>`。
-- 阶段元信息只能从下表选择一组，禁止混用、改名或自行扩写。
-
-| 阶段 | 阶段行 | 要求行 |
-|:---|:---|:---|
-| 制定需求草案阶段 | `- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档` | `- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路` |
-| 归档阶段 | `- **阶段** 当前阶段为需求归档，需求草案已稳定，可作为下游文档和实现依据，原则上不再追加未确认内容` | `- **要求** 只允许修正错误、消除歧义和同步已确认结论；新增需求或未确认变更必须退回制定需求草案阶段处理` |
-
-- 一个文档只描述一个业务主题。
-- 正文只允许出现 `## 表` 和 `## 需求描述` 两类二级标题。
-- `## 需求描述` 必须存在；`## 表` 按需存在，不涉及表时必须省略。
-- 禁止为了满足格式硬造表或保留空表区。
-- 有表时，每张表使用一个 `### <表名>`；字段统一写成 `- <字段名>：<字段说明>`。
-- 有表时，`## 表` 只写字段和极简业务含义；不写流程、规则、性能、实现判断。
-- 有表且字段涉及字典时，只引用字典码，例如“字典 `<dict-code>`”或“字典，需补 `<dict-code>`”；确认值域写到 `## 需求描述`。
-- 有表且字段本质上是多值、多对多或独立主体时，必须拆成独立表或关联表，禁止塞进主表字符串字段。
-- `## 需求描述` 下每个业务主题使用一个 `### <需求标题>`，只写规则、流程、边界、范围和例外。
-- `###` 下只允许 `-` 扁平列表；禁止四级标题、嵌套标题、编号大纲、代码块、图和表格。
-
-## 禁止事项
-
-- 禁止写 API 路径、Method、鉴权方式、请求响应结构。
-- 禁止写 Router、API、Service、定时任务、缓存、消息队列等实现设计。
-- 禁止写 SQL 建表语句、字段类型、索引、唯一约束、迁移脚本。
-- 禁止新增 `## 背景`、`## 范围`、`## 总览`、`## 关系图`、`## TODO` 等既定结构外标题。
-- 禁止把需求规则混写到 `## 表`，也禁止把字段清单重复抄到 `## 需求描述`。
-- 禁止无表业务为了套模板编造表、字段、关联关系或空的 `## 表`。
-- 禁止把未确认事项写成确定结论；未确认内容必须标记“需补”或“待确认”。
-- 禁止在 `归档阶段` 继续收集新需求；新增需求必须退回 `制定需求草案阶段`。
-
-## 文档结构
-
-- 有表结构：`# <主题> 需求草案` → 两行阶段元信息 → `## 表` → 多个 `### <表名>` → `## 需求描述` → 多个 `### <需求标题>`。
-- 无表结构：`# <主题> 需求草案` → 两行阶段元信息 → `## 需求描述` → 多个 `### <需求标题>`。
-- 有表时，`### <表名>` 使用业务表名，例如“书籍信息表”“书籍章节表”“订单支付记录表”，不要求等于最终数据库表名。
-- `### <需求标题>` 使用业务主题名，例如“数据来源与上传”“章节重建策略”“评论点赞”“当前范围”。
-- 没有合适标题的信息，归并到语义最近的 `### <需求标题>`；确需新增标题时，只能在 `## 需求描述` 下新增三级标题。
-
-## 输出模板
-
-无表业务模板：
-
-````md
-# <主题> 需求草案
-
-- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档
-- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路
-
-## 需求描述
-
-### <需求1>
-- <规则、边界或待确认事项>
-
-### <需求2>
-- <规则、例外或范围>
-````
-
-有表业务模板：
-
-````md
-# <主题> 需求草案
-
-- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档
-- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路
-
-## 表
-
-### <表1>
-- <字段1>：<说明>
-- <字段2>：<说明或需补>
-- <字段3>：字典 `<dict-code>`
-
-### <表2>
-- <字段1>：<说明>
-
-## 需求描述
-
-### <需求1>
-- <规则、边界或待确认事项>
-
-### <需求2>
-- <规则、例外或范围>
-````
-
-## 与后续文档的关系
-
-- `requirements` 是 `doc-dict`、`doc-sql`、`doc-api` 和代码实现的上游输入，不是替代物。
-- 出现状态、类型、级别、来源、模式、分类等值域时，下一步先补 `.ai-specs/doc-dict/*.md`。
-- 涉及表、字段、关系且已稳定后，下一步补 `.ai-specs/doc-sql/*.md`；无表需求不强制补 `doc-sql`。
-- 默认链路：`requirements(制定需求草案阶段 -> 归档阶段) -> doc-dict / doc-sql -> Model -> Service -> API -> Router`。