adspecs 0.1.32 → 0.1.34

package/references/yudaocloud-end-standard/03-/346/225/260/346/215/256/345/255/227/345/205/270/344/270/216/350/217/234/345/215/225/350/247/204/350/214/203.md

@@ -0,0 +1,336 @@
+# 数据字典与菜单数据规范
+
+> **版本**: v1.0
+> **修订日期**: 2026-08-01
+> **适用范围**: ultracloud 项目所有后端模块的系统设计 SQL 文件生成
+> **目标**: 统一数据字典（system_dict_type + system_dict_data）和菜单数据（system_menu）的 SQL 文件拆分、格式、ID 分配规则
+
+本规范基于 P11-17 Skill 技能管理、P15 本体引擎的实际抽离经验编写，可直接落地。
+
+---
+
+## 1. SQL 文件拆分规则
+
+系统设计阶段必须生成 **2 个独立 SQL 文件**，不得合并：
+
+| 文件 | 命名规则 | 内容 | 依赖 |
+| --- | --- | --- | --- |
+| **建表 DDL** | `{模块编号}-{模块名}_schema.sql` | 业务表 CREATE TABLE + 索引 + COMMENT ON | 无（可独立执行） |
+| **字典菜单数据** | `{模块编号}_menu-dict-type-data.sql` | 系统基础表 CREATE TABLE IF NOT EXISTS + 字典类型 + 字典数据 + 菜单数据 | 无（可独立执行） |
+
+### 1.1 拆分原因
+
+1. **职责分离**：建表 DDL 是结构定义，字典菜单是业务数据
+2. **执行顺序灵活**：字典菜单数据可独立执行，不依赖业务表
+3. **可独立执行**：字典菜单文件包含系统基础表建表语句（CREATE TABLE IF NOT EXISTS），即使数据库未初始化 system 模块也能执行
+4. **便于维护**：字典菜单数据频繁变更，独立文件便于增量更新
+
+### 1.2 文件示例
+
+```
+docs/30-system-design/P11-17/
+├── P11-17_skill-management_schema.sql           # 8 张业务表 DDL
+└── p11_17_menu-dict-type-data.sql               # 字典类型 + 字典数据 + 菜单
+
+docs/30-system-design/P15/
+├── P15-ontology-engine_schema.sql               # 13 张业务表 DDL
+└── p15_menu-dict-type-data.sql                  # 字典类型 + 字典数据 + 菜单
+```
+
+---
+
+## 2. 字典菜单 SQL 文件结构
+
+文件按以下顺序组织，每部分用 `-- ======` 分隔：
+
+```
+1. 文件头注释（模块信息 + 规范说明 + ID 范围）
+2. SET client_encoding / standard_conforming_strings
+3. §零 系统基础表（CREATE TABLE IF NOT EXISTS × 3）
+   - system_dict_type
+   - system_dict_data
+   - system_menu
+4. §一 数据字典类型（INSERT INTO "system_dict_type"）
+5. §二 数据字典数据（INSERT INTO "system_dict_data"）
+6. §三 菜单数据（INSERT INTO "system_menu"）
+7. 文件尾总结注释
+```
+
+---
+
+## 3. 系统基础表结构（CREATE TABLE IF NOT EXISTS）
+
+### 3.1 为什么需要建表语句
+
+这三张表由 `ultracloud-module-system` 模块管理。但在以下场景中数据库可能尚未初始化：
+- 全新数据库部署
+- 仅初始化业务模块未初始化 system 模块
+- 测试环境快速搭建
+
+因此字典菜单文件必须包含 `CREATE TABLE IF NOT EXISTS` 语句，已存在则跳过，不影响已有数据。
+
+### 3.2 system_dict_type（字典类型表）
+
+```sql
+CREATE TABLE IF NOT EXISTS "system_dict_type" (
+    "id"            BIGSERIAL      PRIMARY KEY,
+    "name"          VARCHAR(100)   NOT NULL DEFAULT '',
+    "type"          VARCHAR(100)   NOT NULL DEFAULT '',
+    "status"        SMALLINT       NOT NULL DEFAULT 0,
+    "remark"        VARCHAR(500)   DEFAULT NULL,
+    "creator"       VARCHAR(64)    DEFAULT '',
+    "create_time"   TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updater"       VARCHAR(64)    DEFAULT '',
+    "update_time"   TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "deleted"       SMALLINT       NOT NULL DEFAULT 0,
+    "deleted_time"  TIMESTAMP      DEFAULT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "uk_system_dict_type_type" ON "system_dict_type" ("type") WHERE "deleted" = 0;
+```
+
+### 3.3 system_dict_data（字典数据表）
+
+```sql
+CREATE TABLE IF NOT EXISTS "system_dict_data" (
+    "id"            BIGSERIAL      PRIMARY KEY,
+    "sort"          INTEGER        NOT NULL DEFAULT 0,
+    "label"         VARCHAR(100)   NOT NULL DEFAULT '',
+    "value"         VARCHAR(100)   NOT NULL DEFAULT '',
+    "dict_type"     VARCHAR(100)   NOT NULL DEFAULT '',
+    "status"        SMALLINT       NOT NULL DEFAULT 0,
+    "color_type"    VARCHAR(50)    DEFAULT '',
+    "css_class"     VARCHAR(100)   DEFAULT '',
+    "remark"        VARCHAR(500)   DEFAULT NULL,
+    "creator"       VARCHAR(64)    DEFAULT '',
+    "create_time"   TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updater"       VARCHAR(64)    DEFAULT '',
+    "update_time"   TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "deleted"       SMALLINT       NOT NULL DEFAULT 0,
+    "deleted_time"  TIMESTAMP      DEFAULT NULL
+);
+
+CREATE INDEX IF NOT EXISTS "idx_system_dict_data_type" ON "system_dict_data" ("dict_type");
+```
+
+### 3.4 system_menu（菜单权限表）
+
+```sql
+CREATE TABLE IF NOT EXISTS "system_menu" (
+    "id"              BIGSERIAL      PRIMARY KEY,
+    "name"            VARCHAR(50)    NOT NULL DEFAULT '',
+    "permission"      VARCHAR(100)   NOT NULL DEFAULT '',
+    "type"            SMALLINT       NOT NULL DEFAULT 2,
+    "sort"            INTEGER        NOT NULL DEFAULT 0,
+    "parent_id"       BIGINT         NOT NULL DEFAULT 0,
+    "path"            VARCHAR(200)   DEFAULT '',
+    "icon"            VARCHAR(100)   DEFAULT '#',
+    "component"       VARCHAR(255)   DEFAULT NULL,
+    "component_name"  VARCHAR(255)   DEFAULT NULL,
+    "status"          SMALLINT       NOT NULL DEFAULT 0,
+    "visible"         BOOLEAN        NOT NULL DEFAULT TRUE,
+    "keep_alive"      BOOLEAN        NOT NULL DEFAULT TRUE,
+    "always_show"     BOOLEAN        NOT NULL DEFAULT TRUE,
+    "creator"         VARCHAR(64)    DEFAULT '',
+    "create_time"     TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updater"         VARCHAR(64)    DEFAULT '',
+    "update_time"     TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "deleted"         SMALLINT       NOT NULL DEFAULT 0,
+    "deleted_time"    TIMESTAMP      DEFAULT NULL
+);
+
+CREATE INDEX IF NOT EXISTS "idx_system_menu_parent_id" ON "system_menu" ("parent_id");
+```
+
+> **注意**：三张表均不含 `tenant_id`（字典和菜单为全局共享数据）。`deleted` 用 `SMALLINT`（整数 0/1），`visible`/`keep_alive`/`always_show` 用 `BOOLEAN`。
+
+---
+
+## 4. INSERT 语句格式规范
+
+### 4.1 通用格式要求
+
+所有 INSERT 语句必须遵循以下格式（参照 `system_dict_type.sql` 实际系统表数据）：
+
+| 规范项 | 要求 | 示例 |
+| --- | --- | --- |
+| 表名/字段名 | 双引号包裹 | `"system_dict_type"`、`"id"`、`"name"` |
+| `deleted` 字段值 | 整数 `0`（非 `FALSE`） | `..., 0, NULL` |
+| `deleted_time` 字段 | 必须包含，值为 `NULL` | `..., 0, NULL` |
+| `id` 字段 | 显式指定（非自增分配） | `SELECT 7001, ...` |
+| 时间字段 | `CURRENT_TIMESTAMP` | `CURRENT_TIMESTAMP` |
+| 幂等性 | `INSERT ... SELECT ... WHERE NOT EXISTS` | 见下方模板 |
+| 字符串值 | 单引号包裹 | `'草稿'`、`'DRAFT'` |
+| NULL 值 | 直接写 `NULL` | `NULL` |
+
+### 4.2 system_dict_type INSERT 模板
+
+```sql
+INSERT INTO "system_dict_type" ("id", "name", "type", "status", "remark", "creator", "create_time", "updater", "update_time", "deleted", "deleted_time")
+SELECT {id}, '{中文名}', '{dict_type}', 0, '{备注}', '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0, NULL
+WHERE NOT EXISTS (SELECT 1 FROM "system_dict_type" WHERE "type" = '{dict_type}');
+```
+
+### 4.3 system_dict_data INSERT 模板
+
+```sql
+INSERT INTO "system_dict_data" ("id", "sort", "label", "value", "dict_type", "status", "color_type", "css_class", "remark", "creator", "create_time", "updater", "update_time", "deleted", "deleted_time")
+SELECT {id}, {sort}, '{标签}', '{值}', '{dict_type}', 0, '{color_type}', '', {remark}, '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0, NULL
+WHERE NOT EXISTS (SELECT 1 FROM "system_dict_data" WHERE "dict_type" = '{dict_type}' AND "value" = '{值}');
+```
+
+### 4.4 system_menu INSERT 模板
+
+```sql
+INSERT INTO "system_menu" ("id", "name", "permission", "type", "sort", "parent_id", "path", "icon", "component", "component_name", "status", "visible", "keep_alive", "always_show", "creator", "create_time", "updater", "update_time", "deleted", "deleted_time")
+SELECT {id}, '{菜单名}', '{权限标识}', {type}, {sort}, {parent_id}, '{path}', '{icon}', {component}, {component_name}, 0, TRUE, TRUE, TRUE, '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0, NULL
+WHERE NOT EXISTS (SELECT 1 FROM "system_menu" WHERE "id" = {id});
+```
+
+---
+
+## 5. ID 分配规则
+
+### 5.1 字典类型 ID（system_dict_type.id）
+
+| 模块 | ID 范围 | 示例 |
+| --- | --- | --- |
+| 系统内置 | 1~999 | `system_user_sex` = 1 |
+| P11-17 Skill 技能管理 | 6001~6100 | `ai_skill_status` = 6001 |
+| P15 本体引擎 | 7001~7100 | `ontology_status` = 7001 |
+| 新模块 | 按模块编号 ×1000 起始 | P16 = 8001~8100 |
+
+### 5.2 字典数据 ID（system_dict_data.id）
+
+| 模块 | ID 范围 | 规则 |
+| --- | --- | --- |
+| 系统内置 | 1~9999 | — |
+| P11-17 | 60001~69999 | `{模块ID前缀}00{序号}` |
+| P15 | 70001~79999 | `{模块ID前缀}00{序号}` |
+| 新模块 | 按模块编号 ×10000 起始 | P16 = 80001~89999 |
+
+### 5.3 菜单 ID（system_menu.id）
+
+| 模块 | ID 范围 | 结构 |
+| --- | --- | --- |
+| 系统内置 | 1~1999 | — |
+| MDM 主数据 | 5000~5999 | — |
+| P11-17 Skill 技能管理 | 6000~6199 | 1 目录(6000) + 菜单(6001~6005) + 按钮(6011~6033) |
+| P15 本体引擎 | 7000~7199 | 1 目录(7000) + 菜单(7001~7006) + 按钮(7101~7153) |
+| 新模块 | 按模块编号 ×1000 起始 | P16 = 8000~8199 |
+
+### 5.4 菜单 ID 内部分配规则
+
+```
+{模块千位}000              — 一级目录
+{模块千位}001~{模块千位}099 — 二级菜单（type=2）
+{模块千位}100~{模块千位}199 — 按钮权限（type=3），parent_id 指向对应二级菜单
+```
+
+示例（P15 本体引擎，千位=7）：
+- 7000 = 一级目录"本体引擎"
+- 7001~7006 = 二级菜单（本体管理/实体类管理/...）
+- 7101~7109 = 本体管理按钮（parent_id=7001）
+- 7111~7113 = 实体类管理按钮（parent_id=7002）
+- ...
+
+---
+
+## 6. 字典类型命名规则
+
+### 6.1 dict_type 标识命名
+
+格式：`{模块前缀}_{业务含义}`，全小写 + 下划线分隔
+
+| 模块 | 前缀 | 示例 |
+| --- | --- | --- |
+| System | `system_` | `system_user_sex` |
+| Infra | `infra_` | `infra_config_type` |
+| AI 模块 | `ai_` | `ai_skill_status` |
+| 本体引擎 | `ontology_` | `ontology_status`、`ontology_property_type` |
+| 新模块 | 按模块缩写 | — |
+
+### 6.2 dict_data.value 命名
+
+- **枚举字符串值**：使用 Java Enum 的 `name()` 值（大写下划线），如 `DRAFT`、`PUBLISHED`、`ONE_TO_MANY`
+- **数值型枚举**：使用数值字符串，如 `0`、`1`、`2`
+- **同一 dict_type 下的 value 不可重复**
+
+### 6.3 color_type 约定
+
+| 场景 | color_type |
+| --- | --- |
+| 成功/启用/生效 | `success` |
+| 警告/待处理 | `warning` |
+| 危险/禁止/失效 | `danger` |
+| 普通/信息 | `info` |
+| 主要业务标识 | `primary` |
+| 默认/无特殊含义 | `default` |
+
+---
+
+## 7. 菜单数据规范
+
+### 7.1 菜单类型（type）
+
+| type | 含义 | 必填字段 | component |
+| --- | --- | --- | --- |
+| 1 | 目录 | name, path, icon, sort, parent_id | NULL |
+| 2 | 菜单 | name, path, icon, component, sort, parent_id | 前端组件路径 |
+| 3 | 按钮 | name, permission, parent_id | NULL |
+
+### 7.2 权限标识命名
+
+格式：`{module}:{resource}:{action}`
+
+| 操作 | action | 示例 |
+| --- | --- | --- |
+| 查询 | `read` | `ontology:ontology:read` |
+| 创建 | `create` | `ontology:ontology:create` |
+| 更新 | `update` | `ontology:ontology:update` |
+| 删除 | `delete` | `ontology:ontology:delete` |
+| 导出 | `export` | `ontology:ontology:export` |
+| 导入 | `import` | `ontology:ontology:import` |
+| 特殊操作 | `{action}` | `ontology:ontology:publish`、`ontology:ontology:rollback` |
+
+### 7.3 目录结构层级
+
+```text
+目录 (type=1, parent_id=0)          ← 一级导航
+ └─ 菜单 (type=2, parent_id=父ID)    ← 实际页面
+     ├─ 按钮 (type=3, parent_id=菜单ID) ← 查询/创建/编辑/删除等
+```
+
+按钮的 `path`、`icon`、`component` 字段必须为 `''` 或 `NULL`。
+
+---
+
+## 8. 禁止事项
+
+1. **禁止将字典菜单数据写入 `_schema.sql` 文件** — 必须独立为 `_menu-dict-type-data.sql`
+2. **禁止 `deleted` 使用 `BOOLEAN` 或 `FALSE`** — 统一用 `SMALLINT` + 整数 `0/1`
+3. **禁止省略 `deleted_time` 字段** — 所有 INSERT 必须包含
+4. **禁止表名/字段名不加双引号** — PostgreSQL 中双引号确保大小写敏感一致
+5. **禁止使用 `INSERT INTO ... VALUES (...)` 直接插入** — 必须用 `INSERT ... SELECT ... WHERE NOT EXISTS` 保证幂等
+6. **禁止字典菜单文件不包含 CREATE TABLE IF NOT EXISTS** — 确保文件可独立执行
+7. **禁止菜单 ID 跨模块冲突** — 新模块须按 §5.3 规则分配 ID 范围
+
+---
+
+## 9. 检查清单
+
+生成 `_menu-dict-type-data.sql` 文件后，逐项核对：
+
+- [ ] 文件包含 3 张系统基础表 `CREATE TABLE IF NOT EXISTS`
+- [ ] 表名/字段名全部用双引号包裹
+- [ ] `deleted` 字段用 `SMALLINT DEFAULT 0`（非 BOOLEAN）
+- [ ] 所有 INSERT 包含 `deleted_time` 字段（值为 NULL）
+- [ ] 所有 INSERT 包含显式 `id` 字段
+- [ ] 所有 INSERT 使用 `WHERE NOT EXISTS` 幂等语法
+- [ ] 字典类型 `type` 标识全小写下划线，模块前缀正确
+- [ ] 字典数据 `value` 不重复（同一 dict_type 内）
+- [ ] 菜单 ID 在模块分配范围内
+- [ ] 菜单按钮的 `path`/`icon`/`component` 为空或 NULL
+- [ ] 菜单 `permission` 格式为 `{module}:{resource}:{action}`
+- [ ] `color_type` 值在约定范围内（success/warning/danger/info/primary/default）
+- [ ] 执行顺序：建表 → dict_type → dict_data → menu

