228 lines
19 KiB
Markdown
228 lines
19 KiB
Markdown
# 后端脚本管理与全量 HTTP 验收索引
|
||
|
||
全量验收只认测试环境 HTTP 脚本。它们通过 Gateway 调用已部署服务，按业务模块执行真实登录、权限、状态、幂等、跨服务和数据链路检查；脚本通过后，剩余工作是 Admin/Client 的真实接口调用与浏览器样式验收，以及 PDA 页面/设备验收。
|
||
|
||
进入本目录维护或运行脚本前先读 `scripts/AGENTS.md`；本文件是脚本入口、用途和副作用的唯一总索引，具体模块说明继续下沉到相邻 README。
|
||
|
||
## 验收环境变量文件
|
||
|
||
开发与测试环境的账号、密码和 Gateway 只维护在用户目录的两份外部文件中，不写入仓库：
|
||
|
||
| 环境 | 文件 |
|
||
|---|---|
|
||
| 开发环境 | `$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env` |
|
||
| 测试环境 | `$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env` |
|
||
|
||
两份文件统一提供以下变量：
|
||
|
||
```text
|
||
ADMIN_TEST_GATEWAY
|
||
ADMIN_OVERSEAS_GATEWAY
|
||
ADMIN_TEST_USERNAME
|
||
ADMIN_TEST_PASSWORD
|
||
MERCHANT_TEST_USERNAME
|
||
MERCHANT_TEST_PASSWORD
|
||
```
|
||
|
||
脚本只读取当前 Node 进程的环境变量，不会自行查找或加载上述文件。运行时必须把 `--env-file` 放在脚本路径之前，明确选择环境：
|
||
|
||
```powershell
|
||
# 开发环境
|
||
node --env-file="$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env" scripts/admin-test-env-acceptance.mjs
|
||
|
||
# 测试环境
|
||
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/admin-test-env-acceptance.mjs
|
||
|
||
# 测试环境批量待分柜造数
|
||
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/it-test-wait-split-bulk.mjs
|
||
```
|
||
|
||
Client 全量、Client 二期、待审核订单和批量待分柜均复用这套变量，不再维护各自的 Gateway、管理员或客户账号变量。外部文件必须保留在仓库之外，不得复制到项目目录、报告或提交记录。
|
||
|
||
## 脚本目录归属
|
||
|
||
脚本按作用域放置，不要求全部集中到根 `scripts/`：
|
||
|
||
| 目录 | 归属 | 是否直接运行 |
|
||
|---|---|---|
|
||
| `scripts/` | 仓库级验收、回归、诊断、环境辅助和静态合同 | 本文“仓库级入口清单”列出的文件可以直接运行 |
|
||
| `scripts/admin-test-env-modules/` | `admin-test-env-acceptance.mjs` 动态加载的业务模块、fixture 和离线合同 | 业务 `.mjs` 原则上不直接运行；模块名、依赖和边界见该目录 `README.md` |
|
||
| `scripts/openapi-validation/` | 全仓 OpenAPI 发现、解析和引用校验 | 从该目录安装依赖后运行 `validate-openapi.mjs`；`validate-openapi.test.mjs` 是离线合同 |
|
||
| `firstleg/scripts/` | Firstleg 服务内部 Java 包依赖分析 | 只维护 Firstleg 内部模块化基线，与服务一起演进 |
|
||
| `lastleg-service/scripts/` | Lastleg 服务内部 Java 包依赖分析 | 只维护 Lastleg 内部模块化基线，与服务一起演进 |
|
||
| `warehouse/scripts/` | Warehouse 公共主数据等服务局部离线合同 | 从后端根用 Node test runner 执行，不连接数据库 |
|
||
| `deploy/scripts/` | Jenkins/部署主流程调用的镜像部署与测试库初始化脚本 | 只在受控部署或测试基础设施流程运行 |
|
||
| `deploy/rocketmq/` | RocketMQ 容器启动时渲染 broker 配置 | 由容器入口调用，不作为人工验收入口 |
|
||
|
||
因此 `firstleg/scripts/`、`lastleg-service/scripts/` 和 `deploy/**` 不是散落或放错目录；它们靠近所属部署单元或运行组件。仓库检索到的可执行脚本如果既不在上述目录，也没有在本表登记，应视为脚本归属缺失。
|
||
|
||
## 仓库级入口清单
|
||
|
||
下表覆盖 `scripts/` 下所有非 `*.test.mjs` 的可执行入口。`*.test.mjs` 统一为离线 Node 静态合同，不访问测试环境；`admin-test-env-modules/*.mjs` 的逐模块说明由该目录 `README.md` 和总入口注册表维护。
|
||
|
||
| 分类 | 入口 | 用途与副作用 |
|
||
|---|---|---|
|
||
| 测试环境 HTTP | `admin-test-env-acceptance.mjs` | Admin 全模块真实 HTTP 验收；按模块创建、更新、停用测试数据 |
|
||
| 测试环境 HTTP | `client-test-env-acceptance.mjs` | Client 完整真实 HTTP 链路；写入客户、订单、入库、权限和消息数据 |
|
||
| 测试环境 HTTP | `client-phase2-test-env-acceptance.mjs` | Client 二期入库、测量、费用和权限专项；写测试数据 |
|
||
| 测试环境 HTTP | `create-pending-review-orders.mjs` | 固定客户批量创建并提交待审核订单，不做平台审核和后续履约 |
|
||
| 测试环境 HTTP | `it-test-wait-split-bulk.mjs` | 固定“IT测试”与“义乌仓”，渠道等随机，逐票推进到 `WAIT_SPLIT`；失败继续并落报告。只复用 `TP-001`/`YW-TP-002`，不新增托盘或库位，库位不足使用公共位 `A0` |
|
||
| 测试环境 HTTP | `dimension-ocr-pricing-test-env.ps1` | 尺寸、OCR 和渠道计价专项，上传本地图片并写测试业务数据；包含历史默认参数，只能显式传入当前目标参数后使用 |
|
||
| 测试环境 HTTP | `export-center-test-env-acceptance.ps1` | 导出中心测试环境验收，会创建导出任务和相关测试数据 |
|
||
| 测试环境 HTTP | `phase2-test-env-acceptance.ps1` | 二期测试环境 API 验收，会写业务数据 |
|
||
| 场景组件 | `mojia-measurement-scenario.mjs` | 被 Admin 验收入口复用的墨家测量场景；不是独立 CLI，调用正式测量接口并上传图片 |
|
||
| 定向诊断 | `pda-final-complete-diagnostic.mjs` | 对指定 PDA task 回查最终完成门禁；传 `--seed-evidence` 时会补五类证据并产生写操作 |
|
||
| 本地真实 API | `order-warehouse-real-api-regression.ps1` | 本地 Order/Warehouse 往来单位真实 API 回归，并直接读写本机 MySQL；不得指向共享或测试数据库 |
|
||
| 一期本地验收 | `phase1-acceptance.ps1` | 一期本地服务/API 综合验收，会创建本地业务数据 |
|
||
| 一期本地验收 | `phase1-business-maturity-regression.ps1` | 一期业务成熟度回归，调用本地服务并生成报告 |
|
||
| 一期本地验收 | `phase1-onboarding-order-e2e.ps1` | 注册、资质、审核到下单的本地 E2E，会创建客户、仓库、往来单位和订单 |
|
||
| 本地质量 | `backend-full-regression.ps1` | Mapper 门禁后执行受影响后端 Maven 测试；`-DryRun` 只打印与校验 |
|
||
| 本地质量 | `frontend-full-regression.ps1` | 编排 Admin/Client 本地测试与类型检查，不访问 Gateway |
|
||
| 本地质量 | `database-comment-audit.ps1` | 离线扫描数据库中文注释，不连接数据库 |
|
||
| 本地质量 | `local-db-full-acceptance.ps1` | 只允许本机 MySQL 的受控 SQL 验收；非 dry-run 会写本地测试库 |
|
||
| 本地质量 | `mapper-scan-contract.mjs` | 离线检查 Mapper 注解与扫描入口，不启动 Spring、不连接数据库 |
|
||
| 本地质量 | `java-quality-summary.mjs` | 聚合 Maven 拓扑、OpenAPI、JaCoCo 和 SpotBugs 已有报告，不启动服务 |
|
||
| 本地质量 | `agents-index-contract.ps1` | 离线检查 AGENTS 快速索引与关键入口一致性 |
|
||
| 契约数据 | `synchronous-dependency-baseline.mjs` | 同步服务依赖合同的数据源，只由相邻合同测试导入，不是 CLI |
|
||
| OpenAPI | `openapi-validation/validate-openapi.mjs` | 发现并解析各服务 OpenAPI，检查跨文件引用；只读源码 |
|
||
| 本地环境 | `local-env.ps1` | 本地开发环境公共参数/辅助函数，由其他 PowerShell 脚本加载 |
|
||
| 本地环境 | `publish-local-nacos-config.ps1` | 将 `config/nacos/local/*.yml` 发布到指定本地 Nacos，会修改 Nacos 配置 |
|
||
| 密钥配置 | `generate-overseas-jwk.mjs` | 生成 3072 位海外 JWT RSA JWK 并写入指定 `deploy/env/.env.*`；已有 JWK 时拒绝覆盖，密钥文件不得提交 |
|
||
| 迁移辅助 | `migrate-local-qualification-file.ps1` | 本地资质文件迁移辅助，会修改本地文件/数据；运行前核对脚本参数和备份策略 |
|
||
| Jenkins 管理 | `provision-development-service-jobs.groovy` | Jenkins Script Console 批量准备开发服务 Job；默认 `applyChanges=false` 仅预览，改为 true 会创建 Job |
|
||
|
||
部署目录的入口另有：`deploy/scripts/deploy-built-service.sh`（单服务健康检查与失败回滚）、`deploy/scripts/deploy-development-service.sh`（经 SSH 部署开发服务）、`deploy/scripts/deploy-services.sh`（按服务列表编排部署）、`deploy/scripts/initialize-test-databases.sh`（初始化测试基础设施数据库）和 `deploy/rocketmq/render-broker-config.sh`（容器内渲染并启动 RocketMQ broker）。这些脚本都会改变运行环境，不能作为普通本地检查执行。
|
||
|
||
服务局部分析入口为 `firstleg/scripts/analyze-firstleg-dependencies.mjs` 与 `lastleg-service/scripts/analyze-lastleg-dependencies.mjs`，相邻的 `*.test.mjs` 负责对基线和违规依赖做离线回归；`warehouse/scripts/warehouse-public-master-data-contract.test.mjs` 只读校验 Warehouse 公共主数据 CSV 与 SQL。SQL 辅助文件 `scripts/db/incremental.sql` 不是当前统一部署入口，正式数据库变更以 `deploy/sql/README.md` 指向的统一增量为准。
|
||
|
||
新增可直接运行的脚本时，必须同时在本节登记用途、目标环境、是否写数据和密钥边界，并运行 `node --test scripts/script-documentation-contract.test.mjs`。仅新增 `*.test.mjs` 或 `admin-test-env-modules/` 内部模块时，分别更新对应合同范围或模块 README，不把内部文件误写成独立入口。
|
||
|
||
| 验收目标 | 唯一入口 | 数据副作用 | 覆盖范围 |
|
||
|---|---|---|---|
|
||
| 平台后台全模块 HTTP 验收 | `scripts/admin-test-env-acceptance.mjs` | 会创建、更新或最终停用测试数据 | `--modules` 默认列表中的平台客户、仓储、订单、入库、分柜、装柜、船期、拖车、报关、财务、通知、统计等模块 |
|
||
| 客户工作台完整 HTTP 链路验收 | `scripts/client-test-env-acceptance.mjs` | 会创建测试企业、订单、入库、权限和站内消息数据 | 注册/审核、客户隔离、订单、入库计费、文件、财务、客户侧权限，以及我的消息未读/已读/全部已读链路 |
|
||
| 固定客户批量创建待审核订单 | `scripts/create-pending-review-orders.mjs` | 只使用 `MERCHANT_TEST_USERNAME/PASSWORD` 配置的客户账号创建指定数量订单 | 使用 `ADMIN_TEST_GATEWAY`，选择真实可计价仓库/渠道，创建并提交订单，停在待审核，不创建客户、不审核订单 |
|
||
| Client 二期专项 HTTP 验收 | `scripts/client-phase2-test-env-acceptance.mjs` | 会写入测试环境业务数据 | 二期客户入库、测量、费用和权限专项场景；不是替代 Client 全量入口 |
|
||
| 人工分柜至 LOADED 分段验收 | `scripts/admin-test-env-acceptance.mjs` 的 `manual-*-fixture/verify` 可选模块；步骤和参数见 `scripts/admin-test-env-modules/README.md` | fixture 通过正式 HTTP 准备本轮数据，verify 只读核验；不进入默认全量 | `WAIT_SPLIT → 人工分柜 → 推送预装 → 订舱关联/计划确认 → PDA 领取与原子 batch → 五类证据/完成 → LOADED` |
|
||
|
||
执行前必须确认目标环境、账号和数据清理/停用策略，并获得当前对话的测试环境验收授权。`admin-test-env-modules/*contract.test.mjs` 只验证模块脚本结构，不能代替 HTTP 验收。
|
||
|
||
推荐顺序：部署服务 → Admin 全模块 HTTP 验收 → Client 完整 HTTP 链路验收 → 前端真实页面调用和样式验收 → PDA 页面/设备验收。任何本地单测通过都不能替代 HTTP 全量验收。
|
||
|
||
## 固定客户待审核订单
|
||
|
||
需要为人工审核准备固定数量的订单时，使用 `create-pending-review-orders.mjs`。Gateway 统一读取 `ADMIN_TEST_GATEWAY`，客户账号统一读取 `MERCHANT_TEST_USERNAME/PASSWORD`；数量可通过 `--count` 或 `PENDING_REVIEW_ORDER_COUNT` 设置，默认 50。脚本不会创建客户，也不会调用平台审核、入库或后续履约接口。数量支持 `1-100`，每张订单创建后立即提交并回查客户端状态为 `SUBMITTED`，报告统一记录为 `PENDING_REVIEW`。
|
||
|
||
```powershell
|
||
node scripts/create-pending-review-orders.mjs
|
||
```
|
||
|
||
## 本地质量检查（非全量验收）
|
||
|
||
以下命令只用于代码质量和契约回归，不访问测试环境，不代表服务全量可用：
|
||
|
||
| 检查 | 入口 |
|
||
|---|---|
|
||
| 后端 Maven 契约/单元测试 | `scripts/backend-full-regression.ps1` |
|
||
| Admin/Client 本地测试与类型检查 | `scripts/frontend-full-regression.ps1` |
|
||
| PDA 本地页面和状态测试 | `../apps/pda-uniapp/tests/*.test.mjs` |
|
||
| 本地数据库 SQL 静态/受控验收 | `scripts/local-db-full-acceptance.ps1` |
|
||
| AGENTS 快速索引一致性 | `scripts/agents-index-contract.ps1`；只读核对根快速表唯一性、部署单元、业务模块、Client active 路由、四期范围漂移、仓库主档唯一权威、订舱候选与柜量语义、整柜出仓与船节点单调性、海外 Gateway 覆盖、PDA 页面/运行配置/独立更新/语言预留/能力开关、人工分段验收链、Maven 模块、Lastleg 海外安全投影、同步 Trace、关键入口与排除目录 |
|
||
| Mapper 注册静态合同 | `node scripts/mapper-scan-contract.mjs`、`node --test scripts/mapper-scan-contract.test.mjs`；自动核对全部持久化模块的 `@Mapper`、服务根包注解过滤扫描和唯一扫描入口，不启动 Spring、不连接数据库；`backend-full-regression.ps1` 在 Maven 前强制执行 |
|
||
| Java 质量聚合摘要 | `node --test scripts/java-quality-summary.test.mjs`、`node scripts/java-quality-summary.mjs --output target/java-quality-summary.json`；聚合 Maven/服务拓扑、OpenAPI 覆盖、JaCoCo 和 SpotBugs 报告，默认只报告存量缺口，CI 用显式 `--require-jacoco --require-spotbugs` 检查报告完整性且当前允许失败 |
|
||
| 单服务部署失败回滚合同 | `scripts/deploy-built-service-rollback.test.mjs`；模拟成功、健康失败和启动失败，确认仅恢复同服务先前健康镜像且部署任务仍失败 |
|
||
| 容器日志单写合同 | `scripts/container-logging-contract.test.mjs`；离线确认应用只写标准输出、Compose 默认使用宝塔可见的有界 `json-file` 驱动且不挂载应用日志目录 |
|
||
|
||
Admin/Client HTTP 脚本的离线合同只验证脚本结构、参数和模块边界，不访问测试环境：
|
||
|
||
| 合同范围 | 入口 |
|
||
|---|---|
|
||
| Admin 订单、箱码、三期装柜/PDA、订舱、拖车、通知 | `scripts/admin-test-env-modules/*contract.test.mjs`；模块映射见 `scripts/admin-test-env-modules/README.md` |
|
||
| Client 消息中心调用 | `scripts/client-notifications-contract.test.mjs` |
|
||
| 验收入口与模块注册 | `scripts/full-regression-entry-contract.test.mjs`、`scripts/controller-pipeline-contract.test.mjs` |
|
||
|
||
## 后端全量回归
|
||
|
||
## 入口
|
||
|
||
在 `baiyue-firstleg` 根目录执行：
|
||
|
||
```powershell
|
||
.\scripts\backend-full-regression.ps1
|
||
```
|
||
|
||
## 前端全量回归
|
||
|
||
`frontend-full-regression.ps1` 只编排本地 Admin/Client 的 `pnpm test` 与 `pnpm typecheck`，不调用 Gateway、不部署、不连接数据库。
|
||
|
||
```powershell
|
||
.\scripts\frontend-full-regression.ps1 -DryRun
|
||
.\scripts\frontend-full-regression.ps1
|
||
.\scripts\frontend-full-regression.ps1 -SkipAdmin
|
||
.\scripts\frontend-full-regression.ps1 -SkipClient
|
||
```
|
||
|
||
脚本会检查 `pnpm` 和目标应用的 `package.json`；任一命令失败时立即透传退出码，不能同时跳过 Admin 和 Client。
|
||
|
||
后端脚本固定运行：
|
||
|
||
```text
|
||
mvn -f <仓库根>/pom.xml -pl order,firstleg,iam,gateway,file,warehouse -am test
|
||
```
|
||
|
||
这会先构建公共依赖，再运行 `order`、`firstleg`、`iam`、`gateway`、`file` 与 `warehouse` 的全部 Maven 测试。覆盖包括：
|
||
|
||
- 三期 Ocean Booking Controller/Service/Mapper/SQL 契约；
|
||
- 三期 Truck Appointment Controller/Service/Mapper 契约、状态机、乐观锁和幂等操作；
|
||
- 二期 `WAIT_SPLIT` 的 firstleg 查询、order 统一查询及筛选语义；
|
||
- Warehouse 海外仓阶梯费用 SQL 与 Controller 权限合同；
|
||
- 拣货/预装/装柜模型映射与既有 Smart Loading/Split 契约。
|
||
|
||
## Dry-run
|
||
|
||
```powershell
|
||
.\scripts\backend-full-regression.ps1 -DryRun
|
||
```
|
||
|
||
Dry-run 只检查根 `pom.xml` 和关键回归测试文件并打印 Maven 命令，不启动 Java 服务，不请求 Gateway，不连接或写入任何数据库。
|
||
|
||
## 现有相关脚本与边界
|
||
|
||
### 数据库中文注释审计
|
||
|
||
`database-comment-audit.ps1` 离线扫描各模块 `src/main/resources/db/*.sql` 中的 `CREATE TABLE` 定义，不连接数据库、不执行 SQL，也不修改任何文件。
|
||
|
||
```powershell
|
||
.\scripts\database-comment-audit.ps1
|
||
.\scripts\database-comment-audit.ps1 -Modules finance,order
|
||
.\scripts\database-comment-audit.ps1 -Modules finance -SummaryOnly
|
||
.\scripts\database-comment-audit.ps1 -Format Json
|
||
.\scripts\database-comment-audit.ps1 -FailOnIssues
|
||
.\scripts\database-comment-audit.ps1 -SelfTest
|
||
```
|
||
|
||
默认报告模式即使存在存量缺口也返回 `0`；CI 使用 `-FailOnIssues`，缺失或纯英文表/字段注释返回 `1`，模块或路径配置错误返回 `2`。规范和注释口径见 `../docs/数据库注释维护规范.md`。
|
||
|
||
### 本地 MySQL 全量验收
|
||
|
||
正式入口是 `local-db-full-acceptance.ps1`，只允许连接本机 `127.0.0.1` 或 `localhost`，默认端口 `3306`；测试库 `8.163.30.128` 会立即以退出码 2 拒绝。脚本固定校验统一 SQL SHA-256 `00E8F9C24CE16FE6B4D2B6AF60460AE1AF1D264DFE110D4BDCE611F09EB69EAA` 和 15403 行，并静态确认中文注释升级采用校验入队、每表一次 ALTER、结构签名复核、九库覆盖断言及唯一最终 `PASS`。
|
||
|
||
```powershell
|
||
.\scripts\local-db-full-acceptance.ps1 -DryRun
|
||
.\scripts\local-db-full-acceptance.ps1
|
||
```
|
||
|
||
Dry-run 只校验 SQL 输入并打印空库、复跑、两类 picking 旧结构、WAIT_SPLIT/IAM、海外仓旧结构、中断恢复和最终结构的执行顺序，不启动 MySQL、不写库。真实运行每阶段写入 `.codex-tmp/p23-04-acceptance/acceptance-run-*.log`，不使用 `--force`，任一 SQL 错误立即停止并透传退出码，最后执行 `verify-final.sql`。脚本不保存或传入数据库密码，使用本机默认认证环境。
|
||
|
||
仓库中 `phase2-test-env-acceptance.ps1`、`admin-test-env-acceptance.mjs`、`client-test-env-acceptance.mjs`、`export-center-test-env-acceptance.ps1` 等属于测试环境/API 验收脚本；它们可能读取或写入测试环境数据，不由本入口调用。`migrate-local-qualification-file.ps1`、`local-env.ps1` 等是环境/迁移辅助脚本，也不由本入口调用。
|
||
|
||
本入口不读取数据库凭据、不执行 MySQL、HTTP、迁移、DDL、INSERT/UPDATE/DELETE，也不启动 Nacos、Gateway 或业务服务。需要数据库矩阵时必须单独运行受控验收流程。
|
||
|
||
## 退出码
|
||
|
||
- `0`：dry-run 检查通过或 Maven 全量测试通过；
|
||
- `2`：仓库根 pom 或关键测试文件缺失，脚本未启动 Maven；
|
||
- 其他非零值：原样透传 Maven 失败退出码。
|
||
|
||
脚本不设置 `MAVEN_OPTS`、数据库 URL 或测试账号；环境参数仅为可选的 `$MavenCommand`（默认 `mvn`），用于指定本机 Maven 可执行文件。
|