444 lines
12 KiB
Markdown
444 lines
12 KiB
Markdown
# 对外开放接口文档（ImagesOpenController）
|
||
|
||
## 目录
|
||
|
||
- [接口概览](#接口概览)
|
||
- [通用说明](#通用说明)
|
||
- [用户接口（Account）](#用户接口account)
|
||
- [机构信息接口（OrgInfo）](#机构信息接口orginfo)
|
||
- [数据模型](#数据模型)
|
||
|
||
---
|
||
|
||
## 接口概览
|
||
|
||
> 所有接口统一前缀：`/safetyEval/images`
|
||
> **免登录、免鉴权**，适用于注册、短信验证等对外开放场景。
|
||
|
||
| 模块 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| 用户 | `POST` | `/safetyEval/images/account/save` | 新增用户（注册） |
|
||
| 用户 | `GET` | `/safetyEval/images/account/get` | 查询用户详情 |
|
||
| 用户 | `POST` | `/safetyEval/images/account/modify` | 修改用户 |
|
||
| 用户 | `POST` | `/safetyEval/images/account/delete` | 删除用户 |
|
||
| 用户 | `GET` | `/safetyEval/images/account/page` | 分页查询用户 |
|
||
| 用户 | `GET` | `/safetyEval/images/account/syncUserToGBS` | 用户同步 GBS |
|
||
| 用户 | `GET` | `/safetyEval/images/account/verificationCode` | 验证码校验 |
|
||
| 用户 | `GET` | `/safetyEval/images/account/checkTerminalType` | 校验终端类型 |
|
||
| 用户 | `POST` | `/safetyEval/images/account/sendMessage` | 发送短信验证码 |
|
||
| 机构 | `POST` | `/safetyEval/images/org-info/save` | 新增机构信息（注册） |
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
### 基础路径
|
||
|
||
```
|
||
开发环境: http://{host}:{port}/safetyEval/images
|
||
生产环境: http://{gateway}/safetyEval/images
|
||
```
|
||
|
||
### 鉴权说明
|
||
|
||
- 无需携带 Token / Cookie
|
||
- 已配置 GBS 白名单：`/**/images/**`
|
||
- 与 `/safetyEval/account/**` 内部接口功能相同，但路径不同；内部接口仍需登录
|
||
|
||
### 统一响应体（SingleResponse）
|
||
|
||
大部分接口返回项目自定义 `SingleResponse`：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"message": null,
|
||
"errMessage": null,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `success` | boolean | 是否成功 |
|
||
| `code` | string | 响应码，`0` 表示成功 |
|
||
| `message` | string | 响应消息 |
|
||
| `errMessage` | string | 错误消息（失败时） |
|
||
| `data` | object | 业务数据 |
|
||
|
||
### 分页响应体（PageResponse）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"data": [],
|
||
"total": 100
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `data` | array | 当前页数据列表 |
|
||
| `total` | long | 总条数 |
|
||
|
||
### 短信接口响应体（COLA SingleResponse）
|
||
|
||
`sendMessage` 接口返回 GBS COLA 格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"errCode": null,
|
||
"errMessage": null,
|
||
"data": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 用户接口（Account）
|
||
|
||
### 1. 新增用户（注册）
|
||
|
||
```
|
||
POST /safetyEval/images/account/save
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体（AccountAddCmd）**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `userName` | string | 否 | 用户名称/姓名 |
|
||
| `account` | string | 否 | 账号 |
|
||
| `phone` | string | 否 | 手机号 |
|
||
| `password` | string | 否 | 密码 |
|
||
| `profileUrl` | string | 否 | 头像地址 |
|
||
| `verificationCode` | string | 否 | 短信验证码 |
|
||
| `type` | integer | 否 | 类型：`1` 机构端，`2` 监管端（默认 `1`） |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"userName": "张三",
|
||
"account": "zhangsan",
|
||
"phone": "13800138000",
|
||
"password": "a123456",
|
||
"verificationCode": "123456",
|
||
"type": 1
|
||
}
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"data": {
|
||
"id": 1001,
|
||
"userName": "张三",
|
||
"account": "zhangsan",
|
||
"phone": "13800138000",
|
||
"profileUrl": null,
|
||
"type": 1,
|
||
"tenantId": 1001
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 查询用户详情
|
||
|
||
```
|
||
GET /safetyEval/images/account/get?id={id}
|
||
```
|
||
|
||
**Query 参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | long | 是 | 用户主键 ID |
|
||
|
||
**响应**：`SingleResponse<AccountCO>`
|
||
|
||
---
|
||
|
||
### 3. 修改用户
|
||
|
||
```
|
||
POST /safetyEval/images/account/modify
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体（AccountModifyCmd）**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | long | 是 | 主键 ID |
|
||
| `userName` | string | 否 | 用户名称/姓名 |
|
||
| `account` | string | 否 | 账号 |
|
||
| `phone` | string | 否 | 手机号 |
|
||
| `password` | string | 否 | 密码 |
|
||
| `profileUrl` | string | 否 | 头像地址 |
|
||
| `type` | integer | 否 | 类型：`1` 机构端，`2` 监管端 |
|
||
|
||
**响应**：`SingleResponse<AccountCO>`
|
||
|
||
---
|
||
|
||
### 4. 删除用户
|
||
|
||
```
|
||
POST /safetyEval/images/account/delete
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `data` | long | 是 | 用户主键 ID |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"data": 1001
|
||
}
|
||
```
|
||
|
||
**响应**：`SingleResponse<Void>`
|
||
|
||
---
|
||
|
||
### 5. 分页查询用户
|
||
|
||
```
|
||
GET /safetyEval/images/account/page
|
||
```
|
||
|
||
**Query 参数（AccountPageQuery）**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `current` | long | 否 | 当前页，默认 `1` |
|
||
| `size` | long | 否 | 每页条数，默认 `10` |
|
||
| `orders` | string | 否 | 排序，格式：`column:asc\|desc`，多个逗号分隔 |
|
||
| `startTime` | datetime | 否 | 开始时间，格式 `yyyy-MM-dd HH:mm:ss` |
|
||
| `endTime` | datetime | 否 | 结束时间，格式 `yyyy-MM-dd HH:mm:ss` |
|
||
| `userName` | string | 否 | 用户名称（模糊） |
|
||
| `account` | string | 否 | 账号 |
|
||
| `phone` | string | 否 | 手机号 |
|
||
| `type` | integer | 否 | 类型：`1` 机构端，`2` 监管端 |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
GET /safetyEval/images/account/page?current=1&size=10&userName=张&type=1
|
||
```
|
||
|
||
**响应**：`PageResponse<AccountCO>`
|
||
|
||
---
|
||
|
||
### 6. 用户同步 GBS
|
||
|
||
```
|
||
GET /safetyEval/images/account/syncUserToGBS?account={account}
|
||
```
|
||
|
||
**Query 参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `account` | string | 是 | 用户账号 |
|
||
|
||
**响应**：`SingleResponse<AccountCO>`
|
||
|
||
---
|
||
|
||
### 7. 验证码校验
|
||
|
||
```
|
||
GET /safetyEval/images/account/verificationCode?phone={phone}&code={code}
|
||
```
|
||
|
||
**Query 参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `phone` | string | 是 | 手机号 |
|
||
| `code` | string | 是 | 短信验证码 |
|
||
|
||
**响应**：`SingleResponse<AccountCO>`
|
||
|
||
---
|
||
|
||
### 8. 校验终端类型
|
||
|
||
```
|
||
GET /safetyEval/images/account/checkTerminalType
|
||
```
|
||
|
||
**说明**：校验当前用户是机构端还是监管端。
|
||
|
||
**响应**：`SingleResponse<Integer>`
|
||
|
||
| 返回值 | 说明 |
|
||
|--------|------|
|
||
| `1` | 机构端 |
|
||
| `2` | 监管端 |
|
||
|
||
---
|
||
|
||
### 9. 发送短信验证码
|
||
|
||
```
|
||
POST /safetyEval/images/account/sendMessage
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体（SendMessageCmd）**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `mobile` | string | **是** | 手机号 |
|
||
| `params` | object | 否 | 消息模板参数 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"mobile": "13800138000"
|
||
}
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 机构信息接口（OrgInfo）
|
||
|
||
### 10. 新增机构信息（注册）
|
||
|
||
```
|
||
POST /safetyEval/images/org-info/save
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体（OrgInfoAddCmd）**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `unitName` | string | 否 | 生产经营单位名称 |
|
||
| `creditCode` | string | 否 | 统一社会信用代码 |
|
||
| `safetyIndustryCategoryCode` | string | 否 | 安全生产监管行业类别编码 |
|
||
| `safetyIndustryCategoryName` | string | 否 | 安全生产监管行业类别名称 |
|
||
| `districtCode` | string | 否 | 所属县区编码 |
|
||
| `districtName` | string | 否 | 所属县区名称 |
|
||
| `townStreet` | string | 否 | 所属镇街道 |
|
||
| `villageCommunity` | string | 否 | 属村社区 |
|
||
| `longitude` | decimal | 否 | 经度 |
|
||
| `latitude` | decimal | 否 | 纬度 |
|
||
| `registerAddress` | string | 否 | 注册地址 |
|
||
| `businessAddress` | string | 否 | 经营地址 |
|
||
| `ownershipTypeCode` | string | 否 | 归属类型编码 |
|
||
| `ownershipTypeName` | string | 否 | 归属类型名称 |
|
||
| `legalRepresentative` | string | 否 | 法定代表人 |
|
||
| `legalRepresentativePhone` | string | 否 | 法定代表人联系电话 |
|
||
| `principalName` | string | 否 | 主要负责人 |
|
||
| `principalPhone` | string | 否 | 主要负责人联系电话 |
|
||
| `safetyDeptManager` | string | 否 | 安全管理部门负责人 |
|
||
| `safetyDeptManagerPhone` | string | 否 | 安全管理部门负责人联系电话 |
|
||
| `safetyDeputyPhone` | string | 否 | 主管安全副总联系电话 |
|
||
| `productionDate` | date | 否 | 投产日期，格式 `yyyy-MM-dd` |
|
||
| `businessStatusCode` | integer | 否 | 企业经营状态编码 |
|
||
| `businessStatusName` | string | 否 | 企业经营状态名称 |
|
||
| `infoDisclosureUrl` | string | 否 | 信息公开网址 |
|
||
| `workplaceArea` | decimal | 否 | 工作场所建筑面积（平方米） |
|
||
| `archiveRoomArea` | decimal | 否 | 档案室面积（平方米） |
|
||
| `fulltimeEvaluatorCount` | integer | 否 | 专职安全评价师数量 |
|
||
| `registeredEngineerCount` | integer | 否 | 注册安全工程师数量 |
|
||
| `economyIndustryCode` | string | 否 | 国民经济行业分类编码 |
|
||
| `economyIndustryName` | string | 否 | 国民经济行业分类名称 |
|
||
| `authStatusCode` | integer | 否 | 认证状态：`1` 填写信息，`2` 审核中，`3` 通过 |
|
||
| `authStatusName` | string | 否 | 认证状态名称 |
|
||
| `enterpriseStatusCode` | integer | 否 | 企业状态：`1` 正常，`2` 停业，`3` 注销 |
|
||
| `enterpriseStatusName` | string | 否 | 企业状态名称 |
|
||
| `enterpriseScaleCode` | string | 否 | 企业规模编码 |
|
||
| `enterpriseScaleName` | string | 否 | 企业规模名称（大/中/小/微型） |
|
||
| `filingTypeCode` | string | 否 | 备案类型：`1` 审核备案，`2` 确认备案 |
|
||
| `filingTypeName` | string | 否 | 备案类型名称 |
|
||
| `filingRecordStatusCode` | integer | 否 | 备案状态：`1` 已备案，`2` 未备案 |
|
||
| `filingRecordStatusName` | string | 否 | 备案状态名称 |
|
||
| `attachmentUrls` | string | 否 | 上传附件地址（多个逗号分隔） |
|
||
| `registerUserId` | long | 否 | 注册用户 ID |
|
||
|
||
**响应**：`SingleResponse<OrgInfoCO>`
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### AccountCO
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | long | 主键 ID |
|
||
| `userName` | string | 用户名称/姓名 |
|
||
| `account` | string | 账号 |
|
||
| `phone` | string | 手机号 |
|
||
| `profileUrl` | string | 头像地址 |
|
||
| `type` | integer | `1` 机构端，`2` 监管端 |
|
||
| `tenantId` | long | 租户 ID |
|
||
|
||
### OrgInfoCO（主要字段）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | long | 主键 ID |
|
||
| `unitName` | string | 单位名称 |
|
||
| `creditCode` | string | 统一社会信用代码 |
|
||
| `authStatusCode` | integer | 认证状态编码 |
|
||
| `enterpriseStatusCode` | integer | 企业状态编码 |
|
||
| `filingRecordStatusCode` | integer | 备案状态编码 |
|
||
| `state` | integer | 状态：`0` 启用，`1` 禁用 |
|
||
| `tenantId` | long | 租户 ID |
|
||
| `orgId` | long | 单位 ID |
|
||
| `createTime` | datetime | 创建时间 |
|
||
|
||
> `OrgInfoCO` 完整字段见 `OrgInfoAddCmd` 请求体字段及代码 `OrgInfoCO.java`。
|
||
|
||
---
|
||
|
||
## 与内部接口对照
|
||
|
||
| 开放接口（免鉴权） | 内部接口（需登录） |
|
||
|--------------------|--------------------|
|
||
| `/safetyEval/images/account/save` | `/safetyEval/account/save` |
|
||
| `/safetyEval/images/account/get` | `/safetyEval/account/get` |
|
||
| `/safetyEval/images/account/modify` | `/safetyEval/account/modify` |
|
||
| `/safetyEval/images/account/delete` | `/safetyEval/account/delete` |
|
||
| `/safetyEval/images/account/page` | `/safetyEval/account/page` |
|
||
| `/safetyEval/images/account/syncUserToGBS` | `/safetyEval/account/syncUserToGBS` |
|
||
| `/safetyEval/images/account/verificationCode` | `/safetyEval/account/verificationCode` |
|
||
| `/safetyEval/images/account/checkTerminalType` | `/safetyEval/account/checkTerminalType` |
|
||
| `/safetyEval/images/account/sendMessage` | —（仅开放接口） |
|
||
| `/safetyEval/images/org-info/save` | `/safetyEval/org-info/save` |
|
||
|
||
---
|
||
|
||
*文档来源：`ImagesOpenController.java`，生成时间：2026-07-08*
|