Files
tdc-rs/docs/contract.md
T
adminandClaude Code ec47f47d46 feat(b3): 子表聚合补齐 —— 挂载面逐父子照抄上游(不新增端点)
影响: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]>
2026-10-26 23:15:42 +08:00

6.7 KiB
Raw Blame History

对外契约(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):

  1. 仓里不再手写日历算法 —— 一律用 chrono(已依赖 chrono 0.4,features = ["clock"])。 此前 account.rs 自己实现了一套天元纪日 → 公历的换算(civil_from_days)⇒ 重复造轮子, 且与 code.rs 的时区口径不一致(一个 UTC 一个本地)⇒ 手工算法与它的推论一起删除。
  2. 口径写在代码注释里(不是只在文档里):谁想改时区,必须先改那处的注释 ⇒ 评审时看得见。
  3. ⚠️ 别把 UTC 写成 Local:账号层的 now_iso 用 chrono::Utc::now(); 换成 Local::now() 在非 UTC 时区下会静默改值(src/tdc/service/account.rs 的单测 now_iso_is_utc_and_parsable 会红)。
  4. ⚠️ 别把 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 — — — 无父外键 — 🔴 挂不了(见 §偏离)

规矩:

  1. 🔴 挂载面逐父子不同,不是「都挂详情」—— Resource 的子表只在 /Detail 聚合体(普通 GET /{id} 不带); DataInterface 的子表只在普通详情(上游没有 /Detail 聚合体路由)。
  2. 🔴 父行取值列可以不是 f_id:参与方按平台任务号(f_tds_task_id)挂 ⇒ 任务没有平台任务号时,参与方是空集合(上游同口径,不是"查一次再判空")。
  3. 🔴 存活谓词逐表不同:四张「资源 / 接口」子表没有 f_delete_mark(上游物理删除) ⇒ 不加谓词;参与方表有 ⇒ 按本仓 ALIVE 过滤。
  4. 🔴 列表挂载是批量查(一次 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「明确不在本仓库范围」)⇒ 该表在本仓无父、无消费者 ⇒ 挂不上也不该硬挂