Files
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

13 KiB
Raw Permalink Blame History

尚数网可信数据空间 — 工程总览

与 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. 启动命令

后端

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 跑;先剥离 -- 注释再按 ; 切分

前端

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,要点:

  • 实体/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 工具(不依赖本地文件)