3.6 KiB
3.6 KiB
Client 头程模块指引
路径基准与读取顺序
- 本文件适用于
src/modules/first-leg/，代码路径相对本目录；应用公共规则见../../../AGENTS.md，字段与接口细则见../../../docs/business-index.md。 - 模块分层固定：
views/页面、components/业务组件、api/请求、store/跨页状态、types/、utils/、data/；跨模块只能从本目录public.ts导入。 - 后端只查
order/（订单读写与批量导入）、firstleg/（履约进度、入库费用、报关资料）、file/（资质与附件）；纯页面与文案不读后端。
页面与入口
| 目标 | 页面/路由 | API 与后端 |
|---|---|---|
| 头程订单列表、详情、草稿编辑 | views/FirstLegOrdersView.vue；orders/first-leg、orders/first-leg/:orderId/detail、orders/first-leg/:draftId/edit |
api/firstLeg.ts；store/firstLegOrders.ts；order/ |
| 创建订单入口（选业务类型） | views/FirstLegOrderCreateHubView.vue；orders/first-leg/create |
components/FirstLegOrderEditorShell.vue |
| 快速下单（按渠道/目的仓/SKU 生成草稿） | views/QuickOrderView.vue；first-leg/quick-order |
api/firstLeg.ts；只生成草稿，不提交、不审核 |
| 中文批量导入与逐行结果 | 订单列表导入入口 | api/firstLeg.ts；order/ 批量导入；入仓码与失败原因逐行展示 |
| 履约进度与入仓码关系 | components/OrderProgressPanel.vue、components/InboundCodeAssociationDialog.vue |
api/inboundCodeAssociations.ts、utils/orderProgress.ts；firstleg/ |
| 运输事实与商品图片 | components/TransportFactsTable.vue（纯展示）、utils/transportFacts.ts、utils/productImage.ts |
行数据类型来自 api/unifiedOrders.ts；图片读取归 file/ |
| 入库费用确认与计费重 | components/InboundBillingPanel.vue |
api/inboundBilling.ts；firstleg/service/MerchantInboundBillingService.java |
| 装柜后的退税报关资料 | views/CustomsDocumentsView.vue、components/CustomsDocumentsDialog.vue |
api/customs.ts、store/customsPending.ts、utils/customsEligibility.ts；firstleg/customs/、file/ |
| 船期与参考价格 | views/SailingPricesView.vue；first-leg/sailing-prices |
api/firstLeg.ts；firstleg/ 船期价格 |
| 往来单位候选 | data/firstLegParties.ts、api/partners.ts |
warehouse/ 公共往来单位 |
关键边界
- 头程订单只用当前正式读写契约；不得扩展
LEGACY_MANUAL、旧系统入仓码、C02 不可用回退旧 API、历史部分响应兼容或其他新旧并跑逻辑。触及该链路时同步删除生产分支、类型、文案、Mock 和测试。 - 快速下单只创建草稿，不提交、不审核；逐行失败必须回填原因与入仓码，不用内部 ID 代替业务编号。
- 入库费用确认携带
expectedFeeVersion与幂等键，金额与冻结状态只认服务端结果；列表“确认计费重”仅在具备确认权限且服务端customerFeeConfirmationRequired=true时显示，已确认或未推送费用的订单不显示；详情保留费用查看入口。 - 报关资料在开始后只读冻结资料，未装柜或无资格时不展示入口；
utils/customsEligibility.ts是唯一资格判断入口。 - 模块间协作只能从本模块
public.ts导入，不穿透其他模块的views/或内部目录。
验证
- 定向：
pnpm test src/modules/first-leg/<目标测试>；接口或类型变化同时运行pnpm typecheck。 - 本文件或索引变更后，从后端根运行
./scripts/agents-index-contract.ps1。