影响:6 张「上游无独立控制器」的子表挂进父实体的响应;
245 条测试全绿(+6),冒烟断言数仍 76,边界/实体自检全绿。
Resource/Dataset 的普通详情**不带**子表(上游只在 /Detail 聚合体上挂)。
改动:
- src/tdc/entity/mod.rs:新增 ChildMount(Aggregate/Detail/List 三面)与
ChildTable(key/table/fk_column/parent_column/order_column/alive/mounts),
TableSpec.child_tables 由 (key, table) 二元组升级成 ChildTable 切片;
validate() 增加子表标识符白名单自检 + 「聚合体开关 ⇔ 有 Aggregate 面子表」一致性自检
- src/tdc/entity/{resource,dataset}.rs:字段说明 + 脱敏规则挂 Aggregate 面
- src/tdc/entity/data_interface.rs:参数 + 字段映射挂 Detail 面(上游覆写基类详情)
- src/tdc/entity/delivery_task.rs:参与方挂 Detail+List 面(按 f_tds_task_id),
待发队列挂 Detail 面(按 local_task_id)
- src/tdc/service/crud.rs:子表挂载引擎(父行取值 / 单父取子行 / 批量取子行 /
单行回填 / 列表回填),引擎仍零 match api_name(只认列名)
- tests/child_aggregate.rs(新):4 条集成用例(接口详情带子表 / 资源子表只在聚合体 /
交付任务详情与列表带参与方 / 无平台任务号 ⇒ 参与方空集合)
- docs/contract.md(新增 §子表聚合)/ docs/decisions.md(D19)/
docs/known-limitations.md(L3)/ CLAUDE.md / .workbuddy/memory/2026-10-26.md 同步
设计:挂载面逐父子不同(上游口径不是「子表都挂详情」)—— Resource/Dataset 只在
/Detail、DataInterface 只在普通详情、DeliveryTask 详情+列表;父行取值列不一定是
f_id(参与方按平台任务号挂 ⇒ 无平台任务号即空集合);存活谓词逐表不同(四张
资源/接口子表没有 f_delete_mark ⇒ 物理删除语义,不加谓词)。
outbox 挂详情是本仓扩展(上游不挂);tdc_demo_car_insurance 无父外键 ⇒ 挂不了,
记为已知限制 L3,不硬挂。
Co-Authored-By: Claude Code <[email protected]>
6.7 KiB
6.7 KiB
对外契约(contract)
🔴 本文件记录 tdc-rs 对外可观测的契约:口径、形状、边界。 与
docs/decisions.md(为什么这么定)/docs/known-limitations.md(已知偏差)配套读。当前状态:v3 改造批次 B3 已完成(子表聚合),本文件先落地「时间口径」(C12) 与「子表聚合」(B3)两节;其余章节在 B5 补齐。
时间口径
仓里有两套时间口径,不是随手写的——各对应上游的一个具体行为:
| 面 | 口径 | 代码位置 | 上游对照 | 为什么是它 |
|---|---|---|---|---|
业务编码(PRO- / RES- / API- / DS- 的日期与时刻段) |
服务器本地时区 | src/tdc/util/code.rs:37(day_prefix)、src/tdc/util/code.rs:58(format_code)⇒ Local::now() |
TdcCodeUtil.dayPrefix / TdcCodeUtil.format 用 LocalDateTime.now()(Java,服务器本地) |
编码里的 yyyyMMdd-HHmmss 要与上游同一天同刻;差一个时区偏移时,跨零点的 8 小时里日期段会直接变成前一天 |
DB 审计列(f_creator_time / f_modify_time / f_delete_time …) |
服务器本地时区 | src/tdc/service/crud.rs:520、:524、:530、:624、:688 ⇒ SQL now() |
JNPF BaseEntity 自动填充用 new Date()(服务器本地) |
审计列的时间戳要与上游同一量纲,便于两边的日志按时间轴对齐 |
账号库自己的审计字段(creator_time) |
UTC | src/tdc/service/account.rs:290(now_iso)⇒ chrono::Utc::now() |
上游 j7 的 base_user 走 MySQL 填充,本仓这一格没有上游对照物(账号层原是本机 JSON 文件) |
本仓自有格式 ⇒ 选与时区无关的 UTC,避免换机器/换时区后同一条记录的时间戳含义漂移 |
🔴 收敛后的规矩(v3 spec §2.3.1 C12):
- 仓里不再手写日历算法 —— 一律用
chrono(已依赖chrono 0.4,features = ["clock"])。 此前account.rs自己实现了一套天元纪日 → 公历的换算(civil_from_days)⇒ 重复造轮子, 且与code.rs的时区口径不一致(一个 UTC 一个本地)⇒ 手工算法与它的推论一起删除。 - 口径写在代码注释里(不是只在文档里):谁想改时区,必须先改那处的注释 ⇒ 评审时看得见。
- ⚠️ 别把 UTC 写成 Local:账号层的
now_iso用chrono::Utc::now(); 换成Local::now()在非 UTC 时区下会静默改值(src/tdc/service/account.rs的单测now_iso_is_utc_and_parsable会红)。 - ⚠️ 别把 Local 写成 UTC:业务编码与 DB 审计列必须留在服务器本地时区, 否则同一时刻生成的编码与上游对不上(见上表第一行)。
📌 B4 之后的注意:账号层从本机 JSON 文件迁到 base_user 表后,
f_creator_time 这一格会从「UTC(本仓自有格式)」变成「DB now()(服务器本地时区)」——
那时以表为准(与上游 j7 同口径),并同步更新本节。
子表聚合(挂载点口径)
上游有 7 张「没有独立控制器」的子表 ⇒ 它们的可见性全部挂在父实体的响应里。 本仓不新增端点,照抄上游的挂载位置(v3 spec §6.2 B3)。
| 父实体 | 挂载面 | 输出键 | 子表 | 外键列 → 父行取值列 | 排序 | 上游出处 |
|---|---|---|---|---|---|---|
Resource / Dataset |
GET /{id}/Detail |
fieldRules |
tdc_resource_field |
f_resource_id → f_id |
f_sort_code |
ResourceServiceImpl#withChildren |
Resource / Dataset |
GET /{id}/Detail |
maskRules |
tdc_resource_mask_rule |
f_resource_id → f_id |
f_sort_code |
同上 |
DataInterface |
GET /{id} |
params |
tdc_data_interface_param |
f_interface_id → f_id |
f_sort_code |
DataInterfaceServiceImpl#withChildren(DataInterfaceController#detail 覆写调用) |
DataInterface |
GET /{id} |
fields |
tdc_data_interface_field |
f_interface_id → f_id |
f_sort_code |
同上 |
DeliveryTask |
GET /{id} + 列表 |
participants |
tdc_delivery_task_participant |
f_tds_task_id → f_tds_task_id |
f_connector_id |
TdcDeliveryTaskParticipantServiceImpl#attachParticipants |
DeliveryTask |
GET /{id} |
outbox |
tdc_delivery_outbox |
local_task_id → f_id |
seq |
🔴 本仓扩展(上游不挂,见 §偏离) |
tdc_demo_car_insurance |
— | — | — | 无父外键 | — | 🔴 挂不了(见 §偏离) |
规矩:
- 🔴 挂载面逐父子不同,不是「都挂详情」——
Resource的子表只在/Detail聚合体(普通GET /{id}不带);DataInterface的子表只在普通详情(上游没有/Detail聚合体路由)。 - 🔴 父行取值列可以不是
f_id:参与方按平台任务号(f_tds_task_id)挂 ⇒ 任务没有平台任务号时,参与方是空集合(上游同口径,不是"查一次再判空")。 - 🔴 存活谓词逐表不同:四张「资源 / 接口」子表没有
f_delete_mark(上游物理删除) ⇒ 不加谓词;参与方表有 ⇒ 按本仓ALIVE过滤。 - 🔴 列表挂载是批量查(一次
IN+ 分组)⇒ 不产生 N+1(上游listByTdsTaskIds同款)。
代码位置(file:line):
- 声明结构:
src/tdc/entity/mod.rs:60(ChildMount)、src/tdc/entity/mod.rs:74(ChildTable)、src/tdc/entity/mod.rs:145(TableSpec::child_tables)、src/tdc/entity/mod.rs:164(children_on)。 - 引擎:
src/tdc/service/crud.rs:322(父行取值)、:344(单父取子行)、:373(批量取子行)、:414(单行回填)、:433(列表回填)。 - 逐实体声明:
src/tdc/entity/resource.rs:34、src/tdc/entity/dataset.rs:28、src/tdc/entity/data_interface.rs:26、src/tdc/entity/delivery_task.rs:55。
偏离
| 项 | 上游 | 本仓 | 为什么 |
|---|---|---|---|
outbox(待发队列)挂详情 |
不挂(上游是内部重试队列,只由 DeliveryOutboxRetryTicker 消费) |
挂在 DeliveryTask 详情(键 outbox) |
它货真价实是任务的子表(local_task_id = 任务 f_id),且本仓不实现交付执行 ⇒ 队列恒空 ⇒ 挂了也不产生噪声;将来接入重试时这条挂载即生效 |
tdc_demo_car_insurance |
不挂(它是 SandboxSessionServiceImpl 的降级演示数据源,无父外键) |
不挂 | 上游 Sandbox / Nax 隐私计算属本仓明确排除范围(见 CLAUDE.md「明确不在本仓库范围」)⇒ 该表在本仓无父、无消费者 ⇒ 挂不上也不该硬挂 |