admin-web/src/modules/overseas-master-data/AGENTS.md

# 海外通用资料与车辆管理

- 自有业务：`pages/OwnedBusinessView.vue`、`OwnedBusinessDetailView.vue`及`api/ownedBusiness.ts`沿`fleet-owned-business-v1.yaml`，是原排车装车后未实际接入拼车货物的运营视图，与车辆归属无关，不另建履约流程；共同规则见`../../../../../docs/海外仓业务/自有业务首版开发契约.md`。详情三个页签，运营登记1080px居中、照片760px居中；金额/油耗单位、附加与排车版本分离，`owned-business:list/edit/upload`独立，统计沿完整计划发车日期筛选。
- 外配任务：`pages/OutsourcedBusinessView.vue`、`OutsourcedBusinessDetailView.vue`及`api/outsourcedBusiness.ts`沿`fleet-outsourced-business-v1.yaml`；共同规则见`../../../../../docs/海外仓业务/外配业务首版开发契约.md`。按需求池实际接入本车的拼车货物分类，完整判定见外配契约；车辆归属独立，允许OWNED/DISPATCHED及临时EXTERNAL车辆。一车一行、三页签详情、整车承运金额除实托数、逐目的仓到达和五个装车照片位；无里程/油耗/油耗照片、成本拆分和新增履约流程。三项`outsourced-business:list/edit/upload`与自有权限独立，缺承运商保留空，vehicleId可空；其余版本、原键、真实来源及完整筛选统计沿共同契约，不能静默把外配写入当成自有权限。

- 运输路线地图：`components/TransportRouteDialog.vue`经`index.ts`公开导出，排车装车后、本土散板列表、本土卡车表单共用；来源字段、缺值规则和原型映射唯一见`PROTOTYPE_MATRIX.md`“运输路线地图”。仓库引用经`routeLocations.ts`复用Warehouse列表/详情解析完整地址（warehouse:list）；解析失败不加载地图。仅规划路线，不接GPS、不用固定样例，不在车辆主档顶部重复放入口。

- 当前散板需求：正式列表使用`pages/DispatchCapacityDemandsView.vue`、`api/dispatchCapacityDemands.ts`，只读消费日常派送排车的`/dispatches/capacity-demands`摘要；发布选项在排车新建/维护车辆中默认勾选，规则见拼车主契约当前页面范围。不得以实托数推算标准托位，未知余位明确待确认，不读取客户或司机私人资料。原登记和旧车次入口代码保留隐藏。

- 保留的内部拼车实现：`pages/CapacityOffersView.vue`、`pages/CapacityOfferDetailView.vue`、`api/capacityOffers.ts`，车次详情显式打开 `components/CapacityOfferSettingsDialog.vue` 发布余位；独立 `capacity-offer:list/manage/inquiry-*` 权限，销售只操作本人意向。流程与交互唯一契约见 `../../../../../docs/海外仓业务/内部拼车需求池首版开发契约.md`，服务端沿 `fleet-capacity-offers-v1.yaml`；首版所有货到我仓上车，未确认意向不占位，列表不逐行请求详情。

- 外接预订可选销售报价：`TripBookingPanel.vue`沿车次作用域`/bookings/quote-candidates`读取候选，不由浏览器推城市或有效日期；来源报价版本与实际成交价分别显示。引用要求quote:list，手填成交价不新增该权限门禁；改变客户/卸货站/币种/计价方式后清除不再匹配的引用，迟到候选不覆盖新表单。确认承运由后端复验版本和有效性，实收调价保留来源快照。

- 车次“在途交接”页签按需挂载`TripHandoverPanel.vue`，沿`fleet-handovers-v1.yaml`读取剩余货物和交接记录；确认用trip:handover，旧资源结束用trip:release，saved刷新车次。原DEPART不重写，司机/车辆任务分别结束。

