# 安全巡检接口文档

## 1. 概述

- **基础地址**：`http://{host}:{port}`（WebAPI 独立站点，本地调试默认 `http://localhost:7143`）
- **路由规则**：`api/{controller}/{action}/{id}`
- **Controller**：`SafetyPatrol`
- **数据格式**：JSON（请求体、响应体均为 JSON）

## 2. 通用返回结构 `ResponeData`

所有接口统一返回以下结构：

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | `1` 成功，`0` 失败 |
| `message` | string | 提示消息（成功时为空，失败时为异常信息） |
| `data` | object | 业务数据（各接口不同，见下文） |

```json
{
  "code": 1,
  "message": null,
  "data": { }
}
```

## 3. 数据对象 `SafetyPatrolItem`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `PatrolId` | string | 编辑时必填 | 主键（新增时可不传，服务端自动生成 GUID） |
| `ProjectId` | string | 新增时必填 | 项目主键 |
| `HazardProjectId` | string | 否 | 危大、超危工程主键 |
| `HazardProjectName` | string | 否 | 工程名称 |
| `PatrolDate` | datetime | 否 | 巡检日期（ISO 格式，如 `2026-08-19T10:00:00`） |
| `PatrolMan` | string | 否 | 巡检人 |
| `PatrolStatus` | string | 否 | 巡检状态：`正常` / `待整改` |
| `Content` | string | 否 | 巡检内容（语音转文字） |
| `AttachUrl` | string | 否 | 巡检图片附件 URL（逗号分隔）；查询接口自动回填，新增/编辑时传入则自动写入附件表关联 |

## 4. 接口列表

### 4.1 获取安全巡检分页列表

- **请求方式**：`GET`
- **URL**：`/api/SafetyPatrol/getSafetyPatrolList`

**请求参数（Query）**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `projectId` | string | 是 | 项目主键 |
| `pageNumber` | int | 否 | 页码，从 1 开始；为 0 时不限制 |
| `pageSize` | int | 否 | 每页条数；为 0 时不限制 |
| `keyword` | string | 否 | 工程名称关键字（模糊匹配） |

**示例**

```
GET /api/SafetyPatrol/getSafetyPatrolList?projectId=xxx&pageNumber=1&pageSize=10&keyword=基坑
```

**返回 `data`**

```json
{
  "totalCount": 12,
  "dataList": [
    {
      "PatrolId": "9f1a...",
      "ProjectId": "xxx",
      "HazardProjectId": "hd-001",
      "HazardProjectName": "深基坑土方开挖工程",
      "PatrolDate": "2026-08-19T10:00:00",
      "PatrolMan": "张建国",
      "PatrolStatus": "正常",
      "Content": "现场深基坑边坡稳定，无裂缝。",
      "AttachUrl": "fileupload/safetypatrol/patrol_001.jpg,fileupload/safetypatrol/patrol_002.jpg"
    }
  ]
}
```

### 4.2 获取安全巡检详情

- **请求方式**：`GET`
- **URL**：`/api/SafetyPatrol/getSafetyPatrolById`

**请求参数（Query）**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `patrolId` | string | 是 | 巡检记录主键 |

**示例**

```
GET /api/SafetyPatrol/getSafetyPatrolById?patrolId=9f1a...
```

**返回 `data`**：单个 `SafetyPatrolItem` 对象（含 `AttachUrl`），不存在时为 `null`。

### 4.3 新增安全巡检

- **请求方式**：`POST`
- **URL**：`/api/SafetyPatrol/addSafetyPatrol`
- **Content-Type**：`application/json`

**请求体（JSON）**

```json
{
  "ProjectId": "xxx",
  "HazardProjectId": "hd-001",
  "HazardProjectName": "深基坑土方开挖工程",
  "PatrolDate": "2026-08-19T10:00:00",
  "PatrolMan": "张建国",
  "PatrolStatus": "正常",
  "Content": "现场深基坑边坡稳定，无裂缝。",
  "AttachUrl": "fileupload/safetypatrol/patrol_001.jpg"
}
```

> 说明：`AttachUrl` 非必填；传入图片 URL（多个用英文逗号分隔）时，服务端会自动写入附件表（`ToKeyId`=PatrolId、`MenuId`=SafetyPatrolMenuId），之后查询接口即可回读。

**返回 `data`**

```json
{ "patrolId": "9f1a..." }
```

> 校验：`ProjectId` 为空时返回 `code=0`，`message="项目主键不能为空！"`。

### 4.4 编辑安全巡检

- **请求方式**：`POST`
- **URL**：`/api/SafetyPatrol/updateSafetyPatrol`
- **Content-Type**：`application/json`

**请求体（JSON）**（需携带 `PatrolId`）

```json
{
  "PatrolId": "9f1a...",
  "ProjectId": "xxx",
  "HazardProjectId": "hd-001",
  "HazardProjectName": "深基坑土方开挖工程",
  "PatrolDate": "2026-08-19T10:00:00",
  "PatrolMan": "张建国",
  "PatrolStatus": "待整改",
  "Content": "边坡局部有积水，需整改。",
  "AttachUrl": "fileupload/safetypatrol/patrol_003.jpg"
}
```

> 说明：传入 `AttachUrl` 时会覆盖该记录的原有附件；不传则保留原附件不变。

**返回 `data`**：成功时无数据（`data` 为空）。

> 校验：`PatrolId` 为空返回 `"巡检主键不能为空！"`；记录不存在返回 `"未找到对应记录！"`。

## 5. 错误码

| `code` | 含义 |
|--------|------|
| `1` | 成功 |
| `0` | 失败（`message` 为具体原因，如参数校验失败、数据库异常） |