17 KiB
17 KiB
Admin Web Instructions
快速读取顺序
- 用“模块快速路由”选择最小业务模块，进入后读取该目录最近的
AGENTS.md；按routes.ts → pages/ → api/types/stores/composables下钻，不先扫描全部src/。 - 页面、布局或交互任务同时读取
../../docs/Admin-Client前端原型还原验收规则.md和后台原型../../docs/悦/货代SAAS平台后台/AGENTS.md。 - 标准列表或公共组件任务读取
src/shared/components/AGENTS.md；国内/海外 HTTP、Token 或刷新任务读取src/shared/api/AGENTS.md；Finance 任务读取src/modules/finance/AGENTS.md；四期任务先读../../docs/四期/README.md。 - 平台/客户层级与权限公共语义读取
../../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。订舱关联和预装确认允许真实集装箱号为空；首次补录可在 EDITING/LOADING 进行，PDA 最终完成前必须补齐；已有柜号纠正只允许 EDITING 且任务未领取、无物理作业事实。整柜报关逐资料完成，全买单柜使用 complete-all-buy |
| 合柜报关 / 同柜不可拆组 | 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/ 的 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/、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 执行：
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 验收后仍由人工完成页面和截图确认。