# HOWTO_ENTITY —— 加一个实体 > 🔴 **本手册只讲一件事:怎么加一个新的可 CRUD 实体。** > 加实体的**全部改动**落在 **4 个文件**里,**通用 CRUD 引擎一行都不用碰**。 > > 目标读者:要给 `tdc-rs` 加一个新表 / 一组新端点的人。 **一句话版本**: ``` 新建 src/tdc/entity/<名字>.rs → 在 src/tdc/entity/mod.rs 加 2 行 → (新表则)schema/migrate.sql 加 DDL → 重生成 docs/contract.md 的端点表 → 跑五把尺子 ``` --- ## 0. 前置:确认这个实体**该**加在这儿 本仓的 CRUD 引擎是**声明式**的:实体 = 一张表 + 一组元数据。 先确认你要做的不是下面这几类(它们**不**走本手册): | 你要做的事 | 该去哪 | |---|---| | 隐私计算 / Nax / Sandbox 作业 | ❌ **不做**(依赖 Nax 引擎 + scard 安全平面,见 `CLAUDE.md` §明确不在范围) | | 策略校验 / 策略执行 | ❌ 同上 | | 交付执行 / 调度 / 心跳 | ❌ 同上 | | 菜单 / 角色 / 授权 | ❌ 不引入 j7 菜单模型(`docs/known-limitations.md` L2) | | 出向 TDS 的新接口 | 改 `src/tdc/client/tds.rs`(**不是** CRUD 引擎) | | 账号 / 权限管理 | 改 `src/tdc/service/account.rs`(**不是** CRUD 引擎) | | **一张新的业务表,要在本仓自己的控制台里增删改查** | ✅ **本手册** | --- ## 1. 改动清单(4 个文件) | # | 文件 | 改什么 | 必改? | |---|---|---|---| | ① | `src/tdc/entity/<名字>.rs` | **新建**:一个 `pub const SPEC: TableSpec` | ✅ | | ② | `src/tdc/entity/mod.rs` | `pub mod <名字>;` + `ALL_SPECS` 里加一行 | ✅ | | ③ | `schema/migrate.sql` | 新表的 DDL(**复用已有表则不用**) | 视情况 | | ④ | `docs/contract.md` | 端点表重生成(**自动**,见 §5) | ✅ | 外加**两个可选**: | 文件 | 什么时候 | 怎么改 | |---|---|---| | `src/tdc/entity/mod.rs` 的 `create_codes` | 新增时要**服务端生成编码**(如 `PRO20260127xxxx`) | 加一个 `"" => &[CodeSpec{…}]` 分支 | | `src/tdc/entity/mod.rs` 的 `create_defaults` / `create_now_columns` | 新增时要**服务端补默认值** | 同上,加一个分支 | | `scripts/upstream-json-ignore.tsv` | 上游实体标了 `@JsonIgnore` | 加一行 `<实体>\t<驼峰键>` | 🔴 **不改**这些(引擎不许出现实体名): `src/tdc/service/crud.rs`(CRUD 引擎)· `src/tdc/mapper.rs`(SQL 拼装)· `src/tdc/controller/crud.rs`(路由装配)—— 它们**遍历 `ALL_SPECS`**,新实体自动生效。 --- ## 2. 步骤 ### 2.1 照抄一个最简的模板 新文件 `src/tdc/entity/<名字>.rs`(用 `policy_template` 当模板,它最简): ```rust //! `` 的实体元数据(对位上游 `ssw.tdc.entity.Entity`)。 //! //! <一句话说明与上游的差异,没有就写「与上游逐字一致」> //! //! 本文件只放**这一个**实体的 spec —— 通用元数据结构见 [`super::TableSpec`]。 use super::TableSpec; /// 本实体的完整元数据(注册表唯一真源)。 pub const SPEC: TableSpec = TableSpec { api_name: "PolicyTemplate", path: "/api/ssw/tdc/PolicyTemplate", table: "tdc_policy_template", // 关键字模糊匹配列(多列 OR)。🔴 列**必须真实存在**(查 `migrate.sql`)。 keyword_columns: &["f_name"], // 精确过滤:`(请求参数名, DB 列名)`。请求参数名是 camelCase。 filter_columns: &[("status", "f_status")], // 租户列;`Some` 时客户端传 `tenantId` 一律拒(对齐上游 `tenantColumn()`)。 tenant_column: Some("f_tenant_id"), // 默认排序列(**倒序**)。 default_order_column: "f_creator_time", // 附加固定谓词(与 `ALIVE` AND 起来);没有就 `None`。 extra_where: None, // 三个「禁改写」拒因;`None` = 允许。上游只读视图才禁。 no_create: None, no_update: None, no_delete: None, // 不可经编辑入口改写的列(服务端权威列)。 frozen_columns: &[], // **不外泄字段**(上游 `@JsonIgnore`)—— 键是 camelCase JSON 键。 hidden_fields: &[], // 子表挂载声明;没有子表就 `&[]`。 child_tables: &[], // 「查无此条」文案(上游逐字)。 not_found_msg: "记录不存在或已删除", // 是否注册只读聚合体路由 `GET {path}/{id}/Detail`。 aggregate_detail: false, }; ``` ### 2.2 字段怎么填(逐条对着上游抄) | 字段 | 上游对应 | 本仓怎么写 | |---|---|---| | `api_name` | 控制器的实体名 | 原样(如 `PolicyTemplate`) | | `path` | `@RequestMapping` 的值 | **必须** = `/api/ssw/tdc/`(尺子 E2 会断言) | | `table` | 实体上的 `@TableName` | 如 `tdc_policy_template`;🔴 必须是 `migrate.sql` 里**已存在**的表(E1) | | `keyword_columns` | 控制器 `keywordColumns()` | 逐字抄;🔴 **列必须真实存在**(上游 `ApiConsumeLog` 抄漏过一列 ⇒ 一搜就 `42703`) | | `filter_columns` | 控制器 `filterColumns()` | 逐字抄;键是**请求参数名**(camelCase),值是**列名**(`f_` 前缀) | | `tenant_column` | 控制器 `tenantColumn()` | 逐字抄(`Identity` 是 `None`) | | `default_order_column` | 控制器 `defaultOrderColumn()` | 逐字抄 | | `extra_where` | 控制器里的固定谓词 | 照抄(如 `Dataset` 的 `DATASET_EXTRA_WHERE`) | | `no_create` / `no_update` / `no_delete` | 上游的只读视图 | 写上游的**原话**;允许写就 `None` | | `frozen_columns` | 控制器 `changedAuthorityColumn()` | 逐字抄(列名 + 中文标签) | | `hidden_fields` | 实体上的 `@JsonIgnore` | camelCase JSON 键;🔴 尺子 E4 断言**上游清单 ⊆ 本仓** | | `child_tables` | 服务的 `withChildren()` | 见 §2.3 | | `not_found_msg` | 控制器「查无此条」文案 | 上游逐字 | | `aggregate_detail` | 控制器有 `GET /{id}/Detail` | `true` / `false` | ### 2.3 子表挂载(`child_tables`) 如果新实体的详情要带子表: ```rust use super::{ChildMount, ChildTable, TableSpec}; child_tables: &[ ChildTable { key: "fieldRules", // 输出 JSON 键(上游实体属性名) table: "tdc_resource_field", // 子表名 fk_column: "f_resource_id", // 子表侧外键列 parent_column: "f_id", // 父行取值列 order_column: "f_sort_code", // 子表侧排序列 alive: None, // 存活谓词;该子表无逻辑删除列 ⇒ None mounts: &[ChildMount::Aggregate], }, ], ``` `mounts` 三个值对应**三个挂载面**(上游逐父子不同,别猜): | `ChildMount` | 挂在哪 | 上游对照 | |---|---|---| | `Aggregate` | `GET {path}/{id}/Detail` | `ResourceController#detailOf` | | `Detail` | `GET {path}/{id}` | `DataInterfaceController#detail` | | `List` | 列表响应(分页 + 全量) | `DeliveryTaskController#decorate` | 🔴 **`aggregate_detail: true` 必须配至少一个 `Aggregate` 面的子表** (单测 `aggregate_detail_is_pinned_to_the_resource_side` 会断言)—— 否则聚合体和普通详情没区别 ⇒ 白开一条路由。 ### 2.4 在 `mod.rs` 注册(2 行) ```rust // ① 模块声明(按字母序插在正确位置) pub mod policy_template; // ← 已有;你的加在正确字母位 // ② ALL_SPECS 里加一行(按 api_name 字母序) pub static ALL_SPECS: &[TableSpec] = &[ // … policy_template::SPEC, <你的>::SPEC, // ← 加这一行 // … ]; ``` ### 2.5 加表(`schema/migrate.sql`) 如果新实体**复用已有表**(像 `Dataset` 复用 `tdc_resource`)⇒ 跳过本步。 否则在 `schema/migrate.sql` 里加 `CREATE TABLE public.tdc_<名字> (...)`: ```sql CREATE TABLE public.tdc_<名字> ( f_id character varying(50) NOT NULL, f_tenant_id character varying(50) DEFAULT '0'::character varying, f_sort_code integer DEFAULT 0, f_name character varying(255), f_status character varying(50), f_delete_mark integer DEFAULT 0, f_creator_time timestamp without time zone DEFAULT now(), f_creator_id character varying(50), f_last_modify_time timestamp without time zone DEFAULT now(), f_last_modify_id character varying(50) ); ``` 🔴 **必须带的列**(引擎硬依赖): | 列 | 少了会怎样 | |---|---| | `f_id` | 主键;缺 ⇒ 插入直接报错 | | `f_delete_mark` | 存活谓词 `(f_delete_mark IS NULL OR f_delete_mark = 0)`;缺 ⇒ **列表 500** | | `f_creator_time` | 默认排序列;缺 ⇒ 列表 500 | | `f_tenant_id` | 租户过滤列(若 `tenant_column: Some(...)`) | 🔴 **改完 `migrate.sql` 必须清数据重建**(探针只在首次建表时跑): ```bash bash scripts/reset-data.sh # 走访达回收站,可恢复 PORT=30000 ./target/debug/tdc-connector ``` ### 2.6 可选:服务端生成编码 / 默认值 若上游在 `beforeSave` 里生成编码或补默认值(照抄上游 `beforeSave`): ```rust // src/tdc/entity/mod.rs pub fn create_codes(api_name: &str) -> &'static [CodeSpec] { match api_name { // …已有的… "<你的>" => &[CodeSpec { key: "<驼峰键>", // 如 "xxxCode" prefix: "XXX", // 🔴 尺子 E5:前缀不能和别的实体重复 style: CodeStyle::DaySeqTail8, retries: 5, fail_msg: "…生成失败(连续 5 次撞库),请重试", baseline_alive: false, }], _ => &[], } } ``` 同理还有 `create_defaults`(`(驼峰键, 常量文本)`,支持 `{id}` 占位)和 `create_now_columns`(要补 `now()` 的列)。 🔴 这三个函数在 `entity/mod.rs` 里,是**业务层**的 `match api_name` —— **允许**(红线的「零 `match api_name`」只针对**引擎**:`service/crud.rs` / `mapper.rs` / `controller/crud.rs`)。 ### 2.7 可选:上游 `@JsonIgnore` ```bash # 追加到 scripts/upstream-json-ignore.tsv(制表符分隔) printf '<你的实体>\t<驼峰键>\n' >> scripts/upstream-json-ignore.tsv ``` 🔴 尺子 E4 断言**上游清单 ⊆ 本仓 `hidden_fields`** ⇒ 漏一条 = **泄密**(尺子会红)。 --- ## 3. 试跑(照着加一个) 完整的「加一个试跑」演练 —— 用 `PolicyTemplate` 当例子(18 个实体里最简的一个): ### 3.1 改前基线 ```bash cargo build && bash scripts/check-entity.sh # ⇒ PASS=13 FAIL=0 ``` ### 3.2 加 1. `src/tdc/entity/policy_template.rs` —— 抄 §2.1 的模板。 2. `src/tdc/entity/mod.rs` —— 加 `pub mod policy_template;` + `ALL_SPECS` 加 `policy_template::SPEC,`。 3. `schema/migrate.sql` —— 加 `CREATE TABLE public.tdc_policy_template (...)`。 ### 3.3 跑 ```bash cargo build # 编译 bash scripts/check-entity.sh # E1 表在不在 / E2 路径对不对 / E7 键闭合 bash scripts/check-boundary.sh # 引擎仍然零 match api_name cargo test # 全绿 ``` ### 3.4 起服务真打一遍 ```bash bash scripts/reset-data.sh # 让新表建出来 PORT=30000 ./target/debug/tdc-connector & sleep 5 TOKEN="ssw-internal-token-e2e" # 列表 curl -s --noproxy '*' -H "X-Internal-Token: ${TOKEN}" \ http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate # 新增 curl -s --noproxy '*' -H "X-Internal-Token: ${TOKEN}" -H 'Content-Type: application/json' \ -d '{"name":"试跑实体","status":"ENABLED"}' \ http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate # 详情 / 修改 / 删除 curl -s --noproxy '*' -H "X-Internal-Token: ${TOKEN}" \ http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate/<上面返回的 id> ``` ### 3.5 收尾 ```bash bash scripts/smoke.sh # PASS=80 FAIL=0 bash scripts/check-contract.sh # 端点表要对账(见 §5) ``` --- ## 4. 常见坑 | 症状 | 根因 | 处理 | |---|---|---| | 列表 500,日志 `42703 column … does not exist` | `keyword_columns` / `filter_columns` 里的列**表里没有** | 逐字核对 `migrate.sql` 的列名 | | 列表 500,`column f_delete_mark does not exist` | 新表漏了 `f_delete_mark` | 补 DDL + `reset-data.sh` | | 新表**根本没建** | 探针只看「public schema 有没有表」⇒ 有表就跳过整个迁移 | `bash scripts/reset-data.sh` 后重起 | | 尺子 E2 红 | `path` ≠ `/api/ssw/tdc/` | 改 `path` | | 尺子 E1 红 | `table` 不在 `migrate.sql` | 补 DDL | | 尺子 E4 红 | 上游 `@JsonIgnore` 字段没进 `hidden_fields` | 补进 spec + `scripts/upstream-json-ignore.tsv` | | 尺子 E5 红 | 编码前缀和别的实体重复 | 换前缀 | | 尺子 E7 红 | 列名 ↔ camelCase 不闭合(如 `f_url` → `url` → `f_url` ✅;`f_2d_code` → `2dCode` → `f_2_d_code` ❌) | 换列名,或在 `src/platform/db.rs` 的映射里补特例 | | 405 / 端点数对不上 | `docs/contract.md` 的端点表没重生成 | 见 §5 | | 详情报「记录不存在或已删除」 | `not_found_msg` 抄错 / id 取值列不对 | 抄上游原话 | | 新增返回 500(`null value in column … violates not-null constraint`) | 该列 NOT NULL 且无 DEFAULT,客户端又不送 | 要么加 `create_codes` / `create_defaults`,要么改 DDL 给 DEFAULT | --- ## 5. 端点表必须重生成(`docs/contract.md`) `docs/contract.md` 的端点表是**脚本生成 + 脚本对账**的 ⇒ 加实体后必须重生成: ```bash # ① 生成新表(Markdown 行) python3 scripts/contract_probe.py --gen # ② 把输出贴进 docs/contract.md 的 # … 之间 # (保留表头那一行:| 方法 | 路径 | 说明 |) # ③ 对账(真起一个进程,逐条打) bash scripts/check-contract.sh # ⇒ ✅ 端点表与实际注册路由完全一致(N 条端点) ``` 🔴 加一个实体 ⇒ 端点数 **+6**(列表 / All / 详情 / 新增 / 修改 / 删除); 再开 `aggregate_detail` ⇒ **+1**(`/Detail`)。 --- ## 6. 做完之后 | 动作 | 为什么 | |---|---| | `cargo test` | 注册表自检 + 引擎回归 | | `bash scripts/check-entity.sh` | E1–E7 七项 | | `bash scripts/check-boundary.sh` | 引擎仍然零 `match api_name`(红线) | | `bash scripts/smoke.sh` | HTTP 契约 | | `bash scripts/check-contract.sh` | 端点表 ↔ 实际路由 | | 更新 `docs/contract.md` 的**数据模型**段 | 表数量变了 | | 更新 `CLAUDE.md` 的实体清单 | 18 → 19 | | 更新 `MIGRATION.md` §1.2 的逐件翻译表 | 加一行对照上游 | | 记一条 `docs/decisions.md` | 如果与上游有偏差 | --- ## 7. 相关文档 | 想知道的 | 去哪 | |---|---| | `TableSpec` 每个字段的完整语义 | `src/tdc/entity/mod.rs:96`(结构定义 + 注释) | | `ChildMount` 三个挂载面 | `src/tdc/entity/mod.rs:51` | | 引擎怎么用 spec | `src/tdc/service/crud.rs` | | 路由怎么自动注册 | `src/tdc/controller/crud.rs:27`(遍历 `ALL_SPECS`) | | SQL 怎么拼 | `src/tdc/mapper.rs` | | 对外契约(端点 / 形状 / 命名) | `docs/contract.md` | | 踩坑历史 | `CLAUDE.md` §已知踩坑清单 | | 上游真源(只读) | `/tmp/sswtdc-probe/boot/ssw-tdc/ssw-tdc-entity/src/main/java/ssw/tdc/entity/` |