refactor(b1b-c10): tdc_identity 领域 SQL 收口到 identity 服务,只 SELECT 明确列

影响:控制器层不再自己拼 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 不会被整行拖进内存。
This commit is contained in:
admin committed 2026-10-26 22:29:04 +08:00
1 parent 49e5fcefe4
commit 3076bdae7a
5 files changed
+111 -41

No files matched your search

+11 -3
View File
@@ -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<TdcState> for AppState`(⇒ axum 里 `State<AppState>` 可用,平台端点不必认识业务类型)。
🔴 `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 每数据目录只允许一个进程)。
+6 -1
View File
@@ -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<AppState>`(靠 `impl FromRef<TdcState> 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(上游无「通用引擎」概念,硬收会失真 ⇒ 显式承认 + 收口)。
## 数据模型
+43
View File
@@ -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
```
+7 -37
View File
@@ -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<String>,
/// `tdc_identity.f_tds_connector_id`(连接器;账单用)。
connector_id: Option<String>,
}
/// 取本端默认身份的 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<String> {
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<String>, local: &LocalIdentity) -> Option<String> {
fn resolve_connector_id_relaxed(explicit: Option<String>, local: &identity::TdsBinding) -> Option<String> {
if let Some(e) = explicit {
if !is_blank(&e) {
return Some(e);
@@ -171,7 +141,7 @@ fn resolve_connector_id_relaxed(explicit: Option<String>, local: &LocalIdentity)
///
/// 只认本端可解析身份;显式 id 与本端**不一致** ⇒ `None`(调用方拒)。
/// 🔴 不沿用宽松口径(那会让调用方自供 id 通过自证)。
fn resolve_connector_id_strict(explicit: Option<String>, local: &LocalIdentity) -> Option<String> {
fn resolve_connector_id_strict(explicit: Option<String>, local: &identity::TdsBinding) -> Option<String> {
let local_id = match local.connector_id.as_ref() {
Some(c) if !is_blank(c) => c.clone(),
_ => return None,
+44
View File
@@ -489,6 +489,50 @@ pub async fn capabilities(state: &TdcState, identity_code: &str) -> Option<Vec<S
}
}
/// 本端默认身份的 **TDS 绑定**(空间 + 连接器)。
///
/// 🔴 **领域 SQL 收口**(v3 spec §2.3.1 C10):`tdc_identity` 的所有领域 SQL
/// 都住在本文件(`tdc/service/identity.rs`)⇒ 控制器层不再自己拼 SQL。
/// 查询**只 SELECT 明确列**,永不 `SELECT *`(避免把密钥列拖进内存)。
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct TdsBinding {
/// `tdc_identity.f_tds_space_id`(空间;服务目录用)。
pub space_id: Option<String>,
/// `tdc_identity.f_tds_connector_id`(连接器;账单用)。
pub connector_id: Option<String>,
}
/// 取本端默认身份的 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<String> {
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::*;