110 lines
7.4 KiB
Markdown
110 lines
7.4 KiB
Markdown
# 测试环境真实联调记录（2026-09-25）
|
||
|
||
本记录只登记已经在测试环境真实调用得到的结果，不把本地单测或设计文档当作真实验收证据。环境配置来自本机受控配置目录，不在文档中记录密码、Token 或 Jenkins 凭据。
|
||
|
||
## 一、本批部署
|
||
|
||
| 部署单元 | 测试构建 | 结果 | 说明 |
|
||
|---|---:|---|---|
|
||
| `backend-java` | 618 | 成功 | `firstleg` 选择构建；第 617 次因测试仍引用已删除旧方法失败，修正后第 618 次成功 |
|
||
| `admin-web-test` | 454 | 成功 | 平台回执上传不再携带 `finalConfirmation`，上传后等待客户确认 |
|
||
| `client-web-test` | 331 | 成功 | 客户端新增整份回执确认、打回和原因展示 |
|
||
|
||
路由合同检查通过；后端报关服务定向测试和 Controller 合同测试通过，Admin 类型检查及报关组件测试通过，Client 类型检查通过。
|
||
|
||
## 二、真实接口证据
|
||
|
||
测试客户属于退税客户，使用已完成装柜的测试订单和柜次进行验证。测试库已补齐 `fl_customs_completion_document` 的客户确认字段，现有记录仅用于本次测试。
|
||
|
||
### 1. 客户查看退税报关资料
|
||
|
||
调用：
|
||
|
||
```text
|
||
GET /api/merchant/v1/customs/orders/{orderId}
|
||
```
|
||
|
||
结果：`200`。客户只能看到自身资料，返回实际箱数 `40`、退税资料 `1` 份；部分装柜的系统展示只读箱数，不做数量拆分。
|
||
|
||
### 2. 平台查看柜级报关状态
|
||
|
||
调用：
|
||
|
||
```text
|
||
GET /api/platform/v1/customs/loading-plans/{loadingPlanId}
|
||
```
|
||
|
||
结果：`200`。平台视角返回同一柜次实际箱数 `40`、退税资料覆盖数和回执状态；客户视角没有返回同柜其他客户资料。
|
||
|
||
### 3. 平台上传报关行回执
|
||
|
||
调用：
|
||
|
||
```text
|
||
POST /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/upload?expectedVersion=1
|
||
```
|
||
|
||
结果：`200`，回执状态为 `PENDING`，文件版本变为 `2`。上传回执没有自动把柜次标记为报关完成。
|
||
|
||
### 4. 客户打回整份回执
|
||
|
||
调用：
|
||
|
||
```text
|
||
POST /api/merchant/v1/customs/documents/{documentId}/receipt/reject
|
||
```
|
||
|
||
结果：`200`，回执状态为 `REJECTED`，打回原因被保存，柜次仍为 `DECLARING`。
|
||
|
||
### 5. 客户确认整份回执
|
||
|
||
调用：
|
||
|
||
```text
|
||
POST /api/merchant/v1/customs/documents/{documentId}/receipt/confirm
|
||
```
|
||
|
||
结果：`200`，回执状态为 `CONFIRMED`；该柜唯一退税客户确认后，柜次变为 `COMPLETED`。相同幂等键重放仍返回同一完成结果。
|
||
|
||
### 6. 头程到报关真实 HTTP 回归
|
||
|
||
在补齐国内 PDA 测试作业员凭据后，使用 `scripts/admin-test-env-acceptance.mjs --modules phase3-container-customs` 重新执行依赖闭环，覆盖客户下单、审核、入库测量、分柜/订舱、预装、PDA 装柜、`LOADED`、退税资料上传、平台回执上传、客户回执确认、自动离仓及船期查询任务。
|
||
|
||
结果：报告 `baiyue-firstleg/reports/e2e-phase3-container-customs-20260925d.json`，`526/526` 断言通过，`0` 失败；其中混合柜验证确认回执后才进入 `COMPLETED`，自动离仓 `SYSTEM` 历史为 `1` 条，`OUTBOUND_CONFIRM` 船期查询任务为 `1` 条。验收脚本同步提交为 `8940c4bc`。
|
||
|
||
### 7. 送港、船期与实际开航真实 HTTP 回归
|
||
|
||
使用 `phase3-port-schedules,phase3-carrier-schedule-queries,phase3-outbound-dispatch` 执行送港和出仓链路，报告 `baiyue-firstleg/reports/e2e-phase3-transport-20260925.json`，`1024/1024` 通过；验证报关完成后国内离仓门禁、拖车自动完成、`OUTBOUND_CONFIRM` 任务唯一性及 `DEPARTED_WAREHOUSE` 事实。
|
||
|
||
随后使用 `phase4-carrier-pickup-ready` 执行船节点人工回填，报告 `baiyue-firstleg/reports/e2e-phase4-carrier-pickup-ready-20260925.json`，`1093/1093` 通过；节点按顺序推进到 `AT_ORIGIN_PORT`、`LOADED_ON_VESSEL`、`DEPARTED_ORIGIN_PORT`，并覆盖幂等重放、旧版本冲突、旧节点回写禁止和至 `PICKUP_READY` 的连续事实。
|
||
|
||
## 三、当前已确认的业务边界
|
||
|
||
- 报关资料、报关行回执和客户确认流程只适用于退税货物。
|
||
- 买单货物不创建客户报关资料、回执和客户确认流程；买单装柜、导出和运输节点独立处理。
|
||
- 报关资料和回执均为文件；回执状态单独保存，文件版本覆盖会重新进入待确认。
|
||
- 部分装柜只展示实际箱数，后续由线下人员处理，系统不自动分摊数量。
|
||
- `LOADED` 后先完成报关协同；报关完成后货柜进入待发区，等待船期承运。甩柜/改配只影响运输航次，不回退或重做报关资料、回执和客户确认。
|
||
|
||
## 四、F01-F24 验证状态
|
||
|
||
| 范围 | 当前证据 | 状态 |
|
||
|---|---|---|
|
||
| F01-F13 下单、审核、到仓、测量、计费、费用确认、组托 | 本批依赖闭环已通过真实 HTTP；仍需拆分逐节点证据和异常分支 | 主链路已验收 |
|
||
| F14-F21 分柜、订舱、拖车、拣货、装柜、`LOADED` | 本批依赖闭环已通过真实 HTTP，包含 PDA 领取、提交、审核和 `LOADED` 冻结 | 主链路已验收 |
|
||
| F22 退税报关资料、回执、客户确认 | 已完成真实平台/客户端闭环 | 本批已验收 |
|
||
| F23 送港、进港、甩柜、改配 | 送港/进港/出仓和船期查询主链路已通过真实 HTTP；已用测试环境真实柜次验证平台人工修改原柜船名/航次/预计时间，柜次、订舱关联和船期记录 ID 不变，修改历史新增 `UPDATE`；报关事实保持不变 | 主链路和原柜人工改船已验收；完整装柜依赖链仍需补 PDA 凭据后复跑 |
|
||
| F24 实际开航 | 已通过人工船节点回填验证 `DEPARTED_ORIGIN_PORT`，顺序、版本和旧节点冲突均通过 | 本批已验收 |
|
||
| F25 以后目的港清关、海外入仓、尾程 | 已有综合真实 HTTP 证据覆盖目的港节点、海外 PDA 收货、库存、排车、出库、派送和跨区回写；`admin-full-postdeploy-66c2651b.json` 相关模块失败数为 0 | 已有主链证据；仍需按具体柜次补最终业务签字和页面截图 |
|
||
|
||
## 五、下一批开发入口
|
||
|
||
下一批聚焦 F23 的人工改船页面回读、客户侧船期投影和异常分支；当前已确认只变更原柜船期，柜次、订舱关联和报关事实均不被覆盖。尾程节点再按 F25 以后阶段推进。每批完成后继续追加真实 HTTP 证据。
|
||
|
||
## 六、2026-09-27 追加验证：F23.3 客户船期投影
|
||
|
||
- 后端提交 `f1218cef` 已由 `backend-java #643` 完整测试并部署，Firstleg 独立任务 `baiyue-firstleg-firstleg #446` 成功；随后提交 `2c4f1ea3` 由 `backend-java #645` 完整测试并部署，Firstleg 独立任务 `baiyue-firstleg-firstleg #448` 成功；当前分支追加船期展示修复后，`backend-java #647` 与 `baiyue-firstleg-firstleg #450` 也已成功。
|
||
- 修复统一订单运输摘要仍读取订舱初始船名/航次的问题：现在按客户、订舱和柜次读取最新 `fl_port_schedule` 记录，采用窗口函数选取最新观测，保留柜次与报关对象独立性。
|
||
- 对退税柜 `TSTU0152125` 实际执行“创建原柜改配船期 → 平台容器详情与客户订单同时查询 → 版本更新恢复原船信息”。平台和客户端均读到新船名、航次及预计时间；柜号不变，恢复后两端再次一致。本轮不涉及 PDA，PDA 仍只作为 `LOADED` 上游事实。
|
||
- 详细请求结果和断言见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`；此前客户侧单独投影证据仍保留在 `transport-projection-after-schedule-update-20260927.json`。
|