docs/海外仓业务/自有业务首版开发契约.md

自有业务首版开发契约

2026-10-20 用户明确先做自有业务，并授权复用既有后端、前端两个独立对话，与当前总控三方并行开发。本契约是本页唯一共同业务边界；实现、检查、部署及真实验收分别记录。排车 HTTP 扩展继续由原排车后端对话独占，不与本页并发操作其样本。

已确认规则

用户最新明确本质：自有业务、外配业务就是现有排车列表装车后数据按自有车辆/外配车辆区分的运营视图，自有车辆管理细，外配车辆相对简化。本批仅实现自有视图。两页共用原排车主单及真实履约事实，不另建第二套任务、车次主单、货物、审核、装车、发车或签收状态机；新增数据仅限关联该排车单的附加运营记录。

1. 自有指我们自己的车辆，不按自有货源过滤；承运货物仍保留各客户真实归属。外配业务本批不实现。
2. 从排车装车完成后展示，覆盖装车后、派送中、派送完成；不把审核通过或拣货核平本身当作装车完成。
3. 一张排车单就是一趟车，列表一张排车单一行；多个目的仓、预约号在行内展开，不按客户或目的地重复整车统计。
4. 后台登记一次整车总金额，单价由系统按整车总金额除以实际托数计算。用明确币种记录，不将该运营金额自动当作客户应收、车队应付、Finance入账或利润；不重复收费。金额未登记与明确零金额区分，实际托数为零时不除零。
5. 实际托数按真实物理托盘去重，同一实托承载两张换标单仍计一托；不得用逻辑明细数、客户数或标准占用托位冒充实际托数。
6. 实际到达时间、实际里程和油耗由后台补录；装车及油耗照片按原型上传。多个目的地的实到时间应与对应目的地匹配，不用签收或派送完成时间伪造到达，不自动推进排车或派送状态。
7. 列表统计、筛选、字段、查看明细和上传照片沿用户新版原型及模块原型核对矩阵；正式外观沿当前Admin高密度规范，操作列在第一列。
8. 详情为独立页面，三个页签为任务与车辆信息、路线货物与凭证、操作记录；排车详情仍保持其已确认四页签，旧车次附加功能不自动迁入本页。
9. 上传照片沿760px居中弹框，装车完成、油耗图片两个页签，JPG/PNG逐框处理；上传图片不等于确认装车。真实持久化、权限和版本明确核对后才记录已上传或已保存。
10. 不写原型的固定日期、默认18.6油耗、预设GPS/ETA、驾驶证状态、占位图片或示例操作历史。缺失显示未登记或—，不借内部ID回退业务编号。
11. 用户补充确认：按计划发车日期筛选，统计随同一筛选变化，原型“今日排车数”改为“排车数”。日期范围不硬编码示例日期，统计不以当前页行数代替全部筛选结果。
12. 用户补充确认：新增“登记运营信息”居中弹框，填写整车金额、逐目的地实到时间、实际里程和油耗；照片继续沿原型独立上传弹框。具体尺寸按当前Admin表单密度与字段数量处理，不改为抽屉。

原型与实现差距

直接依据为用户提供 C:/Users/BY-OY/Documents/WXWork/1688854456873012/Cache/File/2026-10/悦/悦/新版.html：page-vehicle-own-business 8772行，详情8779行，上传弹框8791行；最终照片函数23082行覆盖22842行同名定义。模块 PROTOTYPE_MATRIX.md 的“自有业务准备核对”记录逐操作承载及原型错位。

正式源码已接入本页菜单、列表/详情路由及独立权限；共享路由与权限22项检查通过，尚未据此发布或认定真实页面验收。现有TripOperations仅按实际发车查询，并按OWN/EXTERNAL货源筛选，不能通过换标题或套用其筛选实现本页。车辆归属取原装车完成时点的真实OWNED/DISPATCHED证据；原排车事实、实际托数、预约及多目的地读取与附加运营记录按下文冻结接口实现。

原型统计标题和日期口径已由用户按第11项修正，运营补录承载按第12项冻结。历史车辆归属取值时点及真实提供者按下文接口冻结v1，不由浏览器用当前档案推算历史。

三方职责及写入边界

对话	本轮职责	唯一写入边界
排车派送与费用后端 01a1524f-56a9-7320-a5fd-8ff76fa4356b	自有业务权威查询、附加运营记录及附件代理；先给正式API/数据设计，再实现与直接验证	新增Lastleg fleet/ownedbusiness/及对应测试、新增fleet-owned-business-v1.yaml、docs/海外仓业务/自有业务后端接口设计.md。其它生产目录与共享模型默认只读，需要触点先交总控协调
排车前端与PDA 01a1524f-52c7-7cc3-9b08-d34ad24c172a	列表、独立三页签详情、照片及运营补录操作、前端API/类型与直接回归	Admin海外通用资料模块中新增OwnedBusiness前缀页面/组件、ownedBusiness前缀API/类型及其测试；共同API冻结前不猜DTO。不得写PDA或其它业务页
当前总控 01a15230-a9d6-7503-a8a9-d70691df49e5	业务及接口冻结、共享接线、必要提供者与数据结构、集成及审查	本契约、原型矩阵、协作登记、Admin共享导航/路由/权限及测试、IAM和Lastleg初始化基线/必要增量SQL及必要直接File/Gateway接线。执行SQL/部署仍核对当前授权，不由专项自行触发

