From 5aed9d0af0f36a8e038f19622056e2f7b75c018b Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Wed, 21 Oct 2026 15:53:29 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AI工程执行与协作约束.md | 26 +++++++++++++++++++++----- Admin-Client前端原型还原验收规则.md | 10 +++++----- 测试环境Jenkins部署指南.md | 2 +- 测试环境单机部署与配置契约.md | 20 ++++++++++++++++++++ 海外仓业务/README.md | 2 +- 海外仓业务/排车列表统一作业改造契约.md | 4 +++- 海外仓业务/自有业务首版开发契约.md | 1 + 海外仓业务/预约工作日历V13变更说明.md | 2 +- 8 files changed, 53 insertions(+), 14 deletions(-) diff --git a/AI工程执行与协作约束.md b/AI工程执行与协作约束.md index d3ace1c..29406ed 100644 --- a/AI工程执行与协作约束.md +++ b/AI工程执行与协作约束.md @@ -24,11 +24,27 @@ - 查看占用：`& ./baiyue-firstleg/scripts/local-check.ps1 -Status`。默认最多排队 900 秒（`-WaitSeconds`），执行最多 1200 秒（`-TimeoutSeconds`）。排队超时退出 75 且不启动检查；执行超时退出 124 并回收本次进程树；其他情况透传命令退出码。锁由操作系统文件句柄维护，不删除锁文件抢占。正常结束、超时和包装器强制退出均由 Windows Job Object 回收本次后代；不按 Node/Java 进程名清理其他任务。 - 子进程默认设置 Vitest 最多 2 个 worker；Node 单进程堆上限 2048MB；Java 单进程堆上限 1536MB、可见处理器 2 个。直接运行 `node --test` 时自动补 `--test-concurrency=2`；直接运行 Maven 时补 `-T 1 -DforkCount=1 -DreuseForks=true`，拒绝重复指定这些并发参数。嵌套 shell/自定义脚本不得另行提高并发、覆盖限制或并发启动重型任务；经包管理器间接调用 Node 内置测试时，在该测试命令中显式保留 `--test-concurrency=2`。这些是每进程限制，并非整个进程树的总内存限额。 - 后端分层入口 `backend-check.ps1` 及前后端全量入口 `backend-full-regression.ps1`、`frontend-full-regression.ps1` 执行时整批占一个名额，DryRun 不占用。已在入口保护下的批次执行原始命令，不重复申请锁；入口会拒绝嵌套调用，避免互相等待。 -- 每个任务先完成必要的定向检查；批次收尾按应用要求执行受影响模块或全量门禁，不因排队取消必要验证。后端分层及全量触发条件唯一维护在 `../baiyue-firstleg/AGENTS.md`，普通局部任务完成不自动触发全仓回归。复用结果前核对命令、目录、相关源码/依赖/配置均相同；验证期间相关输入变化则作废重跑。交付记录命令、目录、范围、结果及未验证项；只有已有记录且能确认相关输入未变才可复用，不能仅凭时间接近或上次绿灯推定有效。入口仅保存最近一次执行摘要，不自动计算代码快照、不自动跳过测试，也不保证先来先执行。 +- 按下文“验证范围选择”完成必要检查，不因批次收尾扩大范围；排队也不改变检查范围。复用结果须核对命令、目录和相关源码/依赖/配置；输入变化只作废依赖该输入的结果，补跑受影响检查，不自动重跑整批。交付简述范围、结果和未验证项；不能仅凭时间接近或上次绿灯推定有效。入口仅保存最近摘要，不自动计算快照或跳过测试，也不保证先来先执行。 - 本机每槽独立保存占用者与最近结果：首槽 `owner.json`、`last-result.json`，第二槽 `owner-2.json`、`last-result-2.json`。只保存检查名称、目录、工具、PID、槽号、时间和退出码，不保存命令参数、凭据或测试输出；名称不得包含秘密。`-Status` 分别展示两槽及总占用，摘要不是业务/部署事实来源。无需凭据，不访问网络、数据库或部署环境；被包装命令原有的网络/写入能力及授权要求不变。 - 只读检索和互不冲突的编辑可并行；开发服务按应用复用已有实例，不纳入短任务队列，也不通过本入口启动常驻服务。已有运行任务由所属对话收尾；本入口不自动终止它们。 - 免排队范围仅限离线只读的静态合同：`baiyue-firstleg/scripts/agents-index-contract.ps1`、`scripts/mapper-scan-contract.mjs` 等直接扫描文件的 PowerShell/MJS 脚本；`node --test` 形式的合同测试文件仍属测试。任何 `pnpm test`、`pnpm typecheck`、`pnpm build`、`node --test` 和 `mvn` 命令必须经 `local-check.ps1`，不得以“离线合同”为由绕过。 +## 验证范围选择 + +从本轮差异、修改行为及直接引用确定范围，不把整个工作区已有改动算作本轮任务。各应用命令表是可用命令，不是每轮执行清单。 + +| 改动 | 默认验证 | +|---|---| +| 文案、注释、纯展示字段增删 | 核对差异及模板；已有断言受影响则调整并定向运行，不机械新增测试 | +| 文件内小逻辑、局部交互 | 覆盖修改分支和必要边界的定向测试，不自动整模块回归、typecheck 或构建 | +| 类型、签名、接口、模板绑定、模块引用、公共组件或共享逻辑 | 沿符号追踪实际消费者并运行相关测试；类型关系可能受影响时，补覆盖相关生产与测试源码的最小类型检查或编译 | +| 依赖、打包配置、模块装配 | 按变更选择受影响构建或测试；需要构建不等于同时需要全量测试 | +| 广泛公共变更或完整集成验收 | 先说明具体影响及定向检查不足的原因，再选择模块/全量范围；未调查清楚不能作为全量理由 | + +- 用户明确要求完整回归时按指定范围执行；普通提交、对话结束、触及多个文件或发现他人未提交修改均不触发全量。 +- 权限、金额、库存、状态和并发等关键行为必须覆盖相关边界，但不据此扫描或测试无关业务。定向失败先定位，不自动扩大测试范围。 +- 仅复用编译配置、覆盖文件及相关输入相同的成功结果；构建未覆盖测试源码时，不能替代受影响测试的类型检查。API、Mapper、AGENTS 静态合同按各自触发条件执行；文档改动不触发业务回归。 + ## 当前开发阶段 - 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；所有代码与契约直接收敛到当前确认目标，用户确认上线或存在不可变外部契约后才重新建立版本兼容和升级规则。 @@ -47,18 +63,18 @@ ## 通用工程与质量门禁 - 对外 API 新增、改名、删除或访问域变化，以“调用端实际路径（含 API Base）→ 对应区域 Gateway → Controller → OpenAPI → 权限”作为一个交付单元；不能只在修改网关文件时才检查注册。已被正确通配路由覆盖时无需重复添加路由，内部服务令牌接口不得为通过检查而公开。 -- 提交前运行 `node --test scripts/gateway-route-contract.test.mjs` 及受影响服务/调用端的定向测试；路由合同失败不得提交或声称完成。该离线合同检查源码映射、目标服务及内部路径隔离，不代替权限、HTTP 方法、运行时 Nacos 或真实 HTTP 验收；前端 Mock 测试、类型检查及服务单测通过也不证明网关可达。 +- 仅对外 API 路径/访问域新增、改名、删除或 Gateway 路由配置变化时，运行 `node --test scripts/gateway-route-contract.test.mjs` 及受影响服务/调用端测试；命中的路由合同失败不得声称完成。纯文案、内部逻辑和路径未变的前端消费不触发。该离线合同不代替权限、HTTP 方法、运行时 Nacos 或真实 HTTP 验收。 - 交付列明变更接口、路由是否复用或新增、验证结果及部署单元；Gateway 配置变化必须包含对应网关，Nacos 配置变化单独说明发布项。没有环境授权时只交付代码和待验收说明，不自动部署、发布配置或调用真实 HTTP。 - 修改范围与停止条件遵循[工作区根指引](../AGENTS.md#修改范围与停止条件)，保持目标项目现有命名、分层和格式。 - 优先复用现有依赖和公共能力；新增或升级依赖前说明必要性、影响范围和替代方案。 - 不提交依赖目录、构建产物、运行日志、编辑器缓存或本地临时文件；不写入密钥、令牌、真实客户数据或环境特定地址。 - 用户可见文案保持清晰一致；代码标识符使用英文，业务说明和文档可使用中文。 -- 仅运行目标项目实际声明的安装、检查、测试和构建命令。每次变更至少验证直接受影响的项目，跨项目变更还要验证对应消费者。 +- 仅运行目标项目实际支持的检查命令，按上文选择最小有效范围；“验证受影响项目”不等于运行该项目全部命令。 - 签名、组件 Props、接口/DTO、请求响应结构或影响调用方的行为变化时，用 `rg` 按变更符号核对直接生产调用、测试、Mock、Fixture、契约测试与脚本；只修改实际受影响的引用，必要时沿直接依赖继续追踪。仅内部实现调整且调用契约与对外行为未变时，验证受影响逻辑，不自动修改调用方、Mock、Fixture 或文档。 - 参数或类型签名变化必须运行会编译测试源码的最小检查；无法验证时明确列出未验证范围。 -- 修复缺陷优先增加复现测试；没有现成测试设施时不为小改动引入整套框架，应记录验证步骤和剩余风险。 -- UI 变更按受影响范围检查加载、空态、错误态、权限、目标视口和可访问性；Admin/Client 视觉细则查 `Admin-Client前端原型还原验收规则.md` 和目标应用指引。 +- 行为缺陷优先用已有测试复现，缺失时补必要用例；文案和纯展示不机械新增测试，不为小改动引入框架。 +- UI 只检查本轮影响的状态与交互，不机械遍历加载、空态、错误态和权限；布局或承载方式变化再按前端验收规则核对对应视觉证据。 - 需求、技术栈或接口未确认时停在可逆设计阶段，不自行作出高成本平台决策。 ## 独立任务与多任务协作 diff --git a/Admin-Client前端原型还原验收规则.md b/Admin-Client前端原型还原验收规则.md index a285ad6..f4478b5 100644 --- a/Admin-Client前端原型还原验收规则.md +++ b/Admin-Client前端原型还原验收规则.md @@ -8,13 +8,13 @@ ## 修改门禁 -每个页面修改前必须先形成以下矩阵，并给出原型文件及行号、元素 ID、函数名或截图证据： +新页面、整体视觉还原、布局重排或页面/弹框/抽屉承载变化，才对受影响操作形成以下矩阵，并给出原型或用户截图依据。文案、单个展示字段增删、局部逻辑及不改变承载方式的小调整，直接核对差异，不要求矩阵、完整原型检索或全页面验收： | 页面 | 操作 | 原型承载方式 | 原型尺寸/布局 | 当前实现 | 结论 | |---|---|---|---|---|---| | 示例 | 详情 | 独立页面 | 页面级头部、返回列表 | 右侧抽屉 | 改为正式路由页面 | -操作至少分别核对：详情、新增、编辑、审核/确认、文件预览、删除/停用确认。不得以其中一个操作的结论推断其他操作。 +只核对本轮受影响操作，不机械遍历详情、新增、编辑、审核、预览和删除；不得用一个操作的结果推断其他操作已通过。 ## 承载方式 @@ -39,10 +39,10 @@ ## 执行与验收 -1. 先提交逐页矩阵，不直接批量替换公共组件。 +1. 仅满足上述矩阵触发条件时记录受影响操作；局部小改直接核对差异，不批量替换公共组件。 2. 按当前对话确认的范围修改目标模块，保留其他任务在途改动；存在总控协作时沿已冻结结论执行，不因普通样式任务额外创建总控流程。 -3. 修改后由人工在 `1920×1080`、`100%` 缩放下操作并提供截图，标注与原型仍存在的差异；缺少截图时记录“待人工截图确认”，AI 不自行批量取证。 -4. 按应用指引完成受影响测试、类型检查及必要的全量测试和构建，重型检查统一经过 `local-check.ps1`；共享组件变更核对全部直接消费者。公共浮层选择器变更覆盖真实 Element 挂载下的嵌套、Teleport、工具栏内浮层及全屏重开。 +3. 需要视觉验收的布局/承载变化，由人工在 `1920×1080`、`100%` 缩放下提供受影响操作截图；缺少时记“待人工截图确认”，AI 不批量取证。文案、小逻辑和局部展示改动不以重新提交整页截图作为代码交付门禁，不据此宣称已通过视觉验收。 +4. 按 `AI工程执行与协作约束.md` 的“验证范围选择”执行最小有效检查，不因页面修改自动全量测试、类型检查或构建；需要的重型检查经过 `local-check.ps1`。共享组件核对实际消费者，公共浮层选择器变化覆盖受影响的嵌套、Teleport、工具栏及全屏场景。 5. 不触发 Jenkins、不部署、不提交，除非当前对话另有明确授权。 已改造弹框回看时，复用原固定编号清单，从本轮确定的当前项逐个处理，不另建全量清单、不重排编号。单项流程为“原改造记录与当前代码核对 → 实际截图核对 → 明确保留项和必要局部修正 → 有修改时完成相应代码检查 → 本项人工确认 → 下一项”。缺少截图时只记录源码事实与待核对项，不声称视觉通过；本项未确认前不并行修改后续弹框。复杂窗口的分栏、步骤、树表、预览与已确认尺寸分别核对，不按普通表单模板统一重排。 diff --git a/测试环境Jenkins部署指南.md b/测试环境Jenkins部署指南.md index 00bdc43..9456434 100644 --- a/测试环境Jenkins部署指南.md +++ b/测试环境Jenkins部署指南.md @@ -26,7 +26,7 @@ ## 参数与门禁 -总控支持AUTO、SELECT、ALL。AUTO保留失败服务重试与直接依赖识别；架构首次切换使用审核后的完整匹配发布清单，不以AUTO遗漏服务。ENVIRONMENT仅test，下游前缀仅baiyue-firstleg-。DEPLOY默认false；IMAGE_REPOSITORY必须替换为已核镜像仓库，DOCKER_BASE_IMAGE由构建节点可访问的Java17镜像提供。不得将凭据拼入参数、URL或日志。 +总控支持AUTO、SELECT、ALL。AUTO保留失败服务重试与直接依赖识别；架构首次切换使用审核后的完整匹配发布清单，不以AUTO遗漏服务。ENVIRONMENT仅test，下游前缀仅baiyue-firstleg-。DEPLOY默认false；IMAGE_REPOSITORY首次在各Job参数默认值中配置已核镜像仓库，后续流水线沿用当前Job参数值，不在每次构建后重置为空；总控仍明确向下游传递本次地址。更换仓库才需修改，空值、示例域名与格式校验仍保留，不在源码固定环境地址。DOCKER_BASE_IMAGE由构建节点可访问的Java17镜像提供。不得将凭据拼入参数、URL或日志。 默认执行Maven测试；仅明确选择SKIP_TESTS时跳过执行，仍编译测试源码。总控先统一测试，再向固定commit的单服务任务传递跳过重复执行。发布前还须完成网关路由、部署拓扑、失败回滚和受影响前端合同。离线检查不能证明镜像健康或HTTP闭环。 diff --git a/测试环境单机部署与配置契约.md b/测试环境单机部署与配置契约.md index 359a107..0388f39 100644 --- a/测试环境单机部署与配置契约.md +++ b/测试环境单机部署与配置契约.md @@ -20,6 +20,13 @@ ## 2026-10-21 全量验收脚本离线收敛 +### 同日 r1 失败项修复与定向复测（进行中） + +- 固定称重托盘池按原规则复用 `TP-001` / `YW-TP-002` 中任一有效托盘；不要求两只同时存在，不新建托盘。费用目录分别核对 112 条正式科目与完整目录中的扩展科目；船期 ETA 允许缺省但拒绝非法时间；仓库操作员权限按当前初始化基线核对。称重图片改为显式环境配置，本轮使用合成测试图片，只验证接口及人工确认，不作为实拍或 OCR 识别效果验收。 +- 用户授权处理的 5 条旧时区预约中，3 条 ABE4 历史批次已被分批/合并替代，正式取消接口返回 A0409，未修改。另 2 条 `AP-20261016-955ABD8BD866`、`YY202610210002` 已正式取消并保留取消历史；ONT8 / ACY2 公共主档分别按初始化基线修正为 `America/Los_Angeles` / `America/New_York`。取消不释放原实物分配，因此通过原批次更新接口重新安排，两个批次均回查为 PENDING、版本 2 和正确 IANA 时区；未通过 SQL 改写历史。证据位于 `baiyue-firstleg/reports/full-acceptance-20261021-repair/appointment-*-journal.json`。 +- 定向首轮 `targeted.json`：1960 项断言，1947 通过、13 失败，31 个模块、1156 个独立请求。失败集中于 OCR 空字段/修正确认版本的脚本误判、服务重启期间采购请求 HTTP 500、预约完整扫描未完成。OCR 已按服务端合同修复并通过 6 项直接合同测试；船期和海外业务直接合同 10 项通过。 +- 预约同步在 15:27 完成整轮扫描后，`appointment-verify-r3-journal.json` 证明汇总、日历、事项列表均成功。期间 Lastleg 由其他工作发生重启，本轮未触发部署；不得把恢复单独归因于数据修复，也不把定向结果视为全量通过。修复后定向复测继续进行。 + - 本批优化验收范围与报告口径，修复固定称重托盘缺失时借其他托盘兜底、重派脚本仍调用手工派送/发车、初始化基线及迁移/OpenAPI断言滞后、PowerShell子进程版本和文案误触静态断言等问题。当前默认Admin范围为71个模块，可选模块单列，不将本地合同、HTTP和页面验收混为一个结果。 - 根级85个、Admin模块137个测试文件共2290项：完整离线批次2289通过、1条静态断言失败；最后修改的船司合同及直接相关异常合同复测14项全部通过。按受影响文件替换复测结果后，2290项均有通过证据、零跳过；这是批次加定向复测的汇总，不改写原失败报告，也不宣称单次全量零失败。 - 证据：`baiyue-firstleg/reports/acceptance-offline-consolidated-20261021.json`，关联原批次`acceptance-batch-final-green-20261021.xml`及复测`acceptance-carrier-final-20261021.xml`。报告文件名不作为通过依据，以实际断言结果为准。 @@ -2882,3 +2889,16 @@ Client #382（`a0736239e4ee4cd58b620dab912ffc0641360d9f`）正式页面在1920× - 40 项受影响测试、生产构建及 5 项 Gateway 路由合同通过。当前共享工作区全量回归为 468 文件通过、2 文件失败，4,343 项通过、3 项失败：DispatchesView 两项审核操作按钮断言、DispatchDetailView 一项附件 A0404 诊断断言，均位于其他正在修改的排车代码；不标记全量通过，也未将这些工作区改动加入本次发布。 - 发布后直接读取运行容器实际引用的两个页面及 API JS，确认旧的单一 ownership 拒绝条件已替换。另通过实际 Admin API 适配器读取正式 Gateway 响应，两个默认列表及 `PC202610210012`、`PC202610210013` 详情共 4 项通过，覆盖无拼车 DISPATCHED 车辆与有拼车 OWNED 车辆；仅替换 HTTP 传输为真实 fetch，保留生产响应解析，未伪造业务数据。验收会话已退出。没有浏览器实际点击或新增人工视觉验收证据。 - 本次只发布 Admin；Lastleg 镜像仍为 `0af977bdefc1` 且 healthy，无数据库、Gateway、Nacos 或业务数据修改。证据保存在本机私有环境目录 `pool-ui-fix-commit.json`、`pool-ui-fix-release-state.json`、`pool-ui-fix-admin.log`、`pool-ui-fix-assets-before.json`、`pool-ui-fix-assets-report.json` 与 `pool-ui-api-live-report.json`。 + +### 自有业务行操作按钮样式修正（2026-10-21） + +- 用户截图反馈自有业务列表三个操作仍为描边粗体。修复提交 `457a95941d407ff60cb8edb57459a96a274f0b0f` 仅为按钮组接入公共 `row-actions density-actions admin-text-actions`，同步一条密度合同断言及局部核对矩阵；按钮顺序、权限、禁用条件、路由和弹框事件未变。 +- 本地受控检查：77 项定向测试、类型检查及生产构建、5 项 Gateway 路由合同通过；全量 470 文件、4,355 项通过，0 失败。全量针对当时共享工作区，不将其误称为独立发布提交的全量重跑。 +- 发布前核对发现其他任务已通过 `admin-web-test #676` 发布 `e6c864a2a64e44e0b02ee97288c6ed47074150f2`，其父提交即本次修复，且该页面内容与本次准备的最小发布包一致。因而复用已完成发布，本任务未修改 Job 配置或触发重复构建；事先准备的 `test-owned-actions-style-20261021` 标签未用于部署。 +- #676 SUCCESS、运行镜像 `admin-web-test:e6c864a2a64e` healthy；从实际容器入口引用的 `OwnedBusinessView-DRKKyoIB.js` 确认纯文字类已生效，入口公共 CSS 包含对应样式，健康入口通过。证据为私有 `owned-actions-style-release-state.json`、`owned-actions-style-assets-report.json`；修改后的人工截图仍待确认，不把静态资源核对当成像素验收。 + +### 2026-10-21 TEST Jenkins 镜像仓库默认值固定 + +- 用户针对 backend-java #707 的空 IMAGE_REPOSITORY 失败授权固定配置。通过 Jenkins API 核实 #706 成功构建的实际地址，并将相同值写入 backend-java 与13个 baiyue-firstleg- 单服务Job的参数默认值；14项逐一回读通过。保存前核对无运行/排队任务、无构建触发器，保存后按XML语义核对仅此默认值变化；真实地址保留在Jenkins配置，不写入源码与本文。 +- 两份流水线改为沿用当前Job已有 IMAGE_REPOSITORY 参数值，防止声明式参数刷新再次清空默认值；缺失、示例域名与格式拦截继续保留。专属提交 94595c810 已推送 test 分支，仅含两份Jenkinsfile与直接合同测试，不夹带工作区其他修改。 +- 定向流水线合同20项通过，两份文件通过Jenkins declarative validate API语法检查；未触发构建、服务部署或SQL。配置原文备份及逐Job回读报告保存在本机私有环境目录 registry-default-20261021/；这次配置成功不代表排车业务代码已部署。 diff --git a/海外仓业务/README.md b/海外仓业务/README.md index b1b404c..9937a3c 100644 --- a/海外仓业务/README.md +++ b/海外仓业务/README.md @@ -170,7 +170,7 @@ HTTP入口为`/api/platform/v1/last-leg/appointment-planning`，包括`GET /carg - 头程散货在预装确认且真实集装箱号就绪后，按 `集装箱号-FBA仓编码-三位序号` 冻结托盘码；序号在当前柜、当前 FBA 仓内从 001 独立递增。送柜报关、清关提柜和预装清单共用同一按 FBA 仓分组的打印清单，可整柜打印或选择单仓前 N 张补打。该编号随装柜完成事件进入海外，生成入库计划与海外实体托盘时原样沿用；一件代发继续使用国内装箱打托形成的托盘号，不参与散货重新编号。 - 头程与海外仓允许装托密度不同。尾程最终托数取不低于头程已有托盘码数的海外计划结果：头程已有编码全部保留，数量不足时在同柜、同 FBA 内按连续下标补码，不因数量差异阻断。柜级预览必须分别返回并展示头程已有、海外仓补充和最终托数；最终总数不得标成“本次新增”。 - 尾程订单人工节点固定为国内报关完成、预计/实际开船、预计到港、国外清关完成、实际到港等待卸船、预约提柜和卸柜八行完整快照。第一次保存后该订单永久使用 `MANUAL` 来源，读取和页面展示不得再回退柜级节点，也不得反向修改货柜船节点。 -- 目的港码头拖车仍归 Firstleg 货柜聚合，但 Admin 清关提柜列表不再使用预约/实际提柜作为到仓业务时间：原两列改为“预计到仓/实际到仓”。预计到仓在列表内人工选择并由 Lastleg 按 `sourceContainerBookingId` 原子同步整柜尾程订单，已有入库计划后锁定；实际到仓只取海外 PDA 首次开始收货的 `ll_receiving_container_session.receiving_at`。车队、邮件、还柜及 `unloadingCompletedAt + 72h` 还空预警仍按原码头拖车链路处理。 +- 目的港码头拖车仍归 Firstleg 货柜聚合，但 Admin 清关提柜列表不再使用预约/实际提柜作为到仓业务时间：原两列改为“预计到仓/实际到仓”。未人工维护且未建入库计划时，预计到仓按[预约日历统一日期规则](预约工作日历V13变更说明.md#2026-10-19-当前预约列表收敛规则)展示到港日期加两个自然日的默认值，列表与详情一致且不自动写入。人工调整在列表内选择日期时间并由 Lastleg 按 `sourceContainerBookingId` 原子同步整柜尾程订单，已有入库计划后锁定；实际到仓只取海外 PDA 首次开始收货的 `ll_receiving_container_session.receiving_at`。车队、邮件、还柜及 `unloadingCompletedAt + 72h` 还空预警仍按原码头拖车链路处理。 - 手动还柜以真实海外卸柜完成且尚未还柜为准，仍校验独立还柜权限；无需事先存在车队、预约或提柜时间。首次命令使用版本 0 创建拖车记录，车队字段可为空，不补造提柜事实。还柜时间不得早于卸柜完成时间或已有提柜时间，成功后同步标准还柜节点并解除报空预警。 - 船节点是头程海运在途事实与海外接柜之间的衔接能力，业务聚合继续由 Firstleg 按 `containerBookingId` 柜级持有，不绑定客户；跨区域事件使用 `tenantId=0` 平台技术范围，到港/可提柜结果通过明确契约提供给海外区域，不复制第二套轮询任务。 - Admin、Client 仍使用统一账号体系，并按根 `AGENTS.md` 的双区域 API、海外 Token 和跨区域事件约定接入；业务页面不自行实现第二套登录。 diff --git a/海外仓业务/排车列表统一作业改造契约.md b/海外仓业务/排车列表统一作业改造契约.md index 250b2a2..582e789 100644 --- a/海外仓业务/排车列表统一作业改造契约.md +++ b/海外仓业务/排车列表统一作业改造契约.md @@ -12,7 +12,9 @@ 2026-10-21 用户进一步确认：调度审核、理货员审核两个列表分区只提供“审核、详情”，不展示维护车辆信息或其他操作菜单。Admin审核弹框可补充车辆图片、司机照片、驾驶证照片，已有证据只读预览；新增附件随本次通过或驳回保存，不借维护车辆信息重写车辆/司机资料或改变审核依据。上传及提交均按当前待审环节的审核权限校验，并逐文件核验本车及分类归属；附件读取沿列表查看权限。理货驳回、客服修改保留已提供证据，新一轮提交清当前审核附件并保留历史。PDA继续使用既有审核入口，本次不新增PDA上传界面。 4. 2026-10-21 用户确认：装车完成即实际发车，PDA仅提交一次装车完成，直接进入派送中；后台同一装车完成入口遵循相同规则。保留真实拣货核平、实载校验、版本及防重复约束。 5. 装车完成在同一事务内自动按客户和目的地生成出库／派送单、记录实际发车并进入派送中，撤销人工安排派送及确认发车入口。真实外接报价沿原费用路径发布，未知派送补充资料与费用保持未确认，不猜测金额或原费用覆盖、不填写零费；后续由既有后台资料／费用管理维护。失败整体回滚，原请求键恢复最终派送中结果，不能停留半车或重复扣库存。 -6. 实际发车进入派送中；全部正常派送签收完成后自动汇总派送完成。拒收、退回等作为异常，先线下人工处理，不自动视为正常签收完成，不在本批新建线上异常闭环或伪造库存恢复、签收、账务结果。 +6. 实际发车后为派送中；全部正常签收完成后自动进入配送完成。派送中可以“标记异常”：类型必填（拒收、部分签收、车辆异常），退货去向选填（退回海外仓、其他），说明和图片选填。登记沿排车维护权限，按本车版本及原请求键防重，异常记录和图片保存在主单并于现有“排车信息”详情回看；阶段仍为派送中，不自动创建退货、恢复库存或确认签收。异常后续处置由人工处理，本轮不新增线上异常闭环。 + + 2026-10-21 本轮登记契约：`POST /api/platform/v1/last-leg/dispatches/{dispatchNo}/exceptions`，动作`MARK_EXCEPTION`，`recordVersion/idempotencyKey/exceptionType`必填；`returnDirection/description/imageFileIds`选填。说明最多1000字、图片最多20张；异常图片类型`OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE`，平台0、本车ID归属，非空JPG/PNG、单文件10MiB。主表新增可空`exceptions_json`，与原版本、历史、命令账本同事务保存；代码及基线已准备，未执行SQL或部署。 7. 本批聚焦排车列表、详情、直接关联操作及必要生产者和消费者。车辆列表、司机管理、自有业务、外配业务、出车记录的整页改造后续逐页处理。 8. 同时支持先选同一起运仓的可排货物/托盘再生成排车单，以及先创建空排车单再添加货物；空单不能伪造货物、拣货、装车或发车事实。2026-10-21 用户进一步明确先排车和货物，车辆、司机在建单后由调度或客服在后台补充，不涉及客户自助填写；新建排车不展示或要求填写车辆、司机及证照，先完成货物分组，允许选填每趟计划时间和备注。计划托位仅用于预排分组，不表示已绑定真实车辆。后续维护车辆信息及提交审核继续使用既有资源资格校验。用户随后明确：货物计划增减统一在智能排车办理，排车列表车辆信息及详情不再单独提供添加／移除货物。智能排车同时承载新建及已生成排车货物调整，已有单使用原排车号和正式货物命令，不转换为草稿或重建单据；保留真实PDA拣货，已扫码禁止调整，理货审核通过且零扫码时先显式退回重审后再调整。 9. 车辆和司机既可从已有档案选择，也允许临时填写外配车辆和司机；临时填写不伪造车辆或司机档案关联，不自行创建主档。 diff --git a/海外仓业务/自有业务首版开发契约.md b/海外仓业务/自有业务首版开发契约.md index f2134d2..7a617eb 100644 --- a/海外仓业务/自有业务首版开发契约.md +++ b/海外仓业务/自有业务首版开发契约.md @@ -18,6 +18,7 @@ 10. 不写原型的固定日期、默认18.6油耗、预设GPS/ETA、驾驶证状态、占位图片或示例操作历史。缺失显示未登记或—，不借内部ID回退业务编号。 11. 用户补充确认：按计划发车日期筛选，统计随同一筛选变化，原型“今日排车数”改为“排车数”。日期范围不硬编码示例日期，统计不以当前页行数代替全部筛选结果。 12. 用户补充确认：新增“登记运营信息”居中弹框，填写整车金额、逐目的地实到时间、实际里程和油耗；照片继续沿原型独立上传弹框。具体尺寸按当前Admin表单密度与字段数量处理，不改为抽屉。 +13. 2026-10-21 字段核对确认：列表总价、单价、预约到达时间、实际到达时间独立成列，仍一车一行且按目的仓标识关联时间；“派送仓库”就是目的仓，复用同一来源展示，不新增独立仓库关系。“最晚装车完成时间”先留空显示“—”，不以计划发车或实际装车时间代替；保留已有计划发车列。图中仓库名称上方误写的“托数”保留正式名称“提货仓库”，物理托数仍只有一项；状态表头统一为“状态”。本项仅调整列表展示，不新增金额、日期写入或履约逻辑。 ## 原型与实现差距 diff --git a/海外仓业务/预约工作日历V13变更说明.md b/海外仓业务/预约工作日历V13变更说明.md index 93b19e5..4532365 100644 --- a/海外仓业务/预约工作日历V13变更说明.md +++ b/海外仓业务/预约工作日历V13变更说明.md @@ -6,7 +6,7 @@ - 预约列表恢复用户截图 `codex-clipboard-840bcc07-6b54-4afa-9dc7-666d09ff04f2.png` 的左侧月/周日历、右侧当天安排。类型仅为到港、排车、还柜、计划到仓；每日期格最多三条预览，完整记录在右侧查看。保留当前范围搜索和未定日期入口。 - 月视图按当月所需显示4、5或6个完整周，仅在首尾周补齐相邻月份日期，不固定追加六周。2026年10月显示9月28日至11月1日，不显示11月2—8日整周；日历查询同步采用实际展示范围，周视图仍为7天。 -- 到港优先实际到港，缺实际时采用预计到港。计划到仓默认在该到港当地日期上加两个自然日，跨月和夏令时仍按日期加两天，不补造具体时刻。人工保存的整柜时间优先，已有入库计划的冻结时间保持；尚未人工维护和未建计划的默认日期随到港事实变化。该默认值属于日历日期推算，不自动写入入库计划、不充当实际到仓。人工调整复用整柜预计到仓命令、原编辑权限、版本及幂等键；已有入库计划后仍不可改。 +- 到港优先实际到港，缺实际时采用预计到港。计划到仓默认在该到港当地日期上加两个自然日，跨月和夏令时仍按日期加两天，不补造具体时刻。人工保存的整柜时间优先，已有入库计划的冻结时间保持；尚未人工维护和未建计划的默认日期随到港事实变化。预约日历“计划到仓”与清关提柜列表、详情“预计到仓”共用该日期规则，默认值显示日期并标明“默认/默认推算”，不补零点。该默认值不自动写入尾程订单或入库计划、不充当实际到仓；读取失败或已有计划但时间不一致时，不以默认日期掩盖缺失。人工调整复用整柜预计到仓命令、原编辑权限、版本及幂等键；已有入库计划后仍不可改。 - 排车仅指海外仓送往 FBA/客户仓的真实整车排车主单，一张主单中的多客户只展示一次；已发车按实际起运仓当地日期，未发车按计划日期，取消主单不列入活动安排。日历返回真实排车单号并进入排车详情；独立旧车次不作为日历来源，也不得将内部车次号当排车号拼接路径。读取沿用排车列表权限；从详情可返回原日历日期与月/周视图。港口提柜送海外仓不作为排车类型。 - 还柜未完成按原业务截止日期提醒，完成后按实际还柜日期展示；日历不独立计算或改写还柜状态，登记进入原货柜业务。 - 用户随后明确恢复日历顶部“新增预约”：本次先支持FBA，普通客户仓不在本次范围。居中弹框选择已有货物，核对真实来源后复用原预约表单与保存接口；同起运仓、同目的FBA仓可跨客户合约，保留原写权限、版本/幂等、未知结果重试及未保存保护。货物查询栏支持可搜索、可清空的目的FBA仓下拉框；选项来自同权限范围的权威美国FBA目录，不从当前分页推算。提交查询后回到第一页，翻页沿用目的仓条件，重置恢复全部目的仓；跨页已选货物仍保留并执行同起运仓、同目的仓校验。保存成功显示真实预约编号及内容，不自动创建车次，不增加第五类日历或手工编造到港/还柜等事实。