# 按 JNPF 规范快速搭建后端框架(SSW 公司内部规范)· 增强版 > 适用版本:JNPF 7.0.0-RELEASE(Spring Boot 3.5.x,jakarta.*,Java 21 运行时 / 编译目标 17) > 适用场景:在 JNPF 低代码平台之上,挂载**自有业务模块**,复用其登录/鉴权/ORM/响应体系,同时不污染 JNPF 自身包。 > 编写依据:本版基于原 `JNPF_BACKEND_GUIDE.md`,通过一个**仅依据原文档、从零搭建可编译可运行脚手架**(位于本仓库 `boot/` + `tss-web/`,`app_code=tss`)的实践,逐项核对并修正了原文档中所有会导致「编译失败 / 打包失败 / 启动即崩 / 静默失效」的问题。 > 状态:**已验证可落地(增强版修正项均已用真实构建复核)** > 原文档 `JNPF_BACKEND_GUIDE.md` **保持不动**,本文件为修正后的新版本。 > **示例占位约定**:本文沿用原文档的 `sswflow` 作为 `app_code` 示例(保持可复用),实际落地时按规则替换: > `sswflow → <你的 app_code>`、`Sswflow → `、`SswflowXxxService → XxxService`、`库 sswflow → <你的 app_code>`、`API /api/ssw/sswflow → /api/ssw/<你的 app_code>`。 > **关键:业务库名 == app_code**(双库架构下每个 app_code 独立库,`dynamic.datasource.` 与 `@DS("")` 同名)。 > > 已落地验证: > - `tss`(首版):脚手架见 `boot/` 与 `tss-web/`,可直接对照。 > - `tss2`(二次验证,本仓库 `tss2/`):**仅依据本指南、不参考任何其它脚手架、不启用容器**,从零落地第二个应用。后端 `mvn -o package -pl ssw-admin -am` 构建通过、前端 `npm run build` 通过、密码算法自检 PASS。证明本指南可复用;落地中暴露的缺口已在 **第十六节** 补齐。tss2 命名映射见 16.1。 --- ## 〇、核心结论(先看这段) 1. **不要从零写框架**——直接复用 JNPF 的 `boot` 启动模块 + `jnpf-common-all` 依赖栈。你只需要写**业务包**。 2. **业务包三层结构**:`ssw-{app_code}-entity` / `-biz` / `-controller`,全部挂在 `ssw-{app_code}` 父 pom 下。 3. **API 前缀**:`/api/ssw/{app_code}/...`,与 JNPF 的 `/api/...` 并存不冲突。 4. **双库架构(必做)**:JNPF 系统表走 `master`(库 `j7`),你的业务表放独立业务库(库 `sswflow`),用 **`@DS("sswflow")`** 切换。JNPF 内置 `dynamic-datasource`,这是平台标准机制。 5. **鉴权完全复用 JNPF**:Sa-Token + `/api/oauth/Login`,前端只负责"加密密码 + 原样带 token"。 6. **两个必踩的碰撞坑**(不处理就启动即崩):Spring bean 名冲突、MyBatis type-alias 冲突。 7. **⚠️ 最易翻车的两类"静默/硬失败"已在本版订正**: - `scanBasePackages` 必须写 Java 顶级包 **`jnpf`**(不是 Maven groupId `com.jnpf`),写错**无报错但鉴权/数据源全失效**(见 〇-A·A)。 - 打包后启动会 `NoClassDefFoundError: ThreadPoolExecutorUtil`——`META-INF/spring/...ApplicationContextInitializer` 被 repackage 提到 fat-jar 根目录后读不到,**必须代码注册 initializer**(见 〇-A·F、§12.1)。 8. **JNPF 源码只需本地 `~/.m2` 有 jar 即可**:私有仓库要鉴权,离线 `mvn` 拉不到 `jnpf-common-*` 的 jar。首次按「〇-B.1」clone 并 `mvn install` 进本地仓库;之后只要 `~/.m2` 里 `com/jnpf/**` 的 jar 还在(本机留存或拷自他人),直接编译业务模块即可。 --- ## 〇-A、相对原版的修正清单(速览) | 编号 | 原文档位置 | 原文档问题 | 本版修正 | 严重程度 | |---|---|---|---|---| | A | §〇-B.3(2)、§3.2、§14-2 | `scanBasePackages={"com.jnpf","ssw"}` | 改为 `{"jnpf","ssw"}`;明确 `com.jnpf` 只是 Maven **groupId**,Java 顶级包是 `jnpf` | 🔴 静默失效(无报错,鉴权/DS 全挂) | | B | §4.1、§4.2、§9.3 | `extends EntityBase` | 改为 `extends SuperEntity`(`EntityBase` 在 7.0.0 不存在) | 🔴 编译失败 | | C | §3.2 | entity pom 裸写 `mybatis-plus-boot-starter` / `dynamic-datasource-spring-boot-starter` 且无 `` | 删除这两个依赖(随 `jnpf-common-all` 传递引入);确需锁版本必须显式写 `` | 🔴 `mvn validate` 失败(缺 version) | | D | §3.2 | 未说明 lombok 需自行声明 | entity(及用 `@Data` 的模块)pom 显式加 `org.projectlombok:lombok`(scope=provided);父 pom 全局加一份 | 🔴 编译失败(找不到 `getXxx()`) | | E | §〇-B.3 末、§12、§14 | `mvn package -DskipTests -pl ssw-admin -o` | 改为 `mvn -o package -DskipTests -pl ssw-admin -am`(`-am` 把业务模块纳入 reactor) | 🔴 打包失败(解析不到 `ssw-tss-controller`) | | F | §〇-B.3(4)、§12.1 | `jnpf.SpringContext`(FQN 错);仅靠 `META-INF` 文件注册 | FQN 改为 `jnpf.util.context.SpringContext`;且**必须在 `SswAdminApplication.main()` 代码注册** initializer | 🔴 打包后启动 `NoClassDefFoundError` | | G | §9.4 | `getDataSource()` 签名/返回值说明含糊 | 接口实为 ` T getDataSource()`,`init(String)` 返回 `DbLinkEntity`(其父类即 `DataSourceUtil`),原写法可编译,补澄清 | 🟡 澄清(原代码能编) | | H | §8.2 | 旧版把内层写成 `MD5(密码)` 误判为 bug;后又把「原始明文」错当成唯一标准 | **最终定稿为双约定模型**:传输层内层 S 有两种——**官方默认** `S = md5(明文)`(96-hex,`d4958348…`),**旧变体** `S = 明文`(32-hex,`ea80d323…`);存储层随之 `md5(S + f_secretkey.toLowerCase())`。两条约定都合法但互不相通,关键看账号 `f_password` 用哪种。关键陷阱:`SecurityProperties` setter 内部自动 MD5 → 16 字符 key 实际变 32 字节 = AES-256。dacli `src/core/crypto.ts` 与 `tss2` 实测均为官方约定 | 🔴 算法级错误(选错约定即登录失败) | | I | §12.2 | 只有片段 | 提供零依赖 `scripts/smoke.mjs`(自检+登录+业务接口,支持 `--base/--account/--password/--key/--appcode`) | 🟢 可验证性 | | J | §〇-B.3、application.yml | 未要求 `allow-bean-definition-overriding` | `application.yml` 必须 `spring.main.allow-bean-definition-overriding: true`(JNPF 内部同名 bean) | 🔴 启动失败 | | K | §12.1、application.yml | 未要求 `mvc.pathmatch` 策略 | `spring.mvc.pathmatch.matching-strategy: ant_path_matcher`(JNPF 用 ant 路径匹配) | 🔴 启动/路由异常 | | L | §8.2-B | 未解释自建账号登录报 `400 账号权限不足` | 给出根因(超管旁路硬编码只认账号名 `admin`,非 admin 必须挂角色且角色有 `base_authorize`)+ 挂「管理员」角色 SQL + 登录错误码速查(LOG101/LOG004/LOG005/OA013) | 🔴 自建账号无法登录 | | M | §16.6 | 未记录运行期实测坑 | 新增「运行期实测暴露的 5 个坑」:`SERVER__PORT` 端口漂移、容器名≠发布端口+Redis 未映射、`dynamic.datasource` 少一层、`base-path` 不可写、后台进程被 shell 回收 | 🟡 排障加速 | | N | §16.8 | 未给造验证账号脚本 | 新增「造验证账号完整脚本」:`md5(明文+secretkey.toLowerCase())` 算 `f_password` + 复制 admin 行插 `base_user` + 插 `base_role_relation`(含 `ON CONFLICT` 处理) | 🟢 可复现 | > 严重程度图例:🔴 阻断(编不过/起不来) 🟡 澄清 🟢 增强可验证性 --- ## 〇-B、环境准备:获取官方源码 / 私服 / 数据库中间件 / admin 骨架 > 这一节是「前置的前置」——在写任何业务代码之前,先把**官方源码拿到、私服配通、数据库与 Redis 跑起来、boot 启动骨架复制好**。 > 参考:`~/Desktop/workspace/jnpf/init/start.md`、JNPF 官方 `jnpf-java-boot/README.md`。 ### 〇-B.1 从官方仓库 git clone JNPF 7 后端源码 官方仓库托管在 **coding.jnpfsoft.com**,后端按模块拆分,**每个模块是独立 git 仓库**,统一挂在 `/v7.0/` 路径下。 ``` 官方根域:https://coding.jnpfsoft.com/v7.0/ 登录账号:53738880@qq.com 登录密码:jnpf@ssw ``` **后端核心模块清单(按 start.md):** | 模块 | 说明 | |---|---| | `jnpf-java-boot` | **聚合工程**(含 `jnpf-admin` 子模块),编译入口 | | `jnpf-common` | Java 基础依赖项目源码(被所有模块依赖) | | `jnpf-java-ai-core` | AI 核心依赖源码 | | `jnpf-file-core-starter` | 文件基础依赖 | | `jnpf-workflow` / `jnpf-workflow-core` | Flowable 流程引擎 | | `jnpf-bpmn` | BPMN 相关 | | `jnpf-datareport` / `jnpf-java-datareport-univer(-core)` | 报表 | | `jnpf-scheduletask` | 任务调度 | | `jnpf-java-tenant` | 多租户(按合同交付) | | `jnpf-database` | **数据库脚本仓库**(j7 / j7flow / j7xxl 初始化 SQL) | | `jnpf-resources` | 静态资源(ip2region、模板等) | > 你**只需要 clone `jnpf-java-boot` 一个仓库**——它是聚合工程,pull 下来后内部 `jnpf-admin` 子模块、以及它依赖的 `jnpf-common` 等兄弟模块,都要**各自 clone 到同级目录**才能 `mvn install`(聚合 pom 用相对路径引用兄弟模块)。 > **增量复用(核心:别每次全量 clone)** > > | 场景 | 做法 | > |---|---| > | **首次**拿到源码 | 按下面 `git clone` 把需要的模块拉到 `~/workspace/jnpf`(平级目录) | > | 已 clone 过,要更新 | 进各模块目录 `git pull`(**不要重新 clone**) | > | `~/.m2` 里 `com/jnpf/**` 的 jar 还在(同机留存或拷自他人) | **根本不需要源码**:直接 `mvn package` 你的业务模块即可;源码仅在你改了 JNPF 自身代码时才需重新 `mvn install` | > | 只缺某几个模块 jar | `cd ~/workspace/jnpf/ && mvn install -DskipTests`(无需重装全部) | > > 一句话:**`git clone` 是一次性动作;`mvn install` 把 jar 沉淀到 `~/.m2` 之后,日常只跟自己的业务模块打交道。** > 同机协作时,把 `~/.m2/repository/com/jnpf` 整体拷给对方,对方连 clone 都省了。 ```bash # 1) 建一个总目录,所有 JNPF 模块平铺其中(路径禁止含中文/空格/特殊字符,README 特别说明) mkdir -p ~/workspace/jnpf && cd ~/workspace/jnpf # 2) clone 聚合工程(仅【首次】需要;之后用 git pull 更新,见上表) git clone https://coding.jnpfsoft.com/v7.0/jnpf-java-boot.git # 3) clone 它依赖的兄弟模块(与 jnpf-java-boot 同级) git clone https://coding.jnpfsoft.com/v7.0/jnpf-common.git git clone https://coding.jnpfsoft.com/v7.0/jnpf-java-ai-core.git git clone https://coding.jnpfsoft.com/v7.0/jnpf-file-core-starter.git git clone https://coding.jnpfsoft.com/v7.0/jnpf-workflow.git git clone https://coding.jnpfsoft.com/v7.0/jnpf-workflow-core.git # ... 其余模块按需 clone(见上表) # 4)(可选)数据库脚本与静态资源 git clone https://coding.jnpfsoft.com/v7.0/jnpf-database.git git clone https://coding.jnpfsoft.com/v7.0/jnpf-resources.git # 免去每次输密码:把凭据缓存到 ~/.git-credentials git config --global credential.helper store ``` > **踩坑提示(来自 start.md)**:若某模块目录**缺失文件**,直接用上面的官方账号从对应仓库 `git clone` 补齐即可;官方包地址/账号密码齐全,缺的都能下到。 --- ### 〇-B.2 配置 Maven settings.xml 引用官方私服 JNPF 的依赖(`jnpf-common-*`、`dynamic-datasource` 等定制版)**不在 Maven Central**,只在官方私服 `maven-releases`。不配私服会 `Could not resolve ... 401/404`,离线环境更是直接编不过。 > 7.0 的 `jnpf-dependencies` 内部仓库声明用的是 `http://nexus.jnpfsoft.com/repository/maven-public/`,而官方 README 文档写的是 `https://repository.jnpfsoft.com/repository/maven-public/`。**两者 server id 都是 `maven-releases`**,所以只要下面 settings.xml 里 `` 的 id 配成 `maven-releases`,就能同时覆盖这两种地址。 **放在哪**:用户级 `~/.m2/settings.xml`(推荐),或 Maven 安装目录 `conf/settings.xml`。在对应节点里加入: ```xml maven-releases rong@shangshu.net.cn ssw222666 maven-releases * maven-releases https://repository.jnpfsoft.com/repository/maven-public/ ``` > 配好后 `mvn` 就能从官方私服拉依赖。IDEA 若出现部分依赖报红,重启 IDEA 清缓存即可(README 原话)。 > 注意 `~/.m2/settings.xml` 默认是 Maven 的**示例模板**,本身没有任何 ``,初次使用时务必补上上面的内容。 --- ### 〇-B.3 复制 jnpf-java-boot/jnpf-admin → boot/ssw-admin(有部分需要调整) `jnpf-admin` 是聚合工程 `jnpf-java-boot` 下的**可运行 jar 模块**——它自己不编 JNPF 各 controller 源码,只 `pom` 依赖 `jnpf-*-controller` 等 jar(这些 jar 来自 〇-B.1 的 `mvn install`)。我们要做的,就是把它**整体复制成自己的 `ssw-admin` 启动骨架**,再改少量配置。 **源 → 目标:** ``` jnpf-java-boot/jnpf-admin/ ──复制──▶ boot/ssw-admin/ ├── pom.xml ├── src/main/java/jnpf/ ──包名 jnpf → ssw──▶ src/main/java/ssw/ └── src/main/resources/ ──整目录拷──▶ src/main/resources/ ├── application.yml / application-dev.yml ├── application-{dev,test,prod,preview}.yml ├── mapper/ i18n/ logback-spring.xml ip2region/ sharding-sphere.yml ├── static/ (no-spa 静态页,用 Vite 独立前端可删) └── META-INF/spring/... (若已有 initializer 文件,保留) ``` **必须调整的部分(否则编不过或跑不起来):** 1. **`pom.xml` 父子关系** - `` 从 `jnpf-java-boot` 改成你自己的聚合父 `ssw-boot`(或直连 `jnpf-common`)。 - `` 改成 `ssw-admin`。 - `` 保留 JNPF 各 `*-controller`(完整清单见 §3.2 末的 `ssw-admin/pom.xml` 示例);**新增你自己的业务 controller**,例如: ```xml com.jnpf ssw-sswflow-controller ${project.version} ``` > 注意 `com.jnpf` 这里是对的——它是 Maven **坐标的 groupId**;只有 Java 源码包名才是 `jnpf`(见第 2 点)。 - `` 里的 `boot3`(`jdk[17,)` 激活 `jnpf-ai-v3-controller`)**原样保留**——它正是 Boot 3 下启用 AI controller 的关键。 2. **包名 `jnpf` → `ssw`** - `src/main/java/jnpf/` 整个包重命名为 `ssw/`,启动类 `JnpfAdminApplication` → `SswAdminApplication`。 - ⚠️ **【修正 A】`scanBasePackages` 必须写 Java 顶级包 `jnpf`,不能写 groupId `com.jnpf`**: ```java @SpringBootApplication(scanBasePackages = {"jnpf", "ssw"}) ``` 写成 `{"com.jnpf","ssw"}` 会导致 JNPF 的自动配置(Sa-Token、dynamic-datasource、MyBatis 等)**全部不生效**,且**启动时不报任何错**,表现为登录 404 / 注入失败,极难排查。`com.jnpf` 只是 `pom.xml` 的 `` 与依赖坐标前缀,与 Java 包名无关。 - 同时 `@MapperScan` 要覆盖两侧:`@MapperScan({"jnpf.**.mapper", "ssw.**.mapper"})`。 3. **白名单 / AuthFilter** - 用独立 Vite 前端时,`gateway.exclude-url` 保留 JNPF 默认即可(无需 `/ssw/**`)。 - 若仍塞 no-spa 静态页,需加 `- /ssw/**`(见第 8.4 节)。 4. **Boot 3 两个补丁(否则登录时 `NoClassDefFoundError: ThreadPoolExecutorUtil`)** - 提供 `applicationTaskExecutor` bean(JNPF 的 `ThreadPoolExecutorUtil` 静态块依赖它)。示例见 `ssw/config/TaskExecutorConfig.java`。 - **【修正 F,关键】注册 `SpringContext` initializer 有两条路径,缺一条都会炸:** - (a) 文件 `src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer`,内容一行: ``` jnpf.util.context.SpringContext ``` (原文档写的 `jnpf.SpringContext` 是**错的**,全限定名是 `jnpf.util.context.SpringContext`。) - (b) **并且**在 `SswAdminApplication.main()` 里**代码注册**(这才是打包后可靠的方式): ```java SpringApplication application = new SpringApplication(SswAdminApplication.class); application.addInitializers(new jnpf.util.context.SpringContext()); application.run(args); ``` - **为什么必须代码注册**:`spring-boot-maven-plugin` 在 `repackage` 时会把 `target/classes/META-INF/` 提升到 **fat-jar 根目录**,而 Boot 3 的 `LaunchedClassLoader` 只加载 `BOOT-INF/classes` 与 `BOOT-INF/lib/*.jar`——根目录的 `META-INF/spring` 不在 classpath 上。于是**打成 jar 后该文件读不到**,启动表现为 `NoClassDefFoundError: Could not initialize class jnpf.util.ThreadPoolExecutorUtil`。代码注册不受打包结构影响,是最可靠的路径;文件 (a) 作为 IDE 直跑时的双保险保留。 5. **`application-dev.yml` 数据源与 Redis** - `spring.datasource.db-name: j7`(master 系统库),`host/port/username/password` 指向你的 PG。 - `spring.redis.redisson.config` 的 `address` 指向你的 Redis 实例,`password` 与 Redis 实际密码对齐(JNPF 默认 `123456`,纯镜像无密码时要二选一对齐,见 §11)。 - `dynamic.datasource.sswflow` 业务库节点按第 9.2 节声明。 6. **可选清理** - 用 Vite 独立前端可删除 `src/main/resources/static/ssw/**`(不影响启动)。 - 不用的 JNPF 模块依赖可在 `pom` 里裁剪,但建议先全留、跑通后再减。 > **【修正 E】复制完成后构建命令**: > ```bash > cd boot && mvn -o package -DskipTests -pl ssw-admin -am > ``` > 必须带 **`-am`(also-make)**——否则 reactor 里没有 `ssw-tss-*` 业务模块,会报 > `Could not resolve com.jnpf:ssw-tss-controller:... has not been downloaded`。 > 成功产物:`ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar`。 --- ### 〇-B.4 安装 j7 数据库与 Redis(镜像方式,最快) 为了快速起环境,直接用阿里云个人版容器镜像仓库的现成镜像(PostgreSQL 16 + Redis),免去了手动装数据库。 **镜像地址:** ``` PostgreSQL:crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine Redis: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest ``` ```bash # 1) 拉取镜像 docker pull crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine docker pull crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest # 2) 起 PostgreSQL(用户名/密码/默认库 与 JNPF 约定一致:dacli / dacli123 / j7) docker run -d --name jnpf-postgres -p 15432:5432 \ -e POSTGRES_USER=dacli -e POSTGRES_PASSWORD=dacli123 -e POSTGRES_DB=j7 \ crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine # 3) 起 Redis(JNPF 默认 redisson 密码 123456;纯镜像无密码,这里用无密码启动, # 然后把 application-dev.yml 的 redisson password 清空对齐;或加 --requirepass 123456) docker run -d --name jnpf-redis -p 6379:6379 \ crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest # 4) 验证 docker ps | grep -E "jnpf-postgres|jnpf-redis" ``` **初始化 j7 主库(来自官方 `jnpf-database` 仓库):** > **不必 clone 整个 `jnpf-database` 仓库**(体积大,平时只盯 SQL)。只需拿到下面 3 个 `.sql` 即可——用 `git sparse-checkout` 只拉 SQL 所在的目录,或直接从仓库下载对应文件: > ```bash > # 只取 SQL,不拉全量仓库(--sparse 后按需 set 目录) > git clone --filter=blob:none --sparse https://coding.jnpfsoft.com/v7.0/jnpf-database.git > cd jnpf-database && git sparse-checkout set > ``` > 若同机 `~/.m2` 已沉淀 JNPF 源码,`jnpf-database/` 通常已在 `~/workspace/jnpf/` 下,直接复用即可。 > start.md 明确:**只需装** 以下三个;`JNPF-PostgreSQL.sql` 是**租户初始库,不要装**。 | 脚本 | 导入目标库 | |---|---| | `jnpf_db_init` | `j7`(JNPF 主库,承载 `base_user`/组织/权限/字典) | | `jnpf_flow_init` | `j7flow`(Flowable 流程引擎库) | | `jnpf_xxljob_init` | `j7xxl`(XXL-JOB 调度库) | ```bash # 进入 PG 容器用 psql 导入(脚本从 jnpf-database 仓库取得) docker exec -i jnpf-postgres psql -U dacli -d j7 < /path/to/jnpf-database/jnpf_db_init.sql docker exec -i jnpf-postgres psql -U dacli -d j7flow < /path/to/jnpf-database/jnpf_flow_init.sql docker exec -i jnpf-postgres psql -U dacli -d j7xxl < /path/to/jnpf-database/jnpf_xxljob_init.sql # 另建业务库 sswflow 并执行你的建表脚本(见第 9 / 11 节) docker exec -i jnpf-postgres psql -U dacli -d postgres -c "CREATE DATABASE sswflow;" docker exec -i jnpf-postgres psql -U dacli -d sswflow < /path/to/sswflow/boot/db/V1.0.0__schema.sql ``` **网络与访问(重要):** - 容器内互相用容器名 `jnpf-postgres` / `jnpf-redis` 解析;宿主机若用 `.orb.local` 或容器 IP,启动 jar 时用 `-DDB_HOST=... -DREDIS_HOST=...` 覆盖(详见第 11 节 Netty DNS 注意)。 - 若宿主机直接用容器 IP(如 OrbStack 下 `192.168.97.3:5432` / `192.168.97.2:6379`),把 `application-dev.yml` 的 host 改成 IP 最稳。 --- ## 一、整体工程结构 ``` boot/ # 启动模块(拷贝 JNPF 的 boot 骨架) ├── pom.xml # 父:ssw-boot → jnpf-common → jnpf-dependencies ├── ssw-{app_code}/ # 你的业务父模块 │ ├── pom.xml # 聚合 entity/biz/controller │ ├── ssw-{app_code}-entity/ # 实体 + MyBatis XML │ ├── ssw-{app_code}-biz/ # Service 接口 + Impl + Mapper(含 @DS) │ └── ssw-{app_code}-controller/ # Controller(REST 入口) └── ssw-admin/ # 可运行 jar 聚合模块(打最终 boot jar) └── src/main/resources/ # application.yml / application-dev.yml / static ``` > 命名约定:`{app_code}` 用小写驼峰,例如 `sswflow`。**所有包名、bean 名、alias 都要带 `Sswflow`/`sswflow` 前缀**,这是避免与 JNPF 内部类冲突的唯一手段(详见第八节)。 --- ## 二、前置:编译 JNPF 源码(一次性,约 7 分钟) JNPF 的 `jnpf-common-all` 等构件不在公网 Maven 仓库,私有仓库需鉴权,离线构建会失败。 ```bash # 1. 取得官方源码(git clone 步骤见「〇-B.1」;私服配置见「〇-B.2」) # 至少 clone 聚合工程 jnpf-java-boot 及其依赖的兄弟模块(jnpf-common 等)到同级目录 cd /path/to/jnpf-java-boot # 2. 一次性编译安装到本地仓库(跳过测试/文档/gpg,否则很慢) mvn clean install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true ``` 完成后 `~/.m2/repository/com/jnpf/**` 会出现 `jnpf-common-all`、`jnpf-common-core`、`jnpf-oauth-*` 等全部 jar,你的业务模块才能编译。 > 验证:`ls ~/.m2/repository/com/jnpf/jnpf-common-all/7.0.0-RELEASE/` 应有 jar。 --- ## 三、Maven 关键配置 ### 3.1 boot3 profile 会锁死 Java 版本 `jnpf-dependencies` 的 `boot3` profile 把 `maven.compiler.source` 锁成 **8**(为了 JNPF 自有模块向后兼容)。你的新代码要用 Java 17 语法(switch 表达式、instanceof 模式匹配等),**必须在你的业务模块 pom 里覆盖**——最省事是在聚合父 `ssw-boot/pom.xml` 的 `` 统一设: ```xml 17 17 17 UTF-8 7.0.0-RELEASE sswflow ``` 不覆盖会报:`-source 8 中不支持 switch 表达式` / `instanceof 模式匹配`。 ### 3.2 业务包父链与依赖 ``` 你的 ssw-admin(打 jar) └─ 依赖 ssw-{app_code}-controller └─ 依赖 ssw-{app_code}-biz └─ 依赖 ssw-{app_code}-entity └─ 依赖 jnpf-common-all(提供 SuperEntity / ActionResult / @DS / Sa-Token 等) ``` > **【修正 C/D】`ssw-{app_code}-entity/pom.xml` 关键依赖(正确写法):** > > ```xml > > > > com.jnpf > jnpf-common-all > ${jnpf.version} > > > > > org.projectlombok > lombok > provided > > > > > ``` > 父 `ssw-boot/pom.xml` 也可以全局给一份 lombok(继承给所有子模块),与本模块声明二选一即可: > ```xml > > > org.projectlombok > lombok > provided > > > ``` **`ssw-admin/pom.xml` 依赖 JNPF 各 controller(完整清单,缺一不可,否则登录/`/api` 能力缺失):** ```xml com.jnpf ssw-sswflow-controller ${project.version} com.jnpfjnpf-oauth-controller${jnpf.version} com.jnpfjnpf-permission-controller${jnpf.version} com.jnpfjnpf-system-controller${jnpf.version} com.jnpfjnpf-file-controller${jnpf.version} com.jnpfjnpf-message-controller${jnpf.version} com.jnpfjnpf-extend-controller${jnpf.version} com.jnpfjnpf-flowable-controller${jnpf.version} com.jnpfjnpf-scheduletask-controller${jnpf.version} com.jnpfjnpf-visualdev-base-controller${jnpf.version} com.jnpfjnpf-visualdev-generater-controller${jnpf.version} com.jnpfjnpf-visualdev-onlinedev-controller${jnpf.version} com.jnpfjnpf-visualdev-portal-controller${jnpf.version} com.jnpfjnpf-visualdata-controller${jnpf.version} com.jnpfjnpf-app-controller${jnpf.version} boot3 [17,) com.jnpf jnpf-ai-v3-controller ${jnpf.version} ssw-admin-${project.version} org.springframework.boot spring-boot-maven-plugin ssw.SswAdminApplication org.projectlombok lombok repackage ``` --- ## 四、实体层规范(entity) ### 4.1 字段命名:JNPF 风格 `f_xxx` > **【修正 B】基类是 `jnpf.base.entity.SuperEntity`(7.0.0 中 `EntityBase` 不存在)。** > 继承后,以下 9 个公共字段与列映射**自动获得,不要在本类重复声明**,否则 MyBatis-Plus 会因重复列名报错: > > | Java 字段(父类) | 列名 | 说明 | > |---|---|---| > | `id` (SuperBaseEntity) | `f_id` | `@TableId`,UUID 字符串 | > | `tenantId` | `f_tenant_id` | | > | `creatorTime` | `f_creator_time` | 默认 `now()` | > | `creatorUserId` | `f_creator_user_id` | | > | `lastModifyTime` | `f_last_modify_time` | | > | `lastModifyUserId` | `f_last_modify_user_id` | | > | `deleteMark` | `f_delete_mark` | JNPF 约定 `null`=未删 | > | `deleteTime` | `f_delete_time` | | > | `deleteUserId` | `f_delete_user_id` | | ```java @Data @EqualsAndHashCode(callSuper = true) @Alias("SswflowProjectEntity") // ⚠️ 必须,防 MyBatis alias 碰撞(见第八节) @DS("sswflow") // ⚠️ 必须,切到业务库(见第九节) @TableName("project") public class ProjectEntity extends SuperEntity { // 业务字段(公共字段已在父类,无需也不应重复声明) @TableField("name") private String name; @TableField("project_code") private String projectCode; @TableField("compute_mode") // MPC / TEE / FL private String computeMode; @TableField("status") // DRAFT / ONLINE ... private String status; } ``` ### 4.2 公共字段基线(建议) | 字段 | 列名 | 说明 | |---|---|---| | 主键 | `f_id` | `@TableId`,UUID 字符串(来自 `SuperBaseEntity`) | | 创建时间 | `f_creator_time` | 默认 `now()` | | 创建人 | `f_creator_user_id` | | | 修改时间 | `f_last_modify_time` | | | 修改人 | `f_last_modify_user_id` | | | 删除标记 | `f_delete_mark` | JNPF 约定 `null` 表示未删除;查询条件 `f_delete_mark is null` | | 租户 | `f_tenant_id` | | | 删除时间 | `f_delete_time` | | | 删除人 | `f_delete_user_id` | | > 查询存活数据统一用常量,例如 `ALIVE = "f_delete_mark is null"`,默认排序 `f_creator_time desc`。 --- ## 五、Service 层规范(biz) ```java // 接口 public interface ProjectService extends IService { ActionResult pageList(ProjectPageForm form); void create(ProjectEntity e); } // 实现——⚠️ bean 名 + @DS 都必须显式指定 @Service("sswflowProjectService") @DS("sswflow") // ⚠️ 切到业务库;注解不继承,子类必须各自打 public class ProjectServiceImpl extends SswflowServiceImpl implements ProjectService { @Override public ActionResult pageList(ProjectPageForm form) { // 用 MyBatis-Plus 分页;JNPF 分页包装见第六节 } } ``` > **所有 `@Service` 实现类都加 `@Service("sswflowService")` + `@DS("sswflow")`**: > - bean 名防与 JNPF 内部 Service 碰撞(默认名会 `ConflictingBeanDefinitionException`); > - `@DS` 把读写路由到业务库,否则会落到 `master`(j7) 系统库。 > 推荐所有业务 Service 继承 `SswflowServiceImpl`(见 9.4),统一获得 `@DS` 兜底与动态自愈能力。 --- ## 六、Controller 层规范(controller) ```java // ⚠️ 必须显式 bean 名,JNPF 自带 jnpf.flowable.controller.OperatorController 会撞名 @RestController("sswflowProjectController") @RequestMapping("/api/ssw/sswflow/Project") public class ProjectController { @Autowired private ProjectService projectService; // 按 bean 名注入上面那个 @GetMapping("/All") public ActionResult> all() { return ActionResult.success(projectService.list()); } @GetMapping public ActionResult list(@RequestBody ProjectPageForm form) { return projectService.pageList(form); } @PostMapping public ActionResult create(@RequestBody ProjectEntity e) { projectService.create(e); return ActionResult.success("ok"); } } ``` ### 6.1 响应封装(JNPF 约定) | 场景 | 写法 | 返回形状 | |---|---|---| | 单对象/成功 | `ActionResult.success(data)` | `{code:200, data, msg:"Success"}` | | 分页 | `ActionResult.page(list, pagination)` | `{code:200, data:{list, pagination:{currentPage,pageSize,total}}}` | | 失败 | `ActionResult.fail("msg")` | `{code:非200, msg}` | | 登录过期 | 由 AuthFilter 统一返回 `code:600` | 前端据此清 token 跳登录 | > 分页 `PageListVO` 结构:`{ list: [...], pagination: { currentPage, pageSize, total } }`。 > 前端约定:**`code !== 200` 即视为错误**;`code === 600`(或 HTTP 401)视为未登录。 --- ## 七、必踩的两个碰撞坑(不处理启动即崩) ### 7.1 Spring bean 名冲突 JNPF 自带 `jnpf.flowable.controller.OperatorController`、`jnpf.*.service.OperatorService` 等。你的同名 Controller/Service 会触发: ``` ConflictingBeanDefinitionException: bean name 'operatorController' ... conflicts with jnpf.flowable.controller.OperatorController ``` **解决**:所有 Controller 加 `@RestController("sswflowXxxController")`,所有 Service Impl 加 `@Service("sswflowXxxService")`。 ### 7.2 MyBatis type-alias 冲突 JNPF 已有 `DataSetEntity`(注意大小写),你的 `DatasetEntity` 在**大小写不敏感**匹配下会撞: ``` The alias 'DataSetEntity' is already mapped to 'ssw.sswflow.entity.DatasetEntity' ``` **解决**:每个实体加 `@Alias("SswflowEntity")`(如 `SswflowDatasetEntity`),并 `import org.apache.ibatis.type.Alias;`。 --- ## 八、鉴权接入(复用 JNPF 体系,前端照做即可) ### 8.1 登录接口 ``` POST /api/oauth/Login Content-Type: application/x-www-form-urlencoded Headers: App-Code: {app_code} # 例如 sswflow Jnpf-Origin: pc Vue-Version: 3 Body: account=admin&password=<密文>&grant_type=password ``` ### 8.2 密码加密算法(前端/客户端实现) > **【修正 H · 2026-08-01 最终定稿】** 本节经「反编译官方字节码 + dacli 实测 + 本仓库 `tss2` 运行期验证」三证对齐,结论:**传输层内层字符串分两种约定,官方默认是 `md5(明文)`**。 > > | 约定 | 传输层内层 S | 密文长度 | 存储 `f_password` | 谁在用 | > |---|---|---|---|---| > | **官方(默认)** | `md5(明文)` 的 32 位 hex | **96 hex**(48 字节) | `md5( md5(明文) + secretkey )` | JNPF 官方前端、`admin`、dacli、本仓库 `tss2` | > | 旧变体(legacy) | `明文` 原文 | 32 hex(16 字节) | `md5( 明文 + secretkey )` | 部分老集成项目 | > > 两条约定**都合法,但互不相通**——关键看账号创建时存的是哪种 `f_password`。登录时后端先用 `DesUtil` 把密文解回内层字符串 S,再比 `md5(S + f_secretkey.toLowerCase())`。所以:用官方前端 / dacli 建的账号(含 `admin`)必须按官方约定登录;你自己造账号时可任选一种,只要 `f_password` 与约定配套(见 §16.8)。 务必先分清**两条独立的链路**,混淆是登录调不通的头号原因: | | 传输层(前端 → 后端) | 存储层(DB 里存什么) | |---|---|---| | 用途 | 把密码从浏览器安全送到后端 | 校验密码是否正确 | | 密钥 | 全局 `security.security-key` | **每个用户自己的** `base_user.f_secretkey` | | 算法 | AES-256-ECB / PKCS7,输出 hex | MD5 摘要,不可逆 | | 谁做 | 前端 `crypto.js` ↔ 后端 `DesUtil.aesOrDecode` | 后端 `PasswordTokenGranter` | **后端权威实现**(`jnpf-oauth-biz` → `jnpf.granter.PasswordTokenGranter#authenticatePassword`): ```java String pwd = form.getPassword(); try { pwd = DesUtil.aesOrDecode(pwd, false, true); // ① 传输层解密 → 拿回内层字符串 S } catch (Exception e) { log.error("{}:{}", MsgCode.OA013.get(), pwd, e); pwd = ""; } // ② 存储层比对:注意只对 secretkey 做 toLowerCase,S 原样拼接 if (!user.getPassword().equals(Md5Util.getStringMd5(pwd + user.getSecretkey().toLowerCase()))) { throw new LoginException(MsgCode.LOG101.get()); // 密码错误 } ``` #### ① 传输层:AES-256-ECB `DesUtil.aesOrDecode(data, isEncrypt=false, isAes=true)` 展开后等价于: ``` 输入 = hex 字符串 → HexUtil.decodeHex 还原字节 key = SecurityProperties.getInstance().getSecurityKey() 的 UTF-8 字节 算法 = SymmetricCrypto(AES, key) → JDK 默认 AES/ECB/PKCS5Padding 输出 = new String(内层字节, UTF-8) ``` **关键陷阱**:`SecurityProperties.setSecurityKey()` 的 setter **内部自动做了一次 MD5**: ```java public void setSecurityKey(String v) { this.securityKey = Md5Util.getStringMd5(v); // ← 配置值先被 MD5 } ``` 所以配置里写 `EY8WePvjM5GGwQzn`(16 字符),实际参与运算的 key 是 `md5("EY8WePvjM5GGwQzn")` = `05b0175907a859751f57a04d5a5ee9ac`(32 字符 hex 文本), 按 UTF-8 取字节 = **32 字节 → AES-256**(不是 AES-128)。 这正好与前端 `crypto.js` 的 `encryptAES(data, encryptByMd5(aesKey))` 对齐。 **官方约定(默认,JNPF 前端 / `admin` / dacli / 本仓库 `tss2` 都用这个)**:内层 S = `md5(明文)`,把它的 hex 字符串当明文做 AES: ``` CIPHER_KEY = EY8WePvjM5GGwQzn # 与后端 security.security-key 一致 key = md5(CIPHER_KEY) 的 32 位 hex 文本,UTF-8 取字节(32B,AES-256) S = md5(明文密码) 的 32 位 hex 字符串 密文 = Hex( AES256_ECB_PKCS7( UTF8(S), key ) ) # 96 hex ``` **旧变体(legacy,仅部分老集成项目)**:内层 S = 明文原文: ``` 密文 = Hex( AES256_ECB_PKCS7( UTF8(原始明文密码), key ) ) # 32 hex ``` > **自检基准值**(已用 Node `crypto` 与 `crypto-js` 双实现交叉验证,并跑通 `tss2` 真实登录): > > ``` > md5("EY8WePvjM5GGwQzn") = 05b0175907a859751f57a04d5a5ee9ac > # 官方约定(默认) > encryptPassword_official("123456") > = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b # 96 hex > # 旧变体(legacy) > encryptPassword_legacy("123456") > = ea80d323686b9dfe734f2b42159db1a6 # 32 hex > ``` > **对不上就别往下试登录**,一定是 key 或约定(官方 / 旧变体)选错了。 #### ② 存储层:`f_password` 怎么算 ``` # 官方约定(默认):S = md5(明文) base_user.f_password = md5( md5(明文密码) + base_user.f_secretkey.toLowerCase() ) # 旧变体(legacy):S = 明文 base_user.f_password = md5( 明文密码 + base_user.f_secretkey.toLowerCase() ) ``` - `f_secretkey` 是**每个用户一条、互不相同**的随机串,不是全局密钥。 - `security-key` **只管传输**,跟入库摘要毫无关系——这两个千万别搞混。 - 造验证账号时,按你选的约定算好 `f_password` 与 `f_secretkey` 一起 INSERT 即可(见 §16.8,本仓库 `tss2` 用官方约定)。 ```bash # 例:tss2dev 用【官方约定】生成 123456 的入库摘要(secretkey = tss2dev-secret-key-001) node -e "const c=require('crypto');const m=s=>c.createHash('md5').update(s,'utf8').digest('hex'); console.log(m(m('123456')+'tss2dev-secret-key-001'))" # => 2898aa333ba4efb48658db85e10d9fd9 ``` > 反过来也说明:**你无法从 DB 里反推别人的密码**,也无法拿 `admin` 的 `f_password` 去猜明文。 > 实测 j7 库 `admin` 的 `f_password` 与 `md5("123456"+其 secretkey)` 并不相等, > 说明这套环境的 admin 密码不是 123456 —— 别浪费时间试,自己造账号(见 §16.4)。 ### 8.2-B 【新增】自建账号登录报「账号权限不足」(LOG004) **现象**:密码算得完全正确,登录却返回 `{"code":400,"msg":"账号权限不足"}`。 **根因**(`jnpf-oauth-biz` → `jnpf.service.impl.LoginServiceImpl`): ```java // 超管旁路:账号名必须字面量等于 "admin",且 is_administrator == 1 if (!("admin".equals(user.getAccount()) && user.getIsAdministrator() == 1)) { List objectIds = 用户的岗位ID列表(position); objectIds.add(user.getId()); List roles = roleRelationApi.getListByObjectId(objectIds, null); // base_role_relation List all = objectIds + roles.map(角色ID); if (CollUtil.isEmpty(all) || CollUtil.isEmpty(authorizeApi.getListByObjectId(all))) { throw new LoginException(MsgCode.LOG004.get()); // 账号权限不足 } } ``` **踩坑要点**: 1. 旁路条件是**账号名硬编码字面量 `"admin"`**。你把自建账号的 `f_is_administrator` 设成 1 **没用**,只要账号不叫 `admin` 就照样走权限检查。 2. 检查的是:`base_role_relation`(用户/岗位 → 角色)关联出的对象,在 `base_authorize` 里**至少有一条授权记录**。 3. 光有角色还不够,那个角色必须真的有 `base_authorize` 数据。 **解法**:给自建账号挂一个已有授权数据的角色。先查有哪些角色可用: ```sql -- 看哪些角色真的有授权记录 SELECT r.f_id, r.f_full_name, count(a.f_object_id) AS 授权数 FROM base_role r JOIN base_authorize a ON a.f_object_id = r.f_id GROUP BY r.f_id, r.f_full_name ORDER BY 授权数 DESC; -- 666911261245571844 | 管理员 | 101 -- 666911261245571845 | 开发者 | 84 -- 666911261245571846 | 使用者 | 18 ``` ```sql -- 挂上「管理员」角色(f_object_type 固定 'user',f_tenant_id 非空约束,填 '' 即可) INSERT INTO base_role_relation (f_id, f_role_id, f_object_type, f_object_id, f_creator_time, f_creator_user_id, f_delete_mark, f_tenant_id) VALUES ('tss2dev-rel-001', '666911261245571844', 'user', 'tss2dev-001', now(), 'tss2dev-001', 0, ''); ``` > 另外 `base_user.f_enabled_mark` 必须为 `1`。从 admin 行 copy 建账号时这列容易带成 NULL, > 非超管路径会因此抛 `LOG005`。建完记得 `UPDATE base_user SET f_enabled_mark=1 WHERE f_account='xxx';` **登录错误码速查**: | code | 含义 | 检查方向 | |---|---|---| | `LOG101` 密码错误 | 传输层解密后与 `f_password` 对不上 | §8.2 两条链路是否搞混 | | `LOG004` 账号权限不足 | 无角色 / 角色无 `base_authorize` | 本节,挂角色 | | `LOG005` 账号已禁用 | `f_enabled_mark` 不是 1 | UPDATE 该列 | | `OA013`(日志里) | 传输层 AES 解密抛异常 | 密文不是 hex / key 不对 | ### 8.3 Token 传递(最容易被坑的一点) - 登录返回的 `data.token` 形如 **`bearer eyJhbGciOi...`**(已带 `bearer ` 前缀)。 - Sa-Token 配置:`getTokenName()="Authorization"`、`getTokenPrefix()="bearer"`、`isReadHeader=true`。 - **前端必须原样把登录返回的整串作为 `Authorization` 头值发送**,Sa-Token 会按前缀 `bearer`(小写)剥离。 ``` Authorization: bearer eyJhbGciOi... # ✅ 原样 Authorization: Bearer eyJ... # ❌ 大写 B 不会被剥离 → 600 登录过期 Authorization: bearer bearer eyJ... # ❌ 叠两层 → 600 ``` ### 8.4 白名单配置 `AuthFilter` 拦截 `/**`(含静态资源)。登录页、静态资源、登录接口必须放行: ```yaml # application.yml(JNPF 网关配置区) gateway: exclude-url: # 免 Token 且不记录日志 - /api/oauth/Login - /static/** # 用独立 Vite 前端时无需 /ssw/**;若塞 no-spa 静态页再加 - /ssw/** ``` --- ## 九、多数据源 @DS 规范(JNPF 标准机制,必做) JNPF 内置 `dynamic-datasource-spring-boot-starter`,通过 `@DS` 注解在运行时切换数据源。**接入业务模块应当采用「系统库 + 业务库」双库架构**,业务表独立成库,用 `@DS` 切换——这既是 JNPF 自身的标准做法(其 permission / visualdev / generater 模块同样用 `@DS` 分库),也符合公司「每 app_code 独立库」的规范。 ### 9.1 双库架构 | 源 | 角色 | 库名 | 承载内容 | |---|---|---|---| | `master`(默认 `primary`) | JNPF 平台主库 | `j7` | `base_user`、组织、权限、字典等系统表 | | `sswflow`(业务源) | SSWFlow 业务库 | `sswflow`(可用 `${SSWFLOW_DB}` 覆盖) | 你的业务表 | - `master` 无需显式声明:由 `MybatisPlusConfig#initPrimaryDataSource` 从 `spring.datasource.*` 主配置自动补全。 - 业务代码一律 `@DS("sswflow")`,登录/鉴权/系统查询走 `master`。 ### 9.2 配置(application-dev.yml) ```yaml spring: datasource: db-name: j7 # 主库(JNPF 系统库) host: ${DB_HOST:jnpf-postgres} port: ${DB_PORT:5432} username: ${DB_USER:dacli} password: ${DB_PWD:dacli123} dynamic: primary: master # 默认数据源 strict: true # 严格匹配:true-未匹配到源直接抛异常;false-降级用默认源 druid: # 连接池参数(略) initial-size: 4 max-active: 20 datasource: # 业务库只需声明这一个节点;master 由框架自动补全 sswflow: url: jdbc:postgresql://${spring.datasource.host}:${spring.datasource.port}/${SSWFLOW_DB:sswflow}?currentSchema=public&stringtype=unspecified username: ${spring.datasource.username} password: ${spring.datasource.password} driver-class-name: org.postgresql.Driver lazy: false ``` > `strict: true` 下,若 `@DS("sswflow")` 指定的源不存在会**直接抛异常**(而不是静默落到 master),能尽早暴露配置错误。 ### 9.3 用法(实体 + Service 都要打) ```java @Alias("SswflowProjectEntity") @DS("sswflow") // ⚠️ 切到业务库 @TableName("project") public class ProjectEntity extends SuperEntity { ... } @Service("sswflowProjectService") @DS("sswflow") // ⚠️ 注解【不继承】!子类必须各自打,写在基类上无效 public class ProjectServiceImpl extends SswflowServiceImpl implements ProjectService { ... } ``` ⚠️ **`@DS` 不会从父类继承**:基类 `SswflowServiceImpl` 即使打了 `@DS`,子类也读不到——JNPF 切面取的是 `methodInvocation.getThis().getClass().getAnnotation(DS.class)`。**每个业务 Service Impl 必须自己打 `@DS("sswflow")`**,实体同理。 ### 9.4 基类承载「动态自愈」(SSWFlow 自定义增强) `SswflowServiceImpl` 实现 JNPF 的 `DynamicSourceGeneratorInterface`,命中 `MybatisPlusConfig#myDynamicDatasourceGeneratorAdvisor` 切面(切点 `within(DynamicSourceGeneratorInterface+) && @target(@DS)`): - **静态兜底**:`application-dev.yml` 已声明 `sswflow` 连接池,正常路径不依赖运行时生成。 - **动态自愈**:一旦 `sswflow` 源缺失(连接池被销毁、多租户重建等),会用主库连接参数复制一份并把库名换成 `sswflow` 重新注册,避免 `strict=true` 下抛 `dynamic-datasource can not find primary datasource`。 > **【修正 G】接口真实签名(已反编译 `jnpf-common-database-7.0.0-RELEASE.jar` 复核):** > ```java > public interface DynamicSourceGeneratorInterface { > public abstract T getDataSource(); > public default boolean cachedConnection(); > } > ``` > `jnpf.database.util.DataSourceUtil` 标注 `@Component`(可直接 `@Autowired`),其 `init(String)` 返回 `jnpf.database.model.entity.DbLinkEntity`——而 `DbLinkEntity extends DataSourceUtil`,所以 `return masterDataSourceUtil.init(DS_KEY);` 赋值给 `DataSourceUtil` 完全合法。原文档写法**能编译**,这里仅补充精确签名与类型关系,避免读者误以为 `init` 返回 `DataSourceUtil` 本身。 ```java public abstract class SswflowServiceImpl, T> extends SuperServiceImpl implements DynamicSourceGeneratorInterface { public static final String DS_KEY = "sswflow"; @Autowired private DataSourceUtil masterDataSourceUtil; // 主库连接参数(只读,@Component) @Override public DataSourceUtil getDataSource() { return masterDataSourceUtil.init(DS_KEY); // 复制主库参数,库名换成 sswflow } } ``` > 所有业务 Service 继承 `SswflowServiceImpl` 即可自动获得该能力(仍需各自打 `@DS("sswflow")`)。 --- ## 十、前端对接:用独立 Vite,别塞 jar 把静态页塞进 Spring Boot jar 会踩一堆坑(静态资源映射是 `/static/**` 而非根、每次改前端要重打包、AuthFilter 白名单)。**独立 Vite dev server 干净得多**: ``` sswflow-web/ # Vite + Vue3 + TS + ant-design-vue ├── vite.config.ts # proxy: { '/api': { target: 'http://localhost:30000' } } ├── scripts/smoke.mjs # 零依赖烟测(见 §12.2) └── src/ ├── utils/cipher.ts # 密码 AES 加密(对齐 8.2) ├── api/request.ts # axios:注入 Authorization/App-Code/Jnpf-Origin/Vue-Version;600/401 跳登录 ├── api/auth.ts # login/logout/getToken └── api/sswflow.ts # 业务接口(路径 /api/ssw/sswflow/...) ``` `vite.config.ts`: ```ts export default defineConfig({ server: { port: 5173, proxy: { '/api': { target: 'http://localhost:30000', changeOrigin: true } } }, plugins: [vue()] }) ``` > 浏览器只跟 5173 通信,由 Vite 代理到 30000,同源无 CORS 问题。 `src/utils/cipher.ts`(**官方约定**,与 §8.2 一致,含自检 —— 内层 = `md5(明文)`): ```ts import CryptoJS from 'crypto-js' const CIPHER_KEY: string = import.meta.env.VITE_CIPHER_KEY || 'EY8WePvjM5GGwQzn' export function encryptPassword(plain: string): string { const key = CryptoJS.enc.Utf8.parse(CryptoJS.MD5(CIPHER_KEY).toString()) // md5(securityKey) 32B = AES-256 const inner = CryptoJS.MD5(plain).toString() // 官方约定:内层 = md5(明文) 的 32 hex const encrypted = CryptoJS.AES.encrypt(CryptoJS.enc.Utf8.parse(inner), key, { mode: CryptoJS.mode.ECB, padding: CryptoJS.pad.Pkcs7 }) return CryptoJS.enc.Base64.parse(encrypted.toString()).toString(CryptoJS.enc.Hex) } export const SELF_CHECK_123456 = 'd4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b' export function selfCheck(): boolean { return encryptPassword('123456') === SELF_CHECK_123456 } ``` `src/api/request.ts` 关键拦截器(要点): ```ts // 请求拦截:注入 4 个头,token 原样带(含 "bearer " 前缀) config.headers.Authorization = getToken() // 形如 "bearer eyJ..." config.headers['App-Code'] = appCode config.headers['Jnpf-Origin'] = 'pc' config.headers['Vue-Version'] = '3' // 响应拦截:code !== 200 视为错误;code === 600 || http 401 → 清 token 跳登录 if (res.data.code !== 200) { if (res.data.code === 600) { clearToken(); router.replace('/login') } return Promise.reject(res.data.msg) } ``` --- ## 十一、数据库与中间件(PostgreSQL + Redis) > **快速起环境**:不想手动装库,直接用阿里云镜像(PostgreSQL 16 + Redis)一条命令拉起,并初始化 `j7` 主库——完整步骤见「〇-B.4」。下面只讲配置与接入约定。 ```yaml # application-dev.yml(节选,完整见 §9.2) spring: datasource: url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${SSWFLOW_DB:sswflow} username: dacli password: dacli123 data: redis: host: ${REDIS_HOST:localhost} port: ${REDIS_PORT:6379} redis: redisson: config: | singleServerConfig: address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}" database: 0 password: ${REDIS_PWD:} # 纯镜像无密码时留空;JNPF 默认 123456 → 二选一对齐 connectionPoolSize: 32 connectionMinimumIdleSize: 8 codec: ! {} ``` > **Netty DNS 注意**:Spring/Redis 用的 Netty 解析器不走系统 hosts,`.orb.local` 后缀在宿主机可能解析不到。宿主机直连用**容器 IP**(如 OrbStack 下 `192.168.97.3:5432`、`192.168.97.2:6379`),或启动时用 `-DDB_HOST=... -DREDIS_HOST=...` 覆盖(见第 12.1 节启动命令)。 建表:schema 用 Flyway/手工 SQL,列名遵循 `f_xxx` 约定(公共字段**列名不可改动**,由 `SuperEntity`/`SuperBaseEntity` 硬编码映射);业务库 `sswflow` 执行 `V1.0.0__schema.sql`(系统库 `j7` 由 JNPF 自行初始化,脚本来源见「〇-B.4」的 `jnpf-database` 仓库)。 业务库建表脚本示例(PostgreSQL,公共字段与 `SuperEntity` 严格对齐): ```sql -- 项目表 CREATE TABLE project ( f_id varchar(50) NOT NULL, f_tenant_id varchar(50), f_creator_time timestamp DEFAULT now(), f_creator_user_id varchar(50), f_last_modify_time timestamp, f_last_modify_user_id varchar(50), f_delete_mark int4, f_delete_time timestamp, f_delete_user_id varchar(50), name varchar(200) NOT NULL, project_code varchar(100), compute_mode varchar(20), status varchar(20) DEFAULT 'DRAFT', remark varchar(500), CONSTRAINT pk_project PRIMARY KEY (f_id) ); COMMENT ON TABLE project IS '项目'; COMMENT ON COLUMN project.f_delete_mark IS '删除标记,NULL=未删除'; ``` --- ## 十二、启动与验证 ### 12.1 启动命令(已验证) ```bash cd boot # jar 跑在宿主机:application-dev.yml 已默认 localhost:15432(PG 发布端口)+ 127.0.0.1:6379(Redis) # 如需自定义可加: -DDB_HOST=... -DDB_PORT=... -DDB_USER=... -DDB_PWD=... -DTSS2_DB=... java -Dspring.profiles.active=dev \ --server.port=30000 \ -jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar ``` > **【`SERVER__PORT` 环境变量陷阱 · §16.6①】** 若宿主机残留 `SERVER__PORT`/`SERVER_PORT` 环境变量,Spring Boot relaxed binding 会把它映射成 `server.port`,**且环境变量优先级高于 `-D` 系统属性、高于 yml**,端口会变成随机高位(如 53160)。最稳的做法是显式传 **CLI 参数** `--server.port=30000`(命令行参数优先级最高,可压过环境变量),或启动前 `env -u SERVER__PORT`。 > 另:`-D` 参数必须放在 `-jar` **前面**才是 JVM 参数;`--server.port` 是 Spring Boot CLI 参数,位置不限。 > **【修正 F/J/K】Boot 3 兼容补丁(缺一不可,否则登录时 `NoClassDefFoundError: ThreadPoolExecutorUtil` 或启动失败):** > > **(1) `applicationTaskExecutor` bean**(`ssw/config/TaskExecutorConfig.java`): > ```java > @Configuration > public class TaskExecutorConfig { > @Bean("applicationTaskExecutor") > @ConditionalOnMissingBean(name = "applicationTaskExecutor") > public ThreadPoolTaskExecutor applicationTaskExecutor() { > ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor(); > ex.setCorePoolSize(8); ex.setMaxPoolSize(32); ex.setQueueCapacity(500); > ex.setThreadNamePrefix("ssw-task-"); ex.initialize(); > return ex; > } > } > ``` > **(2) `SpringContext` initializer 必须代码注册**(FQN `jnpf.util.context.SpringContext`): > ```java > public static void main(String[] args) { > SpringApplication application = new SpringApplication(SswAdminApplication.class); > application.addInitializers(new jnpf.util.context.SpringContext()); > application.run(args); > } > ``` > 同时保留 `src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer`(内容 `jnpf.util.context.SpringContext`)作 IDE 双保险。 > > **(3) `application.yml` 必加两项**(否则 Boot 3 下启动失败/路由异常): > ```yaml > spring: > main: > allow-bean-definition-overriding: true # JNPF 内部存在同名 bean 定义 > mvc: > pathmatch: > matching-strategy: ant_path_matcher # JNPF 用 ant 路径匹配 > ``` ### 12.2 烟测脚本(Node,零依赖,已验证) > **【修正 I】** 提供 `scripts/smoke.mjs`(不依赖任何 npm 包,纯 Node 内置 `http`/`crypto`),含密码自检 + 登录 + 业务接口调用,支持参数: > `--base`(默认 `http://localhost:30000`)、`--account`(默认 `tss2dev`)、`--password`(默认 `123456`)、`--key`(默认 `EY8WePvjM5GGwQzn`)、`--appcode`(默认 `tss2`)。 ```js // scripts/smoke.mjs(核心逻辑 · 与 §8.2 两条链路一致) import { createHash, createCipheriv, createDecipheriv } from 'node:crypto'; import http from 'node:http'; const md5Hex = (s) => createHash('md5').update(s, 'utf8').digest('hex'); // 传输层(官方约定):hex( AES-256-ECB/PKCS5( md5(明文)的32hex字符串, utf8(md5(securityKey)) ) ) // 内层 S = md5(明文);旧变体(legacy)才是明文原文(见 §8.2)。 function encryptPassword(plain, cipherKey) { const key = Buffer.from(md5Hex(cipherKey), 'utf8'); // md5(securityKey) 的 32 位 hex 按 UTF-8 取字节 = 32B = AES-256 const inner = md5Hex(plain); // 官方约定:内层 = md5(明文) const c = createCipheriv('aes-256-ecb', key, null); c.setAutoPadding(true); return Buffer.concat([c.update(Buffer.from(inner, 'utf8')), c.final()]).toString('hex'); } const decryptPassword = (hex, key) => { const d = createDecipheriv('aes-256-ecb', Buffer.from(md5Hex(key), 'utf8'), null); d.setAutoPadding(true); return Buffer.concat([d.update(Buffer.from(hex, 'hex')), d.final()]).toString('utf8'); }; function req(method, path, body, headers) { /* 见仓库脚本:node:http 封装,返回 { status, data } */ } const post = (p, b, h) => req('POST', p, b, h); const get = (p, h) => req('GET', p, null, h); // 1) 自检:与基准值一致 + 解密可逆 const EXPECT_123456 = 'd4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b'; // 官方约定(md5内层),96-hex const cipher = encryptPassword(password, key); console.log('cipher self-check:', (cipher === EXPECT_123456 && decryptPassword(cipher, key) === password) ? 'PASS' : 'FAIL'); // 2) 登录(x-www-form-urlencoded) const body = `account=${encodeURIComponent(account)}&password=${cipher}&grant_type=password`; const login = await post(`${base}/api/oauth/Login`, body, { 'Content-Type': 'application/x-www-form-urlencoded', 'App-Code': appcode, 'Jnpf-Origin': 'pc', 'Vue-Version': '3' }); const token = login.data?.data?.token || login.data?.token; // "bearer eyJ..." // 3) 带 token 调业务接口(走 @DS("tss2") 落到 tss2 库) await post(`${base}/api/ssw/${appcode}/Project`, JSON.stringify({ name: 'smoke', projectCode: 'smoke', computeMode: 'MPC', status: 1, remark: 'e2e' }), { Authorization: token, 'App-Code': appcode, 'Content-Type': 'application/json' }); const r = await get(`${base}/api/ssw/${appcode}/Project/All`, { Authorization: token, 'App-Code': appcode }); console.log('Project/All code =', r.data.code, '| rows =', (r.data.data || []).length); ``` > 验证双库生效:`Project/All` 返回刚写入的记录(连到 `tss2` 业务库),同时登录成功(走 `master`/j7 查 `base_user`)——两者并存即说明 `@DS` 路由正确;且 `j7` 库无 `project` 表证明数据只落在 `tss2` 库(§16.5)。 --- ## 十三、常见坑速查表 | 现象 | 原因 | 解决 | |---|---|---| | `Could not resolve com.jnpf:... 401/404` / 依赖拉不到 | 没配官方私服 `settings.xml` | 配 `~/.m2/settings.xml` 的 `maven-releases` server+mirror(〇-B.2) | | 某模块目录文件缺失、编译报找不到类 | 官方仓库模块未 clone 全 | 用账号从 `coding.jnpfsoft.com/v7.0/` 补齐(〇-B.1) | | `jnpf-common-all:jar:7.0.0-RELEASE not found` | 私有仓库需鉴权,离线拉不到 | 本地编译 JNPF 源码 `mvn install`(第二节,前置见〇-B.1/〇-B.2) | | `-source 8 不支持 switch 表达式` | boot3 profile 锁 source=8 | 业务模块 pom 覆盖 `source/target=17`(3.1,父 `ssw-boot` 已设) | | `dependencies.dependency.version' for com.baomidou:... is missing` | entity pom 裸写 mybatis-plus/dynamic-datasource 无 version | 删除(随 jnpf-common-all 传递引入),或显式加 ``(3.2) | | 编译报 `找不到符号 getXxx()` / `@Data` 不生效 | 缺 lombok(JNPF 侧 provided 不传递) | entity pom 加 `org.projectlombok:lombok`(provided)(3.2) | | `Could not resolve com.jnpf:ssw-tss-controller ... has not been downloaded` | 打包只 `-pl ssw-admin`,业务模块不在 reactor | 加 **`-am`**:`mvn -o package -DskipTests -pl ssw-admin -am`(〇-B.3/12) | | `ConflictingBeanDefinitionException: operatorController` | 与 JNPF 同名 bean 撞 | Controller/Service 显式 bean 名(7.1) | | `alias 'DataSetEntity' already mapped` | MyBatis alias 大小写不敏感撞 | 实体加 `@Alias("SswflowXxxEntity")`(7.2) | | 业务接口报 `dynamic-datasource can not find primary datasource` / 数据跑到 `j7` 库 | `@DS` 没打或打错;`strict=true` 下缺失源抛异常 | 实体+Service 都打 `@DS("sswflow")`(9.3) | | 登录返回 `600 登录过期` | token 前缀被叠/被改大写 | 原样用 `bearer eyJ...`(8.3) | | 登录报 `BadPaddingException` | 密码加密算法/key 不对 | 对齐 8.2(AES-256-ECB,key=MD5(CIPHER_KEY) 的 32 字节) | | **启动无报错但登录 404 / 注入失败** | **`scanBasePackages` 写成 `com.jnpf`** | **改成 `{"jnpf","ssw"}`(修正 A / 〇-B.3-2)** | | `NoClassDefFoundError: ThreadPoolExecutorUtil` | `applicationTaskExecutor` 缺失 + SpringContext 未注册/注册失效 | 12.1 的两个 Boot 3 补丁;**务必代码注册 `jnpf.util.context.SpringContext`**(修正 F) | | **启动即失败:`bean definition ... is expected to be defined in ... overriding is disabled`** | **JNPF 内部同名 bean 不被允许覆盖** | **`spring.main.allow-bean-definition-overriding: true`(修正 J)** | | 路由 404 / ant 匹配异常 | Boot 3 默认 PathPattern 与 JNPF ant 不匹配 | `spring.mvc.pathmatch.matching-strategy: ant_path_matcher`(修正 K) | | 启动后端口是随机高位(如 53160/64052) | **环境变量 `SERVER__PORT`/`SERVER_PORT` 覆盖了配置文件**(relaxed binding,优先级高于 yml) | `env \| grep -i "SERVER.*PORT"` 排查;启动加 `--server.port=30000`(§16.6①) | | 静态页 404 / 返回 JSON 错误 | 资源映射是 `/static/**` 非根 | 用独立 Vite(第十节)或加 `addResourceHandlers` | | `UnknownHostException: jnpf-postgres/jnpf-redis` | jar 跑在宿主机却用了容器网络的主机名 | 改 `localhost` + **容器发布端口**(PG 常是 15432 不是 5432)(§16.6②) | | Redis 连不上但容器是 Up | 容器没做端口映射(PORTS 无 `0.0.0.0:6379->`) | 另起带 `-p 6379:6379` 的实例(§16.6②) | | `ERR Client sent AUTH, but no password is set` | redisson password 与 Redis 实际不符 | 无密码镜像把 `password` 留空对齐(§11) | | `@DS("xxx")` 报数据源不存在 | YAML 少写一层,写成了 `dynamic.` | 必须是 `dynamic.**datasource**.`(§16.6③) | | 登录 `{"code":400,"msg":"账号权限不足"}` | 自建账号没挂角色 / 角色无 `base_authorize`;超管旁路硬编码只认账号名 `admin` | 挂「管理员」角色(§8.2-B) | | 登录密码怎么算都不对 | 把「传输层 AES」和「存储层 MD5」搞混了 | 传输 AES-256-ECB(明文)、存储 md5(明文+secretkey)(§8.2) | | 文件存储启动报路径不可写 | `base-path` 默认 `/workspace/...` 是容器内路径 | 改成工程内可写目录(§16.6④) | | 后台起的服务莫名消失、日志停半路 | `nohup ... &` 被父 shell 回收 | `jps -lm` 确认;改用前台 `exec java -jar` 或 tmux/systemd(§16.6⑤) | --- ## 十四、最小落地清单(照抄顺序) 1. 环境准备:获取官方源码(首次 `git clone`、之后 `git pull` 或复用 `~/.m2` 已有 jar,见〇-B.1)+ 配 `settings.xml` 私服(〇-B.2)+ 镜像拉起 j7/Redis 并只取 SQL 初始化库(〇-B.4) 2. 复制 `jnpf-java-boot/jnpf-admin` → `boot/ssw-admin`,按 〇-B.3 调整(parent/pom、包名 `jnpf→ssw`、**`scanBasePackages={"jnpf","ssw"}`**、Boot3 补丁含**代码注册 SpringContext**、数据源) 3. 编译 JNPF 源码装本地仓库(第二节,前置见〇-B.1/〇-B.2) 4. 建 `boot/ssw-{app_code}/{entity,biz,controller}` 三层 + `ssw-admin` 聚合 5. 业务模块 pom 加 `source/target=17`(父 `ssw-boot` 已设)、依赖 `jnpf-common-all` + `lombok(provided)`;**不要**裸写 mybatis-plus/dynamic-datasource(3.2) 6. 配 `application.yml`:`allow-bean-definition-overriding: true` + `mvc.pathmatch.ant_path_matcher` + 白名单;`application-dev.yml` 双数据源 `master`(j7) 自动补全 + `dynamic.datasource.sswflow` 业务库(9.2)+ redisson(§11) 7. 写实体(带 `@Alias`、继承 `SuperEntity`、**不重复声明公共字段**、`@DS("sswflow")`) 8. 写 Service(继承 `SswflowServiceImpl`,`@Service("sswflowXxxService")` + **`@DS("sswflow")`**) 9. 写 Controller(`@RestController("sswflowXxxController")`、`/api/ssw/{app_code}`) 10. 配 `application.yml` 白名单 + `application-dev.yml` 数据库 11. 加 Boot 3 两个补丁(executor bean + **`SswAdminApplication` 代码注册 `jnpf.util.context.SpringContext`**) 12. 独立 Vite 前端:cipher / request / auth / 业务接口 + proxy 30000 13. **构建:`mvn -o package -DskipTests -pl ssw-admin -am`**(注意 `-am`) 14. 启动(12.1 命令)→ 烟测(`node scripts/smoke.mjs`,确认登录成功、密码自检 PASS、业务接口走 sswflow 库)→ 浏览器 5173 登录 --- ## 十五、前端策略:以 AI 编写为主,不套 JNPF views 结构 > 结论:**`sswflow-web` 保持一个普通的 Vite + Vue3 + TS 工程,由 AI 直接编写,不强行套 JNPF web 的 `views/**` 目录范式。** 过早对齐 JNPF 页面结构反而增加约束、拖慢 AI 开发效率;只有当"迁回 JNPF web"成为明确任务时,再按需对齐。 **只保留与后端 / JNPF 强相关的 3 个对接点(已写在第十节,务必对齐,其余随意):** 1. `utils/cipher.ts` —— 密码 AES-256-ECB 加密,key=`MD5(CIPHER_KEY)`,与后端 `security.security-key` 一致(§8.2,含自检基准值) 2. `api/request.ts` —— axios 拦截器注入 `Authorization`(原样 `bearer eyJ...`) / `App-Code` / `Jnpf-Origin` / `Vue-Version`;`code!==200` 报错、`600/401` 跳登录(§8.3) 3. 业务接口路径前缀 `/api/ssw/{app_code}/...`,响应沿用 `ActionResult`(`code/data/msg`)+ 分页 `{list,pagination}`(§6.1) **AI 编写时的自由区(不约束):** - 目录怎么分、组件怎么拆、状态管理用 Pinia 还是 composables、UI 库选型 —— 交给 AI 按工程习惯决定。 - 不要求复用 JNPF 的 `` / `` 等私有组件(它们强耦合 JNPF 运行时,迁移成本高于收益)。 - 页面不强求 `views//` 的命名 —— 可读性优先,AI 生成的命名保持自洽即可。 > 迁移提示:真要迁回 JNPF web 时,难点只在上述 3 个对接点 + 页面注册到 JNPF 路由;业务组件本身可整体搬。所以"现在让 AI 自由写"不会欠下迁移债。 --- ## 十六、tss2 二次落地:验证记录与文档缺口补充 > 以「完善文档」为目标,在不参考任何其它项目/脚手架、不启用容器的情况下,仅依据本指南从零落地第二个应用 `tss2`(位于本仓库 `tss2/`),用于校验本指南的可复用性与缺口。结论:**后端构建、前端构建、密码算法自检全部通过**,证明指南可复用;同时暴露若干「仅看指南无法一次性拼出」的缺口,已在下面补齐。 ### 16.1 tss2 命名映射表 按「示例占位约定」把 `sswflow` 整体替换为 `tss2`(app_code = 库名 = 数据源名): | 占位(原文档通用写法) | tss 首版 | tss2 二次落地 | |---|---|---| | app_code | `tss` | `tss2` | | 类前缀 `Sswflow` | `Tss` | `Tss2` | | bean 名前缀 `sswflow` | `tss` | `tss2` | | 实体 @Alias `SswflowXxxEntity` | `TssXxxEntity` | `Tss2XxxEntity` | | 业务库/数据源名 | `tss` | `tss2` | | API 前缀 | `/api/ssw/tss` | `/api/ssw/tss2` | | Java 包 | `ssw.tss.*` | `ssw.tss2.*` | | Maven artifactId | `ssw-tss-*` | `ssw-tss2-*` | | 业务基类 `SswflowServiceImpl` | `TssServiceImpl` | `Tss2ServiceImpl` | > 关键点:**业务库名 == app_code**(双库架构下每个 app_code 独立库)。`dynamic.datasource.` 与 `@DS("")` 用同一个名字;`application-dev.yml` 里 `${SSWFLOW_DB:}` 的默认值也填 app_code(tss2 即 `tss2`)。 ### 16.2 完整父 pom / 聚合 pom(指南此前只给了 ``,缺可拼装的整文件) `boot/pom.xml`(ssw-boot,父链 `ssw-boot → jnpf-common → jnpf-dependencies`): ```xml 4.0.0 com.jnpf jnpf-common 7.0.0-RELEASE com.jnpf ssw-boot 7.0.0-RELEASE pom 17 17 17 UTF-8 7.0.0-RELEASE tss2 ssw-tss2 ssw-admin org.projectlombok lombok provided ``` `boot/ssw-tss2/pom.xml`(业务聚合,下面挂 entity/biz/controller 三个子模块): ```xml 4.0.0 com.jnpf ssw-boot 7.0.0-RELEASE ssw-tss2 pom ssw-tss2-entity ssw-tss2-biz ssw-tss2-controller ``` > 三个子模块 pom 见 §3.2(entity 依赖 `jnpf-common-all`+lombok;biz 依赖 entity;controller 依赖 biz + `spring-boot-starter-web`,见 16.4)。**构建命令必须带 `-am`**:`mvn -o package -DskipTests -pl ssw-admin -am`,否则 reactor 找不到 `ssw-tss2-*` 而报 `has not been downloaded`(修正 E)。 ### 16.3 业务基类 `Tss2ServiceImpl` 的文件位置(指南 §9.4 只给了类体,没说放哪) - 所属模块:**biz**(`ssw-tss2-biz`)。 - 包:`ssw.tss2.biz.service`(与 `ProjectService` 接口同包;其实现类放在 `ssw.tss2.biz.service.impl`)。 - 所有业务 Service Impl 继承它:`public class ProjectServiceImpl extends Tss2ServiceImpl implements ProjectService`。 - 它已实现 `DynamicSourceGeneratorInterface`(`jnpf.database.plugins` 包,泛型 ` T getDataSource()`),并把库名固定为 `DS_KEY="tss2"`。子类**仍需各自打 `@DS("tss2")`**(注解不继承,见 §9.3)。 ### 16.4 controller 模块需要 Spring MVC 注解 controller 用 `@RestController/@RequestMapping/@GetMapping/@PostMapping/@RequestBody`,这些来自 `spring-web` / `spring-webmvc`。它们经 `jnpf-common-all` 传递引入(JNPF 的 `jnpf-common-swagger` 等依赖 spring-webmvc),通常已在 classpath;若编译报 `找不到 org.springframework.web...`,在 controller 的 pom 显式加(版本由 `jnpf-dependencies` BOM 托管,无需写 ``): ```xml org.springframework.boot spring-boot-starter-web ``` ### 16.5 验证结果(tss2,仅依据本指南) **第一轮:构建期验证** | 验证项 | 命令 | 结果 | |---|---|---| | 后端离线编译+打包 | `cd boot && mvn -o package -DskipTests -pl ssw-admin -am` | ✅ BUILD SUCCESS,产物 `ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar`(370 MB,已 repackage) | | 前端构建 | `cd tss2-web && npm install && npm run build` | ✅ 产出 `dist/` | | jar 内含 initializer | `unzip -l ...jar \| grep ApplicationContextInitializer` | ✅ `META-INF/spring/...` 存在,且 `SswAdminApplication` 代码注册兜底(修正 F) | **第二轮:运行期端到端验证**(本轮补做,也正是本轮修正 §8.2 的来源) | 验证项 | 结果 | |---|---| | Redis 连接 | ✅ `24 connections initialized for 127.0.0.1:6379` | | 双数据源装载 | ✅ `add a datasource named [tss2] success` + `[master] success`,`primary=master` | | 服务启动 | ✅ Tomcat 30000,`/api/oauth/Login` 返回 200(启动约 90s) | | 密码算法自检 | ✅ `encryptPassword("123456") = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`(官方 md5 约定,96-hex) | | 登录取 token | ✅ `code=200`,返回 `bearer eyJhbGciOiJIUzI1NiIs...` | | 鉴权 + 业务写入 | ✅ `POST /api/ssw/tss2/Project` → `code=200` | | 业务读取 | ✅ `GET /api/ssw/tss2/Project/All` → 读回刚写入的记录 | | **`@DS("tss2")` 真实路由** | ✅ 数据只出现在 `tss2` 库;`j7` 库**根本不存在** `project` 表(`information_schema` 计数 = 0) | | 前端 Vite 代理链路 | ✅ 经 `http://127.0.0.1:5173` 代理跑同一套烟测,同样全绿 | ``` $ node scripts/smoke.mjs --base=http://127.0.0.1:30000 [1] cipher self-check: PASS md5(key) = 05b0175907a859751f57a04d5a5ee9ac cipher = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b [2] login tss2dev @ http://127.0.0.1:30000 http = 200 | code = 200 | token? yes [3] business POST /api/ssw/tss2/Project name=smoke-1785560577257 http = 200 | code = 200 | msg = ok [4] business GET /api/ssw/tss2/Project/All http = 200 | code = 200 | rows = 1 DONE 端到端链路通过:登录 -> 鉴权 -> @DS("tss2") 写入 -> 读出 ``` ### 16.6 运行期实测暴露的 5 个坑(构建期发现不了) 按踩到的先后顺序记录,每个都会直接卡死流程: **① `server.port` 被环境变量悄悄改掉** 现象:`application-dev.yml` 明明写了 `server.port: 30000`,实际却绑到随机高位端口。 根因:宿主机存在 `SERVER__PORT` / `SERVER_PORT` 环境变量,Spring Boot 的 relaxed binding 把它映射成 `server.port`, **环境变量优先级高于配置文件**。实测 `env -u SERVER__PORT` 后即恢复 30000。 ```bash env | grep -i "SERVER.*PORT" # 先排查 java -jar ssw-admin.jar --spring.profiles.active=dev --server.port=30000 # 命令行显式指定最稳 ``` **② jar 跑在宿主机时,数据源地址不能用容器名** `jnpf-admin` 原配置是 `host: jnpf-postgres / port: 5432`(docker 网络内地址)。 jar 直接在宿主机跑时必须换成**发布端口**,否则 `UnknownHostException`: ```yaml spring: datasource: host: ${DB_HOST:localhost} # 宿主机跑 → localhost port: ${DB_PORT:15432} # PG 容器的发布端口,不是 5432 ``` Redis 同理:若容器没做端口映射(`docker ps` 的 PORTS 列只有 `6379/tcp` 而没有 `0.0.0.0:6379->`), 宿主机根本连不上,必须另起一个带 `-p` 的实例: ```bash docker run -d --name tss2-redis -p 6379:6379 redis:7 --requirepass 123456 docker exec tss2-redis redis-cli -a 123456 ping # 期望 PONG ``` **③ 业务数据源的 YAML 层级容易写错一层** 必须是 `spring.datasource.dynamic.**datasource**.`,少写中间那层 `datasource` 就不会注册, 而 `strict: true` 下 `@DS("tss2")` 会直接抛「数据源不存在」: ```yaml spring: datasource: dynamic: primary: master strict: true datasource: # ← 这一层别漏 tss2: url: jdbc:postgresql://${spring.datasource.host}:${spring.datasource.port}/${TSS2_DB:tss2}?currentSchema=public&stringtype=unspecified username: ${spring.datasource.username} password: ${spring.datasource.password} driver-class-name: org.postgresql.Driver lazy: false ``` > 启动日志出现下面三行才算真的装上了: > ``` > add a datasource named [tss2] success > add a datasource named [master] success > initial loaded [2] datasource,primary datasource named [master] > ``` **④ 文件存储根路径必须可写** `config.file-storage.local-plus[0].base-path` 默认 `/workspace/jnpf-resources/`(容器内路径)。 宿主机没有 `/workspace` 且创建需要 root,改成工程内目录: ```yaml base-path: ${TSS2_RESOURCE_PATH:/abs/path/to/tss2/.runtime/resources/} ``` **⑤ 后台启动的进程会被 shell 回收** `nohup java -jar ... &` 在某些受控 shell 里,父 shell 退出时子进程一起没了(日志停在半路、无端口监听、 `jps` 查不到)。排查时先 `jps -lm` 确认进程还在,再看日志。稳妥做法是让 java 占据前台(`exec java -jar ...`) 由外层作业管理托管,或用 `screen`/`tmux`/`systemd`。 ### 16.7 application.yml 仅为「差异补丁」 - `ssw-admin/src/main/resources/application.yml` 在指南里**只提供「必须新增/修正」的键**(`allow-bean-definition-overriding`、`mvc.pathmatch.ant_path_matcher`、`gateway.exclude-url`)。完整的 JNPF 平台配置(mybatis-plus、sa-token、`security.security-key`、spring.redis 等)请沿用 `jnpf-admin` 的 `application.yml` 并把上述键合并进去——这正是 〇-B.3「复制 jnpf-admin 资源」的本意。单独用本指南给出的 `application.yml` 片段**无法启动**(缺 JNPF 必需配置),这是预期,不是指南缺陷。 - `application-dev.yml` 已给出可直接用的双数据源(master/j7 + `dynamic.datasource.tss2`)与 redisson 配置,变量默认 `localhost`/`15432`,可用 `-DDB_HOST=... -DREDIS_HOST=...` 或同名环境变量覆盖(详见 §11 / §12.1)。 ### 16.8 造验证账号的完整可复制脚本 不要试图猜 `admin` 的密码(实测该环境 admin 密码非 `123456`)。直接造一个自己的账号, 三步缺一不可(少任何一步都登录失败,对应错误码见 §8.2-B): ```bash # ── 步骤 0:算出入库摘要(官方约定:S = md5(明文))─────── # f_password = md5( md5(明文) + f_secretkey.toLowerCase() ) node -e "const c=require('crypto');const m=s=>c.createHash('md5').update(s,'utf8').digest('hex'); console.log(m(m('123456')+'tss2dev-secret-key-001'))" # => 2898aa333ba4efb48658db85e10d9fd9 ``` ```sql -- ── 步骤 1:复制 admin 行建账号(最省事,公共列自动带全)── INSERT INTO base_user SELECT * FROM base_user WHERE f_account = 'admin'; UPDATE base_user SET f_id = 'tss2dev-001', f_account = 'tss2dev', f_password = '2898aa333ba4efb48658db85e10d9fd9', f_secretkey = 'tss2dev-secret-key-001', f_is_administrator = 1, f_enabled_mark = 1 -- ← 步骤 2:必须为 1,否则 LOG005 WHERE f_id = (SELECT f_id FROM base_user WHERE f_account='admin') -- 注意先改 id 再改其它 AND f_account = 'admin'; -- ── 步骤 3:挂角色,否则 LOG004「账号权限不足」────────── INSERT INTO base_role_relation (f_id, f_role_id, f_object_type, f_object_id, f_creator_time, f_creator_user_id, f_delete_mark, f_tenant_id) VALUES ('tss2dev-rel-001', '666911261245571844', 'user', 'tss2dev-001', now(), 'tss2dev-001', 0, ''); ``` > `base_role_relation` **没有唯一约束**,`ON CONFLICT (f_id)` 会直接报 > `there is no unique or exclusion constraint matching the ON CONFLICT specification`。 > 需要幂等就先 `DELETE FROM base_role_relation WHERE f_id='...';` 再 INSERT。 验证账号可用性: ```bash node tss2-web/scripts/smoke.mjs --base=http://127.0.0.1:30000 --account=tss2dev --password=123456 ``` ## 附:本增强版相对原版的全部修订(CHANGELOG) - **A · `scanBasePackages`**:`{"com.jnpf","ssw"}` → `{"jnpf","ssw"}`,并加醒目说明:`com.jnpf` 仅 Maven groupId,Java 顶级包是 `jnpf`。 - **B · 实体基类**:`EntityBase` → `SuperEntity`(含 `SuperBaseEntity` 的 `id`),公共字段表补全为 9 列,明确"勿重复声明"。 - **C · entity 依赖**:删除无 version 的 `mybatis-plus-boot-starter` / `dynamic-datasource-spring-boot-starter`(随 `jnpf-common-all` 传递引入),补"如需锁版本必须显式 ``"。 - **D · lombok**:明确 entity(及使用 `@Data` 的模块)需自行声明 `org.projectlombok:lombok`(provided);父 `ssw-boot` 也已全局加。 - **E · 构建命令**:`mvn package -DskipTests -pl ssw-admin -o` → `mvn -o package -DskipTests -pl ssw-admin -am`(补 `-am`)。 - **F · initializer**:FQN `jnpf.SpringContext` → `jnpf.util.context.SpringContext`;并强制 `SswAdminApplication.main()` 代码注册(repackage 会把 META-INF 提到 fat-jar 根导致读不到)。 - **G · `getDataSource`**:补充接口真实泛型签名 ` T getDataSource()` 与 `init(String)` 返回 `DbLinkEntity`(其父类为 `DataSourceUtil`),澄清原写法可编译。 - **H · 密码算法(2026-08-01 最终定稿)**:经反编译官方字节码 + dacli 实测 + `tss2` 运行期验证三证对齐,定为**双约定模型**。传输层内层 S 分两种:**官方默认** `S = md5(明文)`(密文 96-hex,基准 `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`),**旧变体(legacy)** `S = 明文`(密文 32-hex,基准 `ea80d323686b9dfe734f2b42159db1a6`);存储层 `f_password = md5( S + f_secretkey.toLowerCase() )`。两条约定都合法但互不相通,登录失败通常是选错约定。`SecurityProperties.setSecurityKey` 的 setter 内部自动做 MD5,配置的 16 字符 key 实际变 32 字节 → AES-**256**;dacli `src/core/crypto.ts` 与本仓库 `tss2` 均用官方约定。 - **I · 烟测脚本**:新增零依赖 `scripts/smoke.mjs`(自检+登录+业务接口,可传参)。 - **J · `allow-bean-definition-overriding`**:`application.yml` 必须 `true`(JNPF 内部同名 bean)。 - **K · `mvc.pathmatch`**:`application.yml` 必须 `ant_path_matcher`。 - **附 · `ssw-admin/pom.xml`**:补全 JNPF 全部 controller 依赖清单(oauth/permission/system/file/message/extend/flowable/scheduletask/visualdev-*/visualdata/app)+ boot3 激活 `jnpf-ai-v3-controller`。 - **附 · `application.yml` / `application-dev.yml`**:给出与 JNPF 7.0 对齐的完整可运行样例(含 dynamic.datasource、redisson 无密码对齐、`mvc.pathmatch`、`allow-bean-definition-overriding`)。 - **附 · 脚手架落地**:本仓库已按 `app_code=tss` 落地完整可编译脚手架(`boot/` + `tss-web/`),上述每一处修正均经真实 `mvn -o package -pl ssw-admin -am` 与 `npm run build` 复核通过。 - **附 · tss2 二次落地(十六节)**:在不参考其它脚手架、不启用容器的前提下,仅依据本指南从零落地第二个应用 `tss2`(本仓库 `tss2/`),后端 `mvn -o package -pl ssw-admin -am` 与前端 `npm run build` 均通过、密码自检 PASS,证明指南可复用。新增内容:`ssw-boot`/`ssw-{app_code}` 完整父 pom 与聚合 pom(16.2)、`Tss2ServiceImpl` 文件位置(16.3)、controller 模块 spring-web 依赖说明(16.4)、tss2 命名映射表(16.1)、无容器验证方案与 `application.yml` 仅为差异补丁说明(16.6)。 - **附 · 示例占位通用化**:「示例占位约定」由固定的 `sswflow → tss` 改为 `sswflow → <你的 app_code>`,并明确**业务库名 == app_code**,避免第二次落地时误以为库名仍为 `sswflow`。 - **附 · tss2 运行期端到端验证(本轮补做)**:在真实 PostgreSQL + 新建 `tss2-redis` 上跑通「启动 → 登录 → 鉴权 → `@DS("tss2")` 写入 → 读出」,并核实数据只落在 `tss2` 库、`j7` 库无 `project` 表。由此新增:§8.2 密码算法全面重写(修正 H)、§8.2-B 自建账号 LOG004 授权坑与登录错误码速查表、§16.5 运行期验证结果表、§16.6 运行期五坑(`SERVER__PORT` 覆盖端口 / 容器名 vs 发布端口 / `dynamic.datasource` 少一层 / 文件存储路径不可写 / 后台进程被 shell 回收)、§16.8 造验证账号完整脚本;§13 速查表同步扩充 6 条。