Files
ssw-mvp/AGENTS.md
T
admin cc46c8be56 refactor(ssw): 真源迁 jweb src/views/ssw 并入官方动态路由 + 纳入版本库
- jweb: 真源 src/ssw -> src/views/ssw,164 处 @/ssw/ -> @/views/ssw/
  access.ts 现有 glob ../views/**/*.vue 自动覆盖,官方 jnpf_app_ 动态路由直接命中(B 无需改平台代码)
- web: web/src/ssw 软链重指向 jweb src/views/ssw;删除 web 自有 ssw 副本
  (api/components/types/store/utils/views),统一经软链消费 jweb 真源
- VCS: 移除 jweb/.git(嵌套仓库使 force-add 静默失效),git add -f 将
  jweb/.../src/views/ssw(86 文件)纳入本仓库;.gitignore 注明机制
- 文档/记忆: AGENTS.md、MEMORY.md、.gitignore 同步更新路径与路由说明
2026-08-06 17:22:23 +08:00

16 KiB
Raw Blame History

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Aider, Cursor, Codex, etc.) when working with code in this repository.

项目定位

尚数网可信数据空间(Shangshuwang Trusted Data Space)—— 在 SSWFlow 隐私计算编排平台之上升级出的、对标国家标准的可信数据空间体系。需求基线见 docs/功能清单.md(FL)+ docs/附件1:技术协议_可信数据空间_0512.docx(TP),所有功能点必须实现。

完整工程视角总览见 docs/PROJECT.md(建议先读 docs/arch/ARCHITECTURE.md 理解三子系统边界)。

顶层目录速览

目录 技术栈 职责
boot/ Spring Boot 3 + JNPF 7.0 + Java 21(src=17) + Maven 后端聚合工程,统一入口 ssw-admin
web/ Vite + Vue3 + TS + ant-design-vue 临时前端(AI/手写轻量 dev 入口)
jweb/ Vben + Turbo + pnpm JNPF 官方前端 monorepo;dev 入口 = apps/jnpf-web-apps-main(port 3000)
jweb/apps/jnpf-web-apps-main/src/views/ssw/ Vue3 + TS SSW 业务代码真源(api/components/views/types/store/utils);web/src/views/ssw 软链至此
nax/ Python 3.9+ (Ray ≥2.9) 隐私计算执行引擎(PSI / LR / MLP / FedAvg / SCQL)
scard/ Go 1.21 安全平面(server + connector,软 PKI + 软 TPM)
docs/ Markdown 文档中心(README.md 为索引)
dacli/ TypeScript + commander 12 JNPF 低代码 CLI;详见 .claude/skills/dacli/SKILL.md(gitignored,本地工具)
refs/ 多语言 国标 / 开源参考(FISCO-BCOS、SecretFlow、SecretPad、WeDPR、PrimiHub、kuscia、tee、国标)—— 勿动
log/ 日志 运行时日志(按子系统分目录)
.claude/ 配置 Claude Code 项目配置(含 memory/ 软链到 .workbuddy/memory)
.workbuddy/memory/ Markdown 长期记忆 + 每日日志(通过 .claude/memory 软链访问)

三子系统(业务包)

后端 boot/ 下三个 Maven 模块对应三子系统,业务库、API 前缀、@DS 名一一对应:

代号 全称 Maven 模块 业务库 @DS API 前缀
TDS 可信数据空间管理服务平台 ssw-tds tds @DS("tds") /api/ssw/tds
TDC 数据接入连接器 ssw-tdc tdc @DS("tdc") /api/ssw/tdc
SSWFLOW 隐私计算流程编排 ssw-sswflow-{entity,biz,controller} sswflow @DS("sswflow") /api/ssw/sswflow

关键原则:

  • TDS(运营方中枢) ↔ TDC(数据持有方本地) ↔ SSWFLOW(密态计算执行后端)三足鼎立,数据不经平台,TDC 之间点对点交付。
  • SSWFLOW 算法算子从 V0.13 起走真实 Nax 引擎(engine="mpc"),通过 ProcessBuilder 调 boot/ssw-sswflow/ssw-sswflow-biz/src/main/resources/nax/nax_adapter.py。
  • TDC 多虚拟连接器通过 JNPF 内置 f_tenant_id 隔离,复用平台租户字段不单独设计。

命令速查

后端(必须在 boot/ 目录)

