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

# 自有业务首版开发契约

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

## 已确认规则

2026-10-21 用户确认按实际拼车货物分类：自有业务是未实际接入拼车货物的排车，外配任务是已实际接入拼车货物的排车，与车辆属于自有或外配无关。本契约维护自有视图；外配任务维护在[外配业务首版开发契约](外配业务首版开发契约.md)。两页共用原排车主单及真实履约事实，不另建第二套任务、车次主单、货物、审核、装车、发车或签收状态机。本次最小变更保留原页面、统计项及两页运营表单差异，不新增分类表或分类字段。

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

## 原型与实现差距

直接依据为用户提供 `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、绑定请求键及载荷，重试只绑定；未知上传保留原命令，不自动重新上传或虚称恢复成功。关闭弹框不另造保存动作。
- 车辆归属仍按原排车装车完成时点冻结，仅作车辆事实及装车依据一致性校验，不再决定业务分类。两个入口的vehicle.ownership均可为OWNED/DISPATCHED，临时车辆vehicleId可空；按真实快照返回，不能以所在页面改写车辆归属。原loadingComplete捕获点不变，旧已装车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可分别为空，不混淆两个版本序列；原排车事件不伪造运营快照或照片，运营事件保留其真实快照。

## 当前集成与验收记录（2026-10-20）

- 前端18文件候选`3deb4b56181d2b323298289cde353d1b0ced1cd75f41160ef28c04cd1f94fb40`已逐字节复算；新增页面/弹窗及API六文件直接测试连同共享路由、菜单、密度合同共113项通过。`pnpm typecheck`与`pnpm build`在默认资源限制下通过，完整Admin453文件4087项全部通过；核对全量运行窗口没有Admin TS/Vue/CSS源码改动，不继承旧批次的内存例外。
- 后端首轮统一Maven65项全部通过（本域35、原整车持久化24、只读适配1、Mapper架构2、中文基线3），含原装车捕获失败回滚、不改原主单版本、同实托多来源计一次、真实Mapper/CAS清空及并发、照片历史授权。随后只修正照片保存历史中的内部枚举文案及直接断言，受影响持久化/照片15项及IAM种子5项复验通过。最终25路径候选`b8d7c7d9108fe0475410f950579879ca5b4e3819d05f08a3b6e90cdc99ac456f`仅再收敛独立OpenAPI的multipart上传键声明，不改实际调用。装车完成沿原verifyReviewResources守卫要求计划发车非空，本页不新增门禁。
- File两类平台排车照片及相邻凭证回归21项通过；Mapper扫描406项注册及AGENTS索引1229项通过。新增OpenAPI八路径、39个直接引用可解析，原详情引用保留现行13字段结构。
- 最后全仓API/依赖联合33项全部通过，含Gateway五项和Lastleg依赖十四项。本域只登记五条公开只读端口引用，不开放fleet→dispatch通用许可，不保留实体或具体Service依赖和包循环。根对共享检查发现的六个现存客户端仅补同步依赖事实分类：四个Feign只读，两个HTTP沿真实背景诊断/请求照片读写分类；没有修改它们的业务实现。图谱保留实际Firstleg→Lastleg请求边及原有最长六跳风险，不提高预算或隐藏粗粒度环。明细证据在根`.codex-temp/owned-business-api-contracts-20261020.xml`。
- 本轮获用户明确批准后，最小环境SQL已完成：四张空附加表、三权限及仅PLATFORM_ADMIN授权，四subject持久权限版本和会话刷新；File #154已发布且248项CI通过、实际容器healthy。Admin实际#659已包含本域全部23路径，逐文件核对一致，不重复发布。Lastleg固定38路径候选7c6a已独立复核无阻断，CI #381全量检查进行中，尚未部署；真实HTTP和1920×1080、100%人工截图仍未验收。实时环境事实唯一见部署主契约。旧已装车TEST无归属快照不回填，HTTP使用新原生合成测试资料，与人工原单隔离；明确区分正式HTTP真实写入、TEST合成测量输入和现实硬件/实物测量未验收。