diff --git a/AGENTS.md b/AGENTS.md index c457b9ea..414358d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,44 +38,46 @@ 按短表定位后按需查 [业务细则](docs/business-index.md)；涉及业务行为变更时必须核对对应细则及最近模块指引。从应用根执行 `rg -n -F '任务词或文件名' docs/business-index.md`，只读命中条款。 -路径从应用根起算，`modules/`、`core/` 从 `src/` 起算；接口片段与符号沿同一行代码定位。 +路径从应用根起算，`modules/`、`core/` 从 `src/` 起算；接口片段与符号沿同一行代码定位。模块指引中的后端类名以服务名起算，如 `firstleg/service/X.java` 即 `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/X.java`。 | 业务 | 首个入口 | |---|---| -| 登录、会话与统一 Token | `modules/auth/`、`core/auth/` | +| 登录、会话与统一 Token | `modules/auth/AGENTS.md`、`core/auth/` | | 启动与懒加载资源恢复 | `src/main.ts`、`core/routing/navigationRecovery.ts` | -| 工作台与指标 | `modules/dashboard/` | +| 工作台与指标 | `modules/dashboard/AGENTS.md` | | 自营销量、库存与数据采集 | `modules/self-operated/AGENTS.md` | -| 船期日历 | `modules/sailing-calendar/` | -| 预约管理、预约列表、跨客户同仓预约 | `modules/appointment-calendar/`、`modules/overseas-warehouse/` | +| 船期日历 | `modules/sailing-calendar/AGENTS.md` | +| 预约管理、预约列表、跨客户同仓预约 | `modules/appointment-calendar/AGENTS.md`、`modules/overseas-warehouse/` | | FBA 无匹配价格、人工定价 | `modules/inbounds/fee/api.ts`、`createManualInboundQuote` | -| PDA版本、APK下载、WGT热更新发布与停发 | `modules/pda-releases/pages/PdaReleasesView.vue`、`modules/pda-releases/api/pdaReleases.ts` | -| 客户、企业审核、客户统计 | `modules/customers/` | -| 供应商、国内整柜 | `modules/suppliers/`、`modules/domestic-containers/` | -| 平台仓库与仓储资源 | `modules/warehouses/`、`modules/warehouse-resources/` | -| 平台用户、RBAC、导航 | `modules/iam/`、`core/access/` | +| PDA版本、APK下载、WGT热更新发布与停发 | `modules/pda-releases/AGENTS.md` | +| 客户、企业审核、客户统计 | `modules/customers/AGENTS.md` | +| 供应商、国内整柜 | `modules/suppliers/AGENTS.md`、`modules/domestic-containers/AGENTS.md` | +| 平台仓库与仓储资源 | `modules/warehouses/AGENTS.md`、`modules/warehouse-resources/AGENTS.md` | +| 平台用户、RBAC、导航 | `modules/iam/AGENTS.md`、`core/access/` | | 国内/海外 PDA 独立人员与海外仓绑定 | `modules/iam/pages/InternalUsersView.vue`、`modules/iam/api/platformIam.ts` | -| 消息中心 | `modules/notifications/` | -| 订单列表、批量审核预览、详情、商品图片与入库费用 | `modules/unified-orders/`、`modules/first-leg-orders/` | +| 消息中心 | `modules/notifications/AGENTS.md` | +| 订单列表、批量审核预览、详情、商品图片与入库费用 | `modules/unified-orders/AGENTS.md`、`modules/first-leg-orders/` | | 客户原始申报资料编辑与渠道变更 | `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`modules/unified-orders/api/unifiedOrders.ts` | | 入库扣货、解除与凭证历史 | `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts` | -| 入库、测量、称重库位状态、客户箱规策略与计价主数据 | `modules/inbounds/measurement/InboundMeasurementDialog.vue`、`modules/inbounds/measurement/InboundMeasurementPanel.vue` | +| 入库、测量、称重库位状态、客户箱规策略与计价主数据 | `modules/inbounds/AGENTS.md`、`modules/dimension-config/AGENTS.md` | | 一件代发托盘打印 | `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/DropshipPalletPrintPanel.vue` | | 入库单扣货、解除、凭证与历史 | `modules/inbounds/pages/InboundOrdersView.vue`、`modules/inbounds/core/api.ts` | -| 客户专属价格簿、柜级阶梯运费与受控调价 | `modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue`、`modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue` | +| 客户专属价格簿、柜级阶梯运费与受控调价 | `modules/fba-pricing/AGENTS.md`、`modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue` | | 财务、客户资金账户与柜级公共费用分摊 | `modules/finance/AGENTS.md` | -| 货柜双工作台、排柜、预装/装柜清单、真实柜号后补与整柜报关 | `modules/container-loading/pages/DomesticContainersView.vue`、`modules/container-loading/pages/OverseasContainersView.vue` | +| 货柜双工作台、排柜、预装/装柜清单、装柜照片与证据、真实柜号后补与整柜报关 | `modules/container-loading/AGENTS.md`、`modules/loading-lists/AGENTS.md` | | 合柜报关 / 同柜不可拆组 | `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/pages/UnifiedOrdersView.vue` | | 全局智能装柜工作台、入仓码候选与箱数分配 | `modules/container-loading/components/SmartLoadingDialog.vue`、`modules/container-loading/pages/GlobalSmartLoadingView.vue` | -| 国内货柜履约订舱资料、打印、关联候选与出仓前船期 | `modules/ocean-bookings/`、`modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue` | -| 订舱级拖车预约 | `modules/trucking/api/platformTrucking.ts`、`/candidates` | -| 目的港码头拖车与还空预警 | `modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue` | -| 历史报关协同与国内出仓 | `modules/customs/`、`modules/outbound-dispatch/` | -| 主数据、下载、退避任务重试、审计 | `modules/master-data/`、`modules/downloads/pages/DownloadCenterView.vue` | -| 海外接柜、入库、库存与库内服务 | `modules/overseas-warehouse/` | -| 海外采购、卡车、散板 | `modules/overseas-business/` | -| 海外仓业务合作仓与通用资料 | `modules/warehouses/`、`modules/overseas-master-data/` | -| 海外仓业务国内出仓后船节点 | `modules/port-schedules/`、`modules/ocean-bookings/` | +| 国内货柜履约订舱资料、打印、关联候选与出仓前船期 | `modules/ocean-bookings/AGENTS.md` | +| 订舱级拖车预约 | `modules/trucking/AGENTS.md` | +| 目的港码头拖车与还空预警 | `modules/container-loading/AGENTS.md` | +| 历史报关案件、报关回执与国内出仓 | `modules/customs/AGENTS.md`、`modules/outbound-dispatch/AGENTS.md` | +| 主数据、下载、退避任务重试 | `modules/master-data/AGENTS.md`、`modules/downloads/AGENTS.md` | +| 费用项目、计费科目 | `modules/fee-items/AGENTS.md` | +| 操作日志、审计日志、操作人 | `modules/audit/AGENTS.md` | +| 海外接柜、入库、库存与库内服务 | `modules/overseas-warehouse/AGENTS.md` | +| 海外采购、卡车、散板 | `modules/overseas-business/AGENTS.md` | +| 海外仓业务合作仓与通用资料 | `modules/warehouses/AGENTS.md`、`modules/overseas-master-data/AGENTS.md` | +| 海外仓业务国内出仓后船节点 | `modules/port-schedules/AGENTS.md`、`modules/ocean-bookings/` | | 海外排车、出库与派送 | `modules/overseas-warehouse/AGENTS.md` | | 海外异常退回与客户回访 | `modules/overseas-warehouse/AGENTS.md` | diff --git a/docs/business-index.md b/docs/business-index.md index b5e72cbb..dd0ebd80 100644 --- a/docs/business-index.md +++ b/docs/business-index.md @@ -34,7 +34,7 @@ | 入库单扣货、解除、凭证与历史 | `modules/inbounds/pages/InboundOrdersView.vue`、详情工作区、`modules/inbounds/core/api.ts` | 列表展示服务端 `holdFlag/currentHoldReason` 并支持筛选；详情只按 `canHold/canRelease/actionBlockReason` 开放操作。扣货与解除提交当前 `version`、原因和独立幂等键，可选凭证先按明确客户与入库单上传；历史文件只调用专用下载入口，不把上传成功但未提交命令的文件冒充扣货证据 | | 客户专属价格簿、柜级阶梯运费与受控调价 | 列表/上传 `modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue`，版本详情/仓库映射/确认 `modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue`，路由 `modules/fba-pricing/routes.ts`；`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue` | 列表与上传后按 `versionId` 进入 `fba-carrier-rate-detail` 独立详情页，价格行只读；回归入口 `modules/fba-pricing/carrier-rates/pages/CarrierRatesView.test.ts`。价格簿页面显式选择公共报价或具体客户；列表、上传、确认只作用于该 `customerId`，不得混合版本。计价优先消费客户专属 ACTIVE 版本，无专属版本才回退公共 ACTIVE；柜级阶梯金额和各客户分摊只展示服务端结果。调整计费量只能在服务端返回的上下 10% 范围内并提交当前费用版本、原因与二次确认；私人仓尾程派送费使用稳定 `PRIVATE_LAST_MILE_DELIVERY` 代码且只对 `PRIVATE` 目的地开放；一件代发须在预装确认前完成试算，计价后保持服务端 `WAIT_PALLETIZE` 状态 | | 财务、客户资金账户与柜级公共费用分摊 | `modules/finance/`，继续读该目录 `AGENTS.md`；客户账户 `pages/FinanceCustomerAccountsView.vue`，柜费 `modules/loading-lists/components/ContainerFeesPanel.vue`、`api/containerFees.ts` | `finance/`、`firstleg/`、`file/`、`docs/财务管理/`；实际、冻结、可用余额、授信与流水只消费 Finance 权威结果，充值审核和手工充扣携带版本与幂等键。跨客户公共柜费只按服务端柜内客户/订单事实分摊，金额必须守恒，创建与审核、驳回、调整、作废均整组原子处理 | -| 货柜双工作台、排柜、预装/装柜清单、真实柜号后补与整柜报关 | 国内 `modules/container-loading/pages/DomesticContainersView.vue`、海外 `OverseasContainersView.vue`，共享详情实现 `ContainerDetailView.vue`；预装详情 `modules/loading-lists/pages/PreloadPlanDetailView.vue`，资料/PDA 证据 `components/ContainerOverviewPanel.vue`，报关 `components/ContainerCustomsPanel.vue` | 国内“送柜报关”只消费 `/containers/domestic` 与服务端 `allowedActions`，承载模拟柜、订舱关联、智能装柜；模拟柜创建选择与智能装柜一致的 9 类计划渠道，未关联订舱前实际渠道为空，订舱关联候选按计划渠道组匹配并同时展示订舱号与提单号、装柜清单页签、出口报关和国内出仓；创建柜次时自动生成唯一预装计划，预装详情先调用 `/loading-plans/{planId}/lifecycle`，完成后深链进入国内货柜详情的装柜清单页签，独立装柜清单导航 `/loading-lists` 复用已确认清单 API，查看进入独立详情路由 `/loading-lists/:planId`，保留返回列表和打印；独立清单详情与货柜清单页签共同使用 `useLoadingListDetail.ts` 加载、校验和处理错误，`LoadingListDetailDrawer.vue` 统一密度、摘要、明细、历史及打印入口，打印实现归 `printLoadingList.ts`，外层只保留返回目标与货柜专属 PDA/报关区域；货柜列表经 `ContainerWorkbenchView.vue` 在国内装柜与海外清关提柜之间按权限切换。订舱关联允许真实集装箱号为空，但确认预装和创建 PDA 任务前必须补齐；历史已建但缺号的任务仍可在预装详情首次补录，保存后恢复 PDA 可进入状态；全买单柜继续使用 `complete-all-buy`。海外“清关提柜”只消费 `/containers/overseas`，承载船节点、目的港清关、DO/PU、码头车队和还空；原预约/实际提柜展示位改为整柜预计/实际到仓，预计到仓在列表内人工快捷维护并经海外接口同步整柜尾程订单，实际到仓只读海外 PDA 首次开始收货时间。还空截止事实由服务端基于卸柜完成时间加 72 小时计算，前端不重算。两端统一使用 `containerBookingId`，列表范围由服务端 `scope=ACTIVE/HISTORY` 分页，禁止浏览器筛选或本地推导写资格。后端为 `LoadingListService`、`firstleg/customs/container/`、`firstleg/terminaldrayage/` 和 `lastleg-service/`，文件归 `file/` | +| 货柜双工作台、排柜、预装/装柜清单、真实柜号后补与整柜报关 | 国内 `modules/container-loading/pages/DomesticContainersView.vue`、海外 `OverseasContainersView.vue`，共享详情实现 `ContainerDetailView.vue`；预装详情 `modules/loading-lists/pages/PreloadPlanDetailView.vue`，资料/PDA 证据 `components/ContainerOverviewPanel.vue`，报关 `components/ContainerCustomsPanel.vue` | 规则见下文「货柜工作台规则」 | | 合柜报关 / 同柜不可拆组 | `modules/unified-orders/api/coLoadGroups.ts`、`pages/UnifiedOrdersView.vue`；装柜消费 `modules/container-loading/pages/SmartLoadingWorkbenchView.vue` | 前端只提交订单 ID；Backend `firstleg/loading/coload/` 展开并冻结每票全部可用入仓片段。成员数是入仓片段数，不等于订单票数；只要求同国内仓、同渠道，允许跨客户及不同目的仓港；分配、移除、取消均整组处理 | | 全局智能装柜工作台、入仓码候选与箱数分配 | `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`，柜次页 `SmartLoadingWorkbenchView.vue`，以及 `smartLoadingChannelGroups.ts`、`smartLoadingItems.ts`、`api/platformContainerLoading.ts`；全局页当前不注册独立路由 | Backend `firstleg/` 的 `/inbound-candidates`、`/containers`、`/inbound-assignments`、`/plans/{planId}/pending-review-assignments`、`/group-assignments`、`/unpicked-items`。`orderStatuses` 最多四项且未传表示全部未完成状态；候选状态多选覆盖待审核、待测量、待分柜、装柜中，状态只用于筛选展示，按钮资格以服务端 `canAssign` 为准；待审核/待测量可提前占位但不得提前确认预装或启动 PDA。计划箱数编辑上限、已用和未用展示只消费服务端 `totalPackageCount/remainingPackageCount`，不得从候选页或本地规格重新拼算。人工加入允许跨渠道，智能推荐仍按柜次渠道。柜次容量和限重取服务端字段；同柜组作为单卡整组分页、分配和移除，任一成员已拣时整组保留 | | 国内货柜履约订舱资料、打印、关联候选与出仓前船期 | `modules/ocean-bookings/` 的 `components/OceanBookingDocumentsPanel.vue`、`OceanBookingPrintDialog.vue`，以及 `modules/container-loading/`、`modules/port-schedules/` | 订舱草稿按当前版本维护资料，放舱后资料与表单只读；打印对草稿与已放舱订舱均开放，按当前已保存资料生成，未填写字段显示“—”。`platformOceanBookings.ts` 的 `/link-candidates` 只消费服务端分页，`containerCount` 是柜型需求 `quantity` 总和；Backend `firstleg/oceanbooking/`、`file/`、`print/`、`firstleg/portschedule/` | @@ -53,6 +53,11 @@ 散货托盘码打印：`modules/loading-lists/components/PalletLabelPrintDialog.vue`、`modules/loading-lists/api/platformLoadingLists.ts`，由货柜详情与装柜清单详情进入；先调用 `/pallet-labels/prepare` 获取服务端按 FBA 仓分组的冻结清单，再通过 `/pallet-labels/print` 下载 PDF。托盘码使用“真实柜号-FBA 地址内部编号-三位序号”，页面同时展示 FBA 仓码和内部编号；支持全部打印或按仓指定张数补打，一件代发托盘不在该清单，前端不生成或重新编号托盘码。 + +## 货柜工作台规则 + +- 国内“送柜报关”只消费 `/containers/domestic` 与服务端 `allowedActions`，承载模拟柜、订舱关联、智能装柜；模拟柜创建选择与智能装柜一致的 9 类计划渠道，未关联订舱前实际渠道为空，订舱关联候选按计划渠道组匹配并同时展示订舱号与提单号、装柜清单页签、出口报关和国内出仓；创建柜次时自动生成唯一预装计划，预装详情先调用 `/loading-plans/{planId}/lifecycle`，完成后深链进入国内货柜详情的装柜清单页签，独立装柜清单导航 `/loading-lists` 复用已确认清单 API，查看进入独立详情路由 `/loading-lists/:planId`，保留返回列表和打印；独立清单详情与货柜清单页签共同使用 `useLoadingListDetail.ts` 加载、校验和处理错误，`LoadingListDetailDrawer.vue` 统一密度、摘要、明细、历史及打印入口，打印实现归 `printLoadingList.ts`，外层只保留返回目标与货柜专属 PDA/报关区域；货柜列表经 `ContainerWorkbenchView.vue` 在国内装柜与海外清关提柜之间按权限切换。订舱关联允许真实集装箱号为空，但确认预装和创建 PDA 任务前必须补齐；历史已建但缺号的任务仍可在预装详情首次补录，保存后恢复 PDA 可进入状态；全买单柜继续使用 `complete-all-buy`。海外“清关提柜”只消费 `/containers/overseas`，承载船节点、目的港清关、DO/PU、码头车队和还空；原预约/实际提柜展示位改为整柜预计/实际到仓，预计到仓在列表内人工快捷维护并经海外接口同步整柜尾程订单，实际到仓只读海外 PDA 首次开始收货时间。还空截止事实由服务端基于卸柜完成时间加 72 小时计算，前端不重算。两端统一使用 `containerBookingId`，列表范围由服务端 `scope=ACTIVE/HISTORY` 分页，禁止浏览器筛选或本地推导写资格。后端为 `LoadingListService`、`firstleg/customs/container/`、`firstleg/terminaldrayage/` 和 `lastleg-service/`，文件归 `file/` + ## 海外模块内部快速索引（海外仓全流程） - 海外仓的尾程订单控制与柜级入仓计划转换、退货库存、排车出库、异常回访：读取 `src/modules/overseas-warehouse/AGENTS.md`，字段与流程仅在该模块维护。 diff --git a/src/modules/appointment-calendar/AGENTS.md b/src/modules/appointment-calendar/AGENTS.md new file mode 100644 index 00000000..d3274844 --- /dev/null +++ b/src/modules/appointment-calendar/AGENTS.md @@ -0,0 +1,33 @@ +# Admin 预约日历模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/appointment-calendar/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，预约规则见 `../../../docs/business-index.md`；工作日历正式规则在**工作区** `docs/海外仓业务/预约工作日历V13变更说明.md`。 +- 本模块扁平存放页面、面板与 API，无 `pages/`、`components/` 分层：`*.vue` 多为面板，`*Api.ts` 为对应接口，`calendar.ts`/`schedule.ts`/`tripCalendar.ts` 为日历与航段计算，`useWorkDraft.ts`/`useWorkSyncRead.ts` 为草稿与只读同步。 +- 后端只查 `lastleg-service/`（`inboundplan/`、`appointmentplanning/`）；到港事实只读 `firstleg/` 的船节点，纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 入口 | API 与后端 | +|---|---|---| +| 预约列表与日历主页面 | `AppointmentCalendarView.vue`；`appointment-calendar` | `api.ts`、`calendar.ts`；`lastleg-service/inboundplan/` | +| 工作日历、车次与送仓待办 | `WorkCalendarPanel.vue`、`TripAppointmentPanel.vue` | `workApi.ts`、`tripCalendar.ts`；`lastleg-service/appointmentplanning/` | +| 新建/批量预约、多客户共车 | `AppointmentCreatePanel.vue`、`AppointmentBatchForm.vue`、`WorkSharedTripForm.vue` | `workApi.ts`、`batchApi.ts` | +| 货物验证与入仓码关系 | `AppointmentCargoPanel.vue`、`AppointmentCargoTabs.vue`、`AppointmentInboundCodes.vue`、`CargoVerificationForm.vue` | `cargoVerificationApi.ts` | +| 改期、取消与取消记录 | `AppointmentImpactDialog.vue`、`AppointmentCancellationDialog.vue`、`AppointmentCancellationHistory.vue`、`AppointmentCancellationRecords.vue` | `impactApi.ts` | +| 派送安排与分批后送 | `WorkDispatchForm.vue`、`WorkExistingDispatchForm.vue` | `workApi.ts`；`lastleg-service/delivery/` | +| 收货范围与收货计划 | `ReceivingScope.vue`、`WorkReceivingPanel.vue`、`WorkReceiptPlans.vue` | `receivingApi.ts` | +| 外部候选取货与跟进 | `AppointmentExternalCandidates.vue`、`AppointmentFollowupDialog.vue` | `planningApi.ts`、`workApi.ts` | + +## 关键边界 + +- 同仓跨客户共用一张预约，客户归属在货物明细，不为每个客户拆预约；同车多客户按 V13 规则处理。 +- 到港事实只读 Firstleg 船节点，送仓与排车归 Lastleg；不得用预计到港替代计划到仓，也不得反向写船节点。 +- 改期、取消、重新预约必须按服务端影响范围与版本提交，取消记录只追加，不改写历史。 +- 未定日期事项进入待办跟进，不伪造日期；分批后送的批次关系以服务端返回为准。 +- 面板之间共享草稿状态，`useWorkDraft.ts` 是唯一草稿入口；刷新时用 `useWorkSyncRead.ts` 合并服务端事实并保留本机未提交输入。 + +## 验证 + +- 定向：`pnpm test src/modules/appointment-calendar/<目标测试>`；日历与批次规则变更同时核对 V13 规则文档与 `lastleg-service` 合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/audit/AGENTS.md b/src/modules/audit/AGENTS.md new file mode 100644 index 00000000..7a23b512 --- /dev/null +++ b/src/modules/audit/AGENTS.md @@ -0,0 +1,28 @@ +# Admin 操作日志与审计模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/audit/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 本模块**没有独立页面**：审计日志是客户详情里的内嵌面板（`components/CustomerAuditLogsPanel.vue`），查询接口在 `api/platformAudit.ts`。 +- 后端查 `audit-service/`（`PlatformAuditLogController`、`AuditLogQueryService`）；若是“操作人没被记录”，还要查采集侧 `common-audit/`（`BusinessAuditAspect.java`、`AuditEvent.java`）。 + +## 页面与入口 + +| 目标 | 入口 | API 与后端 | +|---|---|---| +| 客户详情内的操作日志面板、分页与详情 | `components/CustomerAuditLogsPanel.vue`（props：`customerId`、`customerName`） | `api/platformAudit.ts` 的 `listPlatformAuditLogs`、`getPlatformAuditLog`；`audit-service/` | +| 日志字段展示、时间与文案映射 | `presentation.ts` | 服务端返回结构 | +| 日志列表/详情的对外类型 | `index.ts` | `audit-service` DTO | +| 操作人缺失、字段为空 | 面板空态与列定义 | 先查 `common-audit/` 是否采集该字段，再查 `audit-service/` 摄取 DTO 与表结构 | + +## 关键边界 + +- 列表不返回变更前后快照，详情才返回已脱敏 JSON；不要在列表里展开完整 payload。 +- 客户账号不得访问平台审计查询；面板只在平台侧客户详情内使用。 +- 审计字段缺失属于“采集侧漏采”或“查询侧未映射”，两者分属 `common-audit/` 与 `audit-service/`，不要只改前端展示。 +- 审计链路故障不得阻塞核心交易，前端也不得据此推断业务失败。 + +## 验证 + +- 定向：`pnpm test src/modules/audit/<目标测试>`；字段或查询变化同时核对 `audit-service` 的查询接口与表结构。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/auth/AGENTS.md b/src/modules/auth/AGENTS.md new file mode 100644 index 00000000..d4a0382b --- /dev/null +++ b/src/modules/auth/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 登录模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/auth/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 模块只有一个页面 `pages/LoginView.vue`；认证状态、Token 刷新与路由守卫在 `../../core/auth/` 与 `../../shared/api/AGENTS.md`，本模块不复制这些逻辑。 +- 后端只查 `auth/`（登录、刷新、退出、改密）。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 平台员工登录页、表单校验与错误提示 | `pages/LoginView.vue` | `../../core/auth/auth.ts` → `../../shared/api/http.ts`；`auth/` | +| 登录态与路由跳转 | 页面不持有状态 | `../../core/auth/auth.ts`、`../../core/access/` | +| 401 刷新与重放 | 页面不处理 | `../../shared/api/http.ts`、`../../shared/api/AGENTS.md` | + +## 关键边界 + +- 页面不读写 Token、不拼 `Authorization`、不自行持久化密码；令牌与刷新编排只在 `src/core/auth/` 与 `src/shared/api/http.ts`。 +- 认证失败提示按服务端返回的 `code` 与文案展示，不把 401/403 混为同一种提示。 +- 登录成功后跳转由路由守卫决定，页面不硬编码默认落地页。 +- 记住账号类能力只保存登录标识，不持久化密码或 Token。 + +## 验证 + +- 定向：`pnpm test src/modules/auth/<目标测试>`；登录或守卫变化同时核对 `src/core/auth/` 与 `src/shared/api/http.ts`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/container-loading/AGENTS.md b/src/modules/container-loading/AGENTS.md new file mode 100644 index 00000000..5a625ee0 --- /dev/null +++ b/src/modules/container-loading/AGENTS.md @@ -0,0 +1,37 @@ +# Admin 货柜模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/container-loading/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，页面/接口细则见 `../../../docs/business-index.md`。 +- 先按下表定位页面，再沿 `routes.ts`、页面 import 与 `api/` 追踪；接口、状态、金额或权限变化时再读详细索引命中行。 +- 后端只查直接消费方：`firstleg/`（`loading/`、`customs/container/`、`terminaldrayage/`、`oceanbooking/`）、`lastleg-service/`（柜级到仓与尾程）、`file/`、`print/`。纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 国内装柜列表、模拟柜、订舱关联 | `pages/ContainersView.vue`、`pages/DomesticContainersView.vue`；`container-loading/domestic` | `api/platformContainerLoading.ts`；`components/ContainerSimulationCreate.vue`、`components/OceanBookingLinkDialog.vue`；`firstleg/loading/` | +| 送柜报关详情、装柜清单页签、报关、出仓 | `pages/DomesticContainerDetailView.vue`、共享 `pages/ContainerDetailView.vue`；`container-loading/domestic/:containerId` | `components/ContainerOverviewPanel.vue`、`components/ContainerCustomsPanel.vue`；`api/platformContainerCustoms.ts`；`firstleg/customs/container/`、`file/` | +| 智能装柜工作台、柜次容量与分配 | `pages/SmartLoadingWorkbenchView.vue`；`container-loading/domestic/:containerId/smart-loading` | `api/platformContainerLoading.ts`；`../unified-orders/workflows/components/SmartLoadingWorkbench.vue`；`firstleg/service/SmartLoadingService.java` | +| 全局智能装柜弹框、入仓码候选与箱数 | `pages/GlobalSmartLoadingView.vue`（内嵌，无独立路由）、`components/SmartLoadingDialog.vue`、`components/SmartLoadingCandidateInbounds.vue` | `smartLoadingChannelGroups.ts`、`smartLoadingItems.ts`、`smartLoadingPlanGroups.ts`；后端 `/inbound-candidates`、`/containers`、`/inbound-assignments` | +| 海外清关提柜工作台、船节点、清关与 DO/PU | `pages/OverseasContainersView.vue`；`container-loading/overseas` | `api/platformContainerLoading.ts`；`firstleg/` 船节点与 `customs/`；`components/ContainerOverviewPanel.vue` | +| 目的港码头拖车、车队与还空 | `pages/OverseasContainerDetailView.vue`（薄包装）、共享 `pages/ContainerDetailView.vue`（实际内容）；`container-loading/overseas/:containerId` | `api/terminalDrayages.ts` 由共享详情调用；`firstleg/terminaldrayage/`（`TerminalDrayageService.java`、`DirectDeliveryService.java`） | +| 整柜预计/实际到仓 | 列表与详情“到仓”列 | `api/containerArrivalTimes.ts`；`lastleg-service/` 柜级订单 | +| 装柜照片与证据的展示/读取（上传在 PDA 与 Firstleg） | `components/ContainerOverviewPanel.vue` | 证据读取走 `file/`；生产与上传见 `firstleg/loading/service/CabinetLoadingEvidenceService.java` 与国内 PDA | +| 海外柜费用 | `components/ContainerLastLegFeesPanel.vue` | `api/overseasContainerFees.ts`；`finance/`、`firstleg/` 费用来源 | + +`pages/ContainerWorkbenchView.vue` 是工作台外壳，按权限在“国内装柜”“清关提柜”间切换；`pages/ContainersView.vue` 与 `ContainerDetailView.vue` 为共享实现，改两份前先确认是否同源。 + +## 关键边界 + +- 列表范围由服务端 `scope=ACTIVE/HISTORY` 分页，写资格只取服务端 `allowedActions`；不用浏览器筛选、本地推导或柜内明细数量代替。 +- 创建柜次时自动生成唯一预装计划；订舱关联允许真实集装箱号为空，但**确认预装和创建 PDA 任务前必须补齐**，历史上已建缺号任务可在预装详情首次补录。 +- 还空截止、超时天数只展示服务端按权威卸柜完成时间加 72 小时计算的结果，前端不重算、不用拖车状态当阻断门禁。 +- 国内“送柜报关”只消费 `/containers/domestic`，海外“清关提柜”只消费 `/containers/overseas`；两端统一用 `containerBookingId`，禁止混用两套列表接口。 +- 智能装柜候选状态只作筛选展示，按钮资格以服务端 `canAssign` 为准；计划箱数只消费 `totalPackageCount/remainingPackageCount`，不从候选页或本地规格重算。 +- 前端不计算托数、不逐票建计划、不预占托盘；柜级转换必须原样回传服务端 `snapshotVersion/snapshotHash`，冲突后重新预览。 + +## 验证 + +- 定向：`pnpm test src/modules/container-loading/<目标测试>`；API 或类型变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`；离线检查不代替真实 HTTP 与人工截图验收。 diff --git a/src/modules/customers/AGENTS.md b/src/modules/customers/AGENTS.md new file mode 100644 index 00000000..46aaaf9b --- /dev/null +++ b/src/modules/customers/AGENTS.md @@ -0,0 +1,32 @@ +# Admin 客户模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/customers/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，客户与权限语义见 `../../../docs/business-index.md`、`docs/平台客户层级与权限契约.md`。 +- 客户主档、成员与角色归 `../iam/`，账号与登录标识归 `backend auth/`，资质文件归 `file/`；本模块只做客户视图、审核入口与客户级计费规则。 +- 后端只查 `iam/`（客户主档与审核）、`auth/`（登录标识）、`file/`（资质）、`firstleg/customerstatistics/`（运营统计）。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 客户列表、筛选与统计 | `pages/CustomersView.vue`；`customers` | `../iam/api/platformIam.ts`；`firstleg/customerstatistics/` | +| 企业审核入口 | `pages/CustomersView.vue`；`customers/reviews` 模式 | `iam/` 审核接口；资质 `file/` | +| 客户详情、计费规则与运营指标 | `pages/CustomerDetailView.vue`、`components/CustomerBillingRulesPanel.vue`、`components/CustomerOperatingMetricCard.vue`；`customers/:tenantId` | `iam/`、`firstleg/` | +| 海外仓阶梯费用 | `pages/OverseasStorageFeesView.vue`、`CustomerOverseasStorageFeePanel.vue`；`customers/overseas-storage-fees` | `overseasStorageFee.ts`、`overseasStorageFeeTiers.ts`；`lastleg-service/` | +| 客户箱规与计费主数据 | `components/CustomerBillingRulesPanel.vue` | `firstleg/` 箱规与计价主数据 | +| 详情浮层标题与密度 | `customerDialogTitle.ts`、`customerDensity.css` | 本地实现，按公共密度样式约束 | + +## 关键边界 + +- 公司联系电话只作企业联系信息，不修改管理员/成员登录手机号，也不要求跨企业唯一；编辑客户资料不提交账号手机号变更。 +- 审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可随资质包提交，也可在已有营业执照后单独补传或替换。 +- 客户列表属 `*:list` 权限，已含详情只读；写操作使用独立权限，前端守卫不替代服务端鉴权。 +- 平台仓库是公共主数据，不与客户绑定；客户筛选不得缩小仓库候选。 +- 长整型客户 ID 按字符串透传，不用内部 ID 作业务编号展示。 +- 海外仓阶梯费用按客户与仓库维度提交版本，金额与生效结果只认服务端返回。 + +## 验证 + +- 定向：`pnpm test src/modules/customers/<目标测试>`；审核必填或费用阶梯变更同时核对 `iam`/`lastleg-service` 合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/customs/AGENTS.md b/src/modules/customs/AGENTS.md new file mode 100644 index 00000000..e44521ee --- /dev/null +++ b/src/modules/customs/AGENTS.md @@ -0,0 +1,29 @@ +# Admin 历史报关模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/customs/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/CustomsCasesView.vue`、`api/platformCustoms.ts`、`types.ts`、`status.ts`：承载历史报关案件、清单、代理提交与报关行回执。 +- 后端归 `firstleg/customs/`（`ContainerCustomsService.java` 等），文件归 `file/`。 +- **不要与货柜详情里的“送柜报关”面板混淆**：整柜报关资料在 `../container-loading/components/ContainerCustomsPanel.vue`，本模块是历史案件入口。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 报关案件列表、状态与筛选 | `pages/CustomsCasesView.vue` | `api/platformCustoms.ts`；`firstleg/customs/` | +| 报关清单与代理提交 | 案件详情与提交动作 | `api/platformCustoms.ts` | +| 报关行回执与完成文件 | 详情附件区 | `file/` 的 `LOADING_LIST_CUSTOMS_RECEIPT`、`LOADING_LIST_CUSTOMS_RESULT` | +| 状态与中文文案 | `status.ts`、`types.ts` | 服务端状态机 | + +## 关键边界 + +- 报关源文件、回执与完成文件都是客户作用域，`businessId` 固定为装柜计划 ID；下载走鉴权入口。 +- 回执与完成文件必须满足整柜完成与可见性条件，前端不自行放宽或绕过。 +- 提交给报关行后案件进入只读确认流程；打回、补资料等状态以服务端为准，不在前端改状态。 +- 与货柜页签共用同一后端能力时，只改一处展示，不要复制业务规则。 + +## 验证 + +- 定向：`pnpm test src/modules/customs/<目标测试>`；文件或状态变化同时核对 `firstleg/customs/` 与 `file/` 的报关合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/dashboard/AGENTS.md b/src/modules/dashboard/AGENTS.md new file mode 100644 index 00000000..35d7ff72 --- /dev/null +++ b/src/modules/dashboard/AGENTS.md @@ -0,0 +1,26 @@ +# Admin 工作台模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/dashboard/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/DashboardView.vue` 与 `api/dashboard.ts`；指标口径与实时/缓存边界见工作区 `docs/首页数据看板真实化与统计策略规划.md`。 +- 后端查 `firstleg/` 的 `firstleg/dashboard/PlatformDashboardMetricsController.java`；自营经营总览是另一个入口（`../self-operated/`），不要混。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 首页指标卡片与趋势 | `pages/DashboardView.vue`；根路径默认页 | `api/dashboard.ts`；`firstleg/dashboard/` | +| 指标筛选与刷新 | 页面顶部筛选 | `api/dashboard.ts`；服务端统计口径 | + +## 关键边界 + +- 指标只展示服务端结果，前端不二次汇总或补算同比/环比。 +- 缓存与实时口径按统计策略文档执行，不在页面自行加轮询或本地缓存。 +- 自营经营总览（领星数据）不进入本模块，走 `../self-operated/AGENTS.md`。 +- 指标下钻跳转要带明确业务筛选条件，不用指标名称反推业务状态。 + +## 验证 + +- 定向：`pnpm test src/modules/dashboard/<目标测试>`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/dimension-config/AGENTS.md b/src/modules/dimension-config/AGENTS.md new file mode 100644 index 00000000..57b9a5d1 --- /dev/null +++ b/src/modules/dimension-config/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 尺寸配置模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/dimension-config/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 本模块**没有页面**，只有 `api.ts`、`types.ts`、`index.ts`：它是客户四档箱规与尺寸系数的数据层，由 `../inbounds/`（测量）和 `../customers/`（客户计费规则）消费。 +- 后端只查 `firstleg/` 的 `CustomerDimensionConfigService.java`、`CustomerDimensionWeightingService.java`。 + +## 页面与入口 + +| 目标 | 入口 | API 与后端 | +|---|---|---| +| 客户箱规配置与四档尺寸 | `api.ts`、`types.ts` | `firstleg/service/CustomerDimensionConfigService.java` | +| 尺寸系数与默认权重算法 | `api.ts` | `firstleg/service/CustomerDimensionWeightingService.java` | +| 模块对外导出 | `index.ts` | 供 `../inbounds/`、`../customers/` 引用 | + +## 关键边界 + +- 客户固定四档箱规，默认计算方式为 `ADD/MULTIPLY`；不要在调用方重写算法或补默认档位。 +- 新建客户时的箱规与权重系数初始化由 IAM 建档流程触发（`iam/` 的初始化服务 + Firstleg 内部接口），本模块只提供查询与保存入口。 +- 尺寸单位固定为厘米，体积由服务端计算；页面与调用方不自行换算。 +- 改类型或字段时同步检查 `../inbounds/`、`../customers/` 两个消费方与 Firstleg 合同测试。 + +## 验证 + +- 定向：`pnpm test src/modules/dimension-config/<目标测试>`；字段变化同时核对两个消费方。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/domestic-containers/AGENTS.md b/src/modules/domestic-containers/AGENTS.md new file mode 100644 index 00000000..65fc7251 --- /dev/null +++ b/src/modules/domestic-containers/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 国内整柜模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/domestic-containers/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 页面：`pages/DomesticContainersView.vue`（整柜业务列表）与 `pages/DomesticContainerInventoryDetailView.vue`（库存详情）；接口 `api/domesticContainers.ts`。 +- 后端归 `warehouse/domesticcontainer/`（`PlatformDomesticContainerController.java`、`DomesticContainerService.java`）。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 整柜入库、出库与库存列表 | `pages/DomesticContainersView.vue`；`domestic-containers` | `api/domesticContainers.ts`；`warehouse/domesticcontainer/` | +| 整柜库存快照与不可变交易记录 | `pages/DomesticContainerInventoryDetailView.vue`；`domestic-containers/inventories/:inventoryId` | `api/domesticContainers.ts` | +| 汇总样式 | `pages/domesticContainersSummary.css` | 本地样式，按公共密度规范接入 | + +## 关键边界 + +- 库存数量与交易记录只读展示服务端快照，不做前端加减或重算。 +- 出入库交易是追加式不可变记录，不提供编辑或删除入口。 +- 与货柜履约（`../container-loading/`）的柜次是不同概念：本模块是国内仓整柜库存业务，不承担装柜与订舱。 +- 权限统一 `platform:domestic-container:list`，写操作按独立权限。 + +## 验证 + +- 定向：`pnpm test src/modules/domestic-containers/<目标测试>`；字段变化同时核对 `domestic-container-v1.yaml`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/downloads/AGENTS.md b/src/modules/downloads/AGENTS.md new file mode 100644 index 00000000..5b644ac0 --- /dev/null +++ b/src/modules/downloads/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 下载中心模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/downloads/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/DownloadCenterView.vue`、`useExportTask.ts`、`api/platformExportTasks.ts`；所有业务导出都走这一套。 +- 后端归 `file/`（`PlatformExportTaskController`、`ExportTaskService`、`ExportStateService`、`ExportDefinitionRegistry`），实际取数由各业务服务的 Provider 分批提供。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 导出任务列表、下载与失败重试 | `pages/DownloadCenterView.vue` | `api/platformExportTasks.ts`；`file/` | +| 业务页面创建导出任务 | `useExportTask.ts`（供其他模块调用） | `api/platformExportTasks.ts` | +| 自动退避与重试状态 | 任务行 `attemptCount/maxAttempts/nextRetryAt` | `file/` `ExportStateService` | + +## 关键边界 + +- 业务页面只创建异步任务，不直接拼装文件，也不直连 Provider。 +- 重试只允许 `FAILED`，或 `PENDING` 且已有失败尝试、正在等待自动退避的任务；`RUNNING`、初次等待、已成功或已过期任务拒绝重试。 +- 导出类型必须在 `ExportDefinitionRegistry` 登记；新增类型同步检查业务 Provider、权限、页面标签与重试映射。 +- 下载链接走鉴权接口，不缓存为公共地址；导出文件不进入浏览器本地持久化。 + +## 验证 + +- 定向：`pnpm test src/modules/downloads/<目标测试>`；导出类型变化同时核对 `file/` 的 Provider 契约与业务服务 Provider。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/fba-pricing/AGENTS.md b/src/modules/fba-pricing/AGENTS.md new file mode 100644 index 00000000..36c92691 --- /dev/null +++ b/src/modules/fba-pricing/AGENTS.md @@ -0,0 +1,29 @@ +# Admin FBA 价格簿模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/fba-pricing/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 子域：`carrier-rates/`（客户专属价格簿、柜级阶梯运费、上传与确认）、`customer-rules/`（客户计费规则）；各自有页面与 API。 +- 后端归 `firstleg/`（`FbaPricingService.java`、`PlatformPriceBookService.java`、`firstleg/pricing/ContainerTierAmountAllocator.java`）；计费消费方见 `../inbounds/`。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 客户专属价格簿列表、上传与确认 | `carrier-rates/pages/CarrierRatesView.vue` | `carrier-rates/api/platformPriceBooks.ts`；`firstleg/PlatformPriceBookService` | +| 价格版本详情、仓库映射与只读价格行 | `carrier-rates/pages/CarrierRateDetailView.vue` | 同上 | +| 客户计费规则 | `customer-rules/api.ts` | `firstleg/` 箱规与计价主数据 | +| 对外导出 | `public.ts` | — | + +## 关键边界 + +- 价格簿页面必须显式选择公共报价或具体客户；列表、上传、确认只作用于该 `customerId`，不混版本。 +- 计价优先客户专属 ACTIVE 版本，无专属才回退公共 ACTIVE；柜级阶梯金额与分摊只展示服务端结果。 +- 调整计费量只能在服务端允许区间内，并提交当前费用版本、原因与二次确认。 +- 上传后按 `versionId` 进入独立详情页，价格行只读；确认动作不可逆，需二次确认。 +- 私人仓尾程派送费使用稳定代码，只对 `PRIVATE` 目的地开放；一件代发须在预装确认前完成试算。 + +## 验证 + +- 定向：`pnpm test src/modules/fba-pricing/<目标测试>`；价格字段变化同时核对 `fba-pricing-v1.yaml` 与 `../inbounds/` 计费消费。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/fee-items/AGENTS.md b/src/modules/fee-items/AGENTS.md new file mode 100644 index 00000000..0d901493 --- /dev/null +++ b/src/modules/fee-items/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 费用项目模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/fee-items/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有一个页面 `pages/FeeItemsView.vue`（路由 `master-data/fee-items`，挂在系统主数据下）和一个接口文件 `api/platformFeeItems.ts`；弹框实现与页面同目录。 +- 后端只查 `firstleg/` 的费用项目与价格簿入口；客户作用域价格归 `../fba-pricing/`，不要混。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 费用项目列表、启停与排序 | `pages/FeeItemsView.vue`；`master-data/fee-items` | `api/platformFeeItems.ts`；`firstleg/controller/PlatformFeeItemController.java` | +| 新增/编辑费用项目弹框 | `pages/FeeItemsView.vue` 内弹框 | `api/platformFeeItems.ts` | +| 默认价格与计费科目 | 列表“默认价格”列 | `api/platformFeeItems.ts`；服务端仍是价格权威 | + +## 关键边界 + +- 费用项目编码与类型是不可变标识，改名不影响历史账单；不要用名称推断科目。 +- 默认价格只是新建费用时的初值，实际计费以服务端价格簿为准，页面不参与金额计算。 +- 停用费用项目不回溯已出账费用；历史账单继续显示原项目名称快照。 +- 供应商类别仅对需要供应商的费用类型有效，留空表示任意启用供应商，不由前端补默认值。 + +## 验证 + +- 定向：`pnpm test src/modules/fee-items/<目标测试>`；字段或权限变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/first-leg-orders/AGENTS.md b/src/modules/first-leg-orders/AGENTS.md new file mode 100644 index 00000000..666197f2 --- /dev/null +++ b/src/modules/first-leg-orders/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 头程订单接口模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/first-leg-orders/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 本模块**没有页面**，只有 `index.ts` 与 `api/platformFirstLegOrders.ts`，提供旧版头程订单列表与客户订单统计接口的封装；新页面统一在 `../unified-orders/`。 +- 后端查 `order/`（`/platform/v1/orders/first-leg`、客户订单统计）。 + +## 页面与入口 + +| 目标 | 入口 | API 与后端 | +|---|---|---| +| 旧版头程订单分页查询 | `api/platformFirstLegOrders.ts` 的 `listPlatformFirstLegOrders` | `order/` | +| 客户维度订单统计 | `api/platformFirstLegOrders.ts` 的 `getPlatformTenantOrderStatistics` | `order/` | +| 对外导出 | `index.ts` | — | + +## 关键边界 + +- 新增订单页面与交互一律进 `../unified-orders/`，不要在本模块长页面。 +- 本模块只做请求封装，不承载业务规则、状态判断或权限逻辑。 +- 客户统计的客户范围由服务端认证上下文决定，前端只传客户 ID。 +- 若确认无调用方，按当前无兼容原则直接删除，不保留别名或兼容分支。 + +## 验证 + +- 定向：`pnpm test src/modules/first-leg-orders/<目标测试>`；改签名前用 `rg` 确认全部调用方。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/iam/AGENTS.md b/src/modules/iam/AGENTS.md new file mode 100644 index 00000000..bcbc0aab --- /dev/null +++ b/src/modules/iam/AGENTS.md @@ -0,0 +1,32 @@ +# Admin 平台用户与权限模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/iam/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，权限语义见 `../../../docs/平台客户层级与权限契约.md`。 +- 本模块是**平台侧**用户、角色与权限资源维护入口；客户侧成员与角色归 `backend iam/`，账号与登录标识归 `backend auth/`，前端守卫在 `../core/access/`。 +- 后端只查 `iam/`（平台 RBAC、菜单资源、客户与成员）与 `auth/`（账号与会话撤销）。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 平台用户列表、PDA 人员与海外仓绑定 | `pages/InternalUsersView.vue`；`system/users` | `api/platformIam.ts`；`iam/`、`auth/` | +| 角色与角色成员 | `pages/RolesView.vue`；`system/roles` | `api/platformIam.ts`；`iam/` | +| 权限资源与菜单 | `pages/PermissionsView.vue`、`utils/permissionTree.ts`；`system/permissions` | `api/platformIam.ts`；`iam/` 菜单资源 | +| 客户作用域选择器 | `components/PlatformTenantSelector.vue` | `iam/` 客户主档 | +| 权限判定与展示 | `utils/platformPermission.ts`、`../core/access/` | 服务端权限快照；前端不替代鉴权 | +| 模块密度样式 | `iamDensity.css` | 按公共密度规范接入 | + +## 关键边界 + +- 平台用户选择 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 时必须选择唯一实际海外收货仓；其他角色不得提交 `overseasWarehouseId`；编辑时保留已绑定仓库，长整型 ID 按字符串透传。 +- 国内 `CN_FIRSTLEG_PDA_OPERATOR` 与海外 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 互斥；候选来自国内 Warehouse 平台仓库 API 的公共 `OVERSEAS + ACTIVE + RECEIVING` 收货仓。 +- 列表权限 `*:list` 同时授权列表与详情只读；`create`、`edit`、`delete`、`status`、`approve` 等保持独立，不保留旧 `*:view`。 +- 供应商固定使用 `platform:supplier:list`；`platform:supplier:view` 不得重新启用以兼容旧调用。 +- 菜单、路由与权限资源三处必须同步：改权限码时同时核对 Controller `@PreAuthorize`、OpenAPI、模块权限 SQL 与菜单资源。 +- 前端守卫只改善体验，服务端必须重复校验租户、角色与数据范围。 + +## 验证 + +- 定向：`pnpm test src/modules/iam/<目标测试>`；权限码或菜单资源变更同时核对 `iam` 菜单 SQL 与权限契约测试。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/inbounds/AGENTS.md b/src/modules/inbounds/AGENTS.md new file mode 100644 index 00000000..fb2f84e7 --- /dev/null +++ b/src/modules/inbounds/AGENTS.md @@ -0,0 +1,32 @@ +# Admin 入库模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/inbounds/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，字段与计费细则见 `../../../docs/business-index.md`。 +- 模块按子域分目录：`measurement/`（测量）、`review/`（测量审核）、`weight/`（称重与 OCR）、`fee/`（费用与人工定价）、`core/`（入库单公共）。先定子域再进文件。 +- 后端只查 `firstleg/`（测量、审核、计价、扣货、称重库位）与 `warehouse/`（库位）；纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/子域入口 | API 与后端 | +|---|---|---| +| 订单测量列表与工作区 | `pages/InboundMeasurementsView.vue`、`components/InboundWorkflowWorkspace.vue`；`inbounds/measurements` | `measurement/api.ts`；`firstleg/service/InboundMeasurementService.java` | +| 测量弹框、测量面板、尺寸策略与证据图 | `measurement/InboundMeasurementDialog.vue`（组合壳）、`measurement/InboundMeasurementPanel.vue`（数据与操作）、`measurement/components/MeasurementEvidenceThumbnail.vue` | 实际请求在 `measurement/InboundMeasurementPanel.vue` → `measurement/api.ts`；弹框只组合面板与 OCR 面板，不直接调接口；`firstleg/service/MojiaMeasurementOpenApiService.java` | +| 测量数据审核 | `pages/MeasurementReviewsView.vue`、`review/MeasurementReviewPanel.vue`；`inbounds/measurement-reviews` | `review/api.ts`；`firstleg/service/MeasurementReviewService.java`、`firstleg/service/InitialInboundPricingService.java` | +| 称重图片、OCR 与库位槽状态 | `weight/components/WeightOcrPanel.vue`、`weight/components/WeightImageThumbnail.vue` | `weight/api/weightOcr.ts`；`firstleg/service/MeasurementLocationOccupationService.java`、`firstleg/service/MeasurementSubmissionService.java` | +| 入库单列表、摘要与历史 | `pages/InboundOrdersView.vue`、`core/InboundSummaryPanel.vue`、`core/InboundHistoryPanel.vue`；`inbounds` | `core/api.ts`、`core/types.ts`；`firstleg/service/InboundOrderQueryService.java` | +| FBA 人工定价（无匹配价格） | `fee/InboundFeePanel.vue` | `fee/api.ts` 的 `/manual-quote`；`firstleg/service/FbaPricingService.java` | +| 一件代发托盘打印 | `core/DropshipPalletPrintPanel.vue` | `core/api.ts`；`print/`；仅一件代发订单展示 | + +## 关键边界 + +- 客户固定四档箱规，默认计算方式为 `ADD/MULTIPLY`；保存后以外箱尺寸、体积重和计费基数只认服务端返回值，页面不独立重算。 +- 费用确认的实际箱数、毛重和体积优先汇总当前 `actualMeasurementRows`，不得用可能滞后的工作区顶层合计覆盖明细。 +- 称重卡片只展示服务端 `locationCode/slotStatus/sharedOverflow`，不渲染或推导整票预留引导；删除图片须提示该槽位仍归本票保留，不按图片下标推导托盘或库位。 +- 人工定价仅 FBA、已有实际测量且价格未命中时开放，客户已确认费用禁止改价；`MANUAL_QUOTE` 不伪造价格簿关联。 +- 扣货与解除、凭证下载走 `../unified-orders/` 与 `../inbounds/` 的正式入口，本模块不另建凭证链路。 + +## 验证 + +- 定向：`pnpm test src/modules/inbounds/<目标测试>`；计费或库位相关变更同时核对 `firstleg` 对应合同测试。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/loading-lists/AGENTS.md b/src/modules/loading-lists/AGENTS.md new file mode 100644 index 00000000..ad0e0a6e --- /dev/null +++ b/src/modules/loading-lists/AGENTS.md @@ -0,0 +1,31 @@ +# Admin 装柜清单模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/loading-lists/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，页面/接口细则见 `../../../docs/business-index.md`。 +- 预装清单与正式装柜清单是两条链路：`loading-plans` 为预装，`loading-lists` 为装柜清单；改前先确认当前页面属于哪条。 +- 后端只查 `firstleg/`（`LoadingListService`、`split/` 预装、`loading/`）与 `print/`（托盘标、单据）；纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 预装清单列表 | `pages/PreloadPlansView.vue`（列表主体在 `components/LoadingListsView.vue`）；`loading-plans` | 请求在 `components/LoadingListsView.vue` → `api/platformLoadingLists.ts`；`firstleg/split/` | +| 预装清单详情、生命周期、真实柜号补录 | `pages/PreloadPlanDetailView.vue`；`loading-plans/:planId` | `/loading-plans/{planId}/lifecycle`；`firstleg/service/LoadingListService.java` | +| 装柜清单列表 | `pages/ConfirmedLoadingListsView.vue`、`components/LoadingListsView.vue`；`loading-lists` | `api/platformLoadingLists.ts` | +| 装柜清单详情、摘要、明细、历史与单据打印 | `pages/ConfirmedLoadingListDetailView.vue`、`components/LoadingListDetailDrawer.vue`；`loading-lists/:planId` | 单据打印走 `printLoadingList.ts`（详情页带 `?print=1` 时触发）；列表数据 `api/platformLoadingLists.ts`；模板归 `print/` | +| 柜级公共费用创建、审核、分摊与作废 | `components/ContainerFeesPanel.vue` | `api/containerFees.ts`；`firstleg/` 柜费来源、`finance/` | +| 散货托盘码打印 | `components/PalletLabelPrintDialog.vue` | `api/platformLoadingLists.ts` 的 `/pallet-labels/prepare`、`/pallet-labels/print`；`print/` | + +## 关键边界 + +- 预装详情进入后先调 `/loading-plans/{planId}/lifecycle`，再按返回状态决定可操作项；不自行推断生命周期阶段。 +- 托盘码格式为“真实柜号-FBA 地址内部编号-三位序号”，清单只取服务端按 FBA 仓分组的冻结结果，前端不生成、不改码、不重新编号；一件代发托盘不进入该清单。 +- 确认预装和创建 PDA 任务前必须补齐真实集装箱号；历史上已建缺号任务可在预装详情首次补录，保存后恢复 PDA 可进入状态。 +- 柜级公共费用只按服务端柜内客户/订单事实分摊，创建、审核、驳回、调整、作废均整组原子，金额必须守恒；待确认时禁止调整或重复作废。 +- 独立清单详情与货柜详情页签共用同一套清单 API 与详情组件；改展示或打印时同步检查 `container-loading` 的装柜清单页签。 + +## 验证 + +- 定向：`pnpm test src/modules/loading-lists/<目标测试>`；`container-loading` 页签相关变更同时跑该模块测试。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/master-data/AGENTS.md b/src/modules/master-data/AGENTS.md new file mode 100644 index 00000000..ab38c121 --- /dev/null +++ b/src/modules/master-data/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 主数据模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/master-data/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 子域分目录：`counterparties/`（往来单位）、`express-companies/`（快递公司），各自有页面与 API。 +- 后端都归 `warehouse/`（`PlatformPartnerController`、`PlatformExpressCompanyController`、`PartnerImportService`）；供应商不在此处，见 `../suppliers/`。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 往来单位列表、导入与启停 | `counterparties/pages/PartnersView.vue` | `counterparties/api/platformPartners.ts`；`warehouse/` | +| 快递公司列表与维护 | `express-companies/pages/ExpressCompaniesView.vue` | `express-companies/api/platformExpressCompanies.ts`；`warehouse/` | +| 导入模板与批量写入 | 往来单位导入入口 | `warehouse/PartnerImportService.java` | + +## 关键边界 + +- 往来单位与快递公司是平台公共主数据（`tenant_id=0`），不绑定客户。 +- 导入先全量校验再原子写入，逐行失败原因回填；不信任模板隐藏列。 +- 供应商（含 TRUCKING 国内/海外车队范围）归 `../suppliers/`，不要在本模块扩展供应商类别。 +- 停用往来单位不影响历史单据的名称快照。 + +## 验证 + +- 定向：`pnpm test src/modules/master-data/<目标测试>`；导入规则变化同时核对 `warehouse/` 的导入合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/notifications/AGENTS.md b/src/modules/notifications/AGENTS.md new file mode 100644 index 00000000..e6762060 --- /dev/null +++ b/src/modules/notifications/AGENTS.md @@ -0,0 +1,29 @@ +# Admin 消息中心模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/notifications/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 消息中心只在顶部入口，不进入左侧菜单；模板维护在系统设置下，两者共用同一套通知契约。 +- 后端只查 `iam/` 的 `notification/` 子域；不读其他服务。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 消息收件箱与已读 | `pages/PlatformNotificationsView.vue`；`notifications` | `api/notificationCenter.ts`；`iam/` notification | +| 消息管理（发送与记录） | `pages/MessageManagementView.vue`、`components/MessageComposerDialog.vue`；`notifications/messages` | `api/notificationCenter.ts`；`iam/` notification | +| 消息模板维护 | `pages/MessageTemplatesView.vue`、`components/TemplateEditorDialog.vue`；`notifications/templates` | `api/notificationCenter.ts`；`iam/` notification | +| 展示文案与类型映射 | `presentation.ts`、`types.ts` | 服务端模板变量 | + +## 关键边界 + +- 消息只展示服务端返回的业务文案与业务编号，不把内部数据库 ID 作为标题或链接参数回退。 +- 模板变量必须来自服务端模板定义，前端不硬编码业务字段名或补默认值。 +- 发送类操作需要确认、处理中与失败反馈；失败保留用户输入，不静默清空草稿。 +- 未读计数与已读状态以服务端为准，不在本地累加或乐观改写后不回读。 +- 顶部入口不擅自扩展到左侧菜单，也不为单条消息新增独立路由页。 + +## 验证 + +- 定向：`pnpm test src/modules/notifications/<目标测试>`；模板变量或发送字段变更同时核对 `iam` 通知契约。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/ocean-bookings/AGENTS.md b/src/modules/ocean-bookings/AGENTS.md new file mode 100644 index 00000000..ed8ebddd --- /dev/null +++ b/src/modules/ocean-bookings/AGENTS.md @@ -0,0 +1,32 @@ +# Admin 订舱模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/ocean-bookings/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，订舱与船期细则见 `../../../docs/business-index.md`。 +- 订舱（本模块）与预装/装柜清单（`../loading-lists/`）、船节点（`../port-schedules/`）是三条链路；本模块只管订舱资料、放舱状态与订舱级船期。 +- 后端只查 `firstleg/` 的 `oceanbooking/`、`portschedule/` 与 `print/`（订舱单据）、`file/`（附件）。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 订舱列表、放舱状态与关联候选 | `pages/OceanBookingsView.vue`；`ocean-bookings` | `api/platformOceanBookings.ts`；`firstleg/oceanbooking/` | +| 新增订舱（登记线下已确认订舱） | `pages/OceanBookingDetailView.vue`；`ocean-bookings/new` | `api/platformOceanBookings.ts` | +| 订舱详情、资料维护与版本 | `pages/OceanBookingDetailView.vue`；`ocean-bookings/:bookingId` | `api/platformOceanBookings.ts` | +| 订舱资料面板与字段边界 | `components/OceanBookingDocumentsPanel.vue` | `firstleg/oceanbooking/`；附件归 `file/` | +| 订舱资料打印 | `components/OceanBookingPrintDialog.vue` | `print/` 单据模板 | +| 柜型需求与数量换算 | `containerRequirements.ts` | `containerCount` 为柜型需求 `quantity` 总和 | +| 订舱代理候选 | `bookingAgents.ts` | 公共供应商列表，仅 `ACTIVE` 且类别/范围匹配 | + +## 关键边界 + +- 订舱草稿按当前版本维护资料；放舱后资料与表单只读，不允许绕过版本直接改字段。 +- 打印对草稿与已放舱订舱均开放，按当前**已保存**资料生成，未填写字段显示“—”，不用未保存的表单值。 +- 关联候选只消费服务端 `/link-candidates` 分页结果，不在浏览器重排或本地拼接候选。 +- 订舱是拖车预约的唯一归属：拖车由 `../trucking/` 创建，本模块不直接建拖车单。 +- 出仓前船期只展示订舱级计划，实际节点归 `../port-schedules/` 与海外回写，本模块不写实际时间。 + +## 验证 + +- 定向：`pnpm test src/modules/ocean-bookings/<目标测试>`；资料字段或打印变更同时核对 `print/` 模板与 `file/` 附件契约。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/outbound-dispatch/AGENTS.md b/src/modules/outbound-dispatch/AGENTS.md new file mode 100644 index 00000000..35e1d5e0 --- /dev/null +++ b/src/modules/outbound-dispatch/AGENTS.md @@ -0,0 +1,28 @@ +# Admin 国内出仓模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/outbound-dispatch/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/OutboundDispatchesView.vue`、`api/platformOutboundDispatch.ts`、`statusLabels.ts`：维护国内出仓状态（确认出仓 / 撤销出仓）。 +- 后端归 `firstleg/outbound/dispatch/`（`OutboundDispatchService.java`）。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 国内出仓列表、状态与筛选 | `pages/OutboundDispatchesView.vue` | `api/platformOutboundDispatch.ts`；`firstleg/outbound/dispatch/` | +| 确认国内出仓 | 行操作 `confirm-dispatch` | `changeOutboundDispatch`，提交 `inboundId`、`containerBookingId`、`expectedVersion`、`remark` | +| 撤销国内出仓 | 行操作 `reverse-dispatch` | 同上，需二次确认 | +| 状态中文文案 | `statusLabels.ts` | 服务端状态机 | + +## 关键边界 + +- 确认出仓前系统校验全部装柜门禁；前端不得逐入仓确认，也不得把拖车状态当阻断门禁。 +- 提交必须携带当前 `version`，冲突时重新读取，不覆盖他人操作。 +- 出仓以真实货柜为原子边界；成功后由服务端同事务推进技术行并幂等创建船节点查询，前端不重复追加实际船节点。 +- 与货柜详情里的“确认离仓”是同一能力的两个入口，改规则时同步检查 `../container-loading/`。 + +## 验证 + +- 定向：`pnpm test src/modules/outbound-dispatch/<目标测试>`；状态或门禁变化同时核对 `firstleg/` 出仓合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/overseas-business/AGENTS.md b/src/modules/overseas-business/AGENTS.md new file mode 100644 index 00000000..1df78962 --- /dev/null +++ b/src/modules/overseas-business/AGENTS.md @@ -0,0 +1,34 @@ +# Admin 海外业务模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/overseas-business/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，采购与本土业务细则见 `../../../docs/business-index.md`。 +- 三条业务线共用同一模块：`purchases`（海外采购）、`trucks`（本土卡车）、`looseboards`（本土散板）；`trucks` 与 `looseboards` 复用同一组页面，按路由区分模式。 +- 后端只查 `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`、`financefee/`；纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 海外采购订单列表与库存变化 | `pages/PurchaseOrdersView.vue`；`overseas-business/purchases` | `api/platformOverseasBusiness.ts`；`lastleg-service/procurement/` | +| 采购订单详情（商品、库存、订单、快递、进销存） | `pages/PurchaseOrderDetailView.vue`；`overseas-business/purchases/:purchaseId` | `api/platformOverseasBusiness.ts` | +| 采购订单编辑（采购商品、库存、快递） | `pages/PurchaseOrderEditView.vue`；`overseas-business/purchases/:purchaseId/edit` | `api/platformOverseasBusiness.ts`（`getOverseasPurchaseEditor`、`updateOverseasPurchase`） | +| 采购订单分区字段：管控、财务、节点、实物、运输 | `components/ProcurementControlFields.vue`、`ProcurementFinanceFields.vue`、`ProcurementNodeActions.vue`、`ProcurementPhysicalFields.vue`、`ProcurementTransportFields.vue` | `api/procurementCommands.ts`；节点动作与费用入池归 `lastleg-service/financefee/` | +| 采购订单分区字段：费用（纯展示，无请求） | `components/ProcurementChargeFields.vue` | 只接收 props，数据由详情页 `PurchaseOrderDetailView.vue` 提供 | +| 本土卡车订单列表 | `pages/TransportOrdersView.vue`；`overseas-business/trucks` | `api/platformOverseasBusiness.ts`；`lastleg-service/trucking/` | +| 本土卡车新增/编辑 | `pages/TransportOrderFormView.vue`；`overseas-business/trucks/new`、`overseas-business/trucks/:orderId/edit` | `api/platformOverseasBusiness.ts`；`components/TransportDemandForm.vue` | +| 本土散板订单列表与新增/编辑 | `pages/TransportOrdersView.vue`、`pages/TransportOrderFormView.vue`；`overseas-business/looseboards`、`.../new`、`.../:orderId/edit` | `api/platformOverseasBusiness.ts`；`lastleg-service/looseboard/` | +| 车次安排摘要 | `components/FleetArrangementSummary.vue` | 无直接请求；数据由 `fleetArrangement.ts` 与父页面传入 | + +## 关键边界 + +- 采购样品履约是一条独立链路：下单、包装、面单、交寄、国内核费、寄客户；改节点或费用前先读 `docs/海外仓业务/采购订单样品履约流程变更需求.md`，不套用普通头程或尾程流程。 +- 本土卡车与散板是海外本地运输业务，区别于国内订舱拖车与客户排车；车型、司机与车队主数据归 `overseas-master-data`，本模块只消费。 +- 采购费用入海外费用池后由 `finance/` 记账，本模块不判定收付状态，不重复写入费用行。 +- 列表与表单的客户、仓库、供应商候选一律取服务端结果，不从本地或名称推算；长整型 ID 按字符串透传。 +- 同一路由组件的两种模式（卡车/散板）变更时，两侧都要回归，避免只改一侧。 + +## 验证 + +- 定向：`pnpm test src/modules/overseas-business/<目标测试>`；采购命令或费用变更同时核对 `lastleg-service` 合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/pda-releases/AGENTS.md b/src/modules/pda-releases/AGENTS.md new file mode 100644 index 00000000..5b8b6b07 --- /dev/null +++ b/src/modules/pda-releases/AGENTS.md @@ -0,0 +1,27 @@ +# Admin PDA 版本发布模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/pda-releases/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/PdaReleasesView.vue` 与 `api/pdaReleases.ts`；上传草稿、发布与停发都在同一页。 +- 后端归 `file/`（`PdaReleaseController`、`PdaReleaseService`、`pda-releases-v1.yaml`），接口经 `/platform/v1/files/pda-releases`；设备端更新逻辑在两端 PDA 的 `app-update` 工具里。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 国内/海外 APK、WGT 版本列表与上传 | `pages/PdaReleasesView.vue` | `api/pdaReleases.ts`；`file/` | +| 发布与停发 | 列表行操作 | `api/pdaReleases.ts`；权限 `platform:pda-release:manage` | +| 匿名清单与包下载（设备侧） | 不在本页 | `file/` 匿名入口，只暴露当前已发布与历史未停发文件 | + +## 关键边界 + +- 上传只创建草稿，不自动发布；发布与停发必须二次确认，并展示影响端（国内/海外）。 +- 国内与海外按 `domestic/overseas` 分开查询与操作，AppID、包名、签名与版本序列不得混用。 +- 列表权限 `platform:pda-release:list`，上传/发布/停发权限 `platform:pda-release:manage`。 +- 停发只影响后续下载，不追回已安装设备；强更与 WGT 安装重启由设备端策略决定，本模块不越权。 + +## 验证 + +- 定向：`pnpm test src/modules/pda-releases/<目标测试>`；接口变化同时核对 `file/` 的 `pda-releases-v1.yaml`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/port-schedules/AGENTS.md b/src/modules/port-schedules/AGENTS.md new file mode 100644 index 00000000..42275ac2 --- /dev/null +++ b/src/modules/port-schedules/AGENTS.md @@ -0,0 +1,28 @@ +# Admin 船期节点模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/port-schedules/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，船节点标准见 `docs/海外仓业务/船节点标准化契约.md`（工作区路径）。 +- 船节点分两类：船公司船期**查询任务**与货柜**实际节点**；本模块维护两者，订舱资料归 `../ocean-bookings/`，码头拖车归 `../container-loading/`。 +- 后端只查 `firstleg/portschedule/`（查询、日历与节点事实）与 `integration-service/`（船司原始状态适配）。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 船期信息列表（组合下面两个面板） | `pages/PortSchedulesView.vue`；`port-schedules` | 页面本身只做壳层，接口在各面板 | +| 船公司船期查询任务 | `components/CarrierScheduleQueryPanel.vue` | `api/platformCarrierScheduleQueries.ts`、`api/platformContainerShippingNodes.ts`；`integration-service/` | +| 货柜实际节点与十节点展示 | `components/ContainerPortSchedulePanel.vue` | `api/platformPortSchedules.ts`；`firstleg/portschedule/` | + +## 关键边界 + +- 预计节点只展示，不推进实际进度；不得用预计到港替代实际节点或计划到仓。 +- 手工实际节点必须严格向后追加并防重复；已保存的人工节点不得回退柜级节点。 +- 十节点标准状态与命名按 `docs/海外仓业务/船节点标准化契约.md`，新增船司先按该契约接入标准化映射。 +- 装柜完成后的节点由服务端事件幂等创建；前端不重复追加实际船节点，也不把拖车状态当阻断门禁。 +- 船司原始状态与标准节点分离：页面只消费标准节点，不直接展示或判断船司原始字符串。 + +## 验证 + +- 定向：`pnpm test src/modules/port-schedules/<目标测试>`；节点语义变更同时核对 `firstleg` 船节点合同与标准化契约。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/sailing-calendar/AGENTS.md b/src/modules/sailing-calendar/AGENTS.md new file mode 100644 index 00000000..8e32d91f --- /dev/null +++ b/src/modules/sailing-calendar/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 船期日历模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/sailing-calendar/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/SailingCalendarView.vue`、`api/platformSailingCalendar.ts`、`types.ts`；规划背景见 `../../../docs/国内货柜履约/船期日历功能规划.md`。 +- 后端查 `firstleg/` 的船期与渠道能力；船节点实际时间归 `../port-schedules/`，本模块只管计划与模板。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 渠道、周模板与单次船期维护 | `pages/SailingCalendarView.vue` | `api/platformSailingCalendar.ts`；`firstleg/` 船期 | +| 收货截止时间 | 日历单元格与详情 | `api/platformSailingCalendar.ts` | +| 按渠道货量统计 | 日历侧栏 | `api/platformSailingCalendar.ts`；服务端统计 | + +## 关键边界 + +- 日历只表达计划船期，不推进货柜实际节点；实际开船、到港归 `../port-schedules/`。 +- 收货截止时间参与下单与装柜门禁，修改前确认是否已有在途订单引用该船期。 +- 渠道、周模板与单次船期三层结构不可互相覆盖：单次船期变更不回写周模板。 +- 货量统计按服务端渠道口径，不用柜量或订单数在前端换算。 + +## 验证 + +- 定向：`pnpm test src/modules/sailing-calendar/<目标测试>`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/self-operated/AGENTS.md b/src/modules/self-operated/AGENTS.md index 51e1f007..1e898871 100644 --- a/src/modules/self-operated/AGENTS.md +++ b/src/modules/self-operated/AGENTS.md @@ -3,7 +3,7 @@ - 模块入口 `routes.ts`；正式页面 `pages/OverviewView.vue`、`SalesView.vue`、`InventoryView.vue`、`CollectionView.vue`。根路由、导航、IAM 由总控装配。 - 文档路径从工作区根起算；本目录代码路径从当前模块起算。总览设计变更查 `docs/自营业务/经营总览图表设计.md`，采集页面变更查 `docs/自营业务/数据采集页面设计.md`；纯文案或局部代码定位不默认加载设计全文。 - `analyticsApi.dashboard` 独立于采集 `overview`。六项指标、日趋势、七桶和三榜共用一次服务端上下文；时间筛选统一影响区间出库、日均、日趋势、库存分布及三个榜单，热销按已采集量排名并标明覆盖不足，库存评估按所选区间完整销量及观察资格计算；库存数量仍取固定当前版本。`dashboardNavigation.ts` 校验下钻版本、日期、枚举、互斥条件和固定返回入口；库存严格下钻必须保留 `drilldownFrom=DASHBOARD` 并从原图上下文传递 CUSTOM 起止日期，不能混用普通库存的10／30日窗口，过期禁止冒充原图结果。经营总览不增加货主筛选或面板；销量、库存明细和库存周转支持按客户名称/编码选择货主，名称取 queryAsOf 时可见的完整领星资料批次，按账号+货主编码关联。 -- API 只经统一 `shared/api/http.ts` 消费 Lastleg 的平台自营统计合同；不得调用 Integration 或持有来源凭据。 +- API 只经统一 `../../shared/api/http.ts` 消费 Lastleg 的平台自营统计合同；不得调用 Integration 或持有来源凭据。 - 北京时间 `Asia/Shanghai`，每 SKU 件数 `PCS`；货主不合并同名 SKU。未知数量保留空值，库存可售天数只用服务端结果。 - 经营查询固定服务端版本和 queryAsOf；显式刷新/切仓重新取上下文，轮询只读运行状态。请求取消和世代校验共同防迟到响应。 - 任务编号仅用 taskNo，不以数据库 ID 回退。重试需独立 sync 权限与 allowedActions，沿 POST sync-tasks 的 RETRY 和 requestKey。 diff --git a/src/modules/suppliers/AGENTS.md b/src/modules/suppliers/AGENTS.md new file mode 100644 index 00000000..bee8fe02 --- /dev/null +++ b/src/modules/suppliers/AGENTS.md @@ -0,0 +1,30 @@ +# Admin 供应商模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/suppliers/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，供应商权限语义见 `../../../docs/平台客户层级与权限契约.md`。 +- 供应商是平台公共主数据（`tenant_id=0`），不按客户隔离；往来单位归 `../master-data/`，国内整柜归 `../domestic-containers/`。 +- 后端只查 `warehouse/`（公共往来单位与供应商主档）与 `file/`（资质附件）。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 供应商列表、类别与范围筛选 | `pages/SuppliersView.vue`；`suppliers` | `api/platformSuppliers.ts`；`warehouse/` 供应商主档 | +| 新增供应商 | `pages/SupplierFormView.vue`；`suppliers/new` | `api/platformSuppliers.ts` | +| 供应商详情 | `pages/SupplierDetailView.vue`；`suppliers/:id` | `api/platformSuppliers.ts` | +| 编辑供应商 | `pages/SupplierFormView.vue`；`suppliers/:id/edit` | `api/platformSuppliers.ts` | +| 资质与证照附件 | `components/SupplierLicenseDialog.vue` | `file/` | + +## 关键边界 + +- 供应商查询接口固定只使用 `platform:supplier:list`；`platform:supplier:view` 必须保持停用/移除，不得为兼容旧调用重新提升。 +- 订舱代理、拖车承运商、报关代理与海外车队都从公共供应商列表选择 `ACTIVE` 且类别/范围匹配的记录；提交服务端供应商 ID，不提交名称或本地推断。 +- 供应商是平台公共主数据，不绑定客户；客户筛选不得缩小供应商候选。 +- 停用、改类别或改范围属高风险操作，必须确认与结果反馈；失败保留用户上下文。 +- 资质附件归 `file/` 的平台作用域，不写入客户文件路径。 + +## 验证 + +- 定向：`pnpm test src/modules/suppliers/<目标测试>`；权限码或类别枚举变更同时核对 `warehouse` 供应商合同与权限初始化 SQL。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/trucking/AGENTS.md b/src/modules/trucking/AGENTS.md new file mode 100644 index 00000000..c306f66a --- /dev/null +++ b/src/modules/trucking/AGENTS.md @@ -0,0 +1,29 @@ +# Admin 拖车模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/trucking/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，订舱级拖车细则见 `../../../docs/business-index.md`。 +- 本模块只做**订舱级拖车预约**，与目的港码头拖车（`../container-loading/api/terminalDrayages.ts`）是不同生命周期；改前先确认属于哪一类。 +- 后端只查 `firstleg/` 的 `firstleg/service/TruckAppointmentService.java` 与 `firstleg/openapi/truck-appointments-v1.yaml`；附件归 `file/`。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 拖车预约列表、状态与筛选 | `pages/TruckAppointmentsView.vue`；`trucking` | `api/platformTrucking.ts`；`firstleg/service/TruckAppointmentService.java` | +| 新建拖车预约、订舱候选 | `pages/TruckAppointmentCreateView.vue`、`components/TruckAppointmentForm.vue`；`trucking/new` | `api/platformTrucking.ts` 的 `/candidates` | +| 预约详情、附件与承运商 | `pages/TruckAppointmentDetailView.vue`、`components/TruckAttachmentDialog.vue`；`trucking/:id` | `api/platformTrucking.ts`；附件 `file/` | +| 集装箱号校验 | `iso6346.ts` | 本地格式校验，服务端仍复核 | + +## 关键边界 + +- 表单只选择服务端返回的 `RELEASED` 订舱与 `TRUCKING + truckingScope=DOMESTIC` 国内拖车供应商；不选择或提交客户、柜次、装柜计划或真实集装箱号。 +- 一个订舱最多一张非终态拖车单；重复创建时转入现有单继续编辑，不新建第二张。 +- 提单号和仓库由订舱冻结事实带入，表单不自行拼接或改写。 +- PDA 完成装柜不自动推进拖车状态；拖车生命周期与 PDA 任务解耦。 +- 附件为平台作用域，不重复上传提单文件；清关提柜固定选择 `OVERSEAS` 海外车队，类型在供应商主档单选维护。 + +## 验证 + +- 定向：`pnpm test src/modules/trucking/<目标测试>`；表单字段或状态链变更同时核对 `truck-appointments-v1.yaml`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/unified-orders/AGENTS.md b/src/modules/unified-orders/AGENTS.md new file mode 100644 index 00000000..fc6ca3e8 --- /dev/null +++ b/src/modules/unified-orders/AGENTS.md @@ -0,0 +1,36 @@ +# Admin 统一订单模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/unified-orders/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，状态与申报细则见 `../../../docs/business-index.md`。 +- 三个路由（`orders`、`orders/inbound/:inboundCode`、`orders/:orderId`）共用 `pages/UnifiedOrdersView.vue`；列表、详情、弹框的区别靠路由与内部状态，不在页面外再拆。 +- 后端只查 `order/`（状态、申报、批量审核）、`firstleg/`（扣货、合柜、入库费用、智能装柜）与 `file/`；纯展示与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 订单列表、筛选、详情与商品图片 | `pages/UnifiedOrdersView.vue`；`orders`、`orders/:orderId`、`orders/inbound/:inboundCode` | `api/unifiedOrders.ts`；`order/` 的 `UnifiedOrderQueryService.java`；图片归 `file/` | +| 批量审核预览 | 列表内批量审核弹框 | `api/unifiedOrders.ts` 的 `/orders/first-leg/batch-review-preview`；`order/service/BatchOrderReviewPreviewService.java` | +| 客户原始申报编辑与渠道变更 | `components/OrderDeclarationEditorDialog.vue` | `api/unifiedOrders.ts`；`order/service/OrderDeclarationUpdateService.java` → `firstleg/service/OrderDeclarationSyncService.java` | +| 履约进度与明细树 | `components/OrderFulfillmentTreePanel.vue` | `api/orderFulfillment.ts`；`firstleg/` 履约投影 | +| 入库扣货、解除与凭证历史 | 列表与详情动作 | `../inbounds/core/api.ts`；`firstleg/service/InboundHoldService.java`、`firstleg/service/InboundHoldGuard.java`、`firstleg/service/InboundHoldEvidenceService.java`；凭证归 `file/` | +| 合柜报关、同柜不可拆组 | `api/coLoadGroups.ts`；装柜消费 `../container-loading/` | `firstleg/loading/coload/service/ColoadGroupService.java`；整组原子分配/移除/取消 | +| 入库费用明细与人工调整 | `components/InboundFeeDetailManager.vue` | `api/inboundFeeDetails.ts`；`firstleg/service/InboundFeeDetailService.java` | +| 一件代发托盘打印 | 详情“托盘打印”页签 | `../inbounds/core/DropshipPalletPrintPanel.vue`；`print/` | + +`workflows/` 存放统一订单工作流页与面板（`workflows/pages/UnifiedOrderWorkflowView.vue`、`workflows/components/UnifiedOrderWorkflowPanel.vue`、`SmartLoadingWorkbench.vue`），路由装配以 `routes.ts` 与 `../../app/router/index.ts` 为准，改前先确认是否已注册。 + +## 关键边界 + +- 申报编辑按订单版本与货物 `itemNo` 整体提交，不允许增删货物行；只改客户申报快照，不覆盖仓库/PDA 实测、测量审核或计费事实；渠道变化需二次确认。 +- Order 状态为 `SUBMITTED` 时列表必须保持 `PENDING_REVIEW/APPROVE_ORDER`，不得被已存在的 Firstleg 准备中入库投影覆盖。 +- 批量审核弹框一次取回全部预览，按服务端 `canApprove/blockReason` 展示，不逐票请求详情，不用内部 ID 作标题。 +- 扣货与解除只消费服务端 `holdFlag/currentHoldReason/canHold/canRelease/actionBlockReason/history`，提交当前版本、幂等键与必填原因；凭证下载只走授权入口。 +- 同柜成员数是入仓片段数，不等于订单票数；只要求同国内仓、同渠道，允许跨客户与不同目的仓港。 +- 入库费用实际、冻结与调整只显示服务端结果；计费量调整不得超出服务端允许区间。 + +## 验证 + +- 定向：`pnpm test src/modules/unified-orders/<目标测试>`；申报、合柜、扣货变更同时核对 `order`/`firstleg` 对应合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/warehouse-resources/AGENTS.md b/src/modules/warehouse-resources/AGENTS.md new file mode 100644 index 00000000..19daef16 --- /dev/null +++ b/src/modules/warehouse-resources/AGENTS.md @@ -0,0 +1,28 @@ +# Admin 仓储资源模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/warehouse-resources/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 模块按子域分目录：`locations/`（库位）、`pallets/`（托盘），各自有页面与 API；先定子域再看文件。 +- 后端分两处：国内库位/托盘归 `warehouse/`，海外库位/托盘归 `warehouse-overseas-service/`；按当前页面仓库类型判断读哪个。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 库位列表、编码、类型与启停 | `locations/pages/LocationsView.vue` | `locations/api/platformLocations.ts`；`warehouse/`（国内）、`warehouse-overseas-service/`（海外） | +| 托盘列表、状态与批量操作 | `pallets/pages/PalletsView.vue` | `pallets/api/platformPallets.ts`；同上 | +| 托盘/库位打印入口 | 托盘行操作 | 打印模板归 `print/` | + +## 关键边界 + +- 海外库位与托盘是公共资源（`customer_id=0`），平台接口不接收目标客户参数；资源锁仍按真实客户隔离。 +- `A0/SHARED_OVERFLOW`、`VIRTUAL` 由服务端事实保护，不能按普通库位编辑、停用或删除。 +- 可预留托盘必须 `IDLE` 且绑定库位为 `VIRTUAL + ACTIVE` 或真实库位 `IDLE`；前端只展示服务端 `reservable` 与阻断原因。 +- 托盘标不得回退到 100×100 mm 箱唛模板；模板只在 `print/` 维护。 +- 本模块只做资源主数据维护，不做排车、出库或派送的资源分配。 + +## 验证 + +- 定向：`pnpm test src/modules/warehouse-resources/<目标测试>`；接口变化同时核对对应服务的资源合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/warehouses/AGENTS.md b/src/modules/warehouses/AGENTS.md new file mode 100644 index 00000000..6409fa56 --- /dev/null +++ b/src/modules/warehouses/AGENTS.md @@ -0,0 +1,27 @@ +# Admin 仓库主档模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/warehouses/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `pages/WarehousesView.vue`、`api/platformWarehouses.ts`、`types.ts`；仓库地址、能力与状态都在同一页维护。 +- 后端唯一权威是 `warehouse/`（`PlatformWarehouseController`、`WarehouseApplicationService.java`）；本页不区分国内/海外仓，类型由服务端字段决定。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 仓库列表、类型、状态与地址 | `pages/WarehousesView.vue` | `api/platformWarehouses.ts`；`warehouse/` | +| 地址与服务能力维护 | 详情与编辑弹框 | `api/platformWarehouses.ts`；`warehouse/` | +| 海外仓合作仓 | 同页面，类型选择 | `warehouse/PlatformWarehouseController.java` | + +## 关键边界 + +- 仓库 ID、类型、状态、地址与能力只在本模块维护；海外资源服务只保存 `warehouseId` 引用，不复制主档。 +- 仓库是平台公共主数据（`tenant_id=0`），不绑定客户；客户筛选不得缩小仓库候选。 +- 停用仓库前确认在途订单、预占与资源锁；停用不回溯历史单据。 +- 海外收货仓必须是 `OVERSEAS + ACTIVE + RECEIVING`，FBA 目的仓必须是 `FBA`，不得互相顶替。 + +## 验证 + +- 定向：`pnpm test src/modules/warehouses/<目标测试>`；字段变化同时核对 `warehouse/` 的 `warehouse-v1.yaml`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。