136 lines
3.4 KiB
Markdown
136 lines
3.4 KiB
Markdown
# 使用文档
|
||
|
||
建教帮（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`，勿随意关闭。
|