# 尚数网可信数据空间 — 工程总览 > 与 `docs/README.md`(文档索引)互补:本文件是**工程视角**的自包含总览,可随目录整体移动。 > 当前基线:架构升级 + 骨架可跑通(核心域 CRUD 跑通),2026-08-02 收尾验证完成; > **2026-08-03 Nax 引擎接入**:`mpc` 算子从模拟切到真实 Nax 计算(详见 `docs/sswflow/NAX_ENGINE.md`); > **2026-08-04 安全平面(scard)**:软 PKI 根证书 + 安全启动 PCR 度量 + 远程证明(enroll-nonce→quote→verify)闭环完成,并在 OrbStack Ubuntu 虚机内跨网络端到端跑通(详见 `docs/security/SECURITY_PLANE.md`); > **2026-08-04 安全平面 → TDS 集成**:V1.3.2 DB 迁移(`tds_security_device` / `tds_attest_record` + `tds_connector` +4 列)+ Java 桥接(`SecurityPlaneClient` + `SyncService` `@Scheduled` 30s cron + `SecurityDevice/AuditController`)+ 前端 `/tds/security`,scard 管理面镜像至 SSWFlow 管理平面,撤销流程双向贯通。 ## 1. 项目定位 在 SSWFlow 隐私计算流程编排平台基础上,升级为「尚数网可信数据空间」——对标国标的三大子系统: | 代号 | 全称 | 定位 | 业务库 | API 前缀 | | --- | --- | --- | --- | --- | | **TDS** | 可信数据空间管理服务平台 | 空间运营方:空间/连接器/目录/合约/使用控制/审计 | `tds` | `/api/ssw/tds` | | **TDC** | 数据接入连接器 | 数据提供/使用方:本地资源/产品封装/合约履行/交付 | `tdc` | `/api/ssw/tdc` | | **SSWFLOW** | 隐私计算流程编排 | 密态计算引擎编排层 | `sswflow` | `/api/ssw/sswflow` | 需求基线:`docs/功能清单.md`(A)与 `docs/附件1:技术协议_可信数据空间_0512.docx`(B)必须全部实现。 ## 2. 目录结构 ``` ssw/ ├── boot/ # 后端 Spring Boot 工程(ssw-admin 为运行入口) │ ├── ssw-admin/ # - main + 启动配置 + yml │ ├── ssw-tds/ # - TDS 子系统(entity/biz/controller,@DS("tds")) │ ├── ssw-tdc/ # - TDC 子系统(@DS("tdc")) │ ├── ssw-sswflow-{entity|biz|controller}/ # - 既有 SSWFlow(含 Nax 引擎 V0.13) │ │ └── ssw-sswflow-biz/src/main/resources/nax/nax_adapter.py # ← Nax 进程适配器 │ └── db/ # 手动迁移 SQL(V1.0.0、V1.0.2、V1.0.3) ├── web/ # 前端 Vite + Vue3 + TS(独立 dev server 5173) │ ├── src/api/ssw/{tds,tdc,sswflow}.ts │ ├── src/views/ssw/{tds,tdc,sswflow}/ # 三个子系统视图页 │ ├── src/components/ssw/common/CrudPage.vue # 通用 CRUD 骨架 │ ├── src/router/modules/{tds,tdc,sswflow}.ts ├── scard/ # 安全平面(security-connector,Go):根密钥/安全启动/远程证明/隧道/国密;软实现与端到端跑通见 docs/security/SECURITY_PLANE.md ├── docs/ # 文档中心(README.md 为索引) │ ├── arch/{ARCHITECTURE,REQUIREMENT_MATRIX,MIGRATION}.md │ ├── tds/{REQUIREMENTS,DOMAIN_MODEL}.md │ ├── tdc/{REQUIREMENTS,DOMAIN_MODEL}.md │ ├── sswflow/{PROJECT,NAX_ENGINE}.md # NAX_ENGINE = V0.13 真实隐私计算执行层 │ ├── security/SECURITY_PLANE.md # 安全平面(scard):根密钥/安全启动/远程证明/隧道/国密,软实现与端到端跑通 │ ├── JNPF_BACKEND_GUIDE.md # 后端编码规范(JNPF 7.0 框架约定) │ └── VERIFICATION_2026-08-02.md # 端到端验证报告 ├── refs/ # 国标/参考实现(不动) └── .claude/ # Claude Code 项目配置(memory/ 为软链) └── .workbuddy/memory/ # 项目记忆(MEMORY.md 长期 + 每日 YYYY-MM-DD.md;通过 .claude/memory 软链访问) ``` ## 3. 环境依赖 | 组件 | 版本 / 配置 | | --- | --- | | JDK | Java 21(编译 source/target=17) | | Node | 22.22.2(managed)+ pnpm 10.12.1 | | PostgreSQL | OrbStack 容器 `jnpf-postgres`(192.168.97.3:5432,user=dacli,pwd=dacli123) | | Redis | OrbStack 容器 `jnpf-redis`(192.168.97.2) | | 三业务库 | `sswflow` / `tds` / `tdc`(同 PostgreSQL 实例,各自独立 schema 隔离) | | 加密 | `crypto-js`(前端)+ Java Sa-Token(后端鉴权) | ⚠️ Netty DNS 不走系统解析,`.orb.local` 不通,**一律用容器 IP**。宿主机 host 网络时改 `localhost`。 ## 4. 启动命令 ### 后端 ```bash cd boot && \ java -DDB_HOST=192.168.97.3 \ -DREDIS_HOST=192.168.97.2 \ -Dserver.port=30000 \ -jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar ``` - 必须 `-Dserver.port=30000`(`-Dspring.profiles.active=dev` 实测不生效) - 后端编译:`mvn -pl ssw-admin -am package -DskipTests` - 手动迁移 SQL:`boot/db/V*.sql`,用 `psycopg2` 或 `psql` 跑;先剥离 `--` 注释再按 `;` 切分 ### 前端 ```bash cd web && pnpm dev # → http://localhost:5173 # vite.config.ts proxy: /api → http://localhost:30000 ``` - 类型检查:`pnpm exec vue-tsc --noEmit` - 生产构建:`pnpm build`(tds/tdc/sswflow 独立分包 + vendor) ⚠️ dev server 启动**用 `run_in_background`**,别用 `nohup ... &` 双重后台——进程会被回收,5173 不在监听会导致看似代理故障(实则 dev server 已死)。 ## 5. 鉴权关键约定(必记) - **密码加密**:`AES-256-ECB-PKCS7`,`key = md5(CIPHER_KEY)` 32字节 UTF8,`明文 = md5(plain)` 字符串,输出 `ciphertext.toString(Hex)` - `CIPHER_KEY = EY8WePvjM5GGwQzn`(同 JNPF web `VITE_CIPHER_KEY`) - **登录端点:`POST /api/oauth/Login`**,`Content-Type: application/x-www-form-urlencoded`,body `account=admin&password=<加密>&grant_type=password` - 不是 `/api/ssw/login` - 发 JSON 或漏 `grant_type` → 400「不支持此登录方式」 - token:登录返回 `data.token="bearer eyJ..."`,前端原样存 `localStorage`,请求头 `Authorization: ` - Sa-Token `getTokenPrefix="bearer"` 只剥离**小写**前缀;大写 `Bearer` → 600 登录过期 - 必带头:`App-Code: sswflow` / `Jnpf-Origin: pc` / `Vue-Version: 3` ## 6. DB 关键约定 - ⚠️ 所有表在 **`public` schema**(DSN `currentSchema=public`),不要写 `sswflow.` 前缀;迁移 SQL 一律 `public.` - 迁移脚本**手动执行**(无 Flyway):`boot/db/V1.0.0__schema.sql`(基线)、`V1.0.2__flow_run_scope.sql`、`V1.0.3__flow_schedule.sql` - 三库隔离:`sswflow`/`tds`/`tdc` 同实例不同数据库;表前缀按子系统识别(`flow_*` / `tds_*` / `tdc_*`) - 软删除:`f_delete_mark=1`,查询带 `f_delete_mark IS NULL` ## 7. 后端规范(对齐 JNPF 7.0) 详细见 [`docs/JNPF_BACKEND_GUIDE.md`](./JNPF_BACKEND_GUIDE.md),要点: - 实体/Service/Mapper 必须各自 `@DS("<子库>")` - Controller `@RestController("sswflowXxxController")`、Service `@Service("sswflowXxxService")` **显式 bean 名**(防与 JNPF 内部撞名) - 实体 `@Alias("SswflowXxxEntity")` - 实体基类用 **`SuperExtendEntity`**(带 `sortCode`,已 `javap` 确认;非技能示例的 `SuperEntity`) - 业务 Service 统一 `extends SswflowServiceImpl`(已实现 `DynamicSourceGeneratorInterface`,`DS_KEY="sswflow"`) - `SswAdminApplication.main()` 必须 `addInitializers(new jnpf.util.context.SpringContext())` - `application.yml` 必须有 `allow-bean-definition-overriding:true` + `spring.mvc.pathmatch.matching-strategy: ant_path_matcher` ### 子系统基类 - **TDS**:`TdsCrudController`(`spaceColumn()` 默认 `"f_space_id"`,自动加 ALIVE 条件) - **TDC**:`TdcCrudController`(`tenantColumn()` 默认 `"f_tenant_id"`,多虚拟连接器租户隔离) ## 8. 前端结构 - 技术栈:Vue3 + Vite + TS + ant-design-vue + pinia + vue-router;`@` 别名 → `src` - 三级导航(`App.vue`):顶栏 `subsystems[]`(tds/tdc/sswflow)+ 侧栏由 `router.getRoutes()` 过滤 `meta.subsystem` 推导(避免菜单与路由漂移) - 通用 CRUD 骨架:`components/ssw/common/CrudPage.vue`,props `{title, api, columns, filters, actions, extraQuery, defaults, prompt?}`;列表响应读 `res.list`(后端返回 `{pagination, list}`) - axios 拦截器解开 `ActionResult.data`,重声明 `SswRequest` 解决类型报错 ## 9. 算子协议(SSWFlow 子系统) - 类别:`source`/`prep`/`stat`/`model`/`sink` - operator 字段:`label`(非 name);key 形如 `source.dataset`/`prep.intersect`;params type:`DATASET/COLUMNS/STRING/SELECT/BOOL/INT/FLOAT/PARTY/SLIDER` - 前端 `store.loadOperators` 拉 `/api/ssw/sswflow/Operator/Catalog` 并 merge 前端 icon/color(按 category 映射) - 算子执行(V0.13 起): - `engine="local"` → `SimulationComputeEngine`(兜底) - `engine="mpc"` → `NaxComputeEngine`(首选,order=100)经 Python 子进程跑真实 Nax 算法 - `engine="tee"` → 预留(TEE 引擎,V0.14+) - 新增算子:`stat.scql`(密态 SQL)/ `model.mlp.train`(密文 MLP)/ `model.fedavg.train`(横向联邦) - 详见 `docs/sswflow/NAX_ENGINE.md` ## 10. P0+P1 功能清单(SSWFlow 子系统,2026-08-01 完成) - P0-1 部分运行/续跑(`RunScope` FULL/SINGLE/SELECTED/UPSTREAM/DOWNSTREAM/RESUME) - P0-2 流程模板库(5 预置流程) - P1-3 结果可视化(报表/指标 KPI) - P1-4 模型产物管理(Artifact 列表+下载) - P1-5 轻量调度(`FlowScheduleTicker` 单线程 30s 轮询,避开 Quartz) ## 10.1 V0.13 Nax 引擎接入(2026-08-03 完成) - `ComputeEngine` SPI 落地:`NaxComputeEngine implements ComputeEngine`,`supports("mpc")=true`,`order()=100` - Python 适配器:`boot/ssw-sswflow/ssw-sswflow-biz/src/main/resources/nax/nax_adapter.py`(随 jar 打包) - `StepContext` 富化:新增 `parties` / `datasets` / `workDir` 字段 - 算子覆盖(16 类): - Nax 真实:PSI / 纵向 LR / MLP / FedAvg / SCQL / 安全统计 / 相关性 / IV / 分箱 / 采样 / 切分 / 填充 - 真实导出(落 CSV) - 兜底(`SimulationComputeEngine`):source.dataset / sink.export / model.gbdt.train - 独立烟测:PSI 真实命中 50/60(83.3%),纵向 LR AUC=0.8317,MLP AUC=0.8064,FedAvg AUC=0.8329,SCQL `SELECT COUNT/AVG` 真实计算;评估 AUC/Ks/ACC 一致 - 部署形态:默认 `LocalBackend`;`NAX_BACKEND=ray` 切到 Ray(V0.14 自动化 Party endpoint → Ray 资源映射) - 已知限制与排错:见 `docs/sswflow/NAX_ENGINE.md` §6 §8 ## 11. TDS+TDC 升级基线(2026-08-02 完成) - TDS:空间/连接器/产品/合约/策略模板/审计日志(含 SHA-256 哈希链 + 180 天留存)/统计/状态机 - TDC:身份注册(mTLS 证书前置)/数据源/资源/产品发布/合约准入/交付任务(策略判定 + 结果回填) - 后端 62/62 烟测全过(`/tmp/ssw_tds_tdc_smoke.js`) - 前端 TDC 6 视图页 + vue-tsc 0 error + pnpm build 成功 - 详见:`docs/tds/DOMAIN_MODEL.md` / `docs/tdc/DOMAIN_MODEL.md` / `docs/arch/MIGRATION.md` / `docs/VERIFICATION_2026-08-02.md` ## 12. 路由一览 ### TDS(`/api/ssw/tds/*`) `Space` / `Connector` / `DataProduct` / `Contract` / `PolicyTemplate` / `AuditLog` / `Space/{id}/Online|Statistic` / `Connector/{id}/Audit|Heartbeat` / `DataProduct/{id}/Submit|Audit|Online|View` / `Contract/{id}/Sign|Effective|Terminate` / `AuditLog/Verify` ### TDC(`api/ssw/tdc/*`) `Identity` / `Datasource` / `Resource` / `Product` / `Contract` / `DeliveryTask` + `Identity/{id}/Default|Register|RegisterCallback|Heartbeat` + `Datasource/{id}/Test|Sync` + `Resource/{id}/Sync|Classify` + `Product/{id}/Publish|PublishCallback|Offline` + `DeliveryTask/{id}/Policy|Finish|Report|Cancel` ### SSWFLOW(`api/ssw/sswflow/*`) `Project` / `Party` / `Dataset` / `Datasource` / `Flow` / `FlowRun` / `Operator` / `Artifact` / `FlowSchedule` + 项目统计/批量运行控制 ## 13. 验证脚本 - `/tmp/ssw_tds_tdc_smoke.js` — TDS+TDC 后端全链路 62/62 - `/tmp/ssw_login_test.js` — 通用登录+业务烟测(接受端口参数) - `/tmp/cipher_check.mjs` — crypto-js 加密自检 - `/tmp/ssw_proxy_probe.cjs` — 经 5173 代理端到端验证 ## 14. 移动目录注意事项 - 工作区相对路径全部存在 `.claude/memory`(软链到 `.workbuddy/memory`)与 `boot/db/`,**移动目录前**: 1. 停掉后端 java 进程(`kill `,lsof `:30000` 查 PID) 2. 停掉前端 vite 进程(lsof `:5173`) 3. 移动后 `/Users/xs/.workbuddy/SOUL.md`、`IDENTITY.md`、`USER.md` 不受影响(用户级 identity 文件独立存储) - 不要破坏 `boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar` —— 已编译产物;如需重新编译 `mvn -pl ssw-admin -am package -DskipTests` - `pnpm` 依赖锁文件:`web/pnpm-lock.yaml`(含前端依赖的完整版本图,移动后 `pnpm install` 会快很多) ## 15. 记忆与上下文 - 长期笔记:`/Users/xs/Desktop/ssw/.claude/memory/MEMORY.md`(≤3000 字符/会话;物理位于 `.workbuddy/memory/`) - 每日日志:`/Users/xs/Desktop/ssw/.claude/memory/YYYY-MM-DD.md`(append-only;物理位于 `.workbuddy/memory/`) - 用户身份:`/Users/xs/.workbuddy/{SOUL,IDENTITY,USER}.md`(用户级,与项目无关) - 对话历史检索:使用 `conversation_search` 工具(不依赖本地文件)