优化
This commit is contained in:
@@ -26,6 +26,7 @@
|
||||
| 履约分配、入库、测量、审核、FBA 计费 | `firstleg/` | `firstleg/AGENTS.md` |
|
||||
| Firstleg 内部模块化与依赖基线 | `firstleg/` | `firstleg/docs/firstleg-internal-modularization-baseline.md`、`firstleg/scripts/analyze-firstleg-dependencies.mjs`；价格簿查询和客户统计按端口/适配器切片，不改变服务与数据库边界 |
|
||||
| Mapper 新增、移动、Bean 缺失与扫描遗漏 | 目标持久化服务 | 所有 Mapper 显式 `@Mapper`，启动类按服务根包注解过滤扫描；先运行 `node scripts/mapper-scan-contract.mjs`，再按目标模块执行 `test-compile/test`，不得等部署启动发现 |
|
||||
| 脚本管理、全量验证、测试造数与诊断 | 仓库根 `scripts/`；服务专属脚本留在 `<service>/scripts/` | 先读 `scripts/AGENTS.md` 和 `scripts/README.md`；Admin HTTP 内部模块继续读 `scripts/admin-test-env-modules/README.md`。新增入口必须登记用途、目标环境、数据副作用和报告位置，并通过 `scripts/script-documentation-contract.test.mjs` |
|
||||
| 分柜、柜次、智能排柜、预装/装柜清单、PDA | `firstleg/` | `firstleg/AGENTS.md`，再按 `split/`、`loading/`、`outbound/` 定位；预装/正式装柜详情阶段由 `/loading-plans/{planId}/lifecycle` 按稳定 planId 解析，不从 404 或文案推断 |
|
||||
| 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | `firstleg/` | `loading/coload/controller/PlatformColoadGroupController.java`、`service/ColoadGroupService.java`、`persistence/ColoadGroupMapper.java`、`src/main/resources/openapi/coload-groups-v1.yaml`；按订单建组并冻结全部可用入仓片段，仅要求同国内仓、同渠道 |
|
||||
| 智能装柜入仓码候选与箱数分配 | `firstleg/` | `controller/PlatformSmartLoadingController.java` 的 `/inbound-candidates`、`/plans/{planId}/inbound-assignments`，业务编排 `service/SmartLoadingService.java` |
|
||||
@@ -94,12 +95,15 @@
|
||||
|
||||
## 全量 HTTP 验收脚本路由
|
||||
|
||||
- 脚本管理的唯一总索引是 `scripts/README.md`，最近执行规则是 `scripts/AGENTS.md`。仓库级脚本、Admin 内部模块、服务局部合同和部署脚本的目录归属以这两个文件为准，不再通过无范围搜索猜测入口。
|
||||
- 全量验收唯一指向测试环境 HTTP：平台端执行 `scripts/admin-test-env-acceptance.mjs`，客户端执行 `scripts/client-test-env-acceptance.mjs`；二期专项场景才单独执行 `scripts/client-phase2-test-env-acceptance.mjs`，不替代客户端全量入口。
|
||||
- 固定客户待审核订单使用 `scripts/create-pending-review-orders.mjs`；固定“IT测试”与“义乌仓”、随机真实线路并推进至 `WAIT_SPLIT` 使用 `scripts/it-test-wait-split-bulk.mjs`。二者都是造数入口，不属于全量验证；会写目标环境且不自动清理成功数据。
|
||||
- Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 `--modules <name>`，模块名称和静态合同先查 `scripts/admin-test-env-modules/README.md`。
|
||||
- 这些脚本会创建、更新或最终停用测试数据，必须在当前对话明确授权测试环境验收后执行，并保存 JSON 报告；未授权不得请求 Gateway。
|
||||
- 后端 Maven、前端 `pnpm test/typecheck`、PDA `node --test` 和数据库 Dry-run 都是本地质量检查，不属于全量 HTTP 验收。
|
||||
- Java 模块、OpenAPI 覆盖、JaCoCo 与 SpotBugs 聚合摘要使用 `node scripts/java-quality-summary.mjs`；默认仅报告存量缺口，是否阻断由显式 `--require-*` 参数决定，输出位于 `target/` 时不得作为业务事实或提交物。
|
||||
- HTTP 全量通过后，才进入 Admin/Client 真实页面调用、浏览器样式和 PDA 页面/设备验收；自动化 HTTP 通过不代表视觉验收完成。
|
||||
- 修改脚本目录、入口或说明后，至少运行 `node --test scripts/script-documentation-contract.test.mjs`；修改 `AGENTS.md` 后继续运行 `./scripts/agents-index-contract.ps1`。两者均为离线只读合同，不能代替真实 HTTP 验收。
|
||||
|
||||
## 阶段文档入口
|
||||
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
# 后端脚本管理指引
|
||||
|
||||
## 适用范围与读取顺序
|
||||
|
||||
- 本文件适用于后端根 `scripts/` 及其子目录；服务自己的 `<service>/scripts/` 继续受对应服务 `AGENTS.md` 约束。
|
||||
- 先用本文件判断脚本类别，再到 `README.md` 查询仓库级入口的用途、参数边界和副作用；Admin HTTP 模块继续读 `admin-test-env-modules/README.md`。
|
||||
- 不扫描 `target/`、`reports/`、`.logs/`、`node_modules/`、`.codex-*`、`output/` 或 `outputs/` 寻找业务脚本和验收事实。
|
||||
|
||||
## 脚本分类与入口
|
||||
|
||||
| 类别 | 正式入口 | 管理边界 |
|
||||
|---|---|---|
|
||||
| Admin 全量 HTTP 验证 | `admin-test-env-acceptance.mjs` | 默认模块覆盖平台全链路；定向验证使用 `--modules`，模块注册和依赖以总入口及 `admin-test-env-modules/README.md` 为准 |
|
||||
| Client 全量 HTTP 验证 | `client-test-env-acceptance.mjs` | 客户工作台完整链路；`client-phase2-test-env-acceptance.mjs` 只是二期专项，不替代全量入口 |
|
||||
| 待审核订单造数 | `create-pending-review-orders.mjs` | 使用已配置客户创建并提交订单，停在待审核；不审核、不推进后续履约 |
|
||||
| 批量待分柜造数 | `it-test-wait-split-bulk.mjs` | 固定“IT测试”和“义乌仓”，随机客户可选真实线路并尽力推进到 `WAIT_SPLIT`；失败记录后继续，不自动删除成功数据；只复用 `TP-001`/`YW-TP-002`，不新增托盘或库位，普通位不足落 `A0` |
|
||||
| Admin HTTP 内部模块 | `admin-test-env-modules/*.mjs` | 由 Admin 总入口动态加载，除文档明确的独立编排器外不得当作独立全量入口；`*contract.test.mjs` 只做离线合同 |
|
||||
| 定向 HTTP/诊断 | 以 `README.md` 的“仓库级入口清单”为准 | 必须明确是只读诊断还是会补证据、创建资源或推进状态，不能用诊断成功冒充全量通过 |
|
||||
| 本地质量与静态合同 | `backend-full-regression.ps1`、`frontend-full-regression.ps1`、`mapper-scan-contract.mjs`、`script-documentation-contract.test.mjs` 等 | 默认不访问测试环境；数据库非 dry-run、Nacos 发布等有写入能力的入口必须按 README 单独识别 |
|
||||
| 部署与基础设施 | `../deploy/scripts/`、`../deploy/rocketmq/` | 靠近部署组件管理，不移动到根脚本目录；部署、初始化数据库或发布配置必须获得当前轮明确授权 |
|
||||
| 服务局部合同 | `../firstleg/scripts/`、`../lastleg-service/scripts/`、`../warehouse/scripts/` | 只服务所属模块，入口与命令登记在服务 `AGENTS.md` 或局部 README；不得散落到 `src/test/scripts/` |
|
||||
|
||||
## 新增与修改规则
|
||||
|
||||
- 跨服务编排、全仓质量检查、测试环境验收和通用诊断放在根 `scripts/`；只理解单一服务源码或数据的脚本放在 `<service>/scripts/`。
|
||||
- 可直接运行的脚本必须在 `README.md` 登记：用途、目标环境、是否写数据、凭据来源、报告位置、失败/重跑语义和清理边界。内部模块必须登记到 `admin-test-env-modules/README.md`，并按需同步总入口模块注册及依赖展开。
|
||||
- 文件命名使用稳定业务语义：离线 Node 合同以 `.test.mjs` 结尾；环境写入入口显式包含 `test-env` 或在 README 中标记目标环境；fixture/verify 必须区分准备写入和只读核验。
|
||||
- 不在源码、AGENTS、README 或报告中写入密码、Token、私钥、真实客户数据和固定环境密钥；环境地址与账号从入口已支持的参数或本机环境配置读取。
|
||||
- 不直接写业务数据库伪造 HTTP 验收成功，不吞掉 `deploymentBlocker`、业务错误码、`requestId` 或 `traceId`。造数脚本的部分成功数据默认保留，清理、重置或删除必须另行授权。
|
||||
- 不默认并发运行共享环境造数。只有用户明确要求并确认序号、报告目录和服务容量边界时，才允许拆分 worker；每个 worker 必须使用不重叠序号和独立报告目录。
|
||||
- 修改公共参数、上下文或模块签名时，定向检查总入口、生产模块、fixture、合同测试、README 和调用命令，禁止保留旧参数兼容分支。
|
||||
|
||||
## 最低验证
|
||||
|
||||
- 修改单个 Node 脚本先运行 `node --check <script>`；PowerShell 使用解析检查或该脚本声明的 `-DryRun`，Shell/Groovy 使用现有离线合同，不为验证触发部署。
|
||||
- 修改 Admin 模块时运行直接对应的 `*contract.test.mjs`；修改造数链时同时运行 `admin-test-env-modules/it-test-wait-split-bulk-contract.test.mjs` 等受影响合同。
|
||||
- 新增、移动或删除脚本后运行 `node --test scripts/script-documentation-contract.test.mjs`，确认目录已登记且所有直接入口都有说明。
|
||||
- 修改任一 `AGENTS.md` 后从后端根运行 `./scripts/agents-index-contract.ps1`；真实 HTTP、数据库、Nacos、Jenkins 和部署验证仍须当前轮明确授权。
|
||||
+3
-1
@@ -1,7 +1,9 @@
|
||||
# 全量 HTTP 验收脚本索引
|
||||
# 后端脚本管理与全量 HTTP 验收索引
|
||||
|
||||
全量验收只认测试环境 HTTP 脚本。它们通过 Gateway 调用已部署服务，按业务模块执行真实登录、权限、状态、幂等、跨服务和数据链路检查；脚本通过后，剩余工作是 Admin/Client 的真实接口调用与浏览器样式验收，以及 PDA 页面/设备验收。
|
||||
|
||||
进入本目录维护或运行脚本前先读 `scripts/AGENTS.md`；本文件是脚本入口、用途和副作用的唯一总索引，具体模块说明继续下沉到相邻 README。
|
||||
|
||||
## 脚本目录归属
|
||||
|
||||
脚本按作用域放置，不要求全部集中到根 `scripts/`：
|
||||
|
||||
@@ -7,7 +7,7 @@ const source = readFileSync(new URL('./phase4-overseas-master-data.mjs', import.
|
||||
const controllerSource = [
|
||||
'../../lastleg-service/src/main/java/com/baiyue/lastleg/masterdata/quote/controller/PlatformOverseasQuoteController.java',
|
||||
'../../lastleg-service/src/main/java/com/baiyue/lastleg/masterdata/exchange/controller/PlatformMonthlyExchangeRateController.java',
|
||||
'../../lastleg-service/src/main/java/com/baiyue/lastleg/masterdata/vehicle/controller/PlatformVehicleController.java',
|
||||
'../../lastleg-service/src/main/java/com/baiyue/lastleg/masterdata/vehicle/adapter/in/web/PlatformVehicleController.java',
|
||||
].map((path) => readFileSync(new URL(path, import.meta.url), 'utf8')).join('\n')
|
||||
const DOMESTIC_BASE = '/api/platform/v1/warehouse-admin'
|
||||
const OVERSEAS_BASE = '/api/platform/v1/last-leg/master-data'
|
||||
|
||||
@@ -92,6 +92,7 @@ $clientAgents = Read-RequiredText $clientAgentsPath
|
||||
$pdaAgents = Read-RequiredText $pdaAgentsPath
|
||||
$overseasPdaAgents = Read-RequiredText $overseasPdaAgentsPath
|
||||
$backendAgents = Read-RequiredText $backendAgentsPath
|
||||
$scriptsAgents = Read-RequiredText (Join-Path $backendRoot 'scripts/AGENTS.md')
|
||||
$engineeringConstraints = Read-RequiredText (Join-Path $workspaceRoot 'docs/AI工程执行与协作约束.md')
|
||||
$mapperScanContract = Read-RequiredText (Join-Path $backendRoot 'scripts/mapper-scan-contract.mjs')
|
||||
|
||||
@@ -100,19 +101,33 @@ Assert-Contains $rootAgents '源码结构、接口与 DTO、字段、状态机
|
||||
Assert-Contains $rootAgents '数据库记录、上传文件、缓存、会话、消息、搜索索引和其他运行状态均视为可丢弃' '根开发运行状态范围'
|
||||
Assert-Contains $rootAgents '后端 MyBatis Mapper 新增、移动或扫描遗漏' '根 Mapper 快速入口'
|
||||
Assert-Contains $rootAgents 'node scripts/mapper-scan-contract.mjs' '根 Mapper 静态门禁'
|
||||
Assert-Contains $rootAgents '脚本管理、全量验证与测试造数' '根脚本管理快速入口'
|
||||
Assert-Contains $rootAgents 'baiyue-firstleg/scripts/AGENTS.md' '根脚本最近指引'
|
||||
Assert-Contains $engineeringConstraints '禁止为旧代码、旧调用或开发环境存量保留旧接口/旧字段别名' '工程无兼容执行规则'
|
||||
Assert-Contains $engineeringConstraints '不授权自动重置数据库、删除数据/文件、执行 SQL、部署或修改环境' '无兼容安全边界'
|
||||
Assert-Contains $clientAgents '不得继续扩展 `LEGACY_MANUAL`、旧系统入仓码、C02 不可用回退旧 API' 'Client 头程无兼容边界'
|
||||
Assert-Contains $backendAgents '所有生产 MyBatis Mapper 接口必须显式标记 `@Mapper`' '后端 Mapper 注册规则'
|
||||
Assert-Contains $backendAgents 'Mapper 新增、移动、Bean 缺失与扫描遗漏' '后端 Mapper 快速路由'
|
||||
Assert-Contains $backendAgents '脚本管理、全量验证、测试造数与诊断' '后端脚本管理快速路由'
|
||||
Assert-Contains $backendAgents 'scripts/it-test-wait-split-bulk.mjs' '后端批量待分柜造数入口'
|
||||
Assert-Contains $backendAgents 'scripts/create-pending-review-orders.mjs' '后端待审核订单造数入口'
|
||||
Assert-Contains $scriptsAgents 'admin-test-env-acceptance.mjs' '脚本指引 Admin 全量入口'
|
||||
Assert-Contains $scriptsAgents 'client-test-env-acceptance.mjs' '脚本指引 Client 全量入口'
|
||||
Assert-Contains $scriptsAgents 'script-documentation-contract.test.mjs' '脚本说明防漏门禁'
|
||||
Assert-Contains $scriptsAgents '不得散落到 `src/test/scripts/`' '服务局部脚本目录边界'
|
||||
Assert-Path 'baiyue-firstleg/scripts/AGENTS.md'
|
||||
Assert-Path 'baiyue-firstleg/scripts/README.md'
|
||||
Assert-Path 'baiyue-firstleg/scripts/script-documentation-contract.test.mjs'
|
||||
Assert-Contains $mapperScanContract 'annotationClass = Mapper.class' 'Mapper 根包注解过滤合同'
|
||||
Assert-Contains $mapperScanContract '禁止分散维护 MapperScan' 'Mapper 单一扫描入口合同'
|
||||
$firstlegAgents = Read-RequiredText (Join-Path $backendRoot 'firstleg/AGENTS.md')
|
||||
$warehouseAgents = Read-RequiredText (Join-Path $backendRoot 'warehouse/AGENTS.md')
|
||||
$coloadOpenApi = Read-RequiredText (Join-Path $backendRoot 'firstleg/src/main/resources/openapi/coload-groups-v1.yaml')
|
||||
Assert-Contains $rootAgents 'modules/unified-orders/api/coLoadGroups.ts' '根同柜不可拆组入口'
|
||||
Assert-Contains $adminAgents '成员数是入仓片段数，不等于订单票数' 'Admin 同柜成员语义'
|
||||
Assert-Contains $backendAgents 'loading/coload/controller/PlatformColoadGroupController.java' '后端同柜不可拆组入口'
|
||||
Assert-Contains $firstlegAgents '服务端冻结每票全部 `WAIT_SPLIT` 可用入仓片段与满箱数' 'Firstleg 同柜建组边界'
|
||||
Assert-Contains $warehouseAgents 'scripts/warehouse-public-master-data-contract.test.mjs' 'Warehouse 局部脚本入口'
|
||||
Assert-Contains $coloadOpenApi '允许跨客户及不同目的仓港成组，仅要求国内仓和渠道一致' '同柜资格 OpenAPI'
|
||||
Assert-Contains $coloadOpenApi '服务端解析每个订单全部 WAIT_SPLIT' '同柜订单展开 OpenAPI'
|
||||
Assert-Contains $rootAgents '用户可见页面、提示和错误不得展示或以内部数据库 ID 作为业务编号回退' '根业务编号展示边界'
|
||||
|
||||
+1
-1
@@ -25,7 +25,7 @@
|
||||
| 国内整柜业务 | `domesticcontainer/controller/PlatformDomesticContainerController.java`、`domesticcontainer/service/DomesticContainerService.java`；契约见 `src/main/resources/openapi/domestic-container-v1.yaml` |
|
||||
| DTO/持久化 | `dto/`、`entity/`、`mapper/`、`repository/` |
|
||||
| SQL | `src/main/resources/db/`；存量统一 `../deploy/sql/头程数据库统一增量-MySQL8.sql` |
|
||||
| 测试/验证 | `src/test/java/com/baiyue/warehouse/`；`mvn -pl warehouse -am test` |
|
||||
| 测试/验证 | Java 测试 `src/test/java/com/baiyue/warehouse/`，执行 `mvn -pl warehouse -am test`；公共 FBA 仓 CSV 与 SQL 离线合同 `scripts/warehouse-public-master-data-contract.test.mjs`，从后端根执行 `node --test warehouse/scripts/warehouse-public-master-data-contract.test.mjs`；局部说明见 `scripts/README.md` |
|
||||
|
||||
## 修改约束
|
||||
|
||||
|
||||
Reference in New Issue
Block a user