Files
ssw-mvp/docs/JNPF_BACKEND_GUIDE.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

1533 lines
87 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.
# 按 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 → <AppCode>`、`SswflowXxxService → <AppCode>XxxService`、`库 sswflow → <你的 app_code>`、`API /api/ssw/sswflow → /api/ssw/<你的 app_code>`。
> **关键:业务库名 == app_code**(双库架构下每个 app_code 独立库,`dynamic.datasource.<app_code>` 与 `@DS("<app_code>")` 同名)。
>
> 已落地验证:
> - `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<String>`(`EntityBase` 在 7.0.0 不存在) | 🔴 编译失败 |
| C | §3.2 | entity pom 裸写 `mybatis-plus-boot-starter` / `dynamic-datasource-spring-boot-starter` 且无 `<version>` | 删除这两个依赖(随 `jnpf-common-all` 传递引入);确需锁版本必须显式写 `<version>` | 🔴 `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 extends DataSourceUtil> 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/<module>` 路径下。
```
官方根域:https://coding.jnpfsoft.com/v7.0/<module>
登录账号:[email protected]
登录密码: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/<module> && 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 里 `<server>` 的 id 配成 `maven-releases`,就能同时覆盖这两种地址。
**放在哪**:用户级 `~/.m2/settings.xml`(推荐),或 Maven 安装目录 `conf/settings.xml`。在对应节点里加入:
```xml
<!-- 1) <servers> 里加:私服账号密码(id 必须叫 maven-releases) -->
<server>
<id>maven-releases</id>
<username>[email protected]</username>
<password>ssw222666</password>
</server>
<!-- 2) <mirrors> 里加:把所有下载请求镜像到官方私服(README 官方写法) -->
<mirror>
<id>maven-releases</id>
<mirrorOf>*</mirrorOf>
<name>maven-releases</name>
<url>https://repository.jnpfsoft.com/repository/maven-public/</url>
</mirror>
```
> 配好后 `mvn` 就能从官方私服拉依赖。IDEA 若出现部分依赖报红,重启 IDEA 清缓存即可(README 原话)。
> 注意 `~/.m2/settings.xml` 默认是 Maven 的**示例模板**,本身没有任何 `<server>`,初次使用时务必补上上面的内容。
---
### 〇-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` 父子关系**
- `<parent>` 从 `jnpf-java-boot` 改成你自己的聚合父 `ssw-boot`(或直连 `jnpf-common`)。
- `<artifactId>` 改成 `ssw-admin`。
- `<dependencies>` 保留 JNPF 各 `*-controller`(完整清单见 §3.2 末的 `ssw-admin/pom.xml` 示例);**新增你自己的业务 controller**,例如:
```xml
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>ssw-sswflow-controller</artifactId>
<version>${project.version}</version>
</dependency>
```
> 注意 `<groupId>com.jnpf</groupId>` 这里是对的——它是 Maven **坐标的 groupId**;只有 Java 源码包名才是 `jnpf`(见第 2 点)。
- `<profiles>` 里的 `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` 的 `<groupId>` 与依赖坐标前缀,与 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 <jnpf_db_init / jnpf_flow_init / jnpf_xxljob_init 所在目录>
> ```
> 若同机 `~/.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` 的 `<properties>` 统一设:
```xml
<!-- ssw-boot/pom.xml 的 properties(父链:ssw-boot → jnpf-common → jnpf-dependencies) -->
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<java.version>17</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!-- JNPF 平台构件统一版本 -->
<jnpf.version>7.0.0-RELEASE</jnpf.version>
<!-- 本工程 app_code,贯穿包名/bean名/API前缀/业务库名 -->
<ssw.app-code>sswflow</ssw.app-code>
</properties>
```
不覆盖会报:`-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
> <dependencies>
> <!--
> jnpf-common-all 提供:
> jnpf.base.entity.SuperEntity / SuperBaseEntity(公共字段,已映射 f_xxx 列)
> jnpf.base.ActionResult / jnpf.base.vo.PageListVO
> jnpf.base.service.SuperServiceImpl / jnpf.base.mapper.SuperMapper
> Sa-Token、dynamic-datasource(@DS)等整套依赖
> -->
> <dependency>
> <groupId>com.jnpf</groupId>
> <artifactId>jnpf-common-all</artifactId>
> <version>${jnpf.version}</version>
> </dependency>
>
> <!--
> lombok:JNPF 侧是 provided scope,不会传递到你的模块。
> 业务实体若使用 @Data/@Getter 必须自行声明,否则编译报 "找不到符号 getXxx()"。
> 放在 entity 模块;若 biz/controller 也用 lombok,同样加。
> -->
> <dependency>
> <groupId>org.projectlombok</groupId>
> <artifactId>lombok</artifactId>
> <scope>provided</scope>
> </dependency>
>
> <!--
> ⚠️ 不要照搬"只写 groupId/artifactId 不写 version"的写法:
> jnpf-common 的 dependencyManagement 并未托管 mybatis-plus-boot-starter /
> dynamic-datasource-spring-boot-starter,缺 version 会直接构建失败:
> 'dependencies.dependency.version' for com.baomidou:... is missing
> 这两者已由 jnpf-common-all 传递引入(MyBatis-Plus 3.5.x + dynamic-datasource 4.x),
> 正常情况【无需声明】。若确需锁版本,必须显式写 <version>。
> -->
> </dependencies>
> ```
> 父 `ssw-boot/pom.xml` 也可以全局给一份 lombok(继承给所有子模块),与本模块声明二选一即可:
> ```xml
> <dependencies>
> <dependency>
> <groupId>org.projectlombok</groupId>
> <artifactId>lombok</artifactId>
> <scope>provided</scope>
> </dependency>
> </dependencies>
> ```
**`ssw-admin/pom.xml` 依赖 JNPF 各 controller(完整清单,缺一不可,否则登录/`/api` 能力缺失):**
```xml
<dependencies>
<!-- 自有业务模块 -->
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>ssw-sswflow-controller</artifactId>
<version>${project.version}</version>
</dependency>
<!-- JNPF 平台 controller:登录 /api/oauth/Login 由 jnpf-oauth-controller 提供,必需 -->
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-oauth-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-permission-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-system-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-file-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-message-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-extend-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-flowable-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-scheduletask-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-base-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-generater-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-onlinedev-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-portal-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdata-controller</artifactId><version>${jnpf.version}</version></dependency>
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-app-controller</artifactId><version>${jnpf.version}</version></dependency>
</dependencies>
<profiles>
<!-- boot3:JDK 17+ 启用 AI v3 controller,原样保留 -->
<profile>
<id>boot3</id>
<activation><jdk>[17,)</jdk></activation>
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-ai-v3-controller</artifactId>
<version>${jnpf.version}</version>
</dependency>
</dependencies>
</profile>
</profiles>
<build>
<finalName>ssw-admin-${project.version}</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>ssw.SswAdminApplication</mainClass>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
<executions><execution><goals><goal>repackage</goal></goals></execution></executions>
</plugin>
</plugins>
</build>
```
---
## 四、实体层规范(entity)
### 4.1 字段命名:JNPF 风格 `f_xxx`
> **【修正 B】基类是 `jnpf.base.entity.SuperEntity<T>`(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<String> {
// 业务字段(公共字段已在父类,无需也不应重复声明)
@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<ProjectEntity> {
ActionResult<PageListVO> pageList(ProjectPageForm form);
void create(ProjectEntity e);
}
// 实现——⚠️ bean 名 + @DS 都必须显式指定
@Service("sswflowProjectService")
@DS("sswflow") // ⚠️ 切到业务库;注解不继承,子类必须各自打
public class ProjectServiceImpl extends SswflowServiceImpl<ProjectMapper, ProjectEntity>
implements ProjectService {
@Override
public ActionResult<PageListVO> pageList(ProjectPageForm form) {
// 用 MyBatis-Plus 分页;JNPF 分页包装见第六节
}
}
```
> **所有 `@Service` 实现类都加 `@Service("sswflow<Short>Service")` + `@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<List<ProjectEntity>> all() {
return ActionResult.success(projectService.list());
}
@GetMapping
public ActionResult<PageListVO> list(@RequestBody ProjectPageForm form) {
return projectService.pageList(form);
}
@PostMapping
public ActionResult<String> 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("Sswflow<Entity>Entity")`(如 `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<String> objectIds = 用户的岗位ID列表(position);
objectIds.add(user.getId());
List<?> roles = roleRelationApi.getListByObjectId(objectIds, null); // base_role_relation
List<String> 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<String> { ... }
@Service("sswflowProjectService")
@DS("sswflow") // ⚠️ 注解【不继承】!子类必须各自打,写在基类上无效
public class ProjectServiceImpl extends SswflowServiceImpl<ProjectMapper, ProjectEntity>
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 extends jnpf.database.util.DataSourceUtil> 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<M extends SuperMapper<T>, T>
extends SuperServiceImpl<M, T> 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: !<org.redisson.codec.JsonJacksonCodec> {}
```
> **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/<module>` 补齐(〇-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 传递引入),或显式加 `<version>`(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.<name>` | 必须是 `dynamic.**datasource**.<name>`(§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<String>`、**不重复声明公共字段**、`@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 的 `<BasicTable>` / `<JnpfForm>` 等私有组件(它们强耦合 JNPF 运行时,迁移成本高于收益)。
- 页面不强求 `views/<module>/<page>` 的命名 —— 可读性优先,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.<app_code>` 与 `@DS("<app_code>")` 用同一个名字;`application-dev.yml` 里 `${SSWFLOW_DB:<app_code>}` 的默认值也填 app_code(tss2 即 `tss2`)。
### 16.2 完整父 pom / 聚合 pom(指南此前只给了 `<properties>`,缺可拼装的整文件)
`boot/pom.xml`(ssw-boot,父链 `ssw-boot → jnpf-common → jnpf-dependencies`):
```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common</artifactId>
<version>7.0.0-RELEASE</version>
</parent>
<groupId>com.jnpf</groupId>
<artifactId>ssw-boot</artifactId>
<version>7.0.0-RELEASE</version>
<packaging>pom</packaging>
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<java.version>17</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<jnpf.version>7.0.0-RELEASE</jnpf.version>
<ssw.app-code>tss2</ssw.app-code>
</properties>
<modules>
<module>ssw-tss2</module>
<module>ssw-admin</module>
</modules>
<dependencies>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
</project>
```
`boot/ssw-tss2/pom.xml`(业务聚合,下面挂 entity/biz/controller 三个子模块):
```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.jnpf</groupId>
<artifactId>ssw-boot</artifactId>
<version>7.0.0-RELEASE</version>
</parent>
<artifactId>ssw-tss2</artifactId>
<packaging>pom</packaging>
<modules>
<module>ssw-tss2-entity</module>
<module>ssw-tss2-biz</module>
<module>ssw-tss2-controller</module>
</modules>
</project>
```
> 三个子模块 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<ProjectMapper, ProjectEntity> implements ProjectService`。
- 它已实现 `DynamicSourceGeneratorInterface`(`jnpf.database.plugins` 包,泛型 `<T extends DataSourceUtil> 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 托管,无需写 `<version>`):
```xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
```
### 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**.<app_code>`,少写中间那层 `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<String>`(含 `SuperBaseEntity` 的 `id`),公共字段表补全为 9 列,明确"勿重复声明"。
- **C · entity 依赖**:删除无 version 的 `mybatis-plus-boot-starter` / `dynamic-datasource-spring-boot-starter`(随 `jnpf-common-all` 传递引入),补"如需锁版本必须显式 `<version>`"。
- **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 extends DataSourceUtil> 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 条。