两个专项不修改AGENTS、共享runner、排车HTTP脚本、原排车/派送主链、旧出车记录实现、共享路由导航权限、数据库基线、依赖与锁文件。跨边界触点先交精确文件和原因，总控处理；不新建对话、不再委派、不创建分支/worktree/项目副本、不覆盖其它在途修改。

顺序与验收

1. 后端先提出API路径、字段、权限、原始事实来源、分页/统计、版本与幂等、附件归属、保存及历史、必要结构；原型未定义的字段不自动放进公开写模型。前端并行完成纯展示组件与逐操作矩阵，等待冻结API接线。
2. 总控核对并冻结共同合同，协调共享文件和提供者触点后，两个任务继续实现；技术例行选择不重复请用户批准，改变业务语义才询问。
3. 只读list权限包含详情、历史和已授权附件读取；保存及上传分别独立权限。所有过滤、所属车辆、阶段、真实单据归属、数量与金额计算由后端保证。
4. 写操作保存稳定请求键、版本与完整载荷，未知结果不当作失败重建；文件上传失败不重建业务记录。后端Money用明确十进制，单价按两位小数展示；前端不重算权威统计或用当前页行数作总数。
5. 覆盖自有/外配区分、装车前不显示与三个阶段、多客户多目的仓去重、同托多换标、金额缺失/零值/单价/币种、逐目的地到达、里程油耗及附件、并发版本/幂等/隔离/权限、空态失败及长编号。若存在需澄清字段，标未验证，不填假数据通过。
6. 所有测试、类型、构建、Maven经local-check串行；默认Node2GB/Java1536MB/CPU2，不继承先前一次性内存例外。先跑受影响检查再统一完成必要门禁，不各自重复全量。
7. 本轮开发不自动授予提交推送、SQL执行、环境发布、清理或业务写入。部署及本页真实HTTP由总控在匹配版本就绪后统一安排；Admin1920×1080、100%缩放人工截图验收，代码通过不代表页面已验收。

接口及技术冻结 v1

共同API结构以 自有业务后端接口设计.md 第2、3、4节为基础，并以下列最终规则覆盖草案中的待选项。两任务可据此实施，不再等待重复业务确认。

• API前缀 /api/platform/v1/last-leg/fleet/owned-business；公开业务身份dispatchNo。前端路由 /overseas-master-data/owned-business 及 /:dispatchNo；list/edit/upload权限分别为 platform:fleet:owned-business:list/edit/upload，新增查看不授予主排车操作权限。
• 查询投影仍读取原排车及真实关联表，详情组合原 DispatchViews.Detail，不复制履约主模型。附加运营recordVersion与只读dispatchRecordVersion分别返回，初始附加版本0合法；GET不建记录。
• 油耗按原型单位L/100km，手填字段 fuelConsumptionLitresPer100Km；实际里程为mile，字段 actualDistanceMiles。不把油耗率变成燃油总升数，不自动推算总油量。
• 金额币种沿已有CNY/USD，必须明确选择，不预选不换汇。一份整车金额可在同一版本化编辑中更正或清空，并保存历史；“登记一次”表示同车唯一记录，不是一次提交后永久不可编辑。零值、未登记及单价除零按既有条款区分。
• 照片沿原型七框，逐槽上传后绑定立即保存；只有绑定回执成功才显示已保存。上传成功绑定失败保留原fileId、绑定请求键及载荷，重试只绑定；未知上传保留原命令，不自动重新上传或虚称恢复成功。关闭弹框不另造保存动作。
• 车辆归属按原排车装车完成时点冻结，作为该排车的归属证据附加行，不构成第二套主单；根只在loadingComplete原事务接一个窄捕获点，新包提供者读取真实车辆ownership/版本。按原资源模式识别临时外配，不把MASTER当OWNED。旧已装车TEST无历史快照不回填、不以当前主档降级推算，本页实际验收使用新原生样本；原排车读取不受影响。
• 数据表为附加record/command/history及ownership证据，结构由后端提出、根维护基线；文件分类为 OVERSEAS_DISPATCH_LOADING_PHOTO/OVERSEAS_DISPATCH_FUEL_PHOTO，平台0、businessId=原dispatch内部主键，JPG/PNG、10MiB。没有新的主排车状态机、客户收费或Finance写入。
• 附加命令唯一键为 (dispatch_id,idempotency_key)，记录并验证原operator；异操作者复用原键A0403，不按操作者分组创建第二条命令。同一原操作者只恢复同动作、原版本、原载荷，异载荷A0409；上传和绑定各保留自己的稳定键。
• 操作记录只读聚合原排车真实历史与本页附加历史，不复制原流水。历史明确 eventSource=DISPATCH/OPERATIONS，附加recordVersion和原dispatchRecordVersion可分别为空，不混淆两个版本序列；原排车事件不伪造运营快照或照片，运营事件保留其真实快照。