cd boot

# 编译(必须 -am 拉所有业务模块)
mvn -pl ssw-admin -am package -DskipTests

# 启动(端口必须 30000;-Dspring.profiles.active=dev 实测不生效)
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

⚠️ 后端必须宿主机网络启动(用 run_in_background),否则连不上 192.168.97.0/24 上的容器化 Postgres / Redis。不要用 nohup ... & 双重后台。

前端(jweb/apps/jnpf-web-apps-main,官方 jnpf_app_ 动态路由)

cd jweb/apps/jnpf-web-apps-main && pnpm dev    # http://localhost:3000,冷启动 30s+(接受)

唯一入口机制 = JNPF 官方多 app + 后端菜单动态路由注册:

  • http://localhost:3000/login、/home —— 主平台
  • http://localhost:3000/jnpf_app_{appCode}/login、/home —— 子 app(勿改 APP_PREFIX,影响平台)
  • 路由不写死在前端:登录后 setupAccessGuard → generateAccess()(src/router/access.ts)拿后端菜单 (accessStore.backMenus)动态注册,菜单的 urlAddress 映射到 pageMap 里的组件。
  • ⚠️ pageMap = import.meta.glob('../views/**/*.vue') —— 官方只扫描 src/views/**。 SSW 业务真源已迁到 src/views/ssw/**(即 src/views/ssw/views/{tds,tdc,sswflow}),已被该 glob 自动覆盖,无需改 access.ts。
  • 菜单/应用由后端数据驱动,用 dacli(dacli/src/cli.ts)的 app create / menu create --type=2 --urlAddress 建。

❌ test_app_ 轻量入口机制已废弃并于 2026-08-06 彻底移除(views/testApp/、router/routes/testApp.ts、 TEST_APP_PREFIX、getTestAppEnCode()、test-pages.json 全部删除,guard.ts 已还原官方版)。 不要再重建这套东西 —— 一律走上面的 jnpf_app_ 官方动态路由。

SSW 业务代码真源(web / jweb 双栈共享,见 .workbuddy/memory/MEMORY.md):

  • 真源落盘 jweb/apps/jnpf-web-apps-main/src/views/ssw/{api,components,views,types,store,utils}(67 个 .vue:35 tds + 23 tdc + 9 sswflow)
  • web/src/views/ssw 是指向它的软链(web 仅作临时调试入口)
  • 真源按 jweb 规范写:import { defHttp } from '@/api/request',内部 import 用 @/views/ssw/*,API 前缀 /api/ssw/*
  • request → defHttp 翻译规则:
    • request.get(url, { params: q }) → defHttp.get({ url, params: q })
    • request.post(url, d) → defHttp.post({ url, data: d })
    • request.put(url, d) → defHttp.put({ url, data: d })
    • request.delete(url) → defHttp.delete({ url })
    • 非 GET 带 query 时 params 会被吞进 body → 加 requestOptions: { joinParamsToUrl: true }
    • api 层统一 .then((r) => r.data) 解包,视图直接消费 res.xxx

旧 web/ 仍是 AI 手写栈临时入口(port 5173,独立),可继续用于纯前端调试:

cd web && pnpm dev    # port 5173,独立轻量栈
  • dev server 进程被杀后端口不再监听,用 run_in_background 启动,别用 nohup 双重后台
  • 类型检查:pnpm exec vue-tsc --noEmit(在对应 app 目录内)
  • 生产构建:pnpm build(子系统独立分包 + vendor)

Nax 引擎(nax/)

cd nax
pip install -e ".[dev]"          # 可选 [ray]
pytest                            # 全量
pytest -m 'not slow'              # 跳过长用例(公钥密码学预处理)
pytest tests/<file>::<test> -v    # 单测

Nax 默认 LocalBackend;NAX_BACKEND=ray 切到 Ray 集群(V0.14 自动化 Party endpoint → Ray 资源映射)。nax/examples/12_k8s_two_party/ 是 k8s 跨方示例。

安全平面(scard/code/)

cd scard/code
export PATH=$HOME/go/go/bin:$PATH
export GOPROXY=https://goproxy.cn,direct
go build ./...                          # 全量
go build -o bin/security-server ./server
go build -o bin/connector ./connector
go test ./common/crypto/... -v          # 单测

scard 详细文档见 docs/security/SECURITY_PLANE.md 与 scard/CLAUDE.md(包含 Zynq-7015 硬件配置、SSH 方式、MAC 冲突修复等)。

JNPF 前端 monorepo(jweb/,仅参考)

cd jweb
pnpm dev            # turbo-run dev
pnpm build          # turbo build
pnpm dlx vsh check-circular && pnpm dlx vsh check-dep

依赖锁定 [email protected]、Node >=20.19.0,运行时 NODE_OPTIONS=--max-old-space-size=8192。这是 vendor 代码,不要直接改。

关键约定(必读)

鉴权(前端 crypto-js + 后端 Sa-Token)

  • 密码加密: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(不是 /api/ssw/login),Content-Type: application/x-www-form-urlencoded,body account=admin&password=<加密>&grant_type=password;发 JSON 或漏 grant_type → 400「不支持此登录方式」
  • token:登录返回 data.token="bearer eyJ...",原样存,请求头 Authorization: <token>;Sa-Token getTokenPrefix="bearer" 只剥小写前缀,大写 Bearer → 600 登录过期
  • 必带头:App-Code: sswflow / Jnpf-Origin: pc / Vue-Version: 3

数据库

  • ⚠️ 所有表都建在 public schema(DSN currentSchema=public),不要写 sswflow. / tds. / tdc. 前缀
  • 三库物理隔离:sswflow / tds / tdc 同 PostgreSQL 实例(192.168.97.3:5432,user=dacli,pwd=dacli123),各自独立数据库
  • 表前缀按子系统识别:flow_* / tds_* / tdc_*
  • 迁移手动执行(无 Flyway):boot/db/V1.0.0__schema.sql(基线)、V1.0.2__flow_run_scope.sql、V1.0.3__flow_schedule.sql;用 psycopg2 / psql 跑,先剥 -- 注释再按 ; 切分
  • 软删除:f_delete_mark=1,查询带 f_delete_mark IS NULL
  • TDS 新建记录勿 setDeleteMark(0),保持 NULL(TdcCrudController 允许 (f_delete_mark IS NULL OR =0),TdsCrudController 只认 IS NULL)

后端规范(对齐 JNPF 7.0)

完整版见 docs/JNPF_BACKEND_GUIDE.md,易踩坑要点:

  • scanBasePackages 必须写 Java 顶级包 jnpf(不是 Maven groupId com.jnpf!写错无报错但鉴权/DS 全失效)
  • SswAdminApplication.main() 必须 addInitializers(new jnpf.util.context.SpringContext())(FQN 是 jnpf.util.context.SpringContext 而不是 jnpf.SpringContext;代码注册而不依赖 META-INF 是因为 fat-jar repackage 后路径错位)
  • application.yml 必须:spring.main.allow-bean-definition-overriding: true + spring.mvc.pathmatch.matching-strategy: ant_path_matcher
  • 实体基类用 SuperExtendEntity<String>(带 sortCode,已 javap 确认;非 SuperEntity<String>)
  • 业务 Service 统一 extends SswflowServiceImpl<Mapper,Entity>(已实现 DynamicSourceGeneratorInterface,DS_KEY="sswflow")
  • 显式 bean 名防 JNPF 内部撞名:Controller @RestController("sswflowXxxController")、Service @Service("sswflowXxxService"),实体 @Alias("SswflowXxxEntity")
  • @DS 严格模式:Entity 上的 @DS 不一定生效,Mapper 和 ServiceImpl 都要加 @DS("tds") / @DS("tdc") / @DS("sswflow")
  • 禁 @Transactional(强切 master);updateById 跳 null,重置用 "NONE" 哨兵
  • 实体表必含 10 基类列(SuperExtendEntity 全字段),否则 SELECT 报 column not exist
  • JNPF 源码只要本地 ~/.m2/repository/com/jnpf/ 有 jar 即可;首次部署按 JNPF_BACKEND_GUIDE.md §〇-B.1 clone 官方模块到 ~/workspace/jnpf/ 平级目录后 mvn install

前端规范

  • web/ 三级导航:App.vue 顶栏 subsystems[](tds/tdc/sswflow)+ 侧栏由 router.getRoutes() 过滤 meta.subsystem 推导(避免菜单与路由漂移)
  • 通用 CRUD 骨架:web/src/components/ssw/common/CrudPage.vue,props {title, api, columns, filters, actions, extraQuery, defaults, prompt?};列表响应读 res.list(后端返回 {pagination, list})
  • axios 拦截器解开 ActionResult.data,重声明 SswRequest 解决类型报错
  • 子系统路由:web/src/router/modules/{tds,tdc,sswflow}.ts,API 客户端:web/src/api/ssw/{tds,tdc,sswflow}.ts

算子协议(SSWFLOW 子系统)

  • 类别:source / prep / stat / model / sink
  • label(非 name);key 形如 source.dataset / prep.intersect;params type:DATASET / COLUMNS / STRING / SELECT / BOOL / INT / FLOAT / PARTY / SLIDER
  • engine="local" → SimulationComputeEngine(兜底);engine="mpc" → NaxComputeEngine(order=100,首选);engine="tee" → 预留(TEE 引擎 V0.14+)
  • 新增算子:stat.scql(密态 SQL)/ model.mlp.train(密文 MLP)/ model.fedavg.train(横向联邦)/ model.gbdt.train(不支持 mpc → FALLBACK)

架构图(一句话版)

┌─────────────────────────────────────────────────────────────┐
│  区域 / 行业功能节点(上级)  身份核验 / 产品登记 / 信息上报   │
└──────────────────────────────┬──────────────────────────────┘
                               │ ① 注册/上报/核验
┌──────────────────────────────┴──────────────────────────────┐
│  TDS 可信数据空间管理服务平台  身份·空间·连接器·目录·合约·   │
│                              使用控制·审计·运营·应用生态      │
└──┬───────────────┬──────────────┬───────────────┬──────────┘
   │ ②③④        │ ③合约下发     │ ⑥编排调度     │ ⑤关键操作上链
┌──┴──────────┐  ┌─┴───────────┐ ┌┴────────────┐ ┌┴──────────┐
│ TDC 连接器   │  │ TDC 连接器   │ │ SSWFLOW 编排 │ │ 飞梭链    │
│ (供方)        │  │ (需方)        │ │ (DAG·运行)      │ │ (开源)    │
└──┬───────────┘  └──────────────┘ └──┬────────────┘ └───────────┘
   │ ④数据交付(点对点,不经平台)        │ ⑦沙箱调度
   └────────────────────────────┐        │
                                ▼        ▼
                  ┌─────────────────────────────┐
                  │ 密态计算底座                 │
                  │ · scard 安全平面(Go)        │
                  │ · nax 引擎(Python / Ray)    │
                  │ · kata confidential containers │
                  │ · TEE(CVM / AMD SEV)        │
                  │ · JupyterLab                 │
                  └─────────────────────────────┘

scard → TDS 集成(V1.3.2+):DB 迁移 tds_security_device / tds_attest_record + tds_connector +4 列;Java 桥 SecurityPlaneClient + SyncService @Scheduled(30s cron) + SecurityDevice/AuditController;前端 /tds/security 镜像至 SSWFlow 管理面。详情 docs/security/SECURITY_PLANE.md。

验证脚本

  • /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 代理端到端验证
  • docs/tdd/nax_e2e_smoke.cjs — Nax 引擎烟测(PSI/LR/MLP/FedAvg/SCQL)

参考完整端到端验证报告:docs/VERIFICATION_2026-08-02.md(TDS+TDC 62/62)、docs/tdd/P1P2_CHAIN_K8S_REPORT.md(飞梭链 + k8s 沙箱/TEE)、docs/sswflow/NAX_ENGINE.md(Nax 引擎 V0.13)。

移动目录注意事项

  • 工作区相对路径全部存在 .claude/memory(软链到 .workbuddy/memory)与 boot/db/,移动目录前:
    1. lsof :30000 杀后端 java 进程
    2. lsof :5173 杀前端 vite 进程
    3. 移动后 /Users/xs/.workbuddy/{SOUL,IDENTITY,USER}.md 不受影响(用户级独立存储)
    4. 移动后须重新创建 .claude/memory 软链:ln -s .workbuddy/memory .claude/memory
  • 不要破坏 boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar——已编译产物;如需重编 mvn -pl ssw-admin -am package -DskipTests
  • web/pnpm-lock.yaml 锁定前端依赖完整版本图,移动后 pnpm install 会快很多

记忆与上下文

  • 长期笔记:/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(用户级,与项目无关;不要迁移到 .claude/)
  • 对话历史检索:使用 conversation_search 工具