虫虫出海管理后台

平台内部运营与管理应用，使用 Vue 3、TypeScript、Vite、Vue Router、Pinia 和 Element Plus。

本地运行

cd apps/admin-web
pnpm install
pnpm dev

发布资源构建：

pnpm typecheck
pnpm build

自动化测试：

pnpm test

发布后的页面资源恢复

src/core/routing/navigationRecovery.ts 统一处理路由懒加载、Vite JS/CSS 预加载和 Vue 异步组件的资源加载失败。无未保存编辑时自动重新加载目标页面，保留路径、查询参数和页签；有未保存编辑时先确认，取消后继续编辑。普通接口错误和业务运行错误不触发刷新。

刷新记录写入当前标签页的 sessionStorage，30 秒内最多自动刷新一次，跨路由成功、重定向和整页刷新仍然保留，防止循环刷新。存储不可用或恢复后仍失败时提示手动刷新。nginx/default.conf.template 已对 HTML 禁用缓存，并让缺失的 /assets/ 文件返回真实 404；使用额外 CDN 时也应保持 HTML 每次重新验证，参见 Vite 资源加载错误处理。

该机制随新版前端生效，已经打开且尚未加载本次改动的旧标签页需要先刷新一次。发布验收可在旧版页面保持打开的情况下发布新版，再打开尚未访问过的页面或异步弹窗，确认自动恢复以及未保存编辑的取消/确认行为。

源码结构

• src/app/：应用壳层、根路由和启动装配。
• src/core/：认证、权限、导航、未保存工作保护等全应用基础能力。
• src/modules/：按业务领域组织页面、接口、组件、类型和模块路由。
• src/shared/：不依赖具体业务的 HTTP、基础组件和工具。
• src/prototype/：尚未进入当前迭代的原型页面与路由，和正式业务代码隔离。

新增业务页面时，在对应 src/modules/<domain>/ 中就近放置页面、测试和领域能力，并从模块 routes.ts 导出路由片段；根路由只负责装配，菜单仍由 src/core/navigation/adminNavigation.ts 集中维护。跨模块调用必须经过模块根入口公开的 API，不能引用对方内部目录。

依赖和 pnpm-lock.yaml 均保存在当前前端项目中，不需要在仓库根目录安装 Node 依赖。

首页数据看板已作为无权限门槛的默认入口恢复，当前按照后台原型展示明确标注的静态演示数据，不请求业务接口；后续接入真实统计契约时应整体替换演示数据。历史通用占位页仍保留在 src/prototype/，但看板本身已迁入正式业务模块。订单与客户 Admin 其他正式路由聚焦登录、客户及注册审核、平台收货仓、快递公司、往来单位、头程订单、内部用户、角色管理和菜单权限；企业注册审核已合并到客户列表，不再保留独立菜单。

后台一级菜单及原型内子菜单严格按最新版原型排序；原型未定义位置的现有功能统一归入“通用”。未接入的原型菜单保留为隐藏节点，待对应业务契约和权限码接入后再恢复展示。企业审核、仓库、头程订单、平台角色、菜单及按钮权限资源均接入真实接口；内部用户管理只维护平台员工账号，企业租户成员由商户成员边界管理。运行时不再提供本地演示业务数据或静态角色预览。

本地 Gateway 联调

开发环境统一通过 Vite 的 /api 代理访问 Gateway，不在浏览器代码中拼接 Nacos 服务名或服务直连端口。复制 .env.example 为 .env.local，并按联调机器修改：

VITE_API_BASE_URL=/api
API_PROXY_TARGET=http://localhost:9000
VITE_CLIENT_WEB_URL=http://localhost:5174

全部业务使用共享 http 和同源 /api，通过统一 Gateway 访问。Access/Refresh Token 与并发刷新由认证层维护，业务模块不得读取 Token 或手拼 Authorization。

本地工具只连接同一测试环境：在未提交 .env.local 配置 API_PROXY_TARGET 和 VITE_CLIENT_WEB_URL；不提供业务服务直连或独立海外代理。

唯一部署入口是 docker-compose.test.yml 和 test Jenkins Job。发布前在 Job/未提交环境文件配置 API_UPSTREAM（统一 Gateway origin，不含 /api）、TEST_NETWORK（后端共享测试网络）、CLIENT_WEB_URL（客户工作台地址）及 IMAGE_TAG。可选 HOST_PORT 默认 9001，NODE_BASE_IMAGE/NGINX_BASE_IMAGE 可指定已授权拉取的基础镜像；私有镜像仓库认证由构建节点配置，不在源码存放凭据。Jenkins 从当前提交生成 IMAGE_TAG，不再按 Job 后缀切换 dev/prod。宿主机反向代理连接 loopback 端口。

