把 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]>
19 KiB
上游控制台 · 浏览器级验收(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/Login200 ⇒ 跳/tdc/home。- 走的是上游前端自己的
cipher.ts:口令在浏览器里被加密成 AES-256-ECB 的 hex 才发出去 ⇒ 这条链同时验了「密文契约」与「账号库」,不依赖本仓的自造向量。
- 走的是上游前端自己的
- 令牌落在
localStorage['ssw_token_sswflow'](32 位 hex,不带bearer前缀 —— 前缀由前端setToken自己补)。 - 后续请求带
Authorization: bearer <token>⇒Auth/Me200、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):
POST /api/permission/Users200「新增成功」⇒ 列表里出现r3probe / R3探针。- 清掉
localStorage后用r3probe/123456登录 ⇒ 登录成功(非管理员也能登进控制台)。 - 打开
/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(坐标在视口外)。
定位(逐层剥):
- 抽屉容器有
ant-drawer-open,但.ant-drawer-content-wrapper的计算样式是transform: matrix(1,0,0,1,620,0)(=translateX(100%))⇒ 停在屏幕外。 - 它匹配的是
…-panel-motion-right-enter-start规则 ⇒ motion 卡在 enter 起始态。 - 页面
document.visibilityState === "hidden"(内核浏览器在后台标签) ⇒requestAnimationFrame与 CSS transition 全部冻结。 - 铁证:给页面注入
*{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.mdL5 / 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)
- 🔴
aix network requests的清单是累积的(不会自动 reset) ⇒ 统计「某页发了哪些调用」必须自己 diff 相邻两次的输出, 否则会把上一页的调用算到下一页头上。 - 🔴 同 URL 的
aix open不刷新(浏览器认为没变)⇒ 走查每条路由前 必须先跳一个空白路径(如/__blank)再开目标页。 - 🔴 上游发令牌的姿势是
Authorization: <localStorage 里那串>, 而那串自带bearer前缀(上游Ci()存进去时就加了) ⇒ 拿它当X-Auth-Token发会 401(本仓只认裸令牌)。 - ⚠️
aix eval里读localStorage的值会被安全分类器拦(凭据物化) ⇒ 只读存在性(tokenPresent=yes/no)或让页面自己发请求(把令牌留在页面内)。