# 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/`、`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` |
| 入库、测量与计价主数据 | `modules/inbounds/`、`modules/fba-pricing/`、`modules/dimension-config/`、`modules/fee-items/` | `firstleg/`、`order/`、`file/`、`integration-service/` |
| 财务 | `modules/finance/`，继续读该目录 `AGENTS.md` | `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 或错误文案猜阶段。整柜报关按 `loadingPlanId` 展示，逐资料完成，全买单柜使用 `complete-all-buy`；Backend `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/pages/SmartLoadingWorkbenchView.vue`、`api/platformContainerLoading.ts` | Backend `firstleg/` 的 `PlatformSmartLoadingController`、`SmartLoadingService`；`GlobalSmartLoadingView.vue` 当前未注册路由，不作为正式入口 |
| 三期订舱、关联候选与出仓前船期 | `modules/ocean-bookings/`、`modules/container-loading/`、`modules/port-schedules/` | `platformOceanBookings.ts` 的 `/link-candidates` 只消费服务端分页；列表 `containerCount` 是柜型需求 `quantity` 总和，不是已关联柜数；Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`，出仓后节点归四期 |
| 拖车、历史报关协同、国内出仓 | `modules/trucking/`、`modules/customs/`、`modules/outbound-dispatch/` | `modules/customs/` 是报关案件/清单/代理提交与回执入口；装柜完成后的整柜退税/买单资料改从货柜详情进入，不得在旧模块复制一套；Backend `firstleg/outbound/dispatch/`、`firstleg/customs/`、`file/` |
| 主数据、下载、审计 | `modules/master-data/`、`modules/downloads/`、`modules/audit/` | `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` |

全量验收按业务从 `../../docs/一期/`、`二期/`、`三期/`、`财务管理/` 选择最小契约；四期开发先读 `../../docs/四期/README.md`。进度、排期或验收状态问题再读取进度表和报告。

## 四期海外模块内部快速索引

| 关键词 | 页面/路由入口 | API 与联查 |
|---|---|---|
| 尾程订单与柜级入仓计划进度 | `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue` | 按 `sourceContainerBookingId` 消费 `/orders/container-summaries` 的 `allPlansReady`、计划统计与冻结 `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/`；覆盖详情、候选、草稿柜、托盘即时锁/解锁/整草稿释放和 `pre-arrange`，不据此开放出库编辑、取消、发车、PDA 出库或派送 |
| 海外出库、派送、异常与回访（范围外现存代码） | `pages/OutboundsView.vue`、`DeliveryOrdersView.vue`、`DeliveryOrderDetailView.vue`、`ExceptionOrdersView.vue`、`CustomerVisitsView.vue` 及对应 `api/outbounds.ts`、`deliveryOrders.ts`、`exceptionOrders.ts`、`customerVisits.ts`；当前路由和导航已有注册 | 当前四期契约仍排除海外仓出库、派送及其派生运营页面；不得因代码、菜单、权限或 API 存在而纳入正式范围、验收或继续扩展，只有用户当前明确确认新范围后才能启用其业务语义 |
| 库存余额、库位与流水 | `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 不显示“租户”。平台仓库是公共主数据，不与客户绑定；客户筛选不得缩小仓库候选。完整语义见平台客户层级与权限契约。
- 菜单、列表路由和详情只读统一使用 `*: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 验收后仍由人工完成页面和截图确认。