admin-web/AGENTS.md

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
工作台与指标	modules/dashboard/	指标所属模块与服务端，不复制领域契约
客户、企业审核、客户统计	modules/customers/	iam/、file/、firstleg/customerstatistics/
供应商、国内整柜	modules/suppliers/、modules/domestic-containers/	Backend warehouse/ 及对应 OpenAPI
平台仓库与仓储资源	modules/warehouses/、modules/warehouse-resources/	warehouse/
平台用户、RBAC、导航	modules/iam/、core/access/、core/navigation/	auth/、iam/、平台权限契约
消息中心	modules/notifications/	Backend iam/.../notification/；仅顶部消息中心，不进入左侧菜单
订单列表、详情与入库费用	modules/unified-orders/、modules/first-leg-orders/	order/、firstleg/、Finance
入库、测量与计价主数据	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/	firstleg/loading/、firstleg/split/、warehouse/、file/
三期订舱、出仓前船期	modules/ocean-bookings/、modules/port-schedules/	firstleg/oceanbooking/、firstleg/portschedule/；出仓后节点归四期
拖车、报关、国内出仓	modules/trucking/、modules/customs/、modules/outbound-dispatch/	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/一期/、二期/、三期/、财务管理/ 选择最小契约；四期开发先读 ../../docs/四期/README.md。进度、排期或验收状态问题再读取进度表和报告。

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

关键词	页面/路由入口	API 与联查
尾程订单	modules/overseas-warehouse/pages/LastMileOrdersView.vue、LastMileOrderDetailView.vue	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/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。
• core/navigation/adminNavigation.ts、app/router/index.ts 和模块 routes.ts 是共享装配文件；并行任务不得覆盖总控已确认语义，重叠时保留现有改动并回传总控。
• 认证统一经过 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 执行：

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 验收后仍由人工完成页面和截图确认。