# 使用文档

建教帮（JJB）微应用，基于 `@cqsjjb/scripts` + Rspack 构建。

## 环境要求

- Node.js >= 14（推荐 18+）
- pnpm / npm / yarn

## 安装

```bash
pnpm install
# 或 npm install
```

## 启动开发

```bash
npm run serve:development
```

默认地址：`http://127.0.0.1:8080`

端口、host 在 `jjb.config.js` → `server` 中配置。

## 打包

```bash
# 开发环境产物
npm run build:development

# 生产环境产物
npm run build:production
```

输出目录：`dist/`（子目录名与 `appIdentifier` 一致，当前为 `safetyEval-h5/`）

## 常用命令

| 命令 | 说明 |
|------|------|
| `npm run serve:development` | 开发模式启动 |
| `npm run serve:production` | 生产配置启动（本地调试） |
| `npm run build:production` | 生产打包 |
| `npm run clean-cache` | 清除构建缓存 |
| `npm run lint` | ESLint 检查并自动修复 |

## 路由访问

页面放在 `src/pages/Container/<PageName>/index.js`，访问格式：

```
http://{host}:{port}/{appIdentifier}/container/{PageName}
```

| 页面 | 路径 |
|------|------|
| 用户注册 | `/safetyEval-h5/container/Register` |
| 机构信息填报 | `/safetyEval-h5/container/RegisterMore` |
| 地图大屏 | `/safetyEval-h5/container/Map` |
| Driver 入口 | `/safetyEval-h5/container/Driver` |
| 分公司白底屏 | `/safetyEval-h5/container/White/BranchOffice` |
| 监管白底屏 | `/safetyEval-h5/container/White/Share` |

`appIdentifier` 在 `jjb.config.js` 中配置，当前为 `safetyEval-h5`。

## 核心配置

**`jjb.config.js`**

| 节点 | 说明 |
|------|------|
| `appIdentifier` | 路由前缀 / 打包目录名 |
| `environment.*.API_HOST` | 接口网关地址 |
| `contextInject.fileUrl` | 文件服务地址 |
| `server.port` / `server.host` | 开发服务端口 |

**接口环境**

- 开发：`http://127.0.0.1`（可按需改 `development.API_HOST`）
- 生产：`https://gbs-gateway.qhdsafety.com`

运行时可通过 `sessionStorage.API_HOST` 覆盖网关。

## GBS 基座集成

从基座跳转时，URL 可携带鉴权参数，Map / Driver 页会自动写入 `sessionStorage`：

- `token`
- `accessTicket`
- `clientId`
- `orgId`

Driver 页根据接口 `GET /safetyEval/org-department/checkTerminalType` 判断终端类型：

- `1` → 机构端 Dashboard
- `2` → 监管端驾驶舱（Cockpit）

左上角「返回」：关闭窗口或跳转 GBS 网关。

**接口错误全局处理**：`public/index.html` 配置了 HTTP 响应拦截，当接口返回 `success: false` 时自动返回基座（`checkTerminalType` 除外，失败时停留在 Driver 页）。

## 目录说明

```
src/
├── api/              # 接口声明（declareRequest）
├── pages/Container/  # 业务页面（约定式路由）
├── components/       # 全局公共组件
├── enumerate/        # namespace / context / 常量
└── main.js           # 微应用入口（qiankun 生命周期）
```

## 相关文档

- [对外开放接口（images）](./对外开放接口-images.md)
- [JJB 微应用模板说明](https://www.yuque.com/buhangjiecheshen-ymbtb/qc0093/gxdun1dphetcurko)

## 常见问题

**编译异常 / 路由报错**

```bash
npm run clean-cache
npm run serve:development
```

**8080 端口占用**

修改 `jjb.config.js` → `server.port`，或结束占用进程后重启。

**pnpm 依赖问题**

项目使用 pnpm，`jjb.config.js` 中已配置 `resolve.symlinks: true`，勿随意关闭。