容器启动通过 CLIENT_WEB_URL 生成 /runtime-config.js；本地 Vite 使用 VITE_CLIENT_WEB_URL。本地构建通过不代表容器或测试环境已发布。真实 HTTP 验收入口为 pnpm test:phase4:test --environment test --gateway <统一入口>，凭据通过环境变量传入，仅在取得对应测试写入授权后执行。

认证请求使用 /api/auth/**，平台 IAM 请求使用 /api/platform/v1/iam/**。登录后只从 JWT 读取平台身份，菜单和操作权限通过当前用户授权接口实时加载，不从 JWT 携带或解析角色权限。企业审核调用 /reviews，打开审核详情后按租户调用 /tenants/{tenantId}/qualifications；营业执照通过 /api/platform/v1/files/qualifications/{tenantId}/{fileName} 携带平台 Token 临时读取，关闭预览后释放本地对象地址。客户端自主注册企业审核通过后继续使用注册账号作为管理员，不展示新凭据；Admin 代建企业并由后端创建管理员时，页面必须展示不可通过遮罩、Esc 或关闭按钮跳过的一次性凭据弹窗，运营人员确认保存后才清除账号密码。平台角色查询、新增、编辑、启停、删除和权限全量保存均已按 RbacController 接入真实 /roles 契约，角色返回的 permissionIds 用于授权回显；系统内置角色及仍被成员使用的角色继续由服务端保护。权限资源查询和新增调用 /permissions，尚未提供的权限编辑、删除和启停不会模拟成功。订单与客户真实权限资源只创建 MENU 与 BUTTON，不创建 PAGE 或 API 类型。其余业务页面需在对应服务契约确认后逐项替换，生产逻辑不得静默回退到模拟数据。

仓库管理已接入真实平台 Warehouse API，统一维护国内收货仓、FBA 仓和海外仓，支持按租户筛选、详情、新增、编辑和启停，并在更新时保留后端返回的地址、能力和截单时间等完整字段。停用仓库保留历史数据，但不再提供给新业务选择；订单详情使用下单时保存的仓库编码、名称和地址快照，仓库主数据后续修改不改变历史展示。库存和出入库作业由对应业务模块管理，不在仓库主数据页面中模拟。

头程订单列表、详情、状态历史、内部备注和快递信息已经接入真实平台 Order API；订单不设“已驳回”，后台修改待审核订单后仍保持待审核并写入审计。快递公司已经接入 Warehouse Service 的真实分页查询、详情、新增、编辑、启停、标准模板下载和 XLSX 整批导入接口，按租户与平台权限访问；订单履约接口当前仍按公司名称和快递单号保存。平台往来单位已经接入 Warehouse Service 的真实分页、新增、编辑和启停接口，当前后端类型契约为客户、供应商及客户/供应商双重类型；批量导入接口尚未提供，不模拟导入成功。内部用户管理仅维护平台员工账号，已接入服务端分页查询、关键词与状态筛选、新增、编辑、平台角色调整、启停、最后登录展示和密码重置接口；账号凭据仍由 Auth Service 独占保存。

真实接口错误会保留后端返回的业务错误码、requestId 和 traceId。登录、企业审核、平台角色及权限资源的主要失败态支持直接复制追踪标识，便于与后端日志关联。

登录表单在开发和生产环境均默认留空，不包含联调账号、密码或演示提示。菜单、路由和操作权限只使用真实登录会话返回的服务端权限快照；前端控制仅改善体验，服务端仍须独立校验身份、角色权限和数据范围。接口失败时页面展示真实错误及追踪标识，不回退到假数据或模拟成功。

同机目标默认值：API_UPSTREAM=http://gateway:9000、TEST_NETWORK=firstleg-test-network；必须与后端同批 test Compose 配置一致。

TEST 入口同时转发两个独立 PDA 静态应用：/pda-domestic/ 到共享网络中的 pda-domestic-h5-test:80，/pda-overseas/ 到 pda-overseas-h5-test:80。各自构建、镜像和静态文件由对应 PDA 项目维护，Admin 不打包 PDA 源码。请求时解析 Docker DNS，PDA 未启动不会阻止 Admin 启动。国内 H5 的 /gateway-api/ 在此转换为同一 API_UPSTREAM 的 /api/，海外 H5 直接使用既有 /api/；所有业务认证与仓绑定仍由统一 Gateway 和服务端校验。发布时先启动 PDA 容器，再验收两个路径的 HTML、资产、登录、权限与缺失资产 404。H5 通过不能替代 Android 真机扫码验收。