package/references/yudaocloud-end-standard/index.md

@@ -2,11 +2,22 @@
 
 ## 推荐读取顺序
 
-1. 01-Python后端编码规范.md
+1. 01-Java后端编码规范.md
 2. 02-数据库设计与使用规范.md
-3. 03-Celery异步任务规范.md
+3. 03-数据字典与菜单规范.md
 4. 04-Redis使用规范.md
 
 
 ## 维护要求
-- 新增规则文件时，同步更新本索引和根目录 `claude.md`。
+- 新增规则文件时，同步更新本索引和根目录 `claude.md`。
+
+## SQL 文件生成规范（系统设计阶段）
+
+生成系统设计时必须产出 **2 个独立 SQL 文件**（详见 `03-数据字典与菜单规范.md`）：
+
+| 文件         | 命名规则                                 | 内容                                                               |
+| ------------ | ---------------------------------------- | ------------------------------------------------------------------ |
+| 建表 DDL     | `{模块编号}-{模块名}_schema.sql`         | 业务表 CREATE TABLE + 索引 + COMMENT                               |
+| 字典菜单数据 | `{模块编号}-{模块名}_menu-dict-data.sql` | 系统基础表 CREATE TABLE IF NOT EXISTS + 字典类型 + 字典数据 + 菜单 |
+
+字典菜单文件必须可独立执行（含 system_dict_type/system_dict_data/system_menu 三张表的 CREATE TABLE IF NOT EXISTS）。