- 车队报价`pages/FleetQuotesView.vue`、`api/fleetQuotes.ts`沿`fleet-quotes-v1.yaml`区分采购/销售；原型通用菜单，编辑780px、CSV导入1040px，未知价格与零价分开。出车记录`pages/TripOperationsView.vue`、`api/tripOperations.ts`沿`fleet-operations-v1.yaml`按实际DEPART查询，列表/图表同筛选，缺少成本或财务事实不推为零；分别使用fleet:quote:list与fleet:operations:list，写入/导出独立权限。

- 车次“直接成本”页签：`components/TripCostPanel.vue`、`api/tripCosts.ts`，选择页签才读取一次分页及整趟汇总；登记/更正分别使用trip:cost-create/cost-edit，历史沿trip:list。编辑先取最新历史快照版本；不修改内容不写入，未知新增结果保留原键及内容重试。按原币种展示，不将未登记或未分摊当零，不推定财务付款；费用表操作列在左，分摊表只读。后端合同为`fleet-trip-costs-v1.yaml`。

- 车辆概览中的派送与更换记录由`components/VehicleFulfillmentTable.vue`、`api/vehicleFulfillment.ts`读取，替代原提示文字。派送要求vehicle:list与delivery:list，更换要求vehicle:list与trip:list；无对应权限不请求接口。两个可见分区各一次分页请求，不逐行加载；换车/换页忽略旧响应，错误保留重试及诊断。更换显示原/新车辆与司机、历史车次及排车业务号；现有快照没有操作人姓名时显示“—”，不用内部操作者ID回退。

- 适用应用规则见 `../../../AGENTS.md`；原型与交互矩阵为本目录 `PROTOTYPE_MATRIX.md`，新增司机页面使用其中用户提供的新版原型入口。
- 报价、汇率、车辆现有 API 在 `api/overseasMasterData.ts`；司机 API 在 `api/drivers.ts`，字段与标签在 `driverTypes.ts`，后端合同为 Lastleg `fleet-drivers-v1.yaml`。
- 共享车次接口在 `api/trips.ts`，类型在 `tripTypes.ts`，后端合同为 `fleet-trips-v1.yaml`；覆盖计划/分配、客户排车关联、实际装载、货物结案和分别结束车辆/司机任务。接口保留稳定幂等键、版本与货物hash，长ID按字符串透传；数量和容量展示服务端结果，不在浏览器推算整车可发或可结案。新页面承载按 `PROTOTYPE_MATRIX.md` 确定，不因API存在推导页面能力。
- 当前日常作业统一从排车列表进入，侧栏`fleet-trips`为hidden；“出车记录”保留实际发车后的运营查询。原`pages/TripsView.vue`、`pages/TripDetailView.vue`及附加能力代码保留，不能作为新排车的前置步骤。旧详情仍按页签按需读取，资源候选聚焦或搜索时查询，不逐行读取。新整车审核、PDA真实拣货、双端装车确认及实际发车规则以`../../../../../docs/海外仓业务/排车列表统一作业改造契约.md`为准；详情只有已确认四页签，不把旧八项附加功能自动迁入或以派送完成自动释放资源。
- 车辆实际托位/载重kg/容积m³分别由服务端返回，三项同填正数或全空待确认；不按车型名称推算。占用期间主档关键变更由服务端拒绝，下载中心 XLSX 导出使用车牌业务标识并包含容量字段。
- 车辆运维在 `VehicleDetailView.vue` 的页签内，表格与编辑框为 `components/VehicleCareTable.vue`、`VehicleCareEditor.vue`；`api/vehicleCare.ts` 对接 `fleet-vehicle-records-v1.yaml`。保养/加油680px，维修/故障/救援/异常620px居中弹框，行操作按 `PROTOTYPE_MATRIX.md` 的逐类型入口执行。进入页签才分页查询，保养加油图片点击才鉴权读取并在新标签页预览；卸载释放Blob。车辆list包含记录只读，record-create/edit/upload独立；未知保存结果保留原请求键，照片重试不重复建记录。处理状态与付款状态独立，费用未填和零值区分；无财务关联时只显示服务端UNLINKED，不自动修改车辆公里码、状态或财务。
- 维修/故障/救援的“更新处理”已获用户确认，复用原620px弹框及record-edit权限；更正说明选填，空值由页面填标准动作说明，不移除服务端不可变历史。
- 司机列表 `pages/DriversView.vue`、详情 `pages/DriverDetailView.vue`，编辑和证照预览在 `components/DriverEditorDialog.vue`、`DriverLicensePreview.vue`。详情独立路由；编辑居中1080px三列表单；预览居中620px。
- 列表与统计使用同一次服务端响应；统计范围与列表筛选一致，30天提醒按证照时区计算。页面不能用当前分页行数替代总统计，也不能在浏览器重算派车资格。
- 姓名/证照关键字段变化与替换驾驶证重新待审；体检、培训和保险当前仅记录日期，不自动成为必需资质。所属仓库使用真实公共目录，不接受自由文本假关联。
- `driver:list` 包含详情、历史、资格预览与关联附件读取；创建、编辑、启停、审核、上传权限独立。前端只隐藏/禁用操作，服务端仍需校验。
- 保存档案成功而上传失败时保留已生成的司机和版本，重试不得再次创建；版本冲突保留表单及服务端错误。审核或修改成功使用返回详情，不无条件再次请求详情。
- 历史按需分页；附件只在打开预览时读取，关闭/卸载释放Blob URL，忽略已关闭后的迟到响应。文件业务错误不能作为图片/PDF预览。
- `DriverDetailView` 资格预览随预计结束时间或档案变化失效；只显示待重新校验，不自行构造服务端资格结论。真实派车和发车仍须服务端命令复核。
- 定向检查：`pnpm test src/modules/overseas-master-data src/core/navigation/adminNavigation.test.ts src/styles/adminDensity.test.ts`；发布前按应用规则执行类型检查、全量测试和构建。

