# 一期前端本地联调任务

## 1. 文档范围

本文只用于本地开发联调，不包含测试环境、生产环境、国内外部署和跨区域事件同步。

一期业务闭环：商户注册 → 登录 → 完善企业资料 → 上传营业执照 → 平台审核 → 审核通过后创建头程订单 → 编辑草稿 → 提交订单。

## 2. 本地联调入口

| 项目 | 地址 |
|---|---|
| 前端统一 API 地址 | `http://127.0.0.1:9000` |
| 局域网前端统一 API 地址 | `http://192.168.110.149:9000` |
| Swagger | `http://127.0.0.1:9000/swagger-ui.html` |
| MySQL | `127.0.0.1:3306`，本地密码 `123456` |
| Redis | `127.0.0.1:6379` |
| Nacos | `http://127.0.0.1:8848/nacos` |

前端不得直连 9100、9201 等业务端口，所有请求统一经过 Gateway 的 9000 端口。

当前允许的前端 Origin：

- `http://localhost:5173`、`http://localhost:5174`
- `http://127.0.0.1:5173`、`http://127.0.0.1:5174`
- `http://192.168.110.149:5173`、`http://192.168.110.149:5174`

如果前端实际 IP 或端口不同，修改 `scripts/local-env.ps1` 中的 `CORS_ALLOWED_ORIGINS`，然后只重启 Gateway。

## 3. 本地启动顺序

先启动 MySQL、Redis、Nacos，再在 IDEA 中启动以下应用：

1. `BaiyueIamApplication`，端口 9201
2. `BaiyueAuthApplication`，端口 9100
3. `BaiyueFirstlegApplication`，端口 9202
4. `BaiyueOrderApplication`，端口 9204
5. `BaiyueWarehouseApplication`，端口 9205
6. `FileServiceApplication`，端口 9206
7. `PrintServiceApplication`，端口 9207
8. `BaiyueGatewayApplication`，端口 9000，最后启动

一期最小主流程必须启动 Gateway、Auth、IAM、Order、File。为了让一期前端菜单、仓储选择、打印与完整 Swagger 不出现缺失，日常联调建议启动上面 8 个应用。

启动后检查：

```text
http://127.0.0.1:9000/actuator/health
http://127.0.0.1:9100/actuator/health
http://127.0.0.1:9201/actuator/health
http://127.0.0.1:9202/actuator/health
http://127.0.0.1:9204/actuator/health
http://127.0.0.1:9205/actuator/health
http://127.0.0.1:9206/actuator/health
http://127.0.0.1:9207/actuator/health
```

预期均返回 `status=UP`。

## 4. 联调账号

| 端 | 用户名 | 密码 |
|---|---|---|
| 平台端 | `platform_admin` | `ChangeMe123!` |
| 商户端 | `merchant_admin` | `ChangeMe123!` |

两端共用登录接口，但 JWT 中 `app_code`、租户、角色和按钮权限不同。平台 Token 不能访问商户接口，商户 Token 不能访问平台接口。

## 5. 前端公共能力任务

- 配置统一请求基地址，不在页面中写死业务服务端口。
- 成功登录后保存 `accessToken` 和 `refreshToken`，业务请求发送 `Authorization: Bearer <accessToken>`。
- 遇到 401 时尝试刷新一次 Token；刷新失败则清理会话并回到登录页，禁止无限重试。
- 统一解析 `{code,message,data,requestId,traceId,timestamp}`。
- HTTP 200 仍需判断业务 `code` 是否为 `0`。
- 统一处理 400、401、403、404、409、422、429、500、503。
- 根据登录返回的角色和权限生成菜单、按钮；按钮隐藏不是安全边界，后端仍执行权限校验。
- 商户页面不允许传入或切换 `tenantId`，租户从 JWT 获取。
- 平台查询租户业务时必须显式传目标 `tenantId`。
- 文件上传使用 `multipart/form-data`，不要手工设置 multipart boundary。

