- 更名并整体重写项目指引:上游真源改指最新版 http://192.168.1.2:8080/ssw/trusted-space/ssw-tdc,原 ssw-mvp 标注为已过时 - 目录树与表清单对齐现状:18 实体 / 30 表 / 模块化 src/ / static/ 托管上游前端产物 - 补齐鉴权三道门、权限键、账号层、缓存布局等章节与踩坑清单 - 踩坑清单新增「后台标签冻结 CSS transition」一行,索引 docs/CONSOLE-ACCEPTANCE.md - 修正密文契约回归防线的表述:除单测向量外,另有 tests/account_api.rs::login_accepts_the_upstream_literal_ciphertext 端到端锚点 Co-Authored-By: Claude Code <[email protected]>
19 KiB
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 的输入,不是本仓现状)。
命令速查
# 编译(自动走本机统一缓存:~/.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 <token> |
命中会话(身份会话 或 本地账号会话) | 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)。
关键实现细节(改代码前必读)
- 查询结果序列化:任意 SELECT 用
SELECT row_to_json(q)::text AS _row FROM (<sql>) q包成单列文本, 后端rows[i].get::<Option<String>>(0)取文本后serde_json::from_str得标准 JSON。 这是规避逐列类型映射的关键手法,新增查询一律沿用query_json(),不要另起逐类型分支。 - 单 backend 串行化:pglite 是单 in-process backend,所有 DB 访问必须持
state.db_lock(tokio::Mutex)。 - 表名白名单:
valid_table()只允许[A-Za-z][A-Za-z0-9_]*,任何拼接表名的地方都要走它;registry::validate()在启动时自检全部拼进 SQL 的标识符(不过白名单 ⇒ 秒退)。 - 路径与 cwd 解耦:
resolve_project_dir()从可执行文件向上找含static/index.html的目录,static/与data/都基于它,不要改成相对 cwd(后台启动时会 500)。 include_str!路径相对src/db.rs:写../schema/migrate.sql,不是../../schema/。- camelCase ↔ snake_case:请求结构体一律加
#[serde(rename_all = "camelCase")]。 🔴 例外:/api/oauth/Login的表单字段名就是grant_type(上游送的就是这个)⇒ 不能加 camelCase (加了字段永远为None),改用#[serde(default, alias = "grantType")]。 - axum 0.8 的
Router<S>语义:S是「还缺什么状态」;with_state把状态烤进当前已有的 endpoint。 ⇒build_router返回Router<AppState>,由main.rs在挂完静态兜底与中间件之后统一with_state收口。 Form<T>在 axum 0.8.9 只实现FromRequest(没有OptionalFromRequest)⇒Option<Form<T>>编译不过 ⇒ 需要「解析失败也走业务信封」的表单端点,取原始 body 自己用serde_urlencoded::from_bytes解析。- 405 的 JSON 兜底在
routes::mw::json_method_not_allowed(响应改写中间件,挂链尾), 不是 axum 的method_not_allowed_fallback(后者只对调用那一刻已注册的路由生效,且丢Allow头)。 - schema 初始化:启动时探测
tdc_identity是否存在,不存在才按;拆分执行migrate.sql。 ecb0.1 只实现*_block_mut(原地改块)⇒ 用encrypt_block_mut/decrypt_block_mut,不是encrypt_block。- 同一文件的多个 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<Form<T>> 编译不过 |
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,
本文件只留「原则 + 决定 + 一句话摘要」。