Files
tdc-rs/docs/known-limitations.md
T
adminandClaude Opus 4.8 70b540f668 feat(b2): 账号层三表入 schema —— base_user / base_role / base_role_relation
影响:/api/health 的 baseTables 从 0 变 3(tables 仍 30);data/ 清空重建。
冒烟断言数 75 → 76(多的那条是 baseTables 对账),其余契约零变化。

改动:
- schema/migrate.sql:末段追加账号层三表(真源 = 上游 j7
  boot/db/j7/V1.0.0__jnpf_base_schema.sql,base_user 在 :17384):
  列类型/列序/96 条 COMMENT ON/3 个索引逐字搬运;
  主键 PRIMARY KEY (f_id, f_tenant_id) 内联(上游在 dump 后置 ALTER 里加,
  pglite 只吃 migrate.sql ⇒ 必须自带)
- tests/schema_init.rs:public 表数 30 → 33,并逐名断言 base_* 三表在位
- src/platform/db.rs:迁移产物单测改成 30 tdc_* + 3 base_* 逐名断言
- scripts/reset-data.sh:提示语改成「30 张 tdc_* + 3 张 base_*」
- docs/known-limitations.md:新增 L2(上游 base_user 的 f_maxkey_user_id
  没建 —— 本仓不实现 MaxKey SSO)
- CLAUDE.md / .workbuddy/memory/2026-10-26.md 同步

设计:tdc_* 侧零 DDL 改动(B0 已逐列对账一致);base_* 只建上游真正用到、
且本仓要用的三张,其余 120 张 base_* 与 base_module/base_authorize 一律不建。

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-10-26 22:58:53 +08:00

3.7 KiB
Raw Blame History

已知限制(Known Limitations)

本文件记录本仓与上游的已知差距,以及刻意保留的取舍。 每条都带 file:line 引用,便于随时核对是否已过时。 决策背景见 decisions.md,对外契约见 contract.md。


L1 · tdc_identity 有两条读写路径(显式承认 + 已收口)

现象:tdc_identity 这一张表同时被两条路径读写 ——

路径 位置 用途
领域路径 src/tdc/service/identity.rs:99、:105、:148、:217、:241、:333、:403、:460、:511 引导身份、登录校验、当前身份、可用空间、能力集、TDS 绑定
引擎路径 src/tdc/service/crud.rs:248、:287、:317、:341、:721、:739 通用 CRUD 引擎对任意实体表(含 tdc_identity)的列表/详情/写入

为什么保留两条:上游没有「通用 CRUD 引擎」这个概念(每个实体一个 Controller + JNPF 底座), 硬把领域 SQL 收进引擎会失真(引擎是实体无关的,列清单/隐藏字段/冻结列都要靠 spec 驱动)。 ⇒ 决策:显式承认 + 收口 + 记账(v3 spec §2.3.1 C10 / 决策 D15)。

已经收口的部分:

  • 领域 SQL 全部集中在 src/tdc/service/identity.rs 一个文件 —— 控制器层不再自己拼 tdc_identity 的 SQL (原先 src/tdc/controller/tds_biz.rs 里的 tdc_identity 查询已移入 src/tdc/service/identity.rs:511 的 local_tds_binding)。
  • 领域查询只 SELECT 明确列,永不 SELECT * ⇒ 密钥列(f_secret_key)不会被整行拖进内存。

仍存在的风险:两条路径的隐藏字段 / 冻结列 / 权限语义可能漂移 —— 例如引擎路径的出参走 spec.hidden_fields 删键(src/tdc/mapper.rs), 而领域路径靠手写 SELECT 列表控制可见列。 新增 tdc_identity 字段时,两条路径都要看一眼。

复现/核对方式:

# 领域路径的 SQL 全在这一个文件里
grep -n "SELECT\|INSERT INTO" src/tdc/service/identity.rs
# 引擎路径的 SELECT *(实体无关,按表结构展开)
grep -n "SELECT \*" src/tdc/service/crud.rs

L2 · 上游 base_user 的 f_maxkey_user_id 列没建

现象:本仓的 base_user(schema/migrate.sql 末段,账号层三表)没有 f_maxkey_user_id 这一列,而上游 j7 的 base_user(最新态)有。

上游怎么来的:上游迁移 boot/db/j7/V1.0.3__base_user_maxkey_user_id.sql 追加的 —— 它是 MaxKey SSO 的「认亲键」:SSO 首次按手机号认亲后,把 MaxKey 的稳定标识 (/sign/api/oauth/v20/me 返回的 userId)写进本地那一行,以后一律用它。

为什么不建:本仓不实现 MaxKey SSO(/api/ssw/tdc/Auth/SsoConfig 恒 enabled:false, 见 src/tdc/service/identity.rs:431)⇒ 这一列没有写入方,也没有读取方 ⇒ 建了就是死列。 同源的取舍:上游 j7 的其余 120 张 base_*(base_module / base_authorize / base_organize …) 也一律不建(上游 ssw.jnpf-permission.enabled=false ⇒ 菜单授权行是死的;v3 spec §3.1)。

补建的触发条件:将来若要接 MaxKey SSO ⇒ ① 加这一列 + 唯一索引 (uk_base_user_maxkey_user_id … WHERE f_maxkey_user_id IS NOT NULL AND <> '') ② 改 schema/migrate.sql ⇒ 必须清空 data/ 重建(见 CLAUDE.md 的坑位表)。

核对方式:

# 本仓建了哪些列
grep -n "f_maxkey_user_id" schema/migrate.sql || echo "(没建,符合预期)"
# 上游那一列的出处
grep -n "f_maxkey_user_id" /tmp/sswtdc-probe/boot/db/j7/V1.0.3__base_user_maxkey_user_id.sql