Files
ssw-mvp/docs/PROJECT.md
T
admin 3247e9fd15 init: ssw-mvp initial commit
- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
2026-08-05 18:29:12 +08:00

202 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 尚数网可信数据空间 — 工程总览
> 与 `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: <token>`
- 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<String>`**(带 `sortCode`,已 `javap` 确认;非技能示例的 `SuperEntity<String>`)
- 业务 Service 统一 `extends SswflowServiceImpl<Mapper,Entity>`(已实现 `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<T>`(`spaceColumn()` 默认 `"f_space_id"`,自动加 ALIVE 条件)
- **TDC**:`TdcCrudController<T>`(`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 <PID>`,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` 工具(不依赖本地文件)