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及拼车唯一主契约。