81 lines
9.2 KiB
Markdown
81 lines
9.2 KiB
Markdown
# 虫虫出海管理后台
|
||
|
||
平台内部运营与管理应用，使用 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/core/routing/navigationRecovery.ts` 统一处理路由懒加载、Vite JS/CSS 预加载和 Vue 异步组件的资源加载失败。无未保存编辑时自动重新加载目标页面，保留路径、查询参数和页签；有未保存编辑时先确认，取消后继续编辑。普通接口错误和业务运行错误不触发刷新。
|
||
|
||
刷新记录写入当前标签页的 `sessionStorage`，30 秒内最多自动刷新一次，跨路由成功、重定向和整页刷新仍然保留，防止循环刷新。存储不可用或恢复后仍失败时提示手动刷新。`nginx/default.conf.template` 已对 HTML 禁用缓存，并让缺失的 `/assets/` 文件返回真实 404；使用额外 CDN 时也应保持 HTML 每次重新验证，参见 [Vite 资源加载错误处理](https://vite.dev/guide/build#load-error-handling)。
|
||
|
||
该机制随新版前端生效，已经打开且尚未加载本次改动的旧标签页需要先刷新一次。发布验收可在旧版页面保持打开的情况下发布新版，再打开尚未访问过的页面或异步弹窗，确认自动恢复以及未保存编辑的取消/确认行为。
|
||
|
||
## 源码结构
|
||
|
||
- `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`，并按联调机器修改：
|
||
|
||
```dotenv
|
||
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 真机扫码验收。
|