57 lines
6.3 KiB
Markdown
57 lines
6.3 KiB
Markdown
# 虫虫出海客户工作台
|
||
|
||
入驻企业及其成员使用的业务应用，使用 Vue 3、TypeScript、Vite、Vue Router、Pinia 和 Element Plus。
|
||
|
||
## 本地运行
|
||
|
||
```bash
|
||
cd apps/client-web
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
发布资源构建：
|
||
|
||
```bash
|
||
pnpm typecheck
|
||
pnpm build
|
||
```
|
||
|
||
自动化测试：
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
## 源码组织
|
||
|
||
业务代码按领域放在 `src/modules/<domain>/`。每个模块可以包含 `views/`、`components/`、`api/`、`store/`、`types/`、`data/`、`utils/`、`contracts.ts`、`public.ts` 和 `routes.ts`，只创建实际需要的目录。
|
||
|
||
模块的 `routes.ts` 是路由与导航共用的 manifest。正式页面标记 `release: 'active'`；尚未接入接口、权限或未进入当前范围的占位页面标记 `release: 'prototype'`，不会被注册为可访问路由。`src/modules/registry.ts` 负责统一装配模块，根路由不再逐页维护配置。
|
||
|
||
跨模块调用只能经过目标模块的 `public.ts`；模块内部 API、store、组件和工具不作为跨模块接口。租户状态、权限映射等稳定模块契约放在 `contracts.ts`。
|
||
|
||
`src/components/common/` 只存放真实跨模块复用的组件，`src/api/` 只存放 HTTP、Token 会话和统一响应等基础设施。模块私有能力不要提前上移到全局目录。
|
||
|
||
依赖和 `pnpm-lock.yaml` 均保存在当前前端项目中，不需要在仓库根目录安装 Node 依赖。
|
||
|
||
订单与客户路由：登录、注册、工作台、我的信息、企业资料、企业成员、角色权限、头程订单、海外采购、美国本土卡、美本土散板以及海外仓入库订单。跨境下单支持真实列表、详情和新增，海外入库支持当前客户列表与详情；均经统一 Gateway 的客户接口访问，客户范围只取 Token，不提交客户 ID。本地代理仅通过 `API_PROXY_TARGET` 配置统一 Gateway。登录使用后端约定的用户名和 8–72 位密码，注册成功后可立即登录，企业资料审核只影响订单提交资格。
|
||
|
||
认证会话保存 Access Token 和轮换后的 Refresh Token，并对并发 401 请求执行单次刷新。刷新或会话上下文加载遇到临时网络故障、超时等非认证错误时保留当前有效 Token，只有服务端明确返回 401/会话失效才清理登录状态。客户端只接受 `app_code` 为 `MERCHANT` 的 JWT；页面权限通过当前用户授权接口实时加载，不从 JWT 携带或解析角色权限。前端权限仅用于导航和交互控制，服务端仍须按用户、客户和权限编码完成最终授权。
|
||
|
||
登录表单在开发和生产环境默认留空；用户主动选择“记住账号”后只回填登录账号、不保存密码，也不改变 Access/Refresh Token 的持久化和刷新策略；URL 显式传入的登录用户名仍优先。源码和构建产物不得包含联调账号、默认密码或开发提示文案。
|
||
|
||
“我的信息”使用真实个人资料和修改密码接口，姓名、电话、邮箱按服务端约束维护；修改密码成功后清理旧会话并返回登录页。成员列表返回姓名、联系方式和 `roleIds`，新增、编辑、角色全量保存、启停和管理员重置密码均使用真实接口，不回退静态成功。角色页同时加载成员关系，直接打开或刷新后成员数仍按真实 `roleIds` 统计。角色列表返回 `permissionIds`，页面可回显并全量保存角色权限；角色编辑、启停、删除分别调用 `PUT /merchant/v1/iam/roles/{roleId}`、`PUT /merchant/v1/iam/roles/{roleId}/status` 和 `DELETE /merchant/v1/iam/roles/{roleId}`，内置角色及仍有关联成员的角色继续受保护。
|
||
|
||
企业资料和资质列表使用真实租户接口，覆盖 `PROFILE_REQUIRED`、`PENDING`、`ACTIVE`、`REJECTED`、`DISABLED` 五种企业状态。企业名称、法定名称和联系人信息支持真实保存；营业执照、法人身份证为必填资质，货代资质证书和银行开户许可证为选填资质，均使用文件服务分别上传，接受 PDF、JPG、PNG 且不超过 5MB；两项必填资质齐全后可显式提交审核，文件预览通过当前商户 Token 临时下载并在关闭弹窗后释放。
|
||
|
||
头程订单列表、详情、仓库查询、创建/编辑草稿和提交已经接入真实 API，并显式映射后端 `transportMode`、`containerMode` 和订单状态。创建与提交请求携带幂等键，`merchant:order:create`、`merchant:order:edit`、`merchant:order:submit` 分别映射到独立前端操作权限。页面补齐渠道、提货方式、报关模式、目的仓类型、包装类型等后端必填字段；API 模式先清空本地记录，请求失败不会回退模拟成功。FBA 和海外仓按公共仓类型筛选，选择后由仓库主数据生成目的仓字段，不再要求客户重复选择收货单位；私人仓才填写并按当前用户缓存收件资料。只有“我司提货”需要填写提货联系人和地址，其他送货方式不发送发货方快照，订单也不再依赖往来单位 `customerId`。快递信息仍由平台维护、客户只读。订单取消不属于本轮本地订单与客户验收，客户端不暴露取消写操作。订单产品状态仍按已确认的七状态执行，不设置“已驳回”；若兼容旧接口数据收到 `REJECTED`，只按待审核展示且不开放编辑。
|
||
|
||
联调远端 Gateway 时，进程环境变量优先于 `.env` 文件。浏览器全部业务统一请求同源 `/api`，由同一代理转发并确保最终路径只有一个 `/api` 前缀。联调时可只读检查同工作区的 `baiyue-firstleg/` Controller、DTO、Service、Repository 和回归脚本，用于发现后端拉取后的契约变化，但不修改后端仓库。
|
||
|
||
## 唯一测试部署入口
|
||
|
||
仅保留 `docker-compose.test.yml` 与 test Jenkins Job。发布前注入 `API_UPSTREAM`（统一 Gateway origin，不含 `/api`）、`TEST_NETWORK`（后端共享测试网络）、`VITE_ADMIN_WEB_ORIGIN`（管理后台 origin，构建时用于安全代登录）与 `IMAGE_TAG`（Jenkins 从当前提交生成）。`HOST_PORT` 默认 9002 且仅绑定 loopback；宿主机反向代理负责外部入口。可选 `NODE_BASE_IMAGE`/`NGINX_BASE_IMAGE`，私有镜像认证由构建节点管理。不得把本地构建结果描述为测试环境已发布。
|
||
|
||
同机目标默认值：`API_UPSTREAM=http://gateway:9000`、`TEST_NETWORK=firstleg-test-network`；必须与后端同批 test Compose 配置一致。
|