Files
tdc-rs/docs/known-limitations.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

19 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

L3 · tdc_demo_car_insurance 不参与任何聚合(它没有父表)

现象:v3 spec §6.2 的 B3 清单列了 7 张「上游无独立控制器、走父实体聚合」的子表, 本仓已覆盖其中 6 张(字段说明 / 脱敏规则 / 接口参数 / 接口字段 / 交付参与方 / 交付待发队列), 唯独 tdc_demo_car_insurance 挂不了。

为什么:那张表没有任何父外键 —— 列只有 f_policy_no / f_vehicle_type / f_age / f_claim_amount / f_drive_score / f_risk_level / f_region(+ 系统列), 它在上游是 SandboxSessionServiceImpl 的**「读不到就喂演示数据」降级数据源** (上游 SandboxSessionServiceImpl:333 的注释原文:FALLBACK → 演示表(tdc_demo_car_insurance)), 不是任何实体的子表。而 Sandbox / Nax 隐私计算属本仓明确排除的范围 (见 CLAUDE.md「明确不在本仓库范围」)⇒ 本仓既没有它的消费者,也没有它的父。

为什么不硬挂:挂到任意父实体上都是编造关系 ⇒ 会让「聚合详情字段齐全」变成一句假话。

核对方式:

# 这张表没有父外键(列里没有 *_id 指向别的表)
grep -n "CREATE TABLE public.tdc_demo_car_insurance" -A 20 schema/migrate.sql
# 没有任何实体声明它当子表(注册表自检里有一条单测钉住这点)
grep -n "tdc_demo_car_insurance" src/tdc/entity/*.rs   # 期望:无输出

若将来要覆盖:前提是本仓接上 Sandbox / Nax 侧的会话实体 ⇒ 那时它才有一个可挂的父(本仓的 tdc_sandbox_exec_run 是执行记录,不是会话主体)⇒ 需要先建模会话实体,再按 ChildTable 声明挂载。


L4 · 实体级写权限没有隔离(显式敞开 + 显式记账)

现象:除管理员端点外,任何登录用户(连接器身份会话 / 本地账号会话)可写全部 18 个实体 —— 建、改、删都只要求「有登录态或内部令牌」。

为什么:D6 / D11 定的口径。旧的「实体 → 权限键」那一层 (entity::PERMISSION_KEYS 18 条 + identity::capabilities() + crud::require_write_permission()) 从来就没在管:

  • 能力集解析不出 ⇒ fail-open(本地单机模式没有能力集)⇒ 绝大多数情况下直接放行;
  • 能解析出时,* / all 也会放行;
  • ⇒ 这一层的实际效果 ≈「登录即可写」。

留着它有两个害处:① 让人以为有实体级隔离;② 制造「本地能用、部署后就锁死」的假象 (部署后能力集能解析出来 ⇒ 行为与本地不一致)。

所以:B4 把整条链路删掉,写操作统一走 platform::auth::require_menu_permission (= 内部令牌 或 有登录态)⇒ 与上游 TdcCrudController.requireMenuPermission() 完全同构 (上游 permissionGuard == null 时也只校验这两样)。

这不是「放权」:上游本仓同款;本仓没有比上游更宽。

仍然在的隔离(别误读):

面 还在吗 位置
实体只读/只写分档(no_create / no_update / no_delete) ✅ 在 src/tdc/entity/mod.rs(TableSpec)
管理员端点(/api/permission/Users* 6 个) ✅ 在(f_is_administrator=1,fail-closed) src/tdc/controller/account.rs(require_admin)
内部令牌通道 ✅ 在 src/platform/auth.rs
实体级按角色的读写隔离 ❌ 没有(上游也没有) —

🔴 部署退出门槛(D11 的兑现处):账号发放只给受信人。 默认引导口令是公开已知的 admin ⇒ 上线前必须改(TDC_STRICT_SECRETS=1 会在 「管理员仍在用默认口令」时拒绝启动;改口令走 /api/permission/Users/{id}/Actions/ResetPassword)。 受限于「任何登录用户可写全部实体」这条,本机部署只要有一个普通账号被拿到 ⇒ 等于全量可写。

核对方式:

# 权限键表已不存在
grep -rn "PERMISSION_KEYS" src/ | grep -v "^src/.*://"   # 期望:无输出
# 写路径只剩登录态闸门
grep -n "require_menu_permission\|require_write_permission" src/tdc/service/crud.rs
# 管理员位判据
grep -n "f_is_administrator" src/tdc/service/account.rs

L5 · 上游的动作端点未实现(分期的正常状态)

现象:上游 18 个 extends TdcCrudController 的控制器里,除了 CRUD-6 基线 (列表 / All / 详情 / 新增 / 修改 / 删除)与 2 条只读聚合体(Resource/{id}/Detail · Dataset/{id}/Detail,本仓 B3 已实现)之外,还有 109 条动作端点 —— 本仓一条都没实现。

🔴 数字口径:scripts/upstream-action-census.py(只读上游克隆)—— 18 个控制器自声明 122 条 method-level 映射,扣掉 11 条重复声明的 CRUD-6 基线 与 2 条已实现的聚合体 ⇒ 109 条未实现(形态 A 26 + 形态 B 83)。 不是「144」那个数 —— 144 是 grep -rhoE 对全部 31 个控制器(含非 CRUD 的 Auth / Billing / ServiceCatalog / Gateway / Portal …)的去重计数,口径不同。

上游那 109 条长什么样(按域分组,括号里是端点数;★ 标的是形态 A ⇒ 见 L7):

域 上游端点 依赖 能否在本仓实现
产品上下架 / 审核 Product/{id}/OnShelf · OffShelf · Audit · AuditReject · Enable · Offline · PublishToTds · PublishNewVersion · PublishCallback · UploadCover · Product/{id}/Cover · Product/Catalog★ · Product/Internal/ForceOffline(13) 上下架状态机 + 出向 TDS 发布 ⚠️ 可做,但要先定状态机(本仓无 f_status 动作语义)
资源挂载 / 脱敏 / 加密 Resource/{id}/Mount · MountData · Disable · Enable · Classify · MarkCipher · Cipher/Query · Sync · Resource/{id}/Fields · MaskRules · Sample · Resource/Sample/{productId} · Resource/Enabled★ · Resource/Search★(14) 加密标记 + 分类 + 同步 ⚠️ 部分可做(Classify/Mount 是纯 DB 写)
合约协商 / 签署 Contract/Proposal★ · CreateByProposal★ · MultiParty/CreateByConnector · InitiateTask★ · Initiables★ · MyOrders★ · UsageMetrics★ · Contract/{id}/Change · ChangeCancel · Initiate · Negotiate · NegotiateRespond · Negotiation/Status · Negotiation/Summary · Negotiations · Parties · Resign · Terminate · Effective · Sync · LocalSign★ · ConnectorSign★(22) 合约状态机 + 多方交互 ❌ 复杂(是本仓最大的一块)
交付执行 DeliveryTask/{id}/DataSetDeliver · Destroy · Cancel · Finish · ReDeliver · RequestClose · Event · Exec/Start · Exec/Status · Result/Artifact · Result/Artifact/Proxy · Result/Download · Result/Pull · Result/Summary · Dev/Open · Dev/Submit · Dev/AuditResult · Dev/Artifact · DeliveryLog/ByTask/{taskId} · DeliveryTask/CountRunning★ · DestroyScan★ · EngineSelfCheck★ · Internal/VoidAlgorithm · EngineJobs/Dispatch(24) Nax 隐私计算引擎 + scard 安全平面 ❌ 本地不可行(见 CLAUDE.md §明确不在范围)
身份注册 / 心跳 Identity/{id}/Register · RegisterCallback · Heartbeat · Default · RotateSecret · Identity/Default★ · AutoProvision★ · Internal/Deregister(8) 私钥签名 + 平台侧注册流程 ⚠️ 部分可做(Default/RotateSecret 是纯 DB 写)
订单 / 凭据 / 策略 / 数据源 / 接口 / 通知 / 审计 Order/{id}/Approve · ConfirmPayment · Reject · Sign · Order/{id}/Delivery · Credential/Verify★ · Credential/{id}/Revoke · Policy/Check★ · Policy/GateCheck★ · Policy/{id}/Enable · Datasource/{id}/Enable · Disable · Sync · Test · Datasource/Enabled★ · Datasource/Types★ · DataInterface/{id}/Enable · Disable · Copy · Preview · DataInterface/Import★ · DataInterface/{id}/Export · Notification/{id}/Read · Notification/UnreadCount★ · AuditLog/Verify★ · AuditLog/ReportNow★(26) 纯业务状态机(部分) ⚠️ 多数可做(纯 DB 写 + 简单校验)
策略模板 / 数据集 PolicyTemplate/Options★ · Dataset/{id}/Sample(2) 下拉项 / 样本预览 ⚠️ 可做(Options 是纯 SELECT)
只读聚合体(已实现,不在 109 内) Resource/{id}/Detail · Dataset/{id}/Detail(2) — ✅ 已实现(B3)

为什么不一次做完:109 条动作端点里,约 1/4 依赖本仓明确排除的引擎 (Nax / Sandbox / scard)⇒ 硬做会造出一堆「点了没反应」的死按钮; 剩下的 80 条是状态机,需要逐域定状态与副作用(尤其合约协商 22 条), 一次性糊出来必然与上游行为对不上 ⇒ 与 v3 spec §2「分批」的原则冲突。

本仓现在做了什么:把 CRUD-6 基线 + 2 条只读聚合体 + 10 个 TDS 出向端点 (共 132 条,docs/contract.md 是唯一真源)做齐做对, 动作端点留到后续批次。

核对方式:

# 本仓的端点全表(132 条)
bash scripts/check-contract.sh

# 上游那 109 条动作端点(脚本统计,只读上游快照;口径见本节开头的说明)
python3 scripts/upstream-action-census.py

# 本仓**没有**的路径 ⇒ 404 是预期行为(★ 形态 A 除外,见 L7)
grep -rn "OnShelf\|OffShelf\|Negotiate\|Exec/Start" src/   # 期望:无输出

L6 · 分发形态缺陷:static/ 靠 current_exe() 向上找(D12 · 本批不修)

现象:本仓的静态前端目录靠从可执行文件向上找来定位:

// src/main.rs:43
fn resolve_project_dir() -> PathBuf { … 向上找含 static/index.html 的目录 … }

⇒ 二进制必须与 static/ 保持「向上可及」的相对关系。

三个具体的坏处:

场景 症状
cargo install 装的二进制 ~/.cargo/bin/tdc-connector 向上找不到 static/ ⇒ 前端 404(后端 API 仍可用)
打成单文件分发 同上(static/ 根本不在旁边)
二进制被软链调用 current_exe() 在 Linux/macOS 上返回真实路径(多数平台已解引用)⇒ 软链目录里的 static/ 看不见

为什么本批不修(D12):真正的修法有两种,都不是本批能顺手做的 —— ① 把 static/ 打进二进制(include_dir! 或 rust-embed)⇒ 二进制体积 +2 MB, 且要处理「版本不匹配时前端与后端对不上」;② 把 static/ 做成可配置的外部资源目录 (环境变量 / 配置文件)⇒ 改配置面 + 改启动装配。 D12 的原话:技能化本批不做,阻塞在分发形态 ⇒ 技能化与分发形态一起单独立项。

当前的规避办法:

# 办法 1:就地跑(仓库根目录)
PORT=30000 ./target/debug/tdc-connector        # ✅ static/ 就在旁边

# 办法 2:把 static/ 拷到二进制的上一级
cp -R static/ ../                                 # 下一个目录有 static/ 即可

核对方式:

grep -n "resolve_project_dir" src/main.rs
# 起服务后确认前端在
curl -s --noproxy '*' -o /dev/null -w '%{http_code}\n' http://127.0.0.1:30000/    # 期望 200

将来立项时要定的:

  1. 静态资源是打进二进制还是外部目录?
  2. 若外部 ⇒ 配置面放哪(环境变量 / 同目录 tdc-connector.toml / 首个 CLI 参数)?
  3. 版本不匹配怎么防(前端 index.html 的 build id vs 后端 protocolVersion)?
  4. 与技能化(SKILL.md + 三处软链 + 「仓根即技能」)一起设计 —— 否则技能装到 ~/.agents/skills/ 后 static/ 又定位不到了。

L7 · 单段尾的动作端点不会 404(被通用详情路由吞掉)

现象:L5 那 109 条动作端点里,有 26 条(★)的路径形状是 /{Entity}/{action}(恰好一个尾段)—— 比如 PolicyTemplate/Options、 Datasource/Types、Resource/Enabled、Product/Catalog。

本仓的通用 CRUD 引擎给每个实体都注册了详情路由:

// src/tdc/controller/crud.rs:65-93
.route(&format!("{}/{{id}}", s.path),
       get(/* detail */).put(/* update */).delete(/* delete */))

⇒ GET /api/ssw/tdc/PolicyTemplate/Options 先被这条路由匹配上 ({id} = 字面量 "Options")⇒ 请求根本走不到 404 ⇒ 进详情处理器 ⇒ 按 f_id = 'Options' 查库 ⇒ 查不到 ⇒ 返回业务失败。

实测行为(26 条逐条打,零偏差):

方法 条数 实测响应
GET 13 HTTP 200 + {"code":400,"msg":"记录不存在或已删除","data":null}
POST 13 HTTP 405 + {"code":405,"msg":"方法不被允许"}({id} 上没注册 POST)

⇒ 🔴 只判 HTTP 状态码会把这 26 条误判成「成功」或「方法错」 —— 这正是 CLAUDE.md 那条红线「业务错误必须读 body 的 code」的现实案例。 ⇒ 剩下 83 条(≥2 尾段,如 Contract/{id}/Negotiate)才是真 404。

上游前端的实际观感(B5 浏览器验收实测):

页面 上游前端调的端点 本仓返回 观感
/tdc/products GET PolicyTemplate/Options 200 + code:400 下拉框空(不是报错页)
/tdc/products GET Resource/Enabled 200 + code:400 同上
/tdc/datasources GET Datasource/Types 200 + code:400 同上
/tdc/delivery GET DeliveryTask/EngineSelfCheck 200 + code:400 引擎自检块空

⇒ 页面不崩,只是下拉项为空 ⇒ 从浏览器上看不出「端点没实现」, 只能从网络面板里看到那个 code:400。这比 404 更难被发现 ⇒ 记账在此。

为什么不修(本批不修的理由):

  • 「让这 26 条真 404」需要把通用详情路由从 /{Entity}/{id} 改成先判字面量动作名 ⇒ 违反 v3 spec C3「引擎必须实体无关(零 match api_name)」—— 除非引入一张「保留字 = 动作名」的全局表(不是实体专属),复杂度与收益不匹配。
  • 「把这 26 条真实现」属 L5 的后续批次(动作端点分批实现)。

核对方式:

# 26 条形态 A 的清单
python3 scripts/upstream-action-census.py | sed -n '/形态 A 明细/,$p'

# 实测其中一条(注意:HTTP 是 200,业务码才是失败)
curl -s --noproxy '*' -H "X-Internal-Token: $SSW_INTERNAL_TOKEN" \
  http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate/Options
# ⇒ {"code":400,"msg":"记录不存在或已删除","data":null}