## 6. 一期页面任务

### 6.1 公共登录与注册

- 完成商户注册表单及前端校验。
- 完成平台、商户统一登录页。
- 完成 Token 刷新、退出登录和登录态恢复。
- 根据 `app_code` 进入平台端或商户端，禁止跨端复用页面权限。

### 6.2 商户端企业入驻

- 企业资料详情页：查询并编辑企业名称、法定名称、联系人、电话、邮箱。
- 资质页：上传营业执照，显示上传结果和资质审核状态。
- 资质图片预览/下载必须携带商户 Token。
- 企业未审核通过时，头程下单入口置灰，并展示后端返回的禁止原因。

状态展示：`PROFILE_REQUIRED`/`PENDING` 表示待完善或待审，`ACTIVE` 表示审核通过，`REJECTED` 表示已驳回。

### 6.3 平台端企业审核

- 待审核列表。
- 查询指定租户资质列表。
- 携带平台 Token 预览资质图片。
- 审核通过、审核驳回及审核意见输入。
- 按钮权限：`platform:customer:review`、`platform:customer:approve`、`platform:customer:reject`。

### 6.4 商户端头程订单

- 订单列表：关键字、状态、客户、目的仓、时间和分页筛选。
- 订单详情：订单、货物、发收货方、状态历史。
- 新建草稿、编辑草稿、提交订单。
- 仅 `DRAFT`、`REJECTED` 可编辑；一期主流程状态为 `DRAFT → SUBMITTED`。
- 商户详情不得展示 `internalNotes`；前端模型即使收到未知字段也不得渲染平台内部备注。
- 按钮权限：`merchant:order:create`、`merchant:order:edit`、`merchant:order:submit`。

## 7. 一期验收清单

- 8 个应用健康检查全部 `UP`。
- 平台账号、商户账号均能通过 Gateway 登录。
- 两类 Token 跨端访问返回 403。
- 商户能查询、编辑企业资料。
- 商户能上传真实 JPG/PNG 营业执照，非图片或超过 5MB 被拒绝。
- 平台能查询待审核记录、查看资质并通过或驳回。
- 企业审核前创建订单被拒绝，审核后可创建草稿。
- 商户可查询、编辑和提交自己的订单，不能读取其他租户订单。
- 商户订单详情不返回平台内部备注。
- 局域网前端 Origin 的 OPTIONS 预检返回 200，非白名单 Origin 返回 403。
- Swagger UI 和一期服务 API 文档均可通过 Gateway 打开。

## 8. 本次本地实测结果

2026-07-30 已完成本机验证：8 个健康检查均为 `UP`；平台/商户登录成功；IAM、Order、Firstleg、Warehouse、File、Print 状态接口及商户资料、订单列表、仓库列表均能通过 Gateway 返回成功；13 个 Swagger 页面/分组返回 200；`http://192.168.110.149:5173` 跨域预检返回 200，非白名单返回 403。

另创建本地联调订单并添加 1 条平台内部备注：平台详情可见 1 条，商户详情返回 0 条，租户端数据隔离验证通过。

2026-07-30 17:20 使用最新代码重新完成成熟度回归：

- 全仓 19 个 Reactor 项目构建成功，75 项单元及组件测试全部通过。
- 认证、个人资料、修改密码、成员、角色、按钮权限、租户隔离共 68 项真实 API 检查全部通过。
- 仓库、往来单位、订单草稿、可信快照、停用限制、重复提交、快递只读共 37 项真实 API 检查全部通过。
- Gateway Swagger UI、配置及 11 个业务分组共 13 个入口全部返回 200。
- 白名单 CORS 预检返回 200，非白名单返回 403。

详细报告见 `docs/phase1-business-maturity-regression-report.md`。营业执照真实图片的桌面端和移动端浏览器查看、替换仍需前端执行人工验收。