safety-eval-service-frontend/docs/dev-guide.md

# 证照管理子应用 — 本地开发指南

## 目录

- [1. 项目概述](#1-项目概述)
- [2. 环境准备与启动](#2-环境准备与启动)
- [3. 路由系统](#3-路由系统)
- [4. 菜单配置](#4-菜单配置)
- [5. 页面开发流程](#5-页面开发流程)
- [6. API 接口声明](#6-api-接口声明)
- [7. 状态管理（DVA）](#7-状态管理dva)
- [8. 共享组件](#8-共享组件)
- [9. 本地模拟布局](#9-本地模拟布局)
- [10. 已知问题与注意事项](#10-已知问题与注意事项)
- [11. 目录结构参考](#11-目录结构参考)

---

## 1. 项目概述

本项目是基于 **qiankun 微前端** 框架的子应用，运行在 **GBS 底座平台** 内。使用以下核心技术栈：

| 技术 | 说明 |
|------|------|
| React 18 | UI 组件框架 |
| Ant Design 5.x | UI 组件库 |
| @cqsjjb/jjb-dva-runtime | 底座 DVA 状态管理运行时 |
| @cqsjjb/jjb-common-decorator | 装饰器工具（权限、模块加载等） |
| rspack | 构建打包工具 |
| pnpm | 包管理器 |

项目通过 `jjb.config.js` 中配置的 `appIdentifier: "certificate"` 注册到底座，所有页面路由前缀为 `/certificate/container/`。

---

## 2. 环境准备与启动

### 2.1 安装依赖

```bash
pnpm install
```

### 2.2 启动命令

| 命令 | 说明 |
|------|------|
| `pnpm run serve:development` | **开发环境启动**（推荐） |
| `pnpm run serve:production` | 生产环境配置启动 |
| `pnpm run build:development` | 开发环境构建 |
| `pnpm run build:production` | 生产环境构建 |

### 2.3 访问地址

启动后开发服务器默认监听 `http://127.0.0.1:8081`，访问：

```
http://localhost:8081/certificate/container/
http://localhost:8081/certificate/container/Test
```

> **注意**：本地独立启动时，应用处于 qiankun 独立运行模式（`window.__POWERED_BY_QIANKUN__` 为 false），
> 会使用内置的 `SimulatedLayout` 模拟侧边栏和标签页布局。

### 2.4 配置说明

`jjb.config.js` 中的关键配置项：

```js
module.exports = {
  appIdentifier: "certificate",   // 应用唯一标识，对应路由前缀
  server: {
    port: "8081",                  // 开发服务器端口
    host: "127.0.0.1",             // 服务地址
  },
  environment: {
    development: {
      API_HOST: "https://gbs-gateway.qhdsafety.com",  // 开发环境接口地址
    },
  },
};
```

---

## 3. 路由系统

### 3.1 约定式路由

本项目使用 **文件系统约定式路由**，由 `@cqsjjb/jjb-dva-runtime` 框架自动注册。页面对应的路径由目录结构决定：

```
src/pages/Container/<目录层级>/index.js  →  /certificate/container/<目录层级>
```

**示例：**

| 文件路径 | 对应路由 |
|----------|----------|
| `src/pages/Container/Test/index.js` | `/certificate/container/Test` |
| `src/pages/Container/Supervision/index.js` | `/certificate/container/Supervision` |
| `src/pages/Container/Supervision/PersonnelLicense/PersonInCharge/List/index.js` | `/certificate/container/Supervision/PersonnelLicense/PersonInCharge/List` |

### 3.2 页面组件类型

项目中有两类页面组件：

1. **容器组件**（中间层级）：作为 `{props.children}` 的容器，负责嵌套子页面
   ```js
   function ContainerPage(props) {
     return <div>{props.children}</div>;
   }
   export default ContainerPage;
   ```

2. **叶子页面**（终端页面）：实际的业务功能页面，通过 `Connect` 连接 DVA 数据
   ```js
   import { Connect } from "@cqsjjb/jjb-dva-runtime";
   import { NS_USER_CERTIFICATE } from "~/enumerate/namespace";

   function List(props) {
     return <div>业务内容</div>;
   }

   export default Connect([NS_USER_CERTIFICATE], true)(List);
   ```

### 3.3 路由匹配规则

- 框架自动递归扫描 `src/pages/` 目录，每个 `index.js` 对应一个路由
- 路由路径是将目录路径转换为小写并用 `/` 连接
- 带参数的路由（如 `/View/:id`）需在目录中创建对应层级

---

## 4. 菜单配置

侧边栏菜单定义在 `src/pages/Container/Layout/menuConfig.js` 中。

### 4.1 菜单数据结构

```js
{
  key: "/certificate/container/<实际路由>",  // 必须与文件目录对应的路由完全一致
  label: "菜单显示名称",
  icon: <SomeIcon />,                          // Ant Design 图标组件
  children: [...]                              // 可选，子菜单项
}
```

### 4.2 当前菜单结构

```
📁 监管端 (Supervision)
  ├── 📄 企业证照 (EnterpriseLicense)
  │   ├── 企业证照管理
  │   ├── 分公司统计
  │   └── 干系人统计
  └── 📄 人员证照 (PersonnelLicense)
      ├── 负责人
      ├── 安全管理员
      ├── 特种设备
      ├── 特种作业人员
      ├── 分公司人员统计
      └── 干系人人员统计

📁 分公司端 (BranchCompany)
  └── 📄 企业证照 (EnterpriseLicense)
      ├── 企业证照管理
      └── 📄 人员证照 (PersonnelLicense)
          ├── 负责人
          ├── 安全管理员
          ├── 特种设备
          └── 特种作业人员

📁 干系人端 (Stakeholder)
  └── 📄 企业证照 (EnterpriseLicense)
      ├── 企业证照管理
      └── 📄 人员证照 (PersonnelLicense)
          ├── 负责人
          ├── 安全管理员
          ├── 特种设备
          └── 特种作业人员

📁 测试页面 (Test)
```

### 4.3 菜单配置注意事项

> **关键规则**：菜单的 `key` 必须与文件系统的实际目录层级完全一致，否则会出现"页面不存在"。

以"干系人端 → 负责人"为例：

- **文件位置**：`Stakeholder/EnterpriseLicense/PersonnelLicense/PersonInCharge/List/index.js`
- **正确路径**：`/certificate/container/Stakeholder/EnterpriseLicense/PersonnelLicense/PersonInCharge/List`
- **错误路径**（缺少 `EnterpriseLicense` 层级）：`/certificate/container/Stakeholder/PersonnelLicense/PersonInCharge/List`

### 4.4 工具函数

`menuConfig.js` 同时导出以下辅助函数：

| 函数 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `flattenMenu(items)` | 菜单树 | 扁平数组 | 将树形菜单拍平 |
| `findMenuPath(path)` | 当前路由 | 菜单项数组 | 从根到叶子节点的面包屑路径 |
| `getPageLabel(path)` | 当前路由 | 字符串 | 获取页面标签名 |
| `getOpenKeys(path)` | 当前路由 | 路径数组 | 默认展开的菜单项 |
| `getSelectedKeys(path)` | 当前路由 | 路径数组 | 默认选中的菜单项 |

---

## 5. 页面开发流程

### 5.1 新增业务页面

以新增"监管端 → 人员证照 → 新增功能"为例：

**步骤 1：创建目录结构**

```
src/pages/Container/Supervision/PersonnelLicense/NewFeature/
├── index.js          # 容器组件
├── List/
│   └── index.js      # 列表页
└── View/
    └── index.js      # 详情页
```

**步骤 2：编写容器组件**

`src/pages/Container/Supervision/PersonnelLicense/NewFeature/index.js`：
```js
function NewFeature(props) {
  return <div>{props.children}</div>;
}
export default NewFeature;
```

**步骤 3：编写列表页面**

`src/pages/Container/Supervision/PersonnelLicense/NewFeature/List/index.js`：
```js
import { Connect } from "@cqsjjb/jjb-dva-runtime";
import { NS_USER_CERTIFICATE } from "~/enumerate/namespace";

function List(props) {
  return (
    <div>
      <h1>新功能列表</h1>
    </div>
  );
}

export default Connect([NS_USER_CERTIFICATE], true)(List);
```

**步骤 4：添加菜单配置**

在 `src/pages/Container/Layout/menuConfig.js` 中添加：
```js
{
  key: "/certificate/container/Supervision/PersonnelLicense",
  label: "人员证照",
  icon: <TeamOutlined />,
  children: [
    // ... 已有菜单项
    {
      key: "/certificate/container/Supervision/PersonnelLicense/NewFeature/List",
      label: "新功能",
      icon: <SomeIcon />,
    },
  ],
}
```

### 5.2 新增测试页面（独立于业务）

在 `src/pages/Container/` 下创建目录，并在菜单中添加即可：

```
src/pages/Container/MyDebug/
└── index.js
```

菜单：
```js
{
  key: "/certificate/container/MyDebug",
  label: "调试页面",
  icon: <ExperimentOutlined />,
}
```

### 5.3 验证路径是否正确

启动项目后，通过以下方式验证：

1. 在浏览器直接访问完整 URL
2. 从侧边栏菜单点击导航
3. 检查开发者工具 Network 面板，404 表示路径不匹配

---

## 6. API 接口声明

### 6.1 接口定义位置

API 接口声明在 `src/api/` 目录下，按模块划分：

```
src/api/
├── userCertificate/index.js    # 人员证书接口
├── corpCertificate/index.js    # 企业证书接口
├── courseware/index.js         # 课件接口
└── global/index.js             # 全局接口
```

### 6.2 declareRequest 语法

```js
import { declareRequest } from "@cqsjjb/jjb-dva-runtime";

// 格式：declareRequest(loadingKey, "HttpMethod > 接口路径")
export const listApi = declareRequest(
  "namespaceLoading",                             // loading 状态 key
  "Post > @/certificate/userCertificate/list",   // POST + 相对路径（带 @）
);

export const getApi = declareRequest(
  "namespaceLoading",
  "Get > /certificate/userCertificate/getInfoById/{id}",  // GET + 绝对路径
);
```

**语法规则：**

| 符号 | 说明 | 示例 |
|------|------|------|
| `@/` | 相对路径，使用 `jjb.config.js` 中配置的 `API_HOST` | `Post > @/certificate/xxx/list` |
| `/` | 绝对路径 | `Get > /config/dict-trees/list` |
| `{param}` | 路径参数 | `/certificate/xxx/delete/{id}` |
| `Post >` | POST 请求 | — |
| `Get >` | GET 请求 | — |
| `Put >` | PUT 请求 | — |
| `Delete >` | DELETE 请求 | — |

### 6.3 在组件中使用 API

API 通过 DVA 的 `dispatch` 和 `Connect` 来调用。`declareRequest` 会自动生成对应的 dva effect：

```js
import { Connect } from "@cqsjjb/jjb-dva-runtime";
import { NS_USER_CERTIFICATE } from "~/enumerate/namespace";

function List({ dispatch, userCertificate }) {
  const fetchData = () => {
    dispatch({
      type: `${NS_USER_CERTIFICATE}/userCertificateList`,  // namespace/接口名
      payload: { page: 1, size: 10 },
    });
  };

  return <div>{/* ... */}</div>;
}

export default Connect([NS_USER_CERTIFICATE], true)(List);
```

---

## 7. 状态管理（DVA）

### 7.1 Namespace 定义

`src/enumerate/namespace/index.js` 中定义了所有 DVA namespace：

```js
export const NS_GLOBAL = defineNamespace("global");
export const NS_PERSNONEL_CERTFICATE = defineNamespace("personnelCertificate");
export const NS_CORP_CERTIFICATE = defineNamespace("corpCertificate");
export const NS_USER_CERTIFICATE = defineNamespace("userCertificate");
export const NS_COURSEWARE = defineNamespace("courseware");
```

### 7.2 Connect 高阶组件

```js
Connect([NS_USER_CERTIFICATE], true)(MyComponent)
```

- 第一个参数：需要连接的 namespace 数组
- 第二个参数：是否在组件挂载时自动加载数据（`true` 表示自动触发 `load` effect）

### 7.3 数据流向

```
dispatch(action) → DVA Effect → declareRequest → HTTP API → reducer → state 更新 → 组件重渲染
```

### 7.4 本地开发时的限制

本地独立运行时（非底座环境），DVA 状态管理正常可用，但 `declareRequest` 发起的 HTTP 请求会因缺少认证 Token 而返回 **401**。详见 [§10 已知问题](#10-已知问题与注意事项)。

---

## 8. 共享组件

业务组件位于 `src/components/` 目录下，目前包括：

```
src/components/
├── PersonInChargeInfo/     # 负责人详情组件
├── PersonInChargeList/     # 负责人列表组件（含搜索、分页、CRUD）
├── SpecialCertificateInfo/ # 特种证书详情组件
└── SpecialCertificateList/ # 特种证书列表组件
```

组件通过 `@/components/xxx` 或别名 `~/components/xxx` 引入：

```js
import PersonInChargeList from "~/components/PersonInChargeList";
```

### 8.1 组件参数传递

列表组件通过 `props` 接收业务参数：

```js
<PersonInChargeList
  props={props}                // dva props 透传
  certificatePhotoType={161}   // 证照照片类型
  personnelType="zyfzr"        // 人员类型标识
  permissionAdd="gfd-xxx-add"  // 新增权限码
  permissionEdit="gfd-xxx-edit" // 编辑权限码
  permissionView="gfd-xxx-info" // 查看权限码
  permissionDel="gfd-xxx-del"  // 删除权限码
  dictionaryType="zyfzrgwmc0000" // 字典类型
/>
```

---

## 9. 本地模拟布局

### 9.1 工作原理

`src/pages/Container/index.js` 中的 `AppMiddle` 组件检测运行环境：

```js
function AppMiddle(props) {
  const content = process.env.NODE_ENV === "development" && !window.__POWERED_BY_QIANKUN__
    ? <SimulatedLayout>{props.children}</SimulatedLayout>
    : props.children;
  // ...
}
```

- **本地开发**（`development` + 非 qiankun）：使用 `SimulatedLayout` 包裹内容，提供模拟的侧边栏、面包屑和标签页
- **底座环境**：由底座平台提供真实的布局

### 9.2 SimulatedLayout 功能

`src/pages/Container/Layout/index.jsx` 提供：

| 功能 | 说明 |
|------|------|
| 侧边栏 | 使用 `menuConfig.js` 的菜单数据渲染，支持折叠 |
| 面包屑 | 根据当前路径自动计算导航路径 |
| 多标签页 | 支持打开多个页面标签，右键关闭操作 |
| 标签持久化 | 使用 sessionStorage 保存标签状态 |
| 主题适配 | 通过 `window.base?.themeConfig` 支持底座主题切换 |

---

## 10. 已知问题与注意事项

### 10.1 API 401 错误

**现象**：本地启动后，点击侧边栏菜单（除 Test 页面外），控制台报 401 错误。

**原因**：本项目是 qiankun 微前端子应用，API 请求需要的认证 Token 由 GBS 底座注入。本地独立运行时没有底座，也就没有 Token，所有 API 调用被拒绝。

**处理方式**：
- **纯前端调试**：使用 Test 页面（`/certificate/container/Test`），该页面不发起任何 API 请求
- **完整功能调试**：在 GBS 底座环境中打开应用

### 10.2 路由路径与菜单 key 必须匹配

菜单的 `key` 值必须和文件目录层级完全一致。错误示例见 [§4.3 菜单配置注意事项](#43-菜单配置注意事项)。

### 10.3 重命名项目目录后需重新安装依赖

由于 pnpm 使用基于绝对路径的符号链接管理 `node_modules`，重命名项目根目录后需要：

```bash
Remove-Item -Recurse -Force node_modules
pnpm install
```

### 10.4 权限控制

页面使用 `@cqsjjb/jjb-common-decorator/permission` 的 `Permission` 装饰器控制访问：

```js
import { Permission } from "@cqsjjb/jjb-common-decorator/permission";

export default Connect([NS_USER_CERTIFICATE], true)(Permission(List));
```

权限码由底座平台管理，本地开发时权限校验可能不生效。

### 10.5 pnpm overrides

`package.json` 中通过 `pnpm.overrides` 强制统一 React 等依赖版本，避免多副本冲突：

```json
{
  "pnpm": {
    "overrides": {
      "react": "$react",
      "react-dom": "$react-dom"
    }
  }
}
```

---

## 11. 目录结构参考

```
safety-eval-service-frontend/
├── public/
│   └── index.html              # HTML 模板
├── src/
│   ├── main.js                  # 应用入口（setup + 生命周期导出）
│   ├── api/                     # API 接口声明
│   │   ├── global/
│   │   ├── userCertificate/
│   │   ├── corpCertificate/
│   │   └── courseware/
│   ├── components/              # 共享业务组件
│   │   ├── PersonInChargeList/
│   │   ├── PersonInChargeInfo/
│   │   ├── SpecialCertificateList/
│   │   └── SpecialCertificateInfo/
│   ├── enumerate/               # 枚举/常量定义
│   │   ├── namespace/           # DVA namespace
│   │   ├── context/             # React Context
│   │   └── constant/            # 常量
│   ├── pages/
│   │   └── Container/
│   │       ├── index.js         # 容器入口（Antd 主题 + 布局切换）
│   │       ├── Entry/           # 底座入口页
│   │       ├── Layout/          # 本地模拟布局
│   │       │   ├── index.jsx    # SimulatedLayout 组件
│   │       │   └── menuConfig.js # ★ 菜单配置
│   │       ├── Test/            # 测试页面（无 API 依赖）
│   │       ├── Supervision/     # 监管端
│   │       │   ├── EnterpriseLicense/
│   │       │   └── PersonnelLicense/
│   │       ├── BranchCompany/   # 分公司端
│   │       │   └── EnterpriseLicense/
│   │       └── Stakeholder/     # 干系人端
│   │           └── EnterpriseLicense/
│   ├── assets/                  # 静态资源
│   └── utils/                   # 工具函数
├── jjb.config.js                # 项目配置（端口、API_HOST、主题等）
├── package.json
├── pnpm-lock.yaml
└── pnpm-workspace.yaml
```