diff --git a/CLAUDE.md b/CLAUDE.md index 9c674ac..0f9a07f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,23 +31,30 @@ tdc-rs/ ├── Cargo.toml # 依赖 + release 优化(lto=thin / strip / panic=abort) ├── Cargo.lock # 锁定版本 ├── src/ -│ ├── main.rs # 启动装配(199 行):PGlite open / 引导身份 / 账号库 / 路由 / 中间件 / 静态兜底 -│ ├── lib.rs # 模块声明(业务逻辑都在 lib 里,bin 只做装配) -│ ├── state.rs # AppState(config + db + db_lock + sessions + accounts + bootstrap + tds) -│ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal) -│ ├── session.rs # 会话存储(两种 kind:Identity / Account) -│ ├── protocol.rs # 协议版本闸门 -│ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data}) -│ ├── registry.rs # 18 实体注册表 + 权限键 + 启动自检 -│ ├── crud.rs # CRUD 引擎(读写路径 + 权限键判定 + 冻结列) -│ ├── db.rs # PGlite 封装(query_json / ensure_schema) -│ ├── codec.rs / ids.rs # 出参 camelCase 编解码 / id 生成 -│ ├── account.rs # 本地账号库(JSON 文件 + Mutex) -│ ├── cipher.rs # 登录口令加解密(MD5 + AES-256-ECB,对齐上游 cipher.ts) -│ ├── config.rs # 环境变量配置 + 密钥守卫 -│ ├── tds/mod.rs # TDS 出向客户端(照抄上游 TdsReportClient 的 internal 通道,9 个方法) -│ ├── domain/identity.rs # 身份引导 / Auth 端点 / 能力集 -│ └── routes/ # 按域装配:health / auth / account / crud / tds_biz / body / mw / fallback +│ ├── main.rs # 启动装配:PGlite open / 引导身份 / 账号库 / 路由 / 中间件 / 静态兜底 +│ ├── lib.rs # 模块声明(只暴露 `platform` 与 `tdc` 两层,bin 只做装配) +│ ├── platform/ # 【平台层】与业务**零**知识(边界由 check-boundary.sh 静态钉住) +│ │ ├── state.rs # AppState(config + db + db_lock + sessions + accounts + bootstrap + tds) +│ │ ├── config.rs # 环境变量配置 + 密钥守卫 +│ │ ├── db.rs # PGlite 封装(query_json / ensure_schema / f_↔camelCase 映射) +│ │ ├── session.rs # 会话存储(两种 kind:Identity / Account) +│ │ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data}) +│ │ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal) +│ │ ├── cipher.rs # 登录口令加解密(MD5 + AES-256-ECB,对齐上游 cipher.ts) +│ │ ├── ids.rs # id 生成 +│ │ ├── protocol.rs # 协议版本闸门 +│ │ ├── body.rs # 宽松 JSON 体 +│ │ ├── mw.rs # 405 JSON 改写中间件 +│ │ └── fallback.rs # 404 JSON + SPA 静态兜底 + DDL 两层守卫 +│ └── tdc/ # 【业务层】对位上游 `ssw.tdc.*` 包族 +│ ├── entity/ # 18 个实体各一文件 + mod.rs(ALL_SPECS / validate / 权限键) +│ ├── mapper.rs # SQL 组装与执行、投影与序列化(引擎的机械活,**实体无关**) +│ ├── service/ # 业务规则:crud(写路径分档)/ account(本地账号库)/ identity(身份域) +│ ├── controller/ # HTTP 端点:crud / health / auth / account / tds_biz +│ ├── client/tds.rs # TDS 出向客户端(照抄上游 TdsReportClient 的 internal 通道,9 个方法) +│ ├── util/code.rs # 业务编码生成器(原 src/codec.rs:PRO/RES/API/DS 前缀 + 两套上游生成器) +│ ├── support/ # 业务侧公共清单(public_paths:免鉴权端点) +│ └── policy/ engine/ schedule/ notify/ heartbeat/ sso/ # 上游同名包占位(后续批) ├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/,8 个产物文件) ├── schema/ │ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制,**30 表**,**不在 web root**) @@ -65,17 +72,23 @@ tdc-rs/ ## 架构约定(红线) +- 🔴 **平台层 / 业务层边界**(v3 spec §2.3):`src/platform/` 里**不许出现业务知识** + ——业务表名(`tdc_*`)、实体名(`Product` / `Resource` / …)、具体端点路径(`/api/ssw/tdc/…`)、 + 业务表数量;`src/tdc/` 里**不许出现平台能力的第二份实现**。 + 这条**可被静态检查** ⇒ `scripts/check-boundary.sh` 的 4 个接触点(CP1–CP4)。 + 🔴 **通用 CRUD 引擎住在业务层**(`tdc/mapper.rs` + `tdc/service/crud.rs` + `tdc/controller/crud.rs`, + 对位上游 `TdcCrudController`)但**逻辑必须实体无关(零 `match api_name`)** ⇒ 分支只能读 `TableSpec` 字段。 - 🔴 **前端不直接持有数据库。** 所有数据访问经 `/api/ssw/tdc/*` REST;不得把 PGlite 重新塞回浏览器。 - 🔴 **不自研前端。** 控制台 = **上游完整前端的构建产物**(`static/`)。改 UI 改上游,**不在本仓写前端**。 - 🔴 **业务错误必须读 body 的 `code`。** 上游 TDS 用 HTTP 200 承载业务错误码(如 `code:600` 登录过期), 只看 HTTP 状态会把失败误判成成功。本仓的**业务失败一律 HTTP 200 + `{code,msg,data}`**; **鉴权/授权失败是另一种形状**:HTTP 401/403 + 裸 `{"success":false,"code":…,"msg":"…"}`(**无 `data` 键**)。 - 🔴 **schema DDL 绝不可从 HTTP 下载。** `schema/migrate.sql` **刻意不在 web root**(`static/` 会被挂上去), - 另有**两层兜底**(`src/routes/fallback.rs` 的 `ddl_guard` 前置守卫 + `ddl_content_guard` 内容兜底)。 + 另有**两层兜底**(`src/platform/fallback.rs` 的 `ddl_guard` 前置守卫 + `ddl_content_guard` 内容兜底)。 - 🔴 **私钥不得外泄。** 身份私钥只落盘 `data/`;API 一律返回去敏后的公开视图 (**不要**用 `#[serde(skip_serializing)]` —— 会让落盘 JSON 缺字段、回读失败)。 🔴 **CRUD 出参也不许带密钥**:上游实体上标了 `@JsonIgnore` 的属性(`Identity.secretKey` / - `DeliveryTask.devUrl` / `devToken`)在本仓由 `registry::TableSpec::hidden_fields` 登记 ⇒ + `DeliveryTask.devUrl` / `devToken`)在本仓由 `crate::tdc::entity::TableSpec::hidden_fields` 登记 ⇒ 出参**整条删键**、入参**静默忽略**(照抄 Jackson 双向语义)。**新增实体/字段前先查上游 `ssw-tdc-entity` 有没有 `@JsonIgnore`**,别靠「这列没人写」蒙混。 - 🔴 **口令不得外泄。** 账号库只存 `md5(明文)`;对外响应**手工挑字段**(`account_view`),不得把 `Account` 整个塞出去。 @@ -175,7 +188,7 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 `Datasource` / `DeliveryLog` / `DeliveryTask` / `DestroyLog` / `Identity` / `Notification` / `Order` / `Policy` / `PolicyCheckLog` / `PolicyTemplate` / `Product` / `Resource` -> ⚠️ 写入能力**按实体分档**(真值见 `src/registry.rs` 的 `no_create` / `no_update` / `no_delete`): +> ⚠️ 写入能力**按实体分档**(真值见 `src/tdc/entity/mod.rs` 的 `no_create` / `no_update` / `no_delete`): > `Dataset` 是 `tdc_resource` 的**只读视图**(禁增/改/删);`ApiConsumeLog` 全只读; > `AuditLog` 禁改禁删(可增);`DeliveryTask` / `DestroyLog` 禁增禁删(可改); > `Contract` / `DeliveryLog` / `PolicyCheckLog` 禁删(可增可改)。 @@ -194,7 +207,7 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 ### 权限键(写操作二次校验) -`src/registry.rs` 的 `PERMISSION_KEYS` 声明 18 条「实体 → 权限键」;权限键来自 +`src/tdc/entity/mod.rs` 的 `PERMISSION_KEYS` 声明 18 条「实体 → 权限键」;权限键来自 `tdc_identity.f_capability`(`domain::identity::capabilities()`)。 - 能力集**解析不出** ⇒ **fail-open**(本地单机模式没有能力集,不该把写操作全锁死)。 @@ -208,10 +221,10 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 **这是规避逐列类型映射的关键手法**,新增查询一律沿用 `query_json()`,不要另起逐类型分支。 2. **单 backend 串行化**:pglite 是单 in-process backend,所有 DB 访问必须持 `state.db_lock`(`tokio::Mutex`)。 3. **表名白名单**:`valid_table()` 只允许 `[A-Za-z][A-Za-z0-9_]*`,任何拼接表名的地方都要走它; - `registry::validate()` 在**启动时**自检全部拼进 SQL 的标识符(不过白名单 ⇒ 秒退)。 + `entity::validate()` 在**启动时**自检全部拼进 SQL 的标识符(不过白名单 ⇒ 秒退)。 4. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找含 `static/index.html` 的目录, `static/` 与 `data/` 都基于它,**不要改成相对 cwd**(后台启动时会 500)。 -5. **`include_str!` 路径相对 `src/db.rs`**:写 `../schema/migrate.sql`,不是 `../../schema/`。 +5. **`include_str!` 路径相对 `src/platform/db.rs`**:写 `../../schema/migrate.sql`,不是 `../schema/`。 6. **camelCase ↔ snake_case**:请求结构体一律加 `#[serde(rename_all = "camelCase")]`。 🔴 **例外**:`/api/oauth/Login` 的表单字段名就是 `grant_type`(上游送的就是这个)⇒ **不能**加 camelCase (加了字段永远为 `None`),改用 `#[serde(default, alias = "grantType")]`。 @@ -270,7 +283,7 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 ⇒ `migrate.sql` 保持逐字节一致、`/api/health` 的 `tables` 恒为 30。 首启引导 `admin` / `admin`(⚠️ **本地调试默认值**,对外部署前必须改掉)。 口令只存 `md5(明文)`;`update` 不动口令;管理员账号不可删;落盘走 `.tmp` → rename,失败**当业务失败抛出**。 -- `src/routes/account.rs`:登录 + 用户管理 6 端点 + 管理员闸门 `require_admin` +- `src/tdc/controller/account.rs`:登录 + 用户管理 6 端点 + 管理员闸门 `require_admin` (连接器身份会话 / 管理员账号放行;**内部令牌刻意 403**,比上游严一档;查不到账号 ⇒ fail-closed 403)。 ## TDS 出向通道(P4) @@ -283,7 +296,7 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 ⇒ `data` 或 `Err(msg)`)/**整包型**(`list_billing_for_connector` / `dispute` / `confirm` / `settle` / `receipt` / `voucher` ⇒ 原始 `{code,msg,data}`)。 ⚠️ 整包型**成功**时 `data` 是**字符串**(账本 id),不是对象。 -- `src/routes/tds_biz.rs`:**10 个对外端点**(服务目录 3 + 账单 7),照抄上游 +- `src/tdc/controller/tds_biz.rs`:**10 个对外端点**(服务目录 3 + 账单 7),照抄上游 `ServiceCatalogController` + `BillingController`。 - 身份解析**两套口径**:宽松(List/Dispute/Receipt/Voucher/LocalCompare)/ 严格(Confirm/Settle)—— 照抄上游,不统一。 @@ -312,7 +325,7 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 | 症状 | 根因 | 处理 | |---|---|---| -| `include_str!` 编译失败找不到文件 | 路径相对 `src/db.rs` | 用 `../schema/migrate.sql` | +| `include_str!` 编译失败找不到文件 | 路径相对 `src/platform/db.rs` | 用 `../../schema/migrate.sql` | | `/` 返回 500、静态资源 404 | 路径基于 cwd,后台启动 cwd 漂移 | 用 `resolve_project_dir()` | | curl 测 localhost 得 502 | 走了系统 HTTP 代理 | 加 `--noproxy '*'` | | 落盘 JSON 回读失败 | 用了 `#[serde(skip_serializing)]` | 磁盘存全量、API 走单独的对外视图 | @@ -322,7 +335,7 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 | `Option