把 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]>
11 KiB
11 KiB
决策记录(decisions)
🔴 本文件是为什么这么定的唯一去处:每条 = 编号 / 决策 / 取值 / 代码落点 / 来源。 规格原文见
docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md§12(D1–D16 的全文在那边)。 与docs/contract.md(对外形状)/docs/known-limitations.md(已知偏差)配套读。「代码落点」列给的是本仓里实现该决策的
文件:行号⇒ 抽查任意一条都能直接跳过去核对。
索引(按批次)
| 批次 | 决策 |
|---|---|
| B0(拍板) | D1–D12 |
| B1b(搬家) | D13 / D14 / D17 / D18 |
| B3(子表) | D19 |
| B4(账号层) | D15 / D16 / D20 / D21 |
| B5(文档层) | D10 / D12 的兑现 |
决策表
| # | 决策 | 取值 | 代码落点 | 来源 |
|---|---|---|---|---|
| D1 | 前端 | 继续用上游 Vue SPA(不做面 B) | static/(构建产物)· src/platform/fallback.rs:120(spa_fallback 托管) |
用户拍板 |
| D2 | 业务边界 | 与上游一致,分批,本批只做底座 | src/tdc/(18 实体 + 10 TDS 端点) |
用户拍板 |
| D3 | 业务包 MVC | 对位上游包结构 + 保留通用引擎 | src/tdc/{entity,mapper,service,controller,client}/ · src/platform/ |
用户拍板 |
| D4 | 库 | 单库 | src/platform/db.rs(pglite 单 backend)+ src/platform/state.rs(process_db_lock) |
用户拍板 |
| D5 | 账号层 | 一步切 base_user(官方双 md5) |
src/tdc/service/account.rs:124(official_password_hash)· schema/migrate.sql(base_user) |
用户拍板 |
| D6 | 权限 | 按上游(角色码 + 管理员位,删 18 键) | src/tdc/service/account.rs:289(is_administrator)· src/tdc/service/account.rs:320(role_codes) |
用户拍板 |
| D7 | 面 B / perm-smoke-jnpf.sh |
不做 | (无实现) | 由 D1 推导 |
| D8 | 存量 accounts.json 账号 |
不导入(D5 推导;文件保留不删) | src/main.rs:148(data/accounts.json 保留但不读) |
由 D5 推导 |
| D9 | tdsReadOnly |
判据在、种子不种(照抄上游不一致) | src/tdc/service/account.rs:53(ROLE_CODES 判据含它)· :56(SEED_ROLES 种子不含它) |
spec §4.1 |
| D10 | 借技能的工程化外壳,不借契约层 | 分层 / 尺子 / 文档 / 手册可借;契约层一律不借(面 A·面 B · 600/602 信封 · base_module 菜单 · 复合主键) |
本仓形状 = src/platform/envelope.rs:27(HTTP 200 + {code,msg,data})⇒ 无 600/602 鉴权信封 |
2026-10-26 对标技能 ssw-jnpf-lite-rust |
| D11 | 权限宽严维持追平上游 = 显式敞开 + 显式记账 | 不收紧为 fail-closed(会造出与上游不一致的新偏差) | src/platform/auth.rs:243(require_menu_permission = 内部令牌 或 有登录态) |
spec §5.2 / §5.4 |
| D12 | 技能化本批不做 | 阻塞在分发形态(static/ 定位依赖 current_exe() 向上找)⇒ 先做文档层(B5) |
src/main.rs:43(resolve_project_dir 从可执行文件向上找 static/index.html) |
spec §0.4 / §11.3 |
| D13 | B1 拆成 B1a(尺子先行)+ B1b(搬家 + 边界收敛) | cargo test 不覆盖 HTTP 层 ⇒ 无尺子不搬家;B1a 先锁基线断言数 N,B1b 后必须 == N |
scripts/smoke.sh(N=75 ⇒ B4 后 N=80) |
spec §2.4 / §8 |
| D14 | codec.rs 归业务层 tdc/util/code.rs |
它是业务编码生成器(PRO/RES/API/DS),不是序列化 codec;ids.rs 留平台层 |
src/tdc/util/code.rs:37(day_prefix)· :58(format_code)· src/platform/ids.rs:119(next_id) |
spec §2.1 |
| D15 | tdc_identity 双读写路径显式承认 + 收口 + 记账 |
不硬收进引擎(上游无「通用引擎」概念)⇒ 领域 SQL 收进 src/tdc/service/identity.rs、只 SELECT 明确列、记进 docs/known-limitations.md L1 |
src/tdc/service/identity.rs(领域路径)· src/tdc/service/crud.rs:207(引擎路径) |
spec §2.3.1 C10 / S8 |
| D16 | numeric 列输出 JSON 数字(不是 JSON 字符串) | 上游 ProductEntity.java:88 的 BigDecimal 只带 @TableField(无 @JsonSerialize)⇒ Jackson 默认 ⇒ 数字 |
src/tdc/mapper.rs(row_to_json_spec 不做字符串化)· src/tdc/entity/product.rs |
2026-10-26 B1a 复核上游取证链 |
| D17 | 鉴权白名单按实际清单剪 9 条(不是 spec 预估的 7 条) | 上游 gateway.white-url 里 P2P 是 5 条(不是 4)⇒ 实际死路径 9 条 ⇒ 本仓照抄实际清单,账本逐条记明 |
src/tdc/support/public_paths.rs:51(all_public_paths) |
2026-10-26 B1b C5 |
| D18 | 时间口径 = 两套,各自绑定上游对照物 | C12 的「口径统一为 UTC」若全仓执行 ⇒ 业务编码与 DB 审计列从服务器本地时区变 UTC ⇒ ①违反 B1b「行为零变化」②产生新的对上游偏差(上游 TdcCodeUtil 用 LocalDateTime.now()、审计列用 MySQL now(),都是服务器本地;跨零点的 8 小时里编码日期段直接差一天)⇒ 不做全仓 UTC。落地口径:① 仓里不再手写日历算法,一律 chrono;② 账号库自有审计字段 = UTC(本仓自有格式、无上游对照物;替换实现时保持原值 ⇒ 零行为变化);③ 业务编码与 DB 审计列 = 服务器本地时区(有上游对照物 ⇒ 必须同口径)。对照表写在 docs/contract.md §时间口径 |
① src/tdc/util/code.rs:38(day_prefix_at(prefix, Local::now()) = 服务器本地)· ② src/tdc/service/account.rs:257 起的账号审计列 = UTC |
2026-10-26 B1b C12(复核上游 TdcCodeUtil.java) |
| D19 | 子表挂载面逐父子不同(Aggregate / Detail / List 三面) |
上游口径不是「子表都挂详情」:Resource/Dataset 的子表只在 /Detail 聚合体(普通详情不带);DataInterface 的子表只在普通详情(上游覆写了基类详情,且没有 /Detail 路由);DeliveryTask 的参与方挂详情与列表(decorate 批量挂)。⇒ 子表声明从 (key, table) 二元组升级为 ChildTable 结构(外键列 / 父行取值列 / 排序列 / 存活谓词 / 挂载面),引擎仍零 match api_name(只认列名)。outbox 是本仓扩展(上游不挂,但 local_task_id = 任务 f_id ⇒ 货真价实的子表);tdc_demo_car_insurance 挂不了(无父外键 ⇒ 记为已知限制 L3) |
src/tdc/entity/mod.rs:60(ChildMount)· :74(ChildTable)· :164(children_on)· src/tdc/entity/resource.rs:34(Resource 挂 Aggregate 面)· src/tdc/entity/delivery_task.rs |
2026-10-26 B3(复核上游 ResourceServiceImpl#withChildren / DataInterfaceController#detail / DeliveryTaskController#decorate) |
| D20 | 账号层切 base_user + 官方双 md5 公式 + 删掉 18 键假权限层 |
① 载体:data/accounts.json → base_user 表(JSON 文件保留不删,但后端不再读取 ⇒ 存量账号不导入,D8);② 口令:入库用官方公式 f_password = md5(lower(md5(明文)) + lower(f_secretkey)),f_secretkey 每账号随机(UUID v4 大写),改密不换 secretkey(与官方一致);③ 引导:base_user 无存活行时种一个管理员(f_is_administrator=1),幂等;base_role 逐字照抄上游 V1.0.1__connector_seed.sql 的三行(tdcProvider/tdcConsumer/user),管理员绑 user 角色;④ 管理员判据 = f_is_administrator=1,查询异常 ⇒ false(fail-closed);⑤ 删掉 18 条实体→权限键(entity::PERMISSION_KEYS + identity::capabilities() + crud::require_write_permission())—— 那层「解析不出 ⇒ fail-open」从来就没在管,留着只是看起来在管 ⇒ 拆掉并显式记账(L4);⑥ 不收紧为 fail-closed(D11)⇒ 写操作改用上游同款 require_menu_permission()(内部令牌 或 有登录态) |
① src/tdc/service/account.rs:621(bootstrap_account_layer)· src/main.rs:148(JSON 不再读);② src/tdc/service/account.rs:124(official_password_hash)· :137(new_j7_id)· :576(reset_password 不换 secretkey);③ src/tdc/service/account.rs:56(SEED_ROLES)· src/tdc/constant.rs:21(默认口令);④ src/tdc/service/account.rs:289(is_administrator fail-closed);⑤ src/tdc/service/crud.rs:515/662/763(三个写路径)· src/platform/auth.rs:243;⑥ src/tdc/controller/account.rs:149(require_admin) |
2026-10-26 B4(复核上游 PasswordTokenGranter.java:186 / AuthController#me:207 / TdcCrudController.java:133) |
| D21 | 角色码暴露在 /Auth/Me 的 roles 键 + 保留 require_menu_permission 登录态闸门 |
① 上游 AuthController#me:207 有 data.put("roles", roles) ⇒ 本仓 me_payload 加 roles 键(出参新增一个键,形状其余不变);角色码判据逐字照抄上游 SQL(IN ('tdcProvider','tdcConsumer','tdsReadOnly'))⇒ 只对账号会话算(上游只有门户登录这一路算角色),身份会话返回空数组;② 写操作的门禁换成 platform::auth::require_menu_permission(已在 list/all/detail/aggregate_detail 用着)⇒ 四个读写面同一个闸门,与上游 requireMenuPermission() 同构;③ D9 的悬空码照抄 ⇒ 引导管理员绑 user 角色 ⇒ 它的 roles 是空数组(上游同口径,不是 bug) |
① src/tdc/service/identity.rs:360(me_payload(…, roles) 出 roles 键)· :311(me)· src/tdc/service/account.rs:320(role_codes 逐字上游 SQL);② src/tdc/service/crud.rs:207/276/461/822(四个读面)· :515/662/763(三个写面)—— 七个面同一个闸门;③ src/tdc/service/account.rs:56(SEED_ROLES) |
2026-10-26 B4 |
补记说明
- D1–D16 的完整措辞(含来源链)在 v3 spec §12;本表只留一行摘要,方便日常查。
- D17–D21 是 v3 spec 落点(
06f5a79)之后、执行中追加的决策 ⇒ 只住本文件。 - D18 是本轮唯一一处「与执行提示词冲突」:提示词要求「口径统一为 UTC」,v3 spec §2.3.1 C12 也写了 UTC, 但全仓 UTC 会引入对上游的新偏差(上游用服务器本地时区)⇒ 按「spec 与提示词冲突时 spec 优先」的规则, v3 spec 赢,但 spec 的「全仓 UTC」与它自己的「B1b 行为零变化」原则冲突 ⇒ 采纳两套口径并显式记账。 这是本轮需要拍板人知晓的偏离点(最终报告里也会单列)。