admin-web/README.md

# 虫虫出海管理后台

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

## 本地运行

```bash
cd apps/admin-web
pnpm install
pnpm dev
```

生产构建：

```bash
pnpm typecheck
pnpm build
```

自动化测试：

```bash
pnpm test
```

## 源码结构

- `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 依赖。

工作台已从一期菜单和默认入口移除；登录后按当前角色进入第一个有权限的业务页面。历史工作台仍保留为不展示菜单的原型路由。一期 Admin 正式路由聚焦登录、客户及注册审核、平台收货仓、快递公司、往来单位、头程订单、内部用户、角色管理和菜单权限；企业注册审核已合并到客户列表，不再保留独立菜单。

后台菜单仅展示已接入的一期模块；其余平台原型菜单保留为导航配置中的注释，待对应业务契约接入后再恢复展示。企业审核、仓库、头程订单、平台角色、菜单及按钮权限资源均接入真实接口；用户管理通过 IAM 统一维护平台账号和企业租户账号。运行时不再提供本地演示业务数据或静态角色预览。

## 本地 Gateway 联调

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

```dotenv
VITE_API_BASE_URL=/api
API_PROXY_TARGET=http://8.163.30.128:9000
```

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

仓库管理已接入真实平台 Warehouse API，支持按租户筛选、详情、新增、编辑和启停，并在更新时保留后端返回的地址、能力和截单时间等完整字段。停用仓库保留历史数据，但不再提供给客户新建头程订单选择；订单详情使用下单时保存的仓库编码、名称和地址快照，仓库主数据后续修改不改变历史展示。本阶段不包含 FBA/海外目的仓、库存、库位或出入库作业。

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

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

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