- 车次详情“计划容量”页签按需读写`/capacity-plan`，复用`TripLoadingPanel`的计划模式，预计重量/体积与实际装载分别保存；只在该页签展示逐段计划余位。`planValid=false`时不展示旧余位，货物变化后重新核对；保存计划只更新车次版本，不把理货审核变成通过或写入实载。

- `TripBookingPanel.vue`在车次详情“外接预订”页签按需读取列表；1080px居中弹框登记/编辑或只读详情，客户聚焦搜索才读取`/fleet/trips/customer-options`。询价只要求客户、既有卸货站和箱数，载荷/价格/联系信息可后补；确认承运由服务端校验余位及完整报价。create/edit/confirm/cancel分别使用独立`trip:booking-*`权限，读操作沿trip:list。未知创建及确认结果保留原请求重试，成功用命令结果更新列表和车次版本；计划容量表展示availableSegments（已扣除外接占位），不使用旧自有货余位覆盖。

- 外接履约弹框`TripBookingFulfillmentDialog.vue`为1080px居中：登记来货、按服务器实托/receiptHash核对实收与约定价格、输入客户排车单号关联；来货详情只读。只有显式打开来货/实收弹框才查询来源，不逐行请求。关联后刷新外接列表及车次详情，更新全部排车成员和理货审核状态；预订取消不删除来货或库存。

- 报价、汇率、车辆、车队报价与出车记录导出统一使用 `../downloads/` 的 `useExportTask`，按当前筛选创建 XLSX 任务；按钮要求原业务导出权限和 `platform:download:list`。出车成本可见性由 File 根据账号权限冻结，不接受页面声明。CSV 仅用于车队报价导入模板。

- 拼车接货简化沿 `FleetCapacityOfferModels.Inquiry.progress` 展示缺项、是否保位、负责人及主要动作，`appointmentCoverage`只消费预约侧真实投影，不以承运成功冒充预约。`CapacityInquiryFulfillment.vue`从原登记按需读取本票履约，不授予销售整车读取权限；来货、核量、排入本车分别保持原写权限。`TripPreparationDialog.vue`和`TripDispatchSelector.vue`通过`index.ts`公开给排车/预约使用；前者提交原子`/fleet/trips/prepare`并衔接容量发布，后者只读取本仓合格候选。新版合同见`fleet-preparation-v1.yaml`及拼车唯一主契约。