diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 7cefb45..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,196 +0,0 @@ -# AGENTS.md - -This file provides guidance to AI coding agents (CodeBuddy / Claude Code / Cursor / Codex 等) when working in this repository. - -## 项目定位 - -**TDC 连接器(tdc-rs)** —— 尚数网可信数据空间中「数据接入连接器(TDC)」子系统的**本地优先 Rust 重实现**。 - -上游真源是 `~/Desktop/workspace/ssw-mvp/boot/ssw-tdc`(Spring Boot 3 + JNPF 7.0 + Java 21,37 个 Controller)。 -本仓库把它的**核心数据生命周期**剥离出 JNPF 重底座,重做成 **单二进制、零外部服务**的形态: - -| 层 | 技术栈 | 职责 | -|---|---|---| -| 后端 | Rust 2021 + axum 0.8 + tokio | 控制面 + 数据面 + 静态托管 + TDC→TDS HTTP 契约网关 | -| 数据库 | `pglite-rs` 0.2(进程内原生 PostgreSQL) | 承载全部 `tdc_*` 业务表,数据落盘 `data/tdc.pg/` | -| 前端 | 静态 HTML + 原生 ESM JS,零构建 | 操作员控制台:schema 自省驱动的通用 CRUD + 生命周期动作 | -| 调试对端 | 零依赖 Node(`tds-stub/`) | 无真 TDS 时提供 TDS 契约桩 | - -> **pglite-rs ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;它把 postgres-pglite 编译成原生静态库链接进二进制, -> 是**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,**无服务器、无 Docker、无 WASM**。 -> 浏览器端 WASM 版(`@electric-sql/pglite` + IndexedDB)曾是本项目的错误实现,已废弃删除,勿再引入。 - -## 顶层目录速览 - -``` -tdc-rs/ -├── Cargo.toml # 依赖 + release 优化(lto=thin / strip / panic=abort) -├── Cargo.lock # 锁定版本 -├── src/main.rs # 全部后端逻辑(769 行,单文件) -├── static/ -│ ├── index.html # SPA 外壳(无 import map、无构建产物) -│ ├── app.js # 通用 CRUD + 生命周期动作(465 行) -│ ├── style.css -│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制,19 表) -├── tds-stub/server.js # TDS 契约桩(仅调试用,非产品) -├── docs/ # 补充文档 -└── data/ # 运行期数据(tdc.pg/ + node-identity.json,已 gitignore) -``` - -**没有** `build.rs` / `export_dynamic` / 前端打包步骤 / Docker Compose / 外部数据库进程。 - -## 架构约定(红线) - -- 🔴 **TDC 与 TDS 只走 HTTP 契约,绝不编译期耦合。** 跨系统读写一律经 `/api/ssw/tdc/tds/{*path}` 代理网关; - 未配置 `SSW_TDS_BASE_URL` 时降级为 **Noop(HTTP 501)**,对应原 `TdcTdsClient` → `NoopTdcTdsClient`。 - 禁止在本仓库引入任何 TDS 侧的 Service / Entity / Mapper 概念或直连 TDS 数据库。 -- 🔴 **前端不直接持有数据库。** 所有数据访问经 `/api/db/*` REST;不得把 PGlite 重新塞回浏览器。 -- 🔴 **业务错误必须读 body 的 `code`。** 真实 TDS 用 HTTP 200 承载业务错误码(如 `code:600` 登录过期), - 只看 HTTP 状态会把失败误判成成功。 -- 🔴 **私钥不得外泄。** `NodeIdentity.private_key` 只落盘 `data/node-identity.json`, - API 一律经 `identity_view()` 返回去敏后的公开视图(`#[serde(skip_serializing)]` 会让落盘 JSON 缺字段导致回读失败,**不要用**)。 - -## 命令速查 - -```bash -# 编译(自动走本机统一缓存:~/.cargo/registry 软链 + sccache) -cargo build # debug -cargo build --release # 发布版,约 2 分钟 - -# 运行 -PORT=30000 ./target/debug/tdc-connector -SSW_TDS_BASE_URL=http://127.0.0.1:30040 PORT=30000 ./target/debug/tdc-connector # 接真实 TDS -cd tds-stub && node server.js # 无 TDS 时起契约桩(:30100) - -# 冒烟 -curl -s http://127.0.0.1:30000/api/health -curl -s http://127.0.0.1:30000/api/db/tables | head -c 200 -``` - -> 本机 curl 走系统代理,**测 localhost 必须加 `--noproxy '*'`**,否则会得到 502。 -> 后台常驻进程必须用 Bash 工具的 `run_in_background` 托管;`nohup ... &` 在工具调用返回后会被回收。 - -## 后端 API - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `/api/health` | 健康检查(含 `tds_mode` / `tds_base_url` / db 模式) | -| GET | `/api/db/tables` | 列出 public schema 下所有表 | -| GET | `/api/db/table/{name}/columns` | 列信息(表名白名单校验,防注入) | -| GET | `/api/db/table/{name}/rows?limit=` | 行数据(`SELECT * LIMIT n`,默认 200 / 上限 1000) | -| POST | `/api/db/query` | 只读查询 → JSON 数组 | -| POST | `/api/db/exec` | 写操作(INSERT/UPDATE/DELETE/DDL) | -| GET/POST | `/api/ssw/tdc/node/identity` | 连接器身份(读 / ed25519 签发) | -| POST | `/api/ssw/tdc/node/identity/register` | 向 TDS 注册;真 TDS 无该端点则返回 `UNSUPPORTED_BY_TDS` | -| POST | `/api/ssw/tdc/node/identity/heartbeat` | 心跳(置 ONLINE;配 base-url 时一并上报 TDS `NodeReport`) | -| ANY | `/api/ssw/tdc/tds/{*path}` | TDC→TDS 契约代理(无 base-url → 501 Noop) | - -### 关键实现细节(改代码前必读) - -1. **查询结果序列化**:任意 SELECT 用 `SELECT row_to_json(q)::text AS _row FROM () q` 包成单列文本, - 后端 `rows[i].get::>(0)` 取文本后 `serde_json::from_str` 得标准 JSON。 - **这是规避逐列类型映射的关键手法**,新增查询一律沿用 `query_json()`,不要另起逐类型分支。 -2. **单 backend 串行化**:pglite 是单 in-process backend,所有 DB 访问必须持 `state.db_lock`(`tokio::Mutex`)。 -3. **表名白名单**:`valid_table()` 只允许 `[A-Za-z][A-Za-z0-9_]*`,任何拼接表名的地方都要走它。 -4. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找含 `static/index.html` 的目录, - `static/` 与 `data/` 都基于它,**不要改成相对 cwd**(后台启动时会 500)。 -5. **`include_str!` 路径相对 `src/main.rs`**:写 `../static/migrate.sql`,不是 `../../static/`。 -6. **逐跳头剥离**:代理转发必须跳过 `host/content-length/connection/transfer-encoding/upgrade/keep-alive/te/trailer`; - `Bridge/**` 由代理统一注入 `App-Code: tdc`,并丢弃客户端自带的该头。 -7. **camelCase ↔ snake_case**:请求结构体一律加 `#[serde(rename_all = "camelCase")]`,否则 `orgName`/`endpoint` 恒为 null。 -8. **schema 初始化**:启动时探测 `tdc_identity` 是否存在,不存在才按 `;` 拆分执行 `migrate.sql`。 - -## 数据模型 - -`static/migrate.sql` 忠实移植原 `ssw-mvp/boot/db/tdc/V1.0.0__tdc_schema.sql`,**19 张表**: -身份 / 数据源 / 资源 / 资源字段 / 脱敏规则 / 数据产品 / 数据需求 / 订单 / 合约 / 使用控制策略 / -策略校验记录 / API 交付服务 / 交付任务 / 交付日志 / TDS 同步日志 / 审计日志 / 环境空间 / 成员 / 机密文件, -另含 6 条内置脱敏规则与默认开发环境空间。列名沿用原 JNPF 约定(`f_` 前缀 + 9 个系统列 + 逻辑删除位)。 - -**改 schema 时**:`migrate.sql` 是编译期内嵌的,改完必须清空 `data/` 重建(探针逻辑只在首次建表), -并同步更新 README 的表清单。 - -## 控制台能力 - -schema 自省驱动的通用 CRUD(新建 / 编辑 / 逻辑删除 / 搜索,全部 19 表)+ 按表生命周期: - -| 表 | 动作 | -|---|---| -| `tdc_product` | 发布 / 下架 / 提交审核 | -| `tdc_order` | 通过 / 驳回 / 签署 | -| `tdc_demand` | 发布 / 关闭 | -| `tdc_contract` | 生效 / 终止 | -| `tdc_resource` | 启用 / 停用 | -| `tdc_datasource` | 测试连接 / 同步资源 | -| `tdc_delivery_task` | 策略校验(写 `tdc_policy_check_log`)/ 完成 / 取消 / 销毁(留证写 `tdc_delivery_log`) | - -## 编译缓存(dev-cache-layout 规范) - -本机已统一,**无需在项目内做任何配置**: - -- `~/.cargo/registry` → `~/.cache/cargo/registry`(软链) -- sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCCACHE_DIR` 启用 -- 缓存实体在 `~/.cache/sccache`(`~/Library/Caches/Mozilla.sccache` 软链透明访问) - -`cargo build` 直接命中。**不要**在仓库内新建 `.cargo/config.toml` 或把 `target/` 挪走。 - -## 发布与体积 - -- release 配置:`opt-level=2` / `lto="thin"` / `strip="symbols"` / `panic="abort"` / `codegen-units=16`。 -- 体积构成:二进制 **27 MB**(主体是内嵌的 PostgreSQL 引擎)+ static 64 KB → **tar.gz 约 11 MB**。 - 对照真实 TDS 的 `ssw-admin` fat jar **368 MB** + 目标机装 JVM + PostgreSQL 四库 + Redis。 -- 首次启动生成 `data/tdc.pg` 约 38 MB(运行期数据,不随包分发)。 - -## 对接真实 TDS(`ssw-mvp/boot/ssw-admin`) - -TDS **不是独立服务**,而是 `ssw-admin` 的角色 profile: - -```bash -# 1) 打包:-pl 时父 pom 的 activeByDefault 不传播到子模块,必须显式 -P full 才把 ssw-tds 打进 fat jar -mvn -f boot/pom.xml -P full -pl ssw-admin -am package -DskipTests - -# 2) 运行(端口避开连接器的 30000;中和本机未启的外部依赖) -DB_HOST=127.0.0.1 DB_PORT=15432 REDIS_HOST=127.0.0.1 REDIS_PORT=16379 \ -java -Xmx2g -jar boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar \ - --spring.profiles.active=dev,full --server.port=30040 \ - --fisco.enabled=false --k8s.enabled=false --kbs.url= \ - --ssw.security-plane.base-url=http://127.0.0.1:1 -``` - -依赖本机已有容器 `jnpf-postgres`(15432) / `jnpf-redis`(16379) 与 `j7 / tdc / tds / sswflow` 四库(PostgreSQL)。 -启动约 30s;跨方算力(30011)、scard 安全平面(8443) 未启只报非致命告警。 - -**真实 TDS 契约要点**: - -- `Bridge/**` 需请求头 **`App-Code: tdc`**(`TdsBridgeInternalController` 白名单只放行 `tdc`); - `X-Internal-Token` 仅在 `tds.internal-secret` 非空时校验(默认空 = 免 token)。 -- 业务错误走 HTTP 200 + body `code`。 -- **无 `POST /Connector/Register`**(连接器由运营方 CRUD 侧建档)→ 连接器如实返回 `UNSUPPORTED_BY_TDS`。 -- 审计/留痕:`POST {base}/api/ssw/tds/Bridge/{AuditChain,ChainEvidence,AuditRecord,AuditTrail}`。 - -## 已知踩坑清单 - -| 症状 | 根因 | 处理 | -|---|---|---| -| `include_str!` 编译失败找不到文件 | 路径相对 `src/main.rs` | 用 `../static/migrate.sql` | -| `/` 返回 500、静态资源 404 | 路径基于 cwd,后台启动 cwd 漂移 | 用 `resolve_project_dir()`(已修) | -| curl 测 localhost 得 502 | 走了系统 HTTP 代理 | 加 `--noproxy '*'` | -| `GET /api/ssw/tdc/node/identity` 404 | 落盘 JSON 缺 `private_key` 无法反序列化 | 磁盘存全量、API 走 `identity_view()` 去敏 | -| 注册返回 600「登录过期」却判成功 | 只看 HTTP 状态 | 必须同时判 body 的 `code` | -| `orgName`/`endpoint` 恒为 null | 请求 camelCase vs 后端 snake_case | 结构体加 `#[serde(rename_all = "camelCase")]` | -| 浏览 `tdc_audit_log` 直接 500 | 查询假定存在 `f_delete_mark`/`f_sort_code` | 改用 `SELECT * LIMIT n` | -| 表名注入 | 直接拼表名 | 一律走 `valid_table()` | -| 两个实例共用 `data/` 报 `postmaster.pid` 锁冲突 | pglite 单实例独占数据目录 | 用不同目录/端口起第二个实例 | -| release 首次编译慢 | 全依赖需重编 | 走 sccache;`cargo build --release` 约 2 分钟 | - -## 明确不在本仓库范围 - -原 `ssw-tdc` 的隐私计算作业——`NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask / -Notebook / VizChart / Quality* / HostingJob / DestroyLog` 等——依赖 **Nax 隐私计算引擎**与 -**scard 安全平面(软 PKI + 软 TPM)**,本地不可行,**未纳入本次重做**。 -需要这部分应保留原 Java/Scala 服务,或作为独立后端经 HTTP 契约接入本连接器。 - -## 记忆约定 - -遵循项目级约定:**踩坑清单与长 traceback 进 `docs/`(本文件表格即其索引),工作日志进 `.workbuddy/memory/YYYY-MM-DD.md`**, -本文件只留「原则 + 决定 + 一句话摘要」。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..08c7cca --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,263 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (CodeBuddy / Claude Code / Cursor / Codex 等) when working in this repository. + +> ⚠️ **本文件是项目级 agent 指引**,内容必须与代码**同步**。改代码后回头核对本文件是否还成立。 + +## 项目定位 + +**TDC 连接器(tdc-rs)** —— 尚数网可信数据空间中「数据接入连接器(TDC)」子系统的**本地优先 Rust 重实现**。 + +上游真源:**最新版**在 `http://192.168.1.2:8080/ssw/trusted-space/ssw-tdc`(只读克隆在 `/tmp/sswtdc-probe`); +更早的 `~/Desktop/workspace/ssw-mvp/boot/ssw-tdc`(Spring Boot 3 + JNPF 7.0 + Java 21)仍在,但**已过时**。 + +本仓库把上游的**数据生命周期 + 控制台**重做成 **单二进制、零外部服务**的形态: + +| 层 | 技术栈 | 职责 | +|---|---|---| +| 后端 | Rust 2021 + axum 0.8 + tokio | 鉴权 / 会话 / 权限键 / 18 实体 CRUD / 聚合详情 / 账号层 / 静态托管 | +| 数据库 | `pglite-rs` 0.2(进程内原生 PostgreSQL) | 承载全部 `tdc_*` 业务表(**30 张**),数据落盘 `data/tdc.pg/` | +| 前端 | **上游(Java/Vue)完整前端的构建产物**,托管在 `static/` | **零自研前端、零构建步骤**(`scripts/build-frontend.sh` 可重放) | +| 账号层 | 本机 JSON 文件 `data/accounts.json` | 顶替上游的 JNPF j7 账号库(上游完整前端的 JNPF 兼容登录) | + +> **pglite-rs ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;它把 postgres-pglite 编译成原生静态库链接进二进制, +> 是**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,**无服务器、无 Docker、无 WASM**。 +> 浏览器端 WASM 版(`@electric-sql/pglite` + IndexedDB)曾是本项目的错误实现,已废弃删除,勿再引入。 + +## 顶层目录速览 + +``` +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) +│ ├── 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 # 环境变量配置 + 密钥守卫 +│ ├── domain/identity.rs # 身份引导 / Auth 端点 / 能力集 +│ └── routes/ # 按域装配:health / auth / account / crud / body / mw / fallback +├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/,8 个产物文件) +├── schema/ +│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制,**30 表**,**不在 web root**) +├── scripts/ # build-frontend.sh / gen-migrate.sh / reset-data.sh +├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail) +├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md) +├── tds-stub/server.js # TDS 契约桩(零依赖,仅供端到端调试) +└── data/ # 运行期数据(tdc.pg/ + accounts.json,已 gitignore) +``` + +**没有** `build.rs` / `export_dynamic` / 前端打包步骤 / Docker Compose / 外部数据库进程。 + +## 架构约定(红线) + +- 🔴 **前端不直接持有数据库。** 所有数据访问经 `/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` 内容兜底)。 +- 🔴 **私钥不得外泄。** 身份私钥只落盘 `data/`;API 一律返回去敏后的公开视图 + (**不要**用 `#[serde(skip_serializing)]` —— 会让落盘 JSON 缺字段、回读失败)。 +- 🔴 **口令不得外泄。** 账号库只存 `md5(明文)`;对外响应**手工挑字段**(`account_view`),不得把 `Account` 整个塞出去。 +- 🔴 **TDC ↔ TDS 尚未对接**(P4 才有出向客户端)。旧版的 `/api/ssw/tdc/tds/*` 代理网关**已下线**(⇒ 404); + 契约清单见 `docs/TDC-TDS-CONTRACT.md`(那是 **P4 的输入**,不是本仓现状)。 + +## 命令速查 + +```bash +# 编译(自动走本机统一缓存:~/.cargo/registry 软链 + sccache) +cargo build # debug +cargo build --release # 发布版 + +# 运行 +PORT=30000 ./target/debug/tdc-connector +cd tds-stub && node server.js # 无 TDS 时起契约桩(:30100) + +# 冒烟 +curl -s --noproxy '*' http://127.0.0.1:30000/api/health +curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode 'account=admin' --data-urlencode "password=<密文hex>" --data-urlencode 'grant_type=password' +``` + +> 本机 curl 走系统代理,**测 localhost 必须加 `--noproxy '*'`**,否则会得到 502。 +> 后台常驻进程必须用 Bash 工具的 `run_in_background` 托管;`nohup … &` 在工具调用返回后会被回收。 +> 起服务时 stdout **不要**指向 `/dev/null`(进程会以 100 退出),**不要**落进提交或报告 +> (首启会打印一次性 `secretKey`)。 + +## 后端 API + +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | `/api/health` | 健康检查(`tables: 30` / `tdsMode` / `protocolVersion`) | +| POST | `/api/oauth/Login` | **JNPF 兼容登录**(form-urlencoded:`account` / `password`(密文 hex) / `grant_type=password`) | +| POST | `/api/ssw/tdc/Auth/Login` | 连接器身份登录(软 PKI,签发会话令牌) | +| GET | `/api/ssw/tdc/Auth/Me` | 当前身份视图(**去敏**:不含私钥/一次性密钥) | +| GET | `/api/ssw/tdc/Auth/Spaces` | 环境空间列表 | +| GET | `/api/ssw/tdc/Auth/SsoConfig` | SSO 配置(上游前端登录页用;本仓恒 `enabled:false`) | +| GET / POST | `/api/permission/Users` | 用户管理 · 列表 / 新建(**仅管理员**) | +| PUT / DELETE | `/api/permission/Users/{id}` | 用户管理 · 改资料 / 删账号(**仅管理员**) | +| POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 重设口令(收 `md5(明文)`;**仅管理员**) | +| PUT | `/api/permission/Users/{id}/Actions/State` | 启用 / 禁用(**仅管理员**) | +| GET / POST | `/api/ssw/tdc/{Entity}` | 18 个实体的列表 / 新建 | +| GET | `/api/ssw/tdc/{Entity}/All` | 不分页全量 | +| GET / PUT / DELETE | `/api/ssw/tdc/{Entity}/{id}` | 详情 / 修改 / 逻辑删除 | +| GET | `/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` | 资源 / 数据集聚合详情 | + +`{Entity}` 的 18 个全名: + +`ApiConsumeLog` / `AuditLog` / `Contract` / `Credential` / `DataInterface` / `Dataset` / +`Datasource` / `DeliveryLog` / `DeliveryTask` / `DestroyLog` / `Identity` / `Notification` / +`Order` / `Policy` / `PolicyCheckLog` / `PolicyTemplate` / `Product` / `Resource` + +> ⚠️ 写入能力**按实体分档**(真值见 `src/registry.rs` 的 `no_create` / `no_update` / `no_delete`): +> `Dataset` 是 `tdc_resource` 的**只读视图**(禁增/改/删);`ApiConsumeLog` 全只读; +> `AuditLog` 禁改禁删(可增);`DeliveryTask` / `DestroyLog` 禁增禁删(可改); +> `Contract` / `DeliveryLog` / `PolicyCheckLog` 禁删(可增可改)。 + +### 鉴权三道门(顺序与文案与上游一致) + +| 门 | 通道 | 判据 | 失败 | +|---|---|---|---| +| ① 协议版本 | `X-Protocol-Version` | 与 `protocol::PROTOCOL_VERSION` 不兼容 ⇒ 拒 | 401「跨端协议版本不兼容,请升级对端」 | +| ② 内部令牌 | `X-Internal-Token` | 与 `SSW_INTERNAL_TOKEN` 相等 | 401「内部接口凭证无效」 | +| ③ 会话令牌 | `X-Auth-Token` 或 `Authorization: bearer ` | 命中会话(**身份会话** 或 **本地账号会话**) | 401「内部接口凭证无效」 | + +- 🔴 内部令牌**只看 `X-Internal-Token` 头**,不接受 query / body。 +- 🔴 `TDC_STRICT_SECRETS=1` ⇒ 默认口令即视为不安全 ⇒ **启动即失败**(`config::check_secret_guard`)。 +- 白名单 `WHITE_URL` 含 `/api/oauth/Login`(登录端点本身不过闸门)。 + +### 权限键(写操作二次校验) + +`src/registry.rs` 的 `PERMISSION_KEYS` 声明 18 条「实体 → 权限键」;权限键来自 +`tdc_identity.f_capability`(`domain::identity::capabilities()`)。 + +- 能力集**解析不出** ⇒ **fail-open**(本地单机模式没有能力集,不该把写操作全锁死)。 +- 解析出来 ⇒ **按键判定**;`*` / `all` 放行。 +- 无凭证 ⇒ 403;内部令牌 ⇒ 放行;**本地账号(`Principal::Account`)⇒ 放行**(⚠️ 已知边界,见 ledger)。 + +## 关键实现细节(改代码前必读) + +1. **查询结果序列化**:任意 SELECT 用 `SELECT row_to_json(q)::text AS _row FROM () q` 包成单列文本, + 后端 `rows[i].get::>(0)` 取文本后 `serde_json::from_str` 得标准 JSON。 + **这是规避逐列类型映射的关键手法**,新增查询一律沿用 `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 的标识符(不过白名单 ⇒ 秒退)。 +4. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找含 `static/index.html` 的目录, + `static/` 与 `data/` 都基于它,**不要改成相对 cwd**(后台启动时会 500)。 +5. **`include_str!` 路径相对 `src/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")]`。 +7. **axum 0.8 的 `Router` 语义**:`S` 是「还缺什么状态」;`with_state` 把状态烤进**当前已有**的 endpoint。 + ⇒ `build_router` 返回 `Router`,由 `main.rs` 在挂完静态兜底与中间件**之后**统一 `with_state` 收口。 +8. **`Form` 在 axum 0.8.9 只实现 `FromRequest`**(没有 `OptionalFromRequest`)⇒ `Option>` **编译不过** + ⇒ 需要「解析失败也走业务信封」的表单端点,取**原始 body** 自己用 `serde_urlencoded::from_bytes` 解析。 +9. **405 的 JSON 兜底**在 `routes::mw::json_method_not_allowed`(**响应改写中间件**,挂链尾), + 不是 axum 的 `method_not_allowed_fallback`(后者只对调用那一刻已注册的路由生效,且丢 `Allow` 头)。 +10. **schema 初始化**:启动时探测 `tdc_identity` 是否存在,不存在才按 `;` 拆分执行 `migrate.sql`。 +11. **`ecb` 0.1 只实现 `*_block_mut`**(原地改块)⇒ 用 `encrypt_block_mut` / `decrypt_block_mut`,**不是** `encrypt_block`。 +12. **同一文件的多个 Edit 必须串行**(并行 Edit 会 last-writer-wins 静默覆盖)。 + +## 数据模型 + +`schema/migrate.sql`(3017 行)是上游 `tdc_*` schema 的生成产物,**30 张表**: + +| 域 | 表 | +|---|---| +| 身份 / 凭据 | `tdc_identity`、`tdc_credential`、`tdc_p2p_session` | +| 数据源 / 接口 | `tdc_datasource`、`tdc_data_interface`、`tdc_data_interface_field`、`tdc_data_interface_param` | +| 资源 / 脱敏 | `tdc_resource`、`tdc_resource_field`、`tdc_resource_mask_rule` | +| 目录 / 交易 | `tdc_product`、`tdc_order`、`tdc_contract` | +| 策略 | `tdc_policy`、`tdc_policy_template`、`tdc_policy_check_log` | +| 交付 | `tdc_delivery_task`、`tdc_delivery_task_participant`、`tdc_delivery_log`、`tdc_delivery_outbox` | +| 执行 / 销毁 | `tdc_privacy_exec_run`、`tdc_sandbox_exec_run`、`tdc_destroy_log` | +| 日志 / 通知 | `tdc_audit_log`、`tdc_api_consume_log`、`tdc_sync_log`、`tdc_notify` | +| 上游示例 | `tdc_demo_car_insurance`、`tdc_demo_insurance_claims`、`tdc_demo_pii` | + +其中 **24 张**带齐 10 个系统列(`f_id` / `f_tenant_id` / `f_sort_code` + 创建·修改·删除审计列), +其余 **6 张**为精简变体;逻辑删除位为 `f_delete_mark`;21 个唯一索引中 14 个是 partial 唯一索引。 + +**改 schema 时**:`migrate.sql` 是编译期内嵌的,改完必须清空 `data/` 重建(探针逻辑只在首次建表), +并同步更新 README 的表清单。 + +## 账号层(本地账号库) + +- `src/cipher.rs`:MD5 + AES-256-ECB,与上游 `frontend/web/src/utils/cipher.ts` **逐字对齐**。 + key = `md5_hex(CIPHER_KEY)` 的 **32 个 ASCII 字节**(⇒ AES-256,**不是** 16 字节原始摘要); + src = `md5_hex(plain)` 的 32 个 ASCII 字节;Pkcs7 补 16×0x10 ⇒ 48 字节 / 96 hex。 + 🔴 这条契约有**两道**回归防线:`src/cipher.rs` 单测里的**上游原始向量** + (`encryptPassword('123456')`)**+** `tests/account_api.rs::login_accepts_the_upstream_literal_ciphertext` + —— 后者拿**字面密文**真打登录端点(改密钥它必红,**不是**自证自洽)。 + 浏览器侧也已验过(上游自己的 `cipher.ts` 加密后能登录 ⇒ 见 `docs/CONSOLE-ACCEPTANCE.md` §3.1)。 +- `src/account.rs`:JSON 文件 `data/accounts.json` + 进程内互斥锁;**刻意不建 `tdc_*` 表** + ⇒ `migrate.sql` 保持逐字节一致、`/api/health` 的 `tables` 恒为 30。 + 首启引导 `admin` / `admin`(⚠️ **本地调试默认值**,对外部署前必须改掉)。 + 口令只存 `md5(明文)`;`update` 不动口令;管理员账号不可删;落盘走 `.tmp` → rename,失败**当业务失败抛出**。 +- `src/routes/account.rs`:登录 + 用户管理 6 端点 + 管理员闸门 `require_admin` + (连接器身份会话 / 管理员账号放行;**内部令牌刻意 403**,比上游严一档;查不到账号 ⇒ fail-closed 403)。 + +## 编译缓存(dev-cache-layout 规范) + +本机已统一,**无需在项目内做任何配置**: + +- `~/.cargo/registry` → `~/.cache/cargo/registry`(软链) +- sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCCACHE_DIR` 启用 +- 缓存实体在 `~/.cache/sccache`(`~/Library/Caches/Mozilla.sccache` 软链透明访问) + +`cargo build` 直接命中。**不要**在仓库内新建 `.cargo/config.toml` 或把 `target/` 挪走。 + +## 发布与体积 + +- release 配置:`opt-level=2` / `lto="thin"` / `strip="symbols"` / `panic="abort"` / `codegen-units=16`。 +- 体积构成:debug 二进制 **~35 MB**(主体是内嵌的 PostgreSQL 引擎)+ static **2 MB**(上游 SPA 产物)。 +- 首次启动生成 `data/tdc.pg` 约 **39 MB**(运行期数据,不随包分发)。 + +## 已知踩坑清单 + +| 症状 | 根因 | 处理 | +|---|---|---| +| `include_str!` 编译失败找不到文件 | 路径相对 `src/db.rs` | 用 `../schema/migrate.sql` | +| `/` 返回 500、静态资源 404 | 路径基于 cwd,后台启动 cwd 漂移 | 用 `resolve_project_dir()` | +| curl 测 localhost 得 502 | 走了系统 HTTP 代理 | 加 `--noproxy '*'` | +| 落盘 JSON 回读失败 | 用了 `#[serde(skip_serializing)]` | 磁盘存全量、API 走单独的对外视图 | +| 注册返回 600「登录过期」却判成功 | 只看 HTTP 状态 | 必须同时判 body 的 `code` | +| `orgName`/`endpoint` 恒为 null | 请求 camelCase vs 后端 snake_case | 结构体加 `#[serde(rename_all = "camelCase")]` | +| `grant_type` 永远是 `None` | 给表单结构体加了 camelCase | 改用 `#[serde(default, alias = "grantType")]` | +| `Option>` 编译不过 | axum 0.8.9 的 `Form` 无 `OptionalFromRequest` | 取原始 body 自己解析 | +| 405 返回 HTML / 丢 `Allow` 头 | 用了 axum 的 `method_not_allowed_fallback` | 用 `routes::mw::json_method_not_allowed` | +| DDL 能从 HTTP 下载 | DDL 落在 web root | 移到 `schema/` + `ddl_guard` 两层兜底(**Range 分段也要拦**) | +| 表名注入 | 直接拼表名 | 一律走 `valid_table()` + `registry::validate()` | +| 两个实例共用 `data/` 报 `postmaster.pid` 锁冲突 | pglite 单实例独占数据目录 | 用不同目录/端口起第二个实例 | +| 并行测试互相撞车 | `tdc_identity` 有唯一约束 / 账号库是持久文件 | 每个用例用**唯一**身份码 + **独立**账号文件 | +| release 首次编译慢 | 全依赖需重编 | 走 sccache | +| 自动化里 antd 抽屉停在屏幕外、点不到「保存」 | 内核浏览器在**后台标签** ⇒ `visibilityState=hidden` ⇒ rAF + CSS transition 全冻结 | 注入 `*{transition:none !important}` + 摘掉卡住的 motion 类(**测试环境假象,非产品缺陷**,见 `docs/CONSOLE-ACCEPTANCE.md` §5) | + +## 明确不在本仓库范围 + +- **上游那 100+ 个「动作端点」**(发布 / 下架 / 提交审核 / 策略校验 / 同步资源 / 销毁 …)属 P2–P5,尚未实现 + ⇒ 上游前端这些按钮点了会 404(分期的正常状态)。 +- 原 `ssw-tdc` 的**隐私计算作业**——`NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask / +Notebook / VizChart / Quality* / HostingJob / DestroyLog` 等——依赖 **Nax 隐私计算引擎**与 +**scard 安全平面(软 PKI + 软 TPM)**,本地不可行。需要这部分应保留原 Java/Scala 服务。 +- **TDS 出向客户端**(`/api/ssw/tdc/tds/*` 代理 + 真实 TDS 联调)属 P4。 +- **JNPF 角色 / 菜单 / 授权模型**(j7 的 `base_role` / `base_module` 等)**不引入** + ⇒ 本仓的权限判定走**声明式权限键**(`registry::PERMISSION_KEYS`),不走菜单。 + +## 记忆约定 + +遵循项目级约定:**踩坑清单与长 traceback 进 `docs/`(本文件表格即其索引),工作日志进 `.workbuddy/memory/YYYY-MM-DD.md`**, +本文件只留「原则 + 决定 + 一句话摘要」。