**影响** - 生产档弱密钥守卫从「只比默认值」升级为上游 `ProdGuard` 的**六条判据**(纯函数), 弱令牌用「默认值加后缀」绕过、弱标记词、长度下限三类都拦得住;`CIPHER_KEY`(协议共享值)**不受管**。 - 出向 TDS 超时**外置到 env**(`SSW_TDS_CONNECT_TIMEOUT_MS` / `SSW_TDS_READ_TIMEOUT_MS`), 且**只有 cause 链里真有超时**才改写文案 ⇒ 连接被拒 / DNS 失败不再被误报成「超时」(排查方向不被带偏)。 - 上游 15 个测试类全部**登记在册**:3 个已移植(29 条对位用例)、12 个判定超范围(逐条记理由)。 - 新增第五把尺子 `scripts/check-upstream-tests.sh`:台账 ⇄ 代码 ⇄ 上游测试类集合三向对账, 上游新增测试类而台账没登记 ⇒ **红**(不靠"记得看"防漂移)。 - 回归网:`cargo test` 246 → **278**(+32),其余四把尺子与引用自检**全绿**。 **改动** - `src/platform/guard.rs`(新):上游 `ProdGuard.violations` 的纯函数移植(弱值清单 / 弱标记词整体词匹配 / `MIN_LEN=12` / 逐条点名)。 - `src/platform/config.rs`:`check_secret_guard` 改走守卫判据;新增 `guard_values`(只放本部署真有的键) 与出向超时两项配置(非法值回落默认,不让连接器起不来)。 - `src/tdc/client/tds.rs`:新增 `cause_chain_has_timeout` / `timeout_text_or_null`(cause 链遍历**有界** `depth<16`), `TdsClient::with_timeouts` 接受超时。 - `tests/upstream_guard_parity.rs`(新 · 19 条)+ `tests/upstream_tds_timeout_parity.rs`(新 · 10 条)。 - `scripts/upstream-test-ledger.tsv`(台账真源)+ `scripts/upstream-test-census.py`(上游测试类普查/对账) + `scripts/check-upstream-tests.sh`(第五把尺子)。 - 文档:`docs/UPSTREAM-TEST-PARITY.md`(新)+ `docs/known-limitations.md` L8 + `docs/decisions.md` D22/D23 + `CLAUDE.md` 同步(尺子表 / 目录树 / 命令速查 / 实现细节 22–23 / 坑位表)。 **设计** - 上游 hop 1 的「反射读 socket 工厂」**抄不了**(`reqwest::Client` 不暴露超时 getter)⇒ 改用**行为级**判别 (同一延迟 TCP 服务器:短超时⇒超时错、长超时⇒成功)⇒ 结论等价且更强(真跑 socket 层)。 - 上游 `*SelfTest.java` **surefire 不跑**(无统一入口)⇒ 判据落成 `cargo test` 常规用例(纯函数 ⇒ 可离线断言)。 - 超范围判定原则:**本仓没有对应功能 ⇒ 不搬**(硬搬只会是假绿);「机制」已覆盖的(P2P 那条)按机制记账。 Co-Authored-By: Claude Code <[email protected]>
64 lines
14 KiB
Markdown
64 lines
14 KiB
Markdown
# 决策记录(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 的兑现 |
|
||
| 上游对齐(测试移植) | D22 / D23 |
|
||
|
||
---
|
||
|
||
## 决策表
|
||
|
||
| # | 决策 | 取值 | 代码落点 | 来源 |
|
||
|---|---|---|---|---|
|
||
| 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 |
|
||
| **D22** | **生产档弱密钥守卫升级为上游 `ProdGuard` 的六条判据**(本仓原来只有「默认口令即不安全」这一条) | ① **判据纯函数化**:上游把判据抽成 `ProdGuard.violations(map)`(纯函数,不读 Spring)⇒ 本仓落成 `platform::guard::guard_violations(map)`,不读进程全局 env ⇒ 可离线逐组断言;② **六条判据缺一不可**:①键不在 map⇒跳过 ②值为 null/空白⇒违规 ③值精确等于弱值⇒违规 ④值**含**弱值⇒违规(**反绕过**:默认值加个后缀也拦住)⑤值命中弱标记词⇒违规 ⑥长度<12⇒违规;③ 与 ④ **分开报错**(照抄上游);③ **双令牌都受管**(上游一个 `ssw.internal-token` 双向通用 ⇒ 本仓拆成入向 `SSW_INTERNAL_TOKEN` / 出向 `SSW_TDS_INTERNAL_TOKEN` ⇒ 两个都受管;出向令牌**仅在配了 `SSW_TDS_BASE_URL` 时**才进守卫 ⇒ 本地单机模式不会被误停);④ **`CIPHER_KEY` 不受管**(上游 chg_0020 已把 `security.security-key` 移出受管清单 —— 那是**协议共享值**,必须发给浏览器 ⇒ 本仓的 `CIPHER_KEY` 同款裁定,否则"保持默认同值"这种正常部署会被判红);⑤ **弱标记词按整体词匹配**(上游正则 `(?i)(^|[\-_.])(…)([\-_.]|$)` ⇒ 手写等价实现,不引 regex 依赖) | `src/platform/guard.rs:134`(`guard_violations`)· `:101`(`has_weak_marker`)· `:188`(`violation_message`)· `:46`(`WEAK_VALUES`)· `:77`(`GUARDED`)· `src/platform/config.rs:247`(`check_secret_guard`)· `:261`(`guard_values`) | 2026-10-27(复核上游 `ProdGuard.java:119` / `ProdGuardSelfTest.java`) |
|
||
| **D23** | **出向 TDS 超时外置到 env + 照抄上游的 cause 链超时分类** | ① **超时值外置**:`SSW_TDS_CONNECT_TIMEOUT_MS`(默认 3000)/ `SSW_TDS_READ_TIMEOUT_MS`(默认 5000)⇒ 上游把超时当**可配项**(不同对端网络条件不同),本仓原来**写死在代码里**;② **cause 链分类**(照抄上游 `ProviderInvokeTimeoutsSelfTest` 第 2 跳):**只有** cause 链里存在超时(`reqwest::Error::is_timeout()` 或 `io::ErrorKind::TimedOut`)才把文案改写成「调用 TDS 超时(当前 connect=…ms / read=…ms,可用 … 调大)」;**连接被拒 / DNS 失败 / 无 cause ⇒ 不改写**(仍是「TDS 不可达」)——🔴 **把连接被拒说成"超时"会把排查引向错误方向**(改超时没用,要改网络/证书);③ **cause 链有界**(`depth < 16`,照抄上游)⇒ 多层包装仍能命中,但环状链不死循环;④ **不引 regex**:弱值/弱标记词判据手写(见 D22) | `src/tdc/client/tds.rs:74`(`cause_chain_has_timeout`)· `:112`(`timeout_text_or_null`)· `:29`(`MAX_CAUSE_DEPTH=16`)· `:171`(`with_timeouts`)· `src/platform/config.rs:130`(`timeout_ms_from`)· `:189`(读 env) | 2026-10-27(复核上游 `ProviderInvokeTimeoutsSelfTest.java`) |
|
||
|
||
---
|
||
|
||
## 补记说明
|
||
|
||
- **D1–D16** 的完整措辞(含来源链)在 v3 spec §12;本表只留一行摘要,方便日常查。
|
||
- **D17–D21** 是 v3 spec 落点(`06f5a79`)之后、执行中追加的决策 ⇒ 只住本文件。
|
||
- **D22–D23** 是「上游测试用例移植」批次追加的决策(守卫语义升级 / 出向超时外置)⇒ 只住本文件;
|
||
对应的上游真源与逐条对照见 [`UPSTREAM-TEST-PARITY.md`](UPSTREAM-TEST-PARITY.md)。
|
||
- **D18 是本轮唯一一处「与执行提示词冲突」**:提示词要求「口径统一为 UTC」,v3 spec §2.3.1 C12 也写了 UTC,
|
||
但**全仓 UTC 会引入对上游的新偏差**(上游用服务器本地时区)⇒ 按「spec 与提示词冲突时 spec 优先」的规则,
|
||
**v3 spec 赢**,但 spec 的「全仓 UTC」与它自己的「B1b 行为零变化」原则冲突 ⇒ 采纳**两套口径**并显式记账。
|
||
**这是本轮需要拍板人知晓的偏离点**(最终报告里也会单列)。
|