120 lines
21 KiB
Markdown
120 lines
21 KiB
Markdown
# Admin Web Instructions
|
||
|
||
## 快速读取顺序
|
||
|
||
1. 用“模块快速路由”选择最小业务模块，进入后读取该目录最近的 `AGENTS.md`；按 `routes.ts → pages/ → api/types/stores/composables` 下钻，不先扫描全部 `src/`。
|
||
2. 页面、布局或交互任务同时读取 `../../docs/Admin-Client前端原型还原验收规则.md` 和后台原型 `../../docs/悦/货代SAAS平台后台/AGENTS.md`。
|
||
3. 标准列表或公共组件任务读取 `src/shared/components/AGENTS.md`；国内/海外 HTTP、Token 或刷新任务读取 `src/shared/api/AGENTS.md`；Finance 任务读取 `src/modules/finance/AGENTS.md`；四期任务先读 `../../docs/四期/README.md`。
|
||
4. 平台/客户层级与权限公共语义读取 `../../docs/平台客户层级与权限契约.md`；双区域 API、海外 Token 和跨区事件读取 `../../docs/跨区域认证与服务通信契约.md`。
|
||
|
||
## 项目定位与技术基线
|
||
|
||
- 本项目是虫虫出海内部运营后台，仅服务平台员工；不承载企业客户自助、官网、小程序、独立 APP 或 PDA 作业。
|
||
- 使用 Vue 3、TypeScript 严格模式、Vite、Vue Router、Pinia、Element Plus、Axios 和 Lucide Vue；保持 ES Module、现有无分号风格和 `@` 对 `src/` 的别名。
|
||
- 不用 `any` 绕过业务模型。模块专属类型留在模块，本应用多模块稳定复用的类型放 `src/shared/`；服务端契约以 Controller/OpenAPI 为准。
|
||
- Element Plus 使用现有自动导入；Vue API 显式导入。`src/auto-imports.d.ts`、`src/components.d.ts` 是生成声明，不手工维护业务内容。
|
||
- 不更换框架、路由、状态管理、组件库或构建工具，除非任务明确要求并完成影响评估。
|
||
|
||
## 目录与依赖方向
|
||
|
||
| 目录 | 职责 |
|
||
|---|---|
|
||
| `src/app/` | 应用装配、布局、根路由、全局守卫和启动；不承载业务 |
|
||
| `src/core/` | 认证、访问控制、导航、路由安全等全应用能力；不得依赖业务模块 |
|
||
| `src/modules/` | 稳定业务领域的页面、API、类型、组件和模块路由；新增业务页面不放根级 `views/` |
|
||
| `src/shared/` | 无业务归属的 HTTP、组件和工具；只有真实跨模块复用才上移 |
|
||
| `src/prototype/` | 未纳入当前迭代的原型实现；正式模块不得依赖 |
|
||
| `src/styles/` | 设计令牌和全局样式，优先复用 `--cc-*` 变量 |
|
||
|
||
- 依赖方向为 `app → modules/core/shared`、`modules → core/shared`、`core → shared`、`shared → 无上层依赖`。模块间只通过对方公开入口或契约协作，不引用其他模块的页面和内部目录。
|
||
- 路由级页面放 `modules/*/pages/`，模块路由放 `modules/*/routes.ts` 并由 `app/router/index.ts` 装配；新增模块同步维护 `core/navigation/adminNavigation.ts`。
|
||
- 领域接口放 `modules/*/api/`；国内、海外公共客户端分别为 `shared/api/http.ts`、`shared/api/overseasHttp.ts`，具体 Token 与刷新规则见 `shared/api/AGENTS.md`。
|
||
- `VITE_API_BASE_URL`、`VITE_OVERSEAS_API_BASE_URL` 分别控制国内、海外浏览器前缀；开发代理上游只由 Vite 读取。环境变量变化同步 `.env.example`，不提交真实地址或凭据。
|
||
|
||
## 模块快速路由
|
||
|
||
| 业务 | Admin 入口 | 联查 |
|
||
|---|---|---|
|
||
| 登录、会话与双区域 Token | `modules/auth/`、`core/auth/` | 国内 `auth/`、`iam/`；海外请求客户端再读 `shared/api/AGENTS.md` |
|
||
| 启动与懒加载资源恢复 | `main.ts`、`core/routing/navigationRecovery.ts` | 仅识别动态模块/Chunk 资源过期；30 秒内同目标最多自动恢复一次，存在未保存编辑时必须先确认 |
|
||
| 工作台与指标 | `modules/dashboard/` | 指标所属模块与服务端，不复制领域契约 |
|
||
| 客户、企业审核、客户统计 | `modules/customers/` | `iam/`、`auth/`、`file/`、`firstleg/customerstatistics/`；公司联系电话只作企业联系信息，不修改管理员/成员登录手机号且不要求跨企业唯一。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可随资质包提交，也可在已有营业执照后单独补传或替换 |
|
||
| 供应商、国内整柜 | `modules/suppliers/`、`modules/domestic-containers/` | Backend `warehouse/` 及对应 OpenAPI |
|
||
| 平台仓库与仓储资源 | 仓库主档 `modules/warehouses/`，国内资源 `modules/warehouse-resources/` | 全部仓库 ID、类型、状态、地址和能力归国内 `warehouse/`；海外 `warehouse-overseas-service/` 只维护引用同一 warehouseId 的库位、托盘和锁 |
|
||
| 平台用户、RBAC、导航 | `modules/iam/`、`core/access/`、`core/navigation/` | `auth/`、`iam/`、平台权限契约 |
|
||
| 国内/海外 PDA 独立人员与海外仓绑定 | `modules/iam/pages/InternalUsersView.vue`、`modules/iam/api/platformIam.ts` | 国内 `CN_FIRSTLEG_PDA_OPERATOR` 与海外 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 互斥；只有海外角色必须且只能绑定一个 `overseasWarehouseId`，候选来自国内 Warehouse 平台仓库 API 的公共 `OVERSEAS + ACTIVE + RECEIVING` 收货仓 |
|
||
| 消息中心 | `modules/notifications/` | Backend `iam/.../notification/`；仅顶部消息中心，不进入左侧菜单 |
|
||
| 订单列表、详情、商品图片与入库费用 | `modules/unified-orders/`、`modules/first-leg-orders/`；平台商品图片由 `modules/unified-orders/api/unifiedOrders.ts` 按客户与 fileId 下载 | `order/`、`firstleg/`、Finance；图片读取归 `file/` 的 `PlatformProductImageController`。Order 状态为 `SUBMITTED` 时统一列表必须保持 `PENDING_REVIEW/APPROVE_ORDER`，不得被已存在的 Firstleg 准备中入库投影覆盖 |
|
||
| 客户原始申报资料编辑与渠道变更 | `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`api/unifiedOrders.ts`、`pages/UnifiedOrdersView.vue` | 使用订单版本和货物 `itemNo` 整体提交，不允许增删货物行；只编辑客户申报快照，不覆盖仓库/PDA 实测、测量审核或计费事实。渠道变化需二次确认并由 Backend `order/` 联查 `firstleg/` 的分柜、同柜、装柜与重新计价门禁；国内收货仓或中转仓变化必须重新下单 |
|
||
| 入库、测量、客户箱规策略与计价主数据 | `modules/inbounds/measurement/`、`modules/fba-pricing/`、`modules/dimension-config/`、`modules/customers/components/CustomerBillingRulesPanel.vue`、`modules/fee-items/` | 客户固定四档箱规，默认计算方式为 `ADD/MULTIPLY`；测量行可选实际尺寸、箱规尺寸策略或客户默认尺寸系数，保存后以 Backend `firstleg/` 返回的外箱尺寸、体积重和计费基数为准，不在页面独立重算 |
|
||
| 财务与柜级公共费用分摊 | `modules/finance/`，继续读该目录 `AGENTS.md`；柜费入口 `modules/loading-lists/components/ContainerFeesPanel.vue`、`api/containerFees.ts` | `finance/`、`firstleg/`、`file/`、`docs/财务管理/`；跨客户公共柜费只按服务端柜内客户/订单事实分摊，金额必须守恒，创建与审核、驳回、调整、作废均整组原子处理 |
|
||
| 货柜、排柜、预装/装柜清单、真实柜号后补与整柜报关 | `modules/container-loading/`、`modules/loading-lists/`；预装详情 `pages/PreloadPlanDetailView.vue`，货柜详情 `pages/ContainerDetailView.vue`，资料/PDA 证据 `components/ContainerOverviewPanel.vue`，报关 `components/ContainerCustomsPanel.vue`、`api/platformContainerCustoms.ts` | 创建柜次时自动生成唯一预装计划，加入入仓码即同步进入该计划，页面不提供创建计划或推送预装操作。预装详情先调用 `/loading-plans/{planId}/lifecycle`，`COMPLETED` 时替换为正式装柜清单详情并关闭旧工作台标签，不按 A0404 或错误文案猜阶段。订舱关联和预装确认允许真实集装箱号为空；首次补录可在 `EDITING/LOADING` 进行，PDA 最终完成前必须补齐；已有柜号纠正只允许 `EDITING` 且任务未领取、无物理作业事实。整柜报关按 `loadingPlanId` 展示、逐资料完成，全买单柜使用 `complete-all-buy`；后端为 `LoadingListService`、`loading-lists-v1.yaml`、`firstleg/customs/container/`，文件归 `file/` |
|
||
| 合柜报关 / 同柜不可拆组 | `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`、`api/platformContainerLoading.ts`；全局页当前不注册独立路由 | Backend `firstleg/` 的 `/inbound-candidates`、`/containers` 和计划分配接口；渠道分组选项与服务端映射必须一致，同柜不可拆组作为单个候选卡片整组分配，前端不得拆成员分页或自行拼组 |
|
||
| 三期订舱资料、打印、关联候选与出仓前船期 | `modules/ocean-bookings/` 的 `components/OceanBookingDocumentsPanel.vue`、`OceanBookingPrintDialog.vue`，以及 `modules/container-loading/`、`modules/port-schedules/` | 订舱草稿按当前版本维护资料，放舱后资料与表单只读；打印只对 `RELEASED` 开放。`platformOceanBookings.ts` 的 `/link-candidates` 只消费服务端分页，`containerCount` 是柜型需求 `quantity` 总和；Backend `firstleg/oceanbooking/`、`file/`、`print/`、`firstleg/portschedule/` |
|
||
| 订舱级拖车预约 | `modules/trucking/api/platformTrucking.ts` 的 `/candidates`、`components/TruckAppointmentForm.vue`、`pages/TruckAppointmentCreateView.vue`、`TruckAppointmentsView.vue` | 表单只选择服务端返回的 `RELEASED` 订舱与拖车供应商，不选择或提交客户、柜次、装柜计划或真实集装箱号；提单号和仓库由订舱冻结事实带入。一个订舱最多一张非终态拖车单，重复创建转入现有单继续编辑；PDA 完成不自动推进拖车。附件为平台作用域且不重复提单文件；Backend `TruckAppointmentService`、`truck-appointments-v1.yaml` |
|
||
| 历史报关协同与国内出仓 | `modules/customs/`、`modules/outbound-dispatch/` | `modules/customs/` 是历史报关案件/清单/代理提交与回执入口；装柜完成后的整柜退税/买单资料从货柜详情进入，不在旧模块复制；Backend `firstleg/outbound/dispatch/`、`firstleg/customs/`、`file/` |
|
||
| 主数据、下载、退避任务重试、审计 | `modules/master-data/`、`modules/downloads/pages/DownloadCenterView.vue`、`modules/audit/` | File 导出任务返回 `attemptCount/maxAttempts/nextRetryAt`；仅失败或已进入自动退避的等待任务显示重试，等待任务重试用于立即执行当前投递，不创建新任务；联查 `warehouse/`、`file/`、`audit-service/` |
|
||
| 四期海外接柜、入库与库存 | `modules/overseas-warehouse/` | `gateway-overseas/`、`lastleg-service/`、`warehouse-overseas-service/`；不含出库和派送 |
|
||
| 四期海外采购、卡车、散板 | `modules/overseas-business/` | `gateway-overseas/`、`lastleg-service/` |
|
||
| 四期合作仓与通用资料 | 合作仓 `modules/warehouses/`；报价/汇率/车辆 `modules/overseas-master-data/` | 国内 `warehouse/`、海外实际资源与服务 |
|
||
| 四期国内出仓后船节点 | `modules/port-schedules/`、`modules/ocean-bookings/`、货柜详情 | `firstleg/portschedule/`、`integration-service/`；预计节点只展示不推进实际进度，手工实际节点必须严格向后追加并防重复，十节点标准见 `../../docs/四期/船节点标准化契约.md` |
|
||
| 五期海外排车、出库与派送 | `modules/overseas-warehouse/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`OutboundsView.vue`、`DeliveryOrdersView.vue`、`DeliveryOrderDetailView.vue` | API 为 `dispatches.ts`、`outbounds.ts`、`deliveryOrders.ts`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`。一件代发出库从服务端库存位置选择并携带幂等键；排车转派送按稳定 `dispatchNo` 进入服务端命令，可在 `PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART` 阶段执行并须在 PDA 发车前生成待出库单 |
|
||
| 五期海外异常退回与客户回访 | `modules/overseas-warehouse/pages/ExceptionOrdersView.vue`、`CustomerVisitsView.vue` | API 为 `exceptionOrders.ts`、`customerVisits.ts`；Backend `lastleg-service/exceptionorder/`、`customervisit/`。派送退回先从服务端查询可关联入仓单，回访附件和派送完成/状态均走海外真实 API |
|
||
|
||
全量验收按业务从 `../../docs/一期/`、`二期/`、`三期/`、`财务管理/` 选择最小契约；四期开发先读 `../../docs/四期/README.md`。进度、排期或验收状态问题再读取进度表和报告。
|
||
|
||
## 海外模块内部快速索引（四期/五期）
|
||
|
||
| 关键词 | 页面/路由入口 | API 与联查 |
|
||
|---|---|---|
|
||
| 尾程订单与柜级入仓计划进度 | `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue` | 柜子工作台按 `sourceContainerBookingId` 消费 `/orders/container-summaries`；服务端在分页前排除全部入仓码均已有有效独立计划的柜，只按冻结 `plannedArrivalAt` 升序、空值最后返回仍有待生成计划入仓码的柜。卡片只展示服务端计划统计，详情弹框返回全柜订单且不受列表分页截断，不得在浏览器拼柜或自行推导就绪。整柜生成调用 `/inbound-plans/convert-container`，每票返回独立计划且整批原子；转仓候选只取 `modules/iam/api/platformIam.ts` 的平台公共 `ACTIVE + FBA` 仓主档，并提交 ID/编码/名称快照。业务 API `modules/overseas-warehouse/api/lastMileOrders.ts`，Backend `lastleg-service/` |
|
||
| 入仓单、入仓计划、FBA 预约 | `modules/overseas-warehouse/pages/InboundOrdersView.vue`、`InboundOrderDetailView.vue` | 列表/预约 `modules/overseas-warehouse/api/inboundOrders.ts`，计划列表/详情 `inboundPlans.ts`；Backend `lastleg-service/inboundplan/` |
|
||
| 四期排车查询与智能预排、五期转派送 | `modules/overseas-warehouse/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`components/SmartDispatchDialog.vue` | `modules/overseas-warehouse/api/dispatches.ts`；Backend `lastleg-service/dispatch/`、`delivery/`；四期覆盖详情、候选、草稿柜、托盘锁和 `pre-arrange`，五期继续使用 `transfer-delivery` 转派送。后台暂无排车编辑、取消和发车调用时，不得仅凭后端 Controller 声称页面已支持 |
|
||
| 五期海外出库与派送 | `pages/OutboundsView.vue`、`DeliveryOrdersView.vue`、`DeliveryOrderDetailView.vue` | `api/outbounds.ts`、`deliveryOrders.ts`；一件代发出库、取消、派送列表/详情及退回入口对应 Backend `lastleg-service/delivery/`、`dropship/` |
|
||
| 五期异常退回与客户回访 | `pages/ExceptionOrdersView.vue`、`CustomerVisitsView.vue` | `api/exceptionOrders.ts`、`customerVisits.ts`；异常关系解析、异常建档、派送退回、完成/状态和回访附件对应 Backend `lastleg-service/exceptionorder/`、`customervisit/` |
|
||
| 库存余额、库位与流水 | `modules/overseas-warehouse/pages/InventoryView.vue`、`InventoryDetailView.vue`、`InventoryTransactionsView.vue` | `modules/overseas-warehouse/api/inventory.ts`；业务库存归 `lastleg-service/inventory/`，实物资源归 `warehouse-overseas-service/` |
|
||
| 托盘、箱唛、产品与换标 | `modules/overseas-warehouse/pages/PalletsView.vue`、`CartonsView.vue`、`ProductsView.vue`、`RelabelOrdersView.vue` 及详情页 | `modules/overseas-warehouse/api/pallets.ts`、`relabelOrders.ts`；路由是否公开以 `modules/overseas-warehouse/routes.ts` 为准 |
|
||
| 海外采购 | `modules/overseas-business/pages/PurchaseOrdersView.vue`、详情/编辑页 | `modules/overseas-business/api/platformOverseasBusiness.ts` 的 purchase 方法；Backend `lastleg-service/procurement/` |
|
||
| 美国卡车、本土散板 | `modules/overseas-business/pages/TransportOrdersView.vue`、`TransportOrderFormView.vue` | 同一 API 的 us-truck/looseboard 方法；Backend `lastleg-service/trucking/`、`looseboard/` |
|
||
| 海外报价、月度汇率、车辆 | `modules/overseas-master-data/pages/OverseasQuotesView.vue`、`ExchangeRatesView.vue`、`VehiclesView.vue` | `modules/overseas-master-data/api/overseasMasterData.ts`；Backend `lastleg-service/masterdata/` |
|
||
|
||
- 三个海外模块统一使用 `shared/api/overseasHttp.ts`；页面是否已接真实接口先查对应 `api/` 和挂载测试，不以 `PROTOTYPE_MATRIX.md` 或 `CONTRACT_GAPS.md` 代替当前代码与服务端契约。
|
||
|
||
## 业务、安全与共享装配
|
||
|
||
- 当前只有平台、客户两级；Admin 不显示“租户”。平台仓库是公共主数据，不与客户绑定；客户筛选不得缩小仓库候选。完整语义见平台客户层级与权限契约。
|
||
- 新建客户时，公司联系电话同时初始化首个管理员登录手机号；创建后公司联系电话只属于企业资料，与首个管理员、成员及平台用户登录手机号独立。编辑客户资料不得提交账号手机号变更，账号手机号改动统一走用户管理并由 IAM/Auth 撤销对应会话。
|
||
- 菜单、列表路由和详情只读统一使用 `*:list`，写操作使用独立权限；前端守卫不能替代服务端鉴权。供应商固定使用 `platform:supplier:list`。
|
||
- 平台用户选择 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 时必须选择唯一实际海外收货仓，其他角色不得提交 `overseasWarehouseId`；编辑时保留已绑定仓库并按字符串透传长整型 ID，前端校验不能替代 IAM 服务端约束。
|
||
- 国内出仓以真实货柜为原子边界：货柜详情只在装柜完成、全部入仓绑定门禁通过且有写权限时显示确认离仓；成功后由服务端同事务推进全部技术行并幂等创建船节点查询。前端不得逐入仓确认、把拖车状态当阻断门禁或重复追加实际船节点。
|
||
- `core/navigation/adminNavigation.ts`、`app/router/index.ts` 和模块 `routes.ts` 是共享装配文件；并行任务不得覆盖总控已确认语义，重叠时保留现有改动并回传总控。
|
||
- `core/routing/navigationRecovery.ts` 只处理已识别的动态 import/Chunk 资源过期；普通路由错误直接提示。自动恢复前保护未保存表单，同一目标 30 秒内不得重复刷新或形成重载循环。
|
||
- 认证统一经过 `core/auth/auth.ts`、`shared/api/http.ts` 和 `shared/api/overseasHttp.ts`。登录/刷新原子替换国内、海外 Token，海外 401 统一刷新并最多重放一次；页面不读写 Token 或手工拼 `Authorization`。
|
||
- 接入真实接口时删除对应模拟路径，不允许生产逻辑静默回退假数据。客户专属写操作显式选择客户，长整型 ID 按字符串透传，不从本地存储推断。
|
||
- 订舱代理、拖车承运商和报关代理提交服务端供应商 ID，从公共供应商列表选择 `ACTIVE` 且类别/范围匹配的记录；参数变化同步检查 API、类型、表单、展示、Mock/Fixture、测试和 OpenAPI。
|
||
- 删除、停用、改权限等高风险操作必须有确认、处理中、成功和失败反馈；失败保留用户上下文。日志、提示和示例不得包含真实账号、Token、隐私或生产数据。
|
||
- 页面和交互必须服从对应原型及验收规则；Admin 当前只验收 `1920×1080`、`100%` 缩放。标准列表和共享组件实现继续读 `src/shared/components/AGENTS.md`。
|
||
|
||
## 开发验收身份
|
||
|
||
- 开发环境人工验收身份为 `platform_admin`。密码从未提交的 `CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD` 或 `C:/Users/BY-OY/.codex/chongchong-global-dev-acceptance.env` 读取；缺失时再向用户索取，不写入仓库、日志或快照。
|
||
- 由人工操作真实页面并截图，AI 核对加载、空态、错误态、权限和桌面布局；缺少截图时标记“待人工截图确认”，不自行批量取证。
|
||
|
||
## 命令与质量门禁
|
||
|
||
在 `apps/admin-web` 执行：
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev
|
||
pnpm test
|
||
pnpm typecheck
|
||
pnpm build
|
||
```
|
||
|
||
- 普通变更至少运行 `pnpm typecheck` 和受影响测试；交付前运行 `pnpm test` 与 `pnpm build`。当前没有 lint 脚本，不声称 lint 通过。
|
||
- 不手工修改 `dist/`、`node_modules/` 或生成声明；依赖变化同步 `package.json` 与锁文件。
|
||
- 测试环境全量验收入口为 `../../baiyue-firstleg/scripts/admin-test-env-acceptance.mjs`，模块说明见同仓库 `scripts/admin-test-env-modules/README.md`；它会写入或停用测试数据，只有本轮明确授权才能运行。
|
||
- `pnpm test/typecheck` 和本地回归脚本不代表真实服务验收完成；HTTP 验收后仍由人工完成页面和截图确认。
|