cq_anquan
/
safety-eval-website
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
safety-eval-website/docs/对外开放接口-images.md

444 lines
12 KiB
Markdown
Raw Permalink Normal View History

h5
2026-07-09 10:05:52 +08:00
# 对外开放接口文档（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*