Files
tdc-rs/HOWTO_ENTITY.md
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。

新增文档:

- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
  唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。

新增尺子(第四把 + 两把专项):

- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。

影响:

- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
  (`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
  ⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
  吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
  POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
  失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
  **不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。

实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。

⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 00:56:09 +08:00

15 KiB
Raw Permalink Blame History

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) 加一个 "<Entity>" => &[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 当模板,它最简):

//! `<Entity>` 的实体元数据(对位上游 `ssw.tdc.entity.<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/<api_name>(尺子 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)

如果新实体的详情要带子表:

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 行)

// ① 模块声明(按字母序插在正确位置)
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_<名字> (...):

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 scripts/reset-data.sh      # 走访达回收站,可恢复
PORT=30000 ./target/debug/tdc-connector

2.6 可选:服务端生成编码 / 默认值

若上游在 beforeSave 里生成编码或补默认值(照抄上游 beforeSave):

// 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

# 追加到 scripts/upstream-json-ignore.tsv(制表符分隔)
printf '<你的实体>\t<驼峰键>\n' >> scripts/upstream-json-ignore.tsv

🔴 尺子 E4 断言上游清单 ⊆ 本仓 hidden_fields ⇒ 漏一条 = 泄密(尺子会红)。


3. 试跑(照着加一个)

完整的「加一个试跑」演练 —— 用 PolicyTemplate 当例子(18 个实体里最简的一个):

3.1 改前基线

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 跑

cargo build                              # 编译
bash scripts/check-entity.sh              # E1 表在不在 / E2 路径对不对 / E7 键闭合
bash scripts/check-boundary.sh            # 引擎仍然零 match api_name
cargo test                               # 全绿

3.4 起服务真打一遍

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 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/<api_name> 改 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 的端点表是脚本生成 + 脚本对账的 ⇒ 加实体后必须重生成:

# ① 生成新表(Markdown 行)
python3 scripts/contract_probe.py --gen

# ② 把输出贴进 docs/contract.md 的
#    <!-- BEGIN ENDPOINTS --> … <!-- END ENDPOINTS --> 之间
#    (保留表头那一行:| 方法 | 路径 | 说明 |)

# ③ 对账(真起一个进程,逐条打)
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/