From 3076bdae7ab1d926a4da6feeb2cc5246e3c5c83c Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 26 Oct 2026 22:29:04 +0800 Subject: [PATCH] =?UTF-8?q?refactor(b1b-c10):=20tdc=5Fidentity=20=E9=A2=86?= =?UTF-8?q?=E5=9F=9F=20SQL=20=E6=94=B6=E5=8F=A3=E5=88=B0=20identity=20?= =?UTF-8?q?=E6=9C=8D=E5=8A=A1=EF=BC=8C=E5=8F=AA=20SELECT=20=E6=98=8E?= =?UTF-8?q?=E7=A1=AE=E5=88=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 影响:控制器层不再自己拼 tdc_identity 的 SQL(原先散在 TDS 账单控制器里的 那一条已移入领域服务);对外行为零变化(237 条测试全绿、冒烟断言数仍 75)。 改动: - src/tdc/service/identity.rs:新增 TdsBinding + local_tds_binding() (取本端默认身份的 f_tds_space_id / f_tds_connector_id,SQL 只列明确列) - src/tdc/controller/tds_biz.rs:local_identity() 改为转调领域服务; 两处 resolve_connector_id_* 的入参类型换成 identity::TdsBinding - docs/known-limitations.md(新):记 L1「tdc_identity 双读写路径」 (上游无通用引擎概念,硬收会失真 ⇒ 显式承认 + 收口 + 记账 = 决策 D15) - CLAUDE.md / .workbuddy/memory/2026-10-26.md 同步 设计:领域路径只 SELECT 明确列 ⇒ 密钥列 f_secret_key 不会被整行拖进内存。 --- .workbuddy/memory/2026-10-26.md | 14 ++++++++--- CLAUDE.md | 7 +++++- docs/known-limitations.md | 43 ++++++++++++++++++++++++++++++++ src/tdc/controller/tds_biz.rs | 44 ++++++--------------------------- src/tdc/service/identity.rs | 44 +++++++++++++++++++++++++++++++++ 5 files changed, 111 insertions(+), 41 deletions(-) create mode 100644 docs/known-limitations.md diff --git a/.workbuddy/memory/2026-10-26.md b/.workbuddy/memory/2026-10-26.md index 0fe0173..992306a 100644 --- a/.workbuddy/memory/2026-10-26.md +++ b/.workbuddy/memory/2026-10-26.md @@ -122,7 +122,8 @@ cargo test → exit 0(全绿) | C6 | 「假权限层」拆除清单**先记账**(零代码改动) | `8618465` | | C7 | `/api/health` 补 `baseTables`(W5 契约的账号层表数) | `f8764b2` | | C8 | 配置分家:平台 `Config` 削掉 5 个业务字段,业务配置进 `tdc::config::TdcConfig` | `1797aa0` | -| C9 | 状态分家:平台 `AppState` 只留配置/db/锁/会话,业务态进 `tdc::state::TdcState`(Deref + FromRef) | 本次提交 | +| C9 | 状态分家:平台 `AppState` 只留配置/db/锁/会话,业务态进 `tdc::state::TdcState`(Deref + FromRef) | `49e5fce` | +| C10 | `tdc_identity` 领域 SQL 收进 `tdc::service::identity`(控制器不再自己拼);只 SELECT 明确列 | 本次提交 | **关键决定** @@ -138,6 +139,13 @@ cargo test → exit 0(全绿) **C9 之后的实测**:`cargo test` **237 passed / 0 failed / 1 ignored**(新增 2 条:业务态默认值 + deref 取平台那半)· `smoke.sh` **PASS=75 FAIL=0** · `check-boundary.sh` **exit 0**(CP5 = 新增的第 5 个接触点,平台层零 `use crate::tdc::`)· `check-entity.sh` **PASS=15 FAIL=0**。 +**C10 的做法**:`tdc_identity` 的领域 SQL 全部收进 `src/tdc/service/identity.rs`; +原先散在控制器里的那一条(`tds_biz` 取本端身份的 TDS 绑定)已移成 +`identity::local_tds_binding()`(`TdsBinding{space_id, connector_id}`)⇒ 控制器不再碰 `tdc_identity` 的 SQL。 +领域查询**只 SELECT 明确列**(不 `SELECT *`)⇒ 密钥列不会被整行拖进内存。 +`tdc_identity` 因此**有两条读写路径**(领域 SQL + 通用引擎)⇒ 新建 `docs/known-limitations.md` 记 L1 +(上游无「通用引擎」概念,硬收会失真 ⇒ 显式承认 + 收口 + 记账 = 决策 D15)。 + **C9 的技术选型**:业务层 `TdcState` **deref 到** `platform::state::AppState`(⇒ `state.db` 等字段访问零改动) + `impl FromRef for AppState`(⇒ axum 里 `State` 可用,平台端点不必认识业务类型)。 🔴 `FromRef` 在 **`axum::extract::FromRef`**(`axum::core::extract::FromRef` 不存在)。 @@ -164,8 +172,8 @@ CP1 只查「表名前缀 / 端点前缀」,查不出模块引用 ⇒ 必须 ## 当前状态 - 分支 `feat/mvc-align-v3`;**回退点 = `06f5a79`**(v3 spec 落点)。 -- B1b 已完成 **C1–C9**;下一条 = **C10**(`tdc_identity` 领域 SQL 收口到 `tdc/service/identity.rs` + 只 SELECT 明确列)/ - **C11**(`constant_time_eq` 上收到平台)/ **C12**(`civil_from_days`/`now_iso` 换 `chrono`,口径 **UTC**)。 +- B1b 已完成 **C1–C10**;下一条 = **C11**(`constant_time_eq` 上收到平台)/ + **C12**(`civil_from_days`/`now_iso` 换 `chrono`,口径 **UTC**)。 - B1b 验收:`cargo test` 全绿 + `smoke.sh` 断言数 **== 75** + `check-boundary.sh` 全绿 (**7 条 B1b 账本条目已清空**)+ `check-entity.sh` 全绿 + 浏览器验收重跑(**未重跑** ⇒ B5 前补)。 - ⚠️ **B2 前必须先停掉占着 `data/tdc.pg` 的旧开发服**(pglite 每数据目录只允许一个进程)。 diff --git a/CLAUDE.md b/CLAUDE.md index 9de7cf4..a30cb63 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,7 +65,7 @@ tdc-rs/ │ # + **三把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态) │ # / check-entity.sh(实体静态)+ boundary-ledger.txt / upstream-json-ignore.tsv ├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail / tds_biz) -├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md) +├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md / known-limitations.md) │ # + superpowers/(v3 spec / 执行提示词 / 上游差异表) ├── tds-stub/server.js # TDS 契约桩(零依赖,仅供端到端调试) └── data/ # 运行期数据(tdc.pg/ + accounts.json,已 gitignore) @@ -272,6 +272,11 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 ⇒ `state.db` / `state.db_lock` / `state.sessions` / `state.config` 照旧可用; axum 里想只拿平台那一半 ⇒ `State`(靠 `impl FromRef for AppState`)。 🔴 `FromRef` 在 **`axum::extract::FromRef`**(不是 `axum::core::extract::FromRef`)。 +18. **领域 SQL 归业务服务层**(C10):`tdc_identity` 的领域 SQL **全部住在 + `src/tdc/service/identity.rs`**(控制器层不再自己拼)⇒ 领域查询**只 SELECT 明确列**, + 永不 `SELECT *`(别把 `f_secret_key` 整行拖进内存)。 + 🔴 `tdc_identity` 因此**有两条读写路径**(领域 SQL + 通用 CRUD 引擎)⇒ 已记进 + `docs/known-limitations.md` L1(上游无「通用引擎」概念,硬收会失真 ⇒ 显式承认 + 收口)。 ## 数据模型 diff --git a/docs/known-limitations.md b/docs/known-limitations.md new file mode 100644 index 0000000..4b3e414 --- /dev/null +++ b/docs/known-limitations.md @@ -0,0 +1,43 @@ +# 已知限制(Known Limitations) + +> 本文件记录**本仓与上游的已知差距**,以及**刻意保留的取舍**。 +> 每条都带 `file:line` 引用,便于随时核对是否已过时。 +> 决策背景见 [`decisions.md`](decisions.md),对外契约见 [`contract.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` 字段时,**两条路径都要看一眼**。 + +**复现/核对方式**: + +```bash +# 领域路径的 SQL 全在这一个文件里 +grep -n "SELECT\|INSERT INTO" src/tdc/service/identity.rs +# 引擎路径的 SELECT *(实体无关,按表结构展开) +grep -n "SELECT \*" src/tdc/service/crud.rs +``` diff --git a/src/tdc/controller/tds_biz.rs b/src/tdc/controller/tds_biz.rs index e608473..56b536d 100644 --- a/src/tdc/controller/tds_biz.rs +++ b/src/tdc/controller/tds_biz.rs @@ -25,6 +25,7 @@ use crate::platform::auth::Principal; use crate::tdc::mapper::{param, parse_query, row_to_json}; use crate::platform::db::query_json_params; use crate::platform::envelope::{ActionResult, CODE_SERVER_ERROR}; +use crate::tdc::service::identity; use crate::tdc::state::TdcState; use crate::tdc::client::tds; @@ -89,43 +90,12 @@ where // 身份解析(照抄上游两套口径) // ================================================================== -/// 本端固定身份(≡ 上游 `TdcInstanceContext.resolve()` 的固定实例身份)。 -#[derive(Debug, Clone, Default)] -struct LocalIdentity { - /// `tdc_identity.f_tds_space_id`(空间;目录查询用)。 - space_id: Option, - /// `tdc_identity.f_tds_connector_id`(连接器;账单用)。 - connector_id: Option, -} - /// 取本端默认身份的 TDS 绑定(空间 + 连接器)。 /// -/// 🔴 取**默认身份行**(`f_default_mark` 优先,其次 `f_id` 序)⇒ 与上游「固定实例身份」同口径。 -/// 两列 schema 里**已存在**(`tdc_identity.f_tds_space_id` / `f_tds_connector_id`)。 -async fn local_identity(state: &TdcState) -> LocalIdentity { - let sql = "SELECT f_tds_space_id, f_tds_connector_id FROM tdc_identity \ - WHERE f_delete_mark IS NULL OR f_delete_mark = 0 \ - ORDER BY f_default_mark DESC, f_id LIMIT 1"; - let rows = { - let _g = state.db_lock.lock().await; - query_json_params(state.db.as_ref(), sql, &[]) - .await - .unwrap_or_default() - }; - let row = match rows.first() { - Some(r) => r, - None => return LocalIdentity::default(), - }; - let pick = |k: &str| -> Option { - row.get(k) - .and_then(|v| v.as_str()) - .map(|s| s.trim().to_string()) - .filter(|s| !s.is_empty()) - }; - LocalIdentity { - space_id: pick("f_tds_space_id"), - connector_id: pick("f_tds_connector_id"), - } +/// 🔴 **领域 SQL 归业务服务层**(v3 spec §2.3.1 C10):`tdc_identity` 的查询 +/// 全部收在 `tdc::service::identity` ⇒ 控制器层不再自己拼 SQL。 +async fn local_identity(state: &TdcState) -> identity::TdsBinding { + identity::local_tds_binding(state).await } /// 宽松取字符串(照抄上游 `BillingController.asText`)。 @@ -158,7 +128,7 @@ fn is_blank(s: &str) -> bool { /// /// ⚠️ 上游对**既有**端点(List/Dispute/Receipt/Voucher/LocalCompare)就是这个宽松口径 /// (上游自己标注「既有安全面本批不加固」)⇒ 照抄,差异登记在 spec D1。 -fn resolve_connector_id_relaxed(explicit: Option, local: &LocalIdentity) -> Option { +fn resolve_connector_id_relaxed(explicit: Option, local: &identity::TdsBinding) -> Option { if let Some(e) = explicit { if !is_blank(&e) { return Some(e); @@ -171,7 +141,7 @@ fn resolve_connector_id_relaxed(explicit: Option, local: &LocalIdentity) /// /// 只认本端可解析身份;显式 id 与本端**不一致** ⇒ `None`(调用方拒)。 /// 🔴 不沿用宽松口径(那会让调用方自供 id 通过自证)。 -fn resolve_connector_id_strict(explicit: Option, local: &LocalIdentity) -> Option { +fn resolve_connector_id_strict(explicit: Option, local: &identity::TdsBinding) -> Option { let local_id = match local.connector_id.as_ref() { Some(c) if !is_blank(c) => c.clone(), _ => return None, diff --git a/src/tdc/service/identity.rs b/src/tdc/service/identity.rs index 9ce16f5..70ea2fb 100644 --- a/src/tdc/service/identity.rs +++ b/src/tdc/service/identity.rs @@ -489,6 +489,50 @@ pub async fn capabilities(state: &TdcState, identity_code: &str) -> Option, + /// `tdc_identity.f_tds_connector_id`(连接器;账单用)。 + pub connector_id: Option, +} + +/// 取本端默认身份的 TDS 绑定(≡ 上游 `TdcInstanceContext.resolve()` 的固定实例身份)。 +/// +/// 🔴 取**默认身份行**(`f_default_mark` 优先,其次 `f_id` 序)⇒ 与上游同口径。 +/// 两列 schema 里**已存在**(`tdc_identity.f_tds_space_id` / `f_tds_connector_id`)。 +/// 查不到行 ⇒ 返回**全空**绑定(调用方按「没有绑定」降级,不报错)。 +pub async fn local_tds_binding(state: &TdcState) -> TdsBinding { + let sql = "SELECT f_tds_space_id, f_tds_connector_id FROM tdc_identity \ + WHERE f_delete_mark IS NULL OR f_delete_mark = 0 \ + ORDER BY f_default_mark DESC, f_id LIMIT 1"; + let rows = { + let _g = state.db_lock.lock().await; + query_json_params(state.db.as_ref(), sql, &[]) + .await + .unwrap_or_default() + }; + let row = match rows.first() { + Some(r) => r, + None => return TdsBinding::default(), + }; + let pick = |k: &str| -> Option { + row.get(k) + .and_then(|v| v.as_str()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + }; + TdsBinding { + space_id: pick("f_tds_space_id"), + connector_id: pick("f_tds_connector_id"), + } +} + #[cfg(test)] mod tests { use super::*;