Files
tdc-rs/docs/CONSOLE-ACCEPTANCE.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 Permalink Blame History

上游控制台 · 浏览器级验收(R3 · B5 重跑版)

日期:2026-10-27(B5 重跑;初版 2026-10-25 = B4 之前,账号层实现已换) 被测物:本仓 tdc-connector(debug 构建,:30000)+ static/ 里的上游完整前端构建产物 (VITE_SSW_APP=tdc) 驱动:aix(xstudio 内核 CDP 浏览器,http://127.0.0.1:19999) 结论:17 个 SPA 路由逐个点过 —— 全部页面渲染出内容、无白屏、无 JS 崩; 登录 / 鉴权 / 写路径 / 管理员闸门 / 逻辑删除 全部按上游预期工作。 🔴 但「HTTP 全 200」不等于「全成功」 —— 本次重跑逐条读 body 的 code, 揪出 5 个 HTTP 200 却业务失败的端点(见 §2 的「业务码」列与 §7)。

本文件是实测记录,不是设计说明。命令与结论都可复现。


1. 怎么复现

# ① 起连接器(首启会打印一次性 secretKey —— 不要把 stdout 落进文件或报告)
PORT=30000 ./target/debug/tdc-connector

# ② 起浏览器内核(幂等;健康检查 /health 的 ok:true 即就绪)
bash /Users/xs/Documents/x/xstudio/source/scripts/xstudio-up.sh
export AGENTX_XSTUDIO_BASE=http://127.0.0.1:19999

# ③ 走查
aix open http://127.0.0.1:30000/          # ⇒ 跳 /login?next=/tdc/home
aix snapshot -i                            # 拿 @eN(账号 / 口令 / 登录按钮)
aix fill @e41 admin && aix fill @e42 admin && aix click @e44

🔴 本机 curl 测 localhost 必须加 --noproxy '*',否则被系统代理劫持成 502。 🔴 页面里的 API 基址是同源相对路径 /api(axios.create({baseURL:"/api"})), 所以「静态托管 + API 同端口」是上游前端能跑的前提。


2. 逐页结果

17 条路由全部渲染出页面(h1 标题 + 表格壳),没有白屏、没有崩溃。

🔴 「业务码」列是本次重跑新增的 —— 初版只记了 HTTP 状态, 而上游 TDS 侧的失败也是 HTTP 200 ⇒ 只看状态码会把失败当成功。 本列 = 响应体里的 code(200 = 成功;400 = 业务失败)。

路由 页面标题 页面发出的后端调用 HTTP 业务码 结果
/tdc/home 工作台 —(首页数字是上游自带的示例占位值) — — ✅
/tdc/identity 连接器身份 Auth/Me、Identity?currentPage=1&pageSize=10、Identity?pageSize=1 200 200 ✅ 表里真的有 LOCAL-CONNECTOR / 本地连接器
/tdc/credentials 身份认证授权 Credential?currentPage=1&pageSize=10 200 200 ✅
/tdc/audit-local 本地审计日志 AuditLog?currentPage=1&pageSize=10 200 200 ✅
/tdc/mask-destroy 数据销毁 DestroyLog?currentPage=1&pageSize=10 200 200 ✅
/tdc/products 数据产品 Auth/Me、Auth/Spaces、Identity?pageSize=100、Product?currentPage=1&pageSize=20、PolicyTemplate/Options、Resource/Enabled 200 200 ×4 ·400 ×2 ⚠️ 两个下拉项空(Options / Enabled 被吞掉,见 §7.1)
/tdc/policy-templates 策略模板 PolicyTemplate?currentPage=1&pageSize=10 200 200 ✅
/tdc/contracts 合约副本 Contract?currentPage=1&pageSize=10 200 200 ✅
/tdc/service-catalog 服务目录 ServiceCatalog?currentPage=1&pageSize=20 200 400 ⚠️ 连接器身份未绑定空间(P4 端点已实现,卡在身份闸门,见 §4)
/tdc/delivery 数据交付 DeliveryTask?currentPage=1&pageSize=10、DeliveryTask?pageSize=1、DeliveryTask/EngineSelfCheck?force=false 200 200 ×2 ·400 ×1 ⚠️ 列表 ✅;引擎自检块空(被吞掉,见 §7.1)
/tdc/demand-order 订单管理 Order?currentPage=1&pageSize=10 200 200 ✅
/tdc/billing 我的账单 Billing/List?currentPage=1&pageSize=10 200 400 ⚠️ 无法确定连接器身份(P4 端点已实现,卡在身份闸门,见 §4)
/tdc/datasources 本地数据源 Datasource?currentPage=1&pageSize=10、Datasource/Types 200 200 ·400 ✅ 列表正常;类型下拉空(被吞掉);写路径实测通过(§3.3)
/tdc/data-interfaces 数据接口 DataInterface?currentPage=1&pageSize=20 200 200 ✅
/tdc/resources 数据资源 Resource?currentPage=1&pageSize=10 200 200 ✅
/tdc/datasets 数据集 Dataset?currentPage=1&pageSize=10 200 200 ✅(只读视图,见 §3.5)
/tdc/users 用户管理 permission/Users?currentPage=1&pageSize=10 200 200 ✅ 表里真的有 admin / 管理员(1 行)

没有任何一个页面出现「白屏 / 路由 404 / JS 崩了」。 统计:17 个路由共发出 26 个页面级调用 ⇒ HTTP 全 200;业务码 200 × 20 · 400 × 6。 ⇒ 🔴 那 6 个 400 里 4 个是「端点没实现但被路由吞掉」(§7.1), 2 个是「P4 端点已实现,但连接器身份没绑定 TDS 空间/连接器」(§4)—— 都不是本仓的 bug,但必须显式记账。


3. 关键链路实测

3.1 登录(上游 JNPF 兼容链)

  • 页面:/login?next=/tdc/home,未登录直接访问深链会被弹回登录页(前端路由守卫 ✅)。
  • 填 admin / admin ⇒ POST /api/oauth/Login 200 ⇒ 跳 /tdc/home。
    • 走的是上游前端自己的 cipher.ts:口令在浏览器里被加密成 AES-256-ECB 的 hex 才发出去 ⇒ 这条链同时验了「密文契约」与「账号库」,不依赖本仓的自造向量。
  • 令牌落在 localStorage['ssw_token_sswflow'](32 位 hex,不带 bearer 前缀 —— 前缀由前端 setToken 自己补)。
  • 后续请求带 Authorization: bearer <token> ⇒ Auth/Me 200、accessAllowed: true。

3.2 鉴权失败的形状(契约核对)

无凭证访问受保护端点 ⇒ HTTP 401 + 裸三字段:

{"code":401,"msg":"内部接口凭证无效","success":false}

没有 data 键 ✅ —— 与 README「业务失败 200 + {code,msg,data} / 鉴权失败 401 + 裸三字段」 的约定一致;前端据此跳登录页而不是把失败当成功。

3.3 写路径(浏览器里真的建了一条数据源)

在 /tdc/datasources 点「新建」填表(名称 / 类型 POSTGRESQL / 主机 / 端口 / 库名 / 归属部门 / 备注):

POST /api/ssw/tdc/Datasource            200   ⇒ toast「新增成功」⇒ 抽屉自动关闭 ⇒ 列表自动刷新
GET  /api/ssw/tdc/Datasource?…          200

表格里那一行确实带上了提交的每个字段:

DS-20261025-PBRRK6 | R3-浏览器验收数据源 | POSTGRESQL | 127.0.0.1 | 5432 | r3_probe | … | R3验收 | 启用

(DS-20261025-xxxxxx 是本仓生成的标识,不是上游的格式 —— 上游这一列是给人看的 f_data_source_code,值由后端生成。)

3.4 逻辑删除(用浏览器自己那张令牌)

拿 localStorage 里那张会话令牌调 DELETE /api/ssw/tdc/Datasource/{id} ⇒ HTTP 200 {"code":200,"msg":"删除成功"} ⇒ 再查列表 total=0 ⇒ 刷新页面表格回到 「No data」。⇒ 逻辑删除 + 列表过滤在浏览器这一侧是自洽的。

3.5 只读分档与上游 UI 天然对齐

页面 上游 UI 给的写入口 本仓 src/tdc/entity/mod.rs 分档 对齐?
/tdc/datasets 无「新建」按钮(只有 查询/刷新/重置) Dataset 禁增/改/删(tdc_resource 的只读视图) ✅
/tdc/audit-local 无「新建」(另有「哈希链完整性校验」) AuditLog 禁改禁删、可增 ✅(上游更严,多出来的能力点不到)
/tdc/delivery 「发起交付」「引擎自检」,无新建 DeliveryTask 禁增禁删、可改 ✅
/tdc/mask-destroy 无新建 DestroyLog 禁增禁删、可改 ✅
/tdc/contracts 无新建 Contract 禁删、可增可改 ✅(上游更严)
/tdc/resources 新建 Resource 可增 ✅
/tdc/users 新建 账号层可增 ✅

⇒ 只读实体在控制台里根本点不出「新建」按钮,所以「禁增」分档不会在 UI 上变成一条 红色报错。

3.6 管理员闸门(负向用例)

浏览器里建了一个非管理员账号 r3probe(默认口令 123456):

  1. POST /api/permission/Users 200「新增成功」⇒ 列表里出现 r3probe / R3探针。
  2. 清掉 localStorage 后用 r3probe / 123456 登录 ⇒ 登录成功(非管理员也能登进控制台)。
  3. 打开 /tdc/users ⇒ GET /api/permission/Users ⇒ 403 ⇒ toast 「仅管理员可管理连接器用户」 ⇒ 表格空(No data)。

⇒ 账号分层(管理员 / 子账号)在浏览器这一层是生效的,不是只在单测里。

3.7 顺手核对到的契约事实

  • 上游 cipher.ts 的自检向量(encryptPassword('123456'))在 Node 里复算一致 ⇒ 本仓 src/platform/cipher.rs 的密钥/编码与上游逐字对齐。
  • 前端 axios 实例是 baseURL: "/api"(相对)⇒ 后端必须与静态产物同源同端口。
  • 未知 /api/** 命中的是页面级 404 + JSON,前端因此显示「接口不存在」而不是把 HTML 当成功数据渲染(见 README「控制台(前端)」小节)。

4. 服务目录 / 我的账单:已实现(P4),当前卡在连接器身份解析

⚠️ 本节是 B5 重跑时改写的 —— 初版(2026-10-25)记的是「404,TDS 代理页」, 那是 P4 出向通道还没落地时的状态。P4 之后这两个端点已实现, 现在是 HTTP 200 + code:400,但不是 TDS NOOP 降级 —— 失败发生在「解析连接器身份」这一步,还没走到出向 TDS。

读上游 boot/ssw-tdc/…/controller/:

  • ServiceCatalogController:GET /api/ssw/tdc/ServiceCatalog → 走 tdsReportClient.catalogSearch(...) / internalCatalog(...) —— 跨服务代理 TDS 的目录查询, 本地无表。
  • BillingController:GET /api/ssw/tdc/Billing/List → tdsReportClient.listBillingForConnector(...) —— 账单在 TDS 侧。

⇒ 本仓照抄了上游这两个控制器(出向 internal 通道,固定 6 个应用层头)。 两个端点都要先解析本端的连接器身份(上游同款前置闸门):

端点 闸门 本仓实现 实测响应
GET /ServiceCatalog 要身份的 f_tds_space_id(空间) src/tdc/controller/tds_biz.rs:262 200 {"code":400,"msg":"连接器未绑定空间,目录不可用"}
GET /Billing/List 要身份的 f_tds_connector_id(连接器;可显式传 connectorId 覆盖) src/tdc/controller/tds_biz.rs:341 200 {"code":400,"msg":"无法确定连接器身份(固定身份不可用或未显式传入)"}

🔴 根因:本仓引导出来的本地连接器身份(LOCAL-CONNECTOR)没有绑定 TDS 空间/连接器 (tdc_identity.f_tds_space_id / f_tds_connector_id 两列存在但为空 —— src/tdc/service/identity.rs:474 只读不写)⇒ 两个端点在出向之前就 fail-closed 了。

⇒ 这是上游同款口径(上游也要求身份先绑定空间/连接器),不是本仓的 bug; 本机没有 TDS ⇒ 这两页注定空。 完整契约(出向路径 / 6 个头 / 三档降级 / 真 TDS 实测表)见 docs/TDC-TDS-CONTRACT.md。

⚠️ 页面观感:服务目录 / 我的账单 的失败不弹 toast(页面自己吞了), 只渲染成空表 ⇒ 从页面看不出「TDS 没接 / 身份没绑定」 ⇒ 排查时先看网络面板里的 code:400 和那句 msg。 要在上游侧统一提示属于前端改动 —— 本仓不自研前端,不动。


5. 踩坑:后台标签页会冻结 CSS transition ⇒ 抽屉看起来「坏在屏幕外」

现象:自动化里点「新建」,抽屉的表单能填、但点不到「保存」: CDP error (Input.dispatchMouseEvent): no element at 1719, 776(坐标在视口外)。

定位(逐层剥):

  1. 抽屉容器有 ant-drawer-open,但 .ant-drawer-content-wrapper 的计算样式是 transform: matrix(1,0,0,1,620,0)(= translateX(100%))⇒ 停在屏幕外。
  2. 它匹配的是 …-panel-motion-right-enter-start 规则 ⇒ motion 卡在 enter 起始态。
  3. 页面 document.visibilityState === "hidden"(内核浏览器在后台标签) ⇒ requestAnimationFrame 与 CSS transition 全部冻结。
  4. 铁证:给页面注入 *{transition:none !important} 后,抽屉立刻回到 x=1780(视口内)。

结论:这是测试环境的假象**,不是本仓的缺陷,也不是上游前端的缺陷**(真人可见的浏览器里 transition 正常跑,抽屉正常滑入)。

自动化里怎么绕过(本次验收用的就是这个):

// ① 关掉 transition,让 rc-motion 的 enter 立刻落位
const s = document.createElement('style');
s.textContent = '*{transition:none !important}';
document.head.appendChild(s);
// ② 顺手把卡住的 motion 类摘掉
document.querySelectorAll('[class*=motion]').forEach(e => {
  e.className = e.className.split(' ')
    .filter(c => !c.includes('-motion-') && !c.includes('enter-prepare') && !c.includes('enter-start'))
    .join(' ');
});

同一原因也会让 Popconfirm / Modal 停在动画中途 —— 本次「删除」按钮的二次确认 就因此点不动(Element is covered by …ant-drawer-mask-motion-leave), 那一例改用浏览器自己那张会话令牌直接打 DELETE 完成验证(§3.4)。


6. 遗留 / 边界

  • P4:两个 TDS 代理页(服务目录 / 我的账单)已实现,当前是 TDS NOOP 降级(§4)。
  • 上游那 109 条动作端点(发布 / 下架 / 提交审核 / 策略校验 / 销毁 …)本仓一条未实现, 分期的正常状态;其中 26 条(/{Entity}/{action} 形状)不会 404 ⇒ HTTP 200 + code:400(GET)/ HTTP 405(POST)⇒ 见 §7.1 与 docs/known-limitations.md L5 / L7。
  • /tdc/home 的数字是上游自带的示例占位值(页面自己也写了「本页数字与清单均为示例占位值」), 不是本仓的聚合接口(聚合接口未建)。⇒ 该路由实测不发出任何后端调用。
  • 验收数据已清理:探针账号 r3probe 已删;测试数据源已逻辑删除 (f_delete_mark)—— 库里留着一条墓碑行,属产品语义,不是残留。
  • 浏览器控制台在登录页会报 4 条 Script error.:同源脚本的运行时错误会带真实消息, Script error. 是跨源脚本被浏览器脱敏后的固定文案 ⇒ 来自内核注入的脚本,不是本仓产物 (同源 /assets/* 请求在网络日志里全是 200,没有加载失败的 chunk)。

7. B5 重跑的新发现

7.1 4 个下拉项是空的,而不是报错 —— 端点被通用详情路由吞掉(L7)

现象:/tdc/products 的「策略模板」「已启用资源」两个下拉、 /tdc/datasources 的「数据源类型」下拉、/tdc/delivery 的「引擎自检」块 —— 全是空的,页面不报错、不弹 toast。

根因:这些是上游的动作端点(PolicyTemplate/Options · Resource/Enabled · Datasource/Types · DeliveryTask/EngineSelfCheck),本仓未实现(L5)。 但它们的路径形状是 /{Entity}/{action}(恰好一个尾段)⇒ 被本仓的通用详情路由先匹配上:

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

⇒ GET /api/ssw/tdc/PolicyTemplate/Options 里 {id} = 字面量 "Options" ⇒ 进详情处理器 ⇒ 查库查不到 ⇒ HTTP 200 + code:400(不是 404)。

实测(26 条形态 A 逐条打,零偏差):

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

剩下 83 条(≥2 尾段,如 Contract/{id}/Negotiate)才是真 404。

⇒ 🔴 教训:只判 HTTP 状态码会把那 13 条 GET 误判成「成功」 —— 这正是 CLAUDE.md 那条红线「业务错误必须读 body 的 code」的现实案例。 本次重跑之所以能发现,就是因为逐条读了 body,而不是只看网络面板的状态列。

复算方式:

python3 scripts/upstream-action-census.py          # 109 条(26 形态 A + 83 形态 B)
bash scripts/check-contract.sh                     # 本仓 132 条端点表对账

7.2 上游动作端点的数字口径纠正:111 → 109

初版文档记的「上游 111 条动作端点」口径是错的(grep -rhoE 只抓带参数的映射, 且跨了全部 31 个控制器,含非 CRUD 的 Auth / Billing / Gateway / Portal …)。

正确口径(scripts/upstream-action-census.py):

项 条数
18 个 extends TdcCrudController 控制器自声明的 method-level 映射(含空路径写法) 122
− 重复声明的 CRUD-6 基线(列表 / 创建 / All / {id})—— 本仓已实现 −11
− 只读聚合体 Resource/{id}/Detail · Dataset/{id}/Detail —— 本仓 B3 已实现 −2
= 未实现的动作端点 109
├ 形态 A(/{Entity}/{action})⇒ 被吞掉 ⇒ 200+code:400 / 405 26
└ 形态 B(≥2 尾段)⇒ 真 404 83

⇒ 109 条逐条对运行中的服务打过,零偏差(26/26 符合 200+400·405,83/83 符合 404)。

7.3 走查脚本本身的四个坑(aix)

  1. 🔴 aix network requests 的清单是累积的(不会自动 reset) ⇒ 统计「某页发了哪些调用」必须自己 diff 相邻两次的输出, 否则会把上一页的调用算到下一页头上。
  2. 🔴 同 URL 的 aix open 不刷新(浏览器认为没变)⇒ 走查每条路由前 必须先跳一个空白路径(如 /__blank)再开目标页。
  3. 🔴 上游发令牌的姿势是 Authorization: <localStorage 里那串>, 而那串自带 bearer 前缀(上游 Ci() 存进去时就加了) ⇒ 拿它当 X-Auth-Token 发会 401(本仓只认裸令牌)。
  4. ⚠️ aix eval 里读 localStorage 的值会被安全分类器拦(凭据物化) ⇒ 只读存在性(tokenPresent=yes/no)或让页面自己发请求(把令牌留在页面内)。