# UrbanOps 开放 API 对接接口文档

> **版本**: v1.1  
> **更新日期**: 2026-06-25  
> **适用对象**: 第三方系统对接开发人员 / Co-Claw AI 助手  
> **鉴权方式**: HMAC-SHA256 API 签名  

---

## 目录

1. [概述](#1-概述)
2. [签名鉴权机制](#2-签名鉴权机制)
3. [通用规范](#3-通用规范)
4. [接口 1：团队考核查询（Co-Claw AI 专用）](#4-接口-1团队考核查询Co-Claw-ai-专用)
5. [接口 2：人员查询](#5-接口-2人员查询)
6. [接口 3：班组查询](#6-接口-3班组查询)
7. [接口 4：考勤查询](#7-接口-4考勤查询)
8. [接口 5：工单查询](#8-接口-5工单查询)
9. [接口 6：物料查询](#9-接口-6物料查询)
10. [接口 7：全量工单统计](#10-接口-7全量工单统计)
11. [错误码说明](#11-错误码说明)
12. [附录：客户端签名代码示例](#12-附录客户端签名代码示例)

---

## 1. 概述

### 1.1 基本信息

| 项目 | 说明 |
|------|------|
| 接口协议 | HTTPS |
| 接口地址 | `https://{host}/open-api/` |
| 鉴权方式 | HMAC-SHA256 API 签名（详见第2节） |
| 响应格式 | JSON |
| 字符编码 | UTF-8 |

### 1.2 接口列表

| # | 接口名称 | 路径 | 方法 | 说明 |
|---|---------|------|------|------|
| 1 | **团队考核查询** ⭐ | `/open-api/team-assessment/query` | GET | **Co-Claw AI 专用**：班组/人员考核聚合接口，含考勤/工单/耗材三维评分 |
| 2 | 人员查询 | `/open-api/staff/query` | GET | 获取人员档案，支持按部门筛选 |
| 3 | 班组查询 | `/open-api/teams/query` | GET | 获取班组信息，含班组长和人员数量 |
| 4 | 考勤查询 | `/open-api/attendance/query` | GET | 获取考勤打卡数据 |
| 5 | 工单查询 | `/open-api/tasks/query` | GET | 获取工单全生命周期数据 |
| 6 | 物料查询 | `/open-api/materials/query` | GET | 获取物料消耗与照片数据 |
| 7 | 全量工单统计 | `/open-api/full-order-statistics/query` | GET | 获取公司/班组工单/巡查/养护完成数量 |

### 1.3 接入前提

接入前需向 UrbanOps 平台申请以下凭证（由运维人员配置到 Redis）：

| 参数 | 说明 |
|------|------|
| `appId` | 应用唯一标识（由平台分配） |
| `appSecret` | 应用密钥（妥善保管，不可泄露） |

---

## 2. 签名鉴权机制

### 2.1 签名参数

每个请求必须携带以下 **4 个请求头**：

| 请求头 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `appId` | String | ✅ | 平台分配的应用 ID |
| `timestamp` | String | ✅ | 当前 Unix 时间戳（**毫秒**），与服务器时间误差不能超过 60 秒 |
| `nonce` | String | ✅ | 随机字符串，**长度 ≥ 10**，每次请求必须不同（防重放） |
| `sign` | String | ✅ | 签名字符串（SHA256 计算结果，**小写十六进制**） |

### 2.2 签名算法

#### 签名字符串构造规则

```
签名字符串 = queryParams(按key字母序排列的value拼接) 
           + headerParams(按key字母序排列的value拼接)
           + appSecret
```

**具体步骤：**

1. **排序 Query 参数值**：将 URL 中所有 query 参数按 key 字母升序排列，拼接所有 value
2. **拼接 Header 参数值**：按 key 字母升序（即 `appId` → `nonce` → `timestamp`），依次拼接它们的值
3. **追加 appSecret**：在最后拼接 `appSecret`
4. **计算 SHA256**：对上述完整字符串计算 SHA256 哈希，转为**小写十六进制**字符串

#### 签名公式

```
sign = SHA256(
    sortedQueryParamValues 
    + appId值 + nonce值 + timestamp值 
    + appSecret
)
```

> **注意**：GET 请求无 body，body 部分为空字符串（不参与签名）。

### 2.3 签名示例

假设：
- `appId` = `my_app_001`
- `appSecret` = `abc123xyz`
- 请求 URL：`/open-api/staff/query?deptId=100`

**步骤拆解：**

```
queryParams(sorted by key): 
  deptId=100
  → values = "100"

headerParams(sorted by key):
  appId=my_app_001, nonce=a1b2c3d4e5f6, timestamp=1749696000000
  → values = "my_app_001" + "a1b2c3d4e5f6" + "1749696000000"

signStr = "100" + "my_app_001" + "a1b2c3d4e5f6" + "1749696000000" + "abc123xyz"

sign = SHA256(signStr)
```

### 2.4 签名校验规则

| 校验项 | 规则 | 失败返回 |
|--------|------|----------|
| appId 非空 | 必须传递 | `400 签名不正确` |
| timestamp 时效 | `|serverTime - timestamp| ≤ 60s` | `400 签名不正确` |
| nonce 长度 | `len(nonce) ≥ 10` | `400 签名不正确` |
| sign 非空 | 必须传递 | `400 签名不正确` |
| 签名比对 | `serverSign == clientSign` | `400 签名不正确` |
| nonce 防重放 | 同一 appId + nonce 组合只能使用一次 | `900 存在重复请求` |

---

## 3. 通用规范

### 3.1 通用响应格式

```json
{
  "code": 0,
  "msg": "成功",
  "data": [ ... ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | `0` 表示成功，非 `0` 表示失败 |
| `msg` | String | 提示信息 |
| `data` | Array | 业务数据列表（根据查询条件返回所有匹配记录） |

### 3.2 日期时间格式

所有日期时间字段统一使用格式：`yyyy-MM-dd HH:mm:ss`

示例：`2026-06-11 09:00:00`

---

## 4. 接口 1：团队考核查询（Co-Claw AI 专用）⭐

> **设计定位**：本接口专为 Co-Claw AI 助手设计，提供班组/人员考核数据的**一站式聚合查询**。
> 接口内部完成考勤、工单、耗材三维度评分计算，Co-Claw 可直接使用返回的得分和扣分明细进行考核分析，
> 无需自行计算。默认只返回汇总指标（`includeDetail=false`），Token 友好。

### 4.1 考核背景

本接口基于《房山区园林所养护队智慧化管理制度》设计，考核满分 100 分，三大维度：

| 维度 | 满分 | 主要扣分规则 |
|------|------|-------------|
| 工单上线率与及时率 | **40分** | 超24h补录 -1分/次 · 超时>2h -1分/次 |
| 人员考勤管理 | **30分** | 缺勤/未打卡 -1分/次 · 缺共同处理人 -1分/次 · 未佩戴工卡 -1分/次 · 班组长记录仪未开 -1分/次 |
| 人机材录入 | **30分** | 工单完成24h内未上报耗材 -2分/次 |

### 4.2 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/team-assessment/query` |
| 方法 | `GET` |
| 说明 | 团队考核聚合查询。支持 **team 模式**（班组→人员+工单→考勤+耗材，三层结构）和 **staff 模式**（人员→考勤+工单→耗材） |

### 4.3 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `keyword` | String | **是** | — | 查询关键字：班组名称或人员姓名，**支持模糊匹配** |
| `queryMode` | String | 否 | `team` | 查询模式：`team` 按班组查询 / `staff` 按人员查询 |
| `startDate` | String | 否 | 当月1日 | 考核开始日期（格式：yyyy-MM-dd） |
| `endDate` | String | 否 | 今天 | 考核结束日期（格式：yyyy-MM-dd） |
| `includeDetail` | Boolean | 否 | `false` | 是否返回明细数据。`false` 仅返回汇总指标（推荐），`true` 同时返回考勤明细和工单耗材明细 |

### 4.4 响应字段（queryMode=team）

#### 顶层结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `queryMode` | String | 查询模式（`team` 或 `staff`） |
| `period` | PeriodVO | 考核周期 |
| `teams` | Array\<TeamVO\> | 班组考核列表（team 模式） |
| `staffList` | Array\<StaffVO\> | 人员考核列表（staff 模式，与 teams 互斥） |

#### TeamVO — 班组考核（第一层）

| 字段 | 类型 | 说明 |
|------|------|------|
| `teamId` | Long | 班组ID |
| `teamName` | String | 班组名称 |
| `parentTeamName` | String | 上级部门名称（所属养护所） |
| `leaderName` | String | 班组长姓名 |
| `totalMembers` | Long | 班组人数 |
| `score` | ScoreVO | 考核得分（详见下方） |
| `orderStats` | OrderStatsVO | 工单统计 |
| `attendanceStats` | AttendanceStatsVO | 考勤统计 |
| `materialStats` | MaterialStatsVO | 耗材统计 |
| `members` | Array\<MemberVO\> | 人员列表（**第二层**，含个人考核指标） |
| `orders` | Array\<OrderVO\> | 工单列表（**第二层**，含耗材） |

#### ScoreVO — 考核得分

| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | Integer | 总分（满分100） |
| `orderScore` | Integer | 工单得分（满分40） |
| `attendanceScore` | Integer | 考勤得分（满分30） |
| `materialScore` | Integer | 人机材得分（满分30） |
| `deductions` | Array\<DeductionVO\> | 扣分明细列表 |

**DeductionVO：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `rule` | String | 扣分规则描述 |
| `count` | Integer | 触发次数 |
| `points` | Integer | 扣分（负数） |

#### OrderStatsVO — 工单统计

| 字段 | 类型 | 说明 |
|------|------|------|
| `totalOrders` | Long | 总工单数 |
| `completedOrders` | Long | 已完成工单数 |
| `completionRate` | BigDecimal | 完成率（%） |
| `onlineRate` | BigDecimal | 线上化率（%） |
| `responseWithin30Min` | Long | 30分钟内响应数 |
| `responseRate30Min` | BigDecimal | 30分钟响应率（%） |
| `overdueOrders` | Long | 超期工单数 |
| `lateSupplementOrders` | Long | 超24小时补录工单数 |

#### AttendanceStatsVO — 考勤统计

| 字段 | 类型 | 说明 |
|------|------|------|
| `totalCheckins` | Long | 总打卡次数 |
| `absentCount` | Long | 缺勤人次 |
| `missedCheckinCount` | Long | 未触发电子围栏打卡次数 |
| `trajectoryLowCount` | Long | 轨迹覆盖率不达标次数 |
| `missingCoHandlerCount` | Long | 缺共同处理人次数 |
| `missingCardCount` | Long | 未佩戴工卡次数 |
| `multiCardViolation` | Boolean | 是否存在一人多卡违规 |
| `leaderRecorderOffCount` | Long | 班组长记录仪未开机次数 |

#### MaterialStatsVO — 耗材统计

| 字段 | 类型 | 说明 |
|------|------|------|
| `ordersWithMaterial` | Long | 已上报耗材的工单数 |
| `ordersMissingMaterial` | Long | 缺耗材上报的工单数 |
| `totalMaterialItems` | Long | 耗材总用量 |
| `materialTypes` | Long | 耗材种类数 |

#### MemberVO — 人员信息（第二层）

| 字段 | 类型 | 说明 |
|------|------|------|
| `userId` | Long | 人员ID |
| `userName` | String | 姓名 |
| `mobile` | String | 手机号 |
| `postNames` | String | 岗位名称（逗号分隔） |
| `cardNumber` | String | 工卡号 |
| `isInner` | Integer | 是否内部人员（1=内部，2=外部） |
| `personalScore` | PersonalScoreVO | 个人考核指标 |
| `attendances` | Array\<AttendanceRecordVO\> | 考勤明细（**第三层**，`includeDetail=true` 时返回） |
| `orders` | Array\<OrderVO\> | 个人工单（**第三层**，`includeDetail=true` 时返回） |

#### PersonalScoreVO — 个人考核指标

| 字段 | 类型 | 说明 |
|------|------|------|
| `attendanceDays` | Long | 出勤天数 |
| `lateCount` | Long | 迟到次数 |
| `absentCount` | Long | 缺勤次数 |
| `assignedOrders` | Long | 承担工单数 |
| `completedOrders` | Long | 完成工单数 |
| `completionRate` | BigDecimal | 完成率（%） |
| `overdueOrders` | Long | 超期工单数 |
| `materialReported` | Long | 已上报耗材工单数 |
| `materialMissing` | Long | 缺耗材上报工单数 |

#### OrderVO — 工单信息（第二层/第三层）

| 字段 | 类型 | 说明 |
|------|------|------|
| `orderNo` | String | 工单号 |
| `orderName` | String | 工单名称 |
| `orderType` | String | 工单类型：Q=快速，C=普通，O=其他 |
| `workerName` | String | 接单人姓名 |
| `status` | Integer | 审批状态 |
| `buzStatus` | String | 业务状态（completed=已完成） |
| `commitDate` | String | 发布时间 |
| `finishDate` | String | 完成时间 |
| `expectedFinishDate` | String | 期望完成时间 |
| `responseMinutes` | Long | 响应时长（分钟） |
| `isOverdue` | Boolean | 是否超期（`finishDate > expectedFinishDate`） |
| `isLateSupplement` | Boolean | 是否超24小时补录 |
| `hasMaterialReported` | Boolean | 是否已上报耗材 |
| `coHandlers` | Array\<String\> | 共同处理人姓名 |
| `materials` | Array\<MaterialVO\> | 耗材明细（**第三层**，`includeDetail=true` 时返回） |

#### 其他嵌套 VO

**AttendanceRecordVO：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `punchType` | String | 打卡类型（上班/下班） |
| `punchTime` | String | 打卡时间 |
| `address` | String | 打卡地址 |

**MaterialVO：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `materialName` | String | 耗材名称 |
| `specifications` | String | 规格 |
| `userCount` | Long | 使用数量 |
| `unitName` | String | 单位 |
| `classifyName` | String | 分类 |

**PeriodVO：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `start` | String | 考核开始日期（yyyy-MM-dd） |
| `end` | String | 考核结束日期（yyyy-MM-dd） |

### 4.5 请求示例

```bash
# team 模式：按班组名称查询考核数据（仅汇总）
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/team-assessment/query?keyword=养护一班&queryMode=team&startDate=2026-06-01&endDate=2026-06-30" \
  -H "appId: my_app_001" \
  -H "timestamp: 1749696000000" \
  -H "nonce: c3d4e5f6g7h8i9j0" \
  -H "sign: ..."

# staff 模式：按人员姓名查询考核数据（含考勤明细和工单耗材）
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/team-assessment/query?keyword=张三&queryMode=staff&includeDetail=true" \
  -H "appId: my_app_001" \
  -H "timestamp: 1749696000000" \
  -H "nonce: d4e5f6g7h8i9j0k1" \
  -H "sign: ..."
```

### 4.6 响应示例（team 模式，includeDetail=false）

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "queryMode": "team",
    "period": {
      "start": "2026-06-01",
      "end": "2026-06-30"
    },
    "teams": [
      {
        "teamId": 100,
        "teamName": "养护一班",
        "parentTeamName": "房山区园林所",
        "leaderName": "张三",
        "totalMembers": 15,
        "score": {
          "total": 85,
          "orderScore": 34,
          "attendanceScore": 25,
          "materialScore": 26,
          "deductions": [
            { "rule": "工单超24小时补录", "count": 1, "points": -1 },
            { "rule": "工单超时>2小时", "count": 2, "points": -2 },
            { "rule": "缺勤/未打卡", "count": 5, "points": -5 },
            { "rule": "人机材24h内未上报", "count": 1, "points": -2 }
          ]
        },
        "orderStats": {
          "totalOrders": 45,
          "completedOrders": 42,
          "completionRate": 93.3,
          "onlineRate": 97.8,
          "responseWithin30Min": 40,
          "responseRate30Min": 88.9,
          "overdueOrders": 2,
          "lateSupplementOrders": 1
        },
        "attendanceStats": {
          "totalCheckins": 570,
          "absentCount": 5,
          "missedCheckinCount": 5,
          "trajectoryLowCount": 1,
          "missingCoHandlerCount": 0,
          "missingCardCount": 0,
          "multiCardViolation": false,
          "leaderRecorderOffCount": 0
        },
        "materialStats": {
          "ordersWithMaterial": 42,
          "ordersMissingMaterial": 1,
          "totalMaterialItems": 230,
          "materialTypes": 15
        },
        "members": [
          {
            "userId": 1001,
            "userName": "张三",
            "mobile": "13800138001",
            "postNames": "班组长,技术员",
            "cardNumber": "DEV001",
            "isInner": 1,
            "personalScore": {
              "attendanceDays": 28,
              "lateCount": 0,
              "absentCount": 0,
              "assignedOrders": 8,
              "completedOrders": 8,
              "completionRate": 100.0,
              "overdueOrders": 0,
              "materialReported": 8,
              "materialMissing": 0
            }
          }
        ],
        "orders": [
          {
            "orderNo": "WO202606250001",
            "orderName": "树木修剪",
            "orderType": "C",
            "workerName": "张三",
            "status": 1,
            "buzStatus": "completed",
            "commitDate": "2026-06-25 09:00:00",
            "finishDate": "2026-06-25 16:30:00",
            "expectedFinishDate": "2026-06-25 18:00:00",
            "responseMinutes": 15,
            "isOverdue": false,
            "isLateSupplement": false,
            "hasMaterialReported": true,
            "coHandlers": ["李四"]
          }
        ]
      }
    ]
  }
}
```

### 4.7 响应示例（staff 模式，includeDetail=true）

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "queryMode": "staff",
    "period": {
      "start": "2026-06-01",
      "end": "2026-06-25"
    },
    "staffList": [
      {
        "userId": 1001,
        "userName": "张三",
        "mobile": "13800138001",
        "deptId": 100,
        "deptName": "养护一班",
        "postNames": "班组长",
        "cardNumber": "DEV001",
        "isInner": 1,
        "assessment": {
          "attendanceDays": 28,
          "lateCount": 0,
          "absentCount": 0,
          "assignedOrders": 8,
          "completedOrders": 8,
          "completionRate": 100.0,
          "overdueOrders": 0,
          "materialReported": 8,
          "materialMissing": 0
        },
        "attendances": [
          { "punchType": "上班", "punchTime": "2026-06-25 08:00:00", "address": "北京市房山区xx路" },
          { "punchType": "下班", "punchTime": "2026-06-25 17:30:00", "address": "北京市房山区xx路" }
        ],
        "orders": [
          {
            "orderNo": "WO202606250001",
            "orderName": "树木修剪",
            "orderType": "C",
            "workerName": "张三",
            "status": 1,
            "buzStatus": "completed",
            "commitDate": "2026-06-25 09:00:00",
            "finishDate": "2026-06-25 16:30:00",
            "expectedFinishDate": "2026-06-25 18:00:00",
            "responseMinutes": 15,
            "isOverdue": false,
            "isLateSupplement": false,
            "hasMaterialReported": true,
            "coHandlers": ["李四"],
            "materials": [
              {
                "materialName": "高效氯氰菊酯",
                "specifications": "500ml/瓶",
                "userCount": 2,
                "unitName": "瓶",
                "classifyName": "药品"
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### 4.8 使用建议（Co-ClawCo-Claw）

| 场景 | 推荐参数 | 说明 |
|------|----------|------|
| 月底考核排名 | `keyword=养护&queryMode=team` | 模糊查询所有养护班组，返回考核得分用于排名 |
| 单班组详情分析 | `keyword=养护一班&queryMode=team&includeDetail=true` | 查看特定班组全部明细，分析扣分原因 |
| 个人绩效查询 | `keyword=张三&queryMode=staff&includeDetail=true` | 查看某人出勤、工单、耗材完整记录 |
| 日常快速巡检 | `keyword=养护&includeDetail=false` | 只看汇总指标，Token 最少 |

---

## 5. 接口 2：人员查询

### 4.1 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/staff/query` |
| 方法 | `GET` |
| 说明 | 获取人员基础档案信息，支持按部门、姓名、手机号等条件筛选 |

### 4.2 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | String | 否 | 姓名，模糊匹配 |
| `mobile` | String | 否 | 手机号，模糊匹配 |
| `deptId` | Long | 否 | 部门ID，精确匹配 |
| `status` | Integer | 否 | 状态：0=启用，1=禁用 |
| `busiLine` | String | 否 | 业务线：yl=园林，wy=物业，sz=市政 |

### 4.3 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 人员ID |
| `username` | String | 用户名 |
| `nickname` | String | 姓名 |
| `mobile` | String | 手机号 |
| `deptId` | Long | 部门ID |
| `deptName` | String | 部门名称（如"养护一班"） |
| `postIds` | Array\<Long\> | 岗位ID列表 |
| `postNames` | String | 岗位名称（逗号分隔，如"班组长,技术员"） |
| `busiLine` | String | 业务线 |
| `status` | Integer | 状态（0=启用，1=禁用） |
| `cardNumber` | String | 工卡号（设备编号，用于考勤打卡） |
| `isInner` | Integer | 是否内部人员（1=内部，2=外部） |
| `createTime` | String | 入职日期（格式：yyyy-MM-dd HH:mm:ss） |

### 4.4 请求示例

```bash
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/staff/query?deptId=100" \
  -H "appId: my_app_001" \
  -H "timestamp: 1749696000000" \
  -H "nonce: a1b2c3d4e5f6g7h8" \
  -H "sign: 3a5f8c9e2b1d4f6a8c0e2b4d6f8a0c2e4b6d8f0a"
```

### 4.5 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": [
    {
        "id": 1001,
        "username": "zhangsan",
        "nickname": "张三",
        "mobile": "13800138001",
        "deptId": 100,
        "deptName": "养护一班",
        "postIds": [10, 20],
        "postNames": "班组长,技术员",
        "busiLine": "yl",
        "status": 0,
        "cardNumber": "DEV001",
        "isInner": 1,
        "createTime": "2024-01-15 00:00:00"
      }
    ],
    "total": 150
  }
```

---

## 6. 接口 3：班组查询

### 5.1 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/teams/query` |
| 方法 | `GET` |
| 说明 | 获取组织架构班组信息，含班组长、所属养护所、人员数量 |

### 5.2 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | String | 否 | 班组名称，模糊匹配 |
| `parentId` | Long | 否 | 父部门ID（上级组织），精确匹配 |
| `status` | Integer | 否 | 状态：0=启用，1=禁用 |

### 5.3 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 班组ID |
| `name` | String | 班组名称 |
| `parentId` | Long | 父部门ID |
| `parentName` | String | 父部门名称（所属养护所） |
| `leaderUserId` | Long | 班组长人员ID（Staff.id） |
| `leaderUserName` | String | 班组长姓名 |
| `memberCount` | Long | 人员数量 |
| `sort` | Integer | 排序 |
| `status` | Integer | 状态（0=启用，1=禁用） |

### 5.4 请求示例

```bash
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/teams/query" \
  -H "appId: my_app_001" \
  -H "timestamp: 1749696000000" \
  -H "nonce: b2c3d4e5f6g7h8i9" \
  -H "sign: ..."
```

### 5.5 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": [
    {
        "id": 100,
        "name": "养护一班",
        "parentId": 1,
        "parentName": "蓟城山水集团",
        "leaderUserId": 1001,
        "leaderUserName": "张三",
        "memberCount": 15,
        "sort": 1,
        "status": 0
      }
    ],
    "total": 12
  }
}
```

---

## 7. 接口 4：考勤查询

### 6.1 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/attendance/query` |
| 方法 | `GET` |
| 说明 | 获取电子围栏打卡与位置数据，支持按班组、人员、时间范围筛选 |

### 6.2 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `userId` | Long | 否 | 人员ID，精确匹配 |
| `deptId` | Long | 否 | 部门ID（班组），精确匹配 |
| `busiLine` | String | 否 | 业务线 |
| `punchType` | String | 否 | 打卡类型（上班/下班） |
| `startTime` | String | 否 | 开始时间（格式：yyyy-MM-dd HH:mm:ss） |
| `endTime` | String | 否 | 结束时间（格式：yyyy-MM-dd HH:mm:ss） |

### 6.3 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Integer | 记录ID |
| `deviceCode` | String | 设备编码 |
| `deviceName` | String | 设备名称 |
| `punchType` | String | 打卡类型 |
| `userId` | Long | 人员ID |
| `nickname` | String | 人员姓名 |
| `deptId` | Long | 部门ID |
| `deptName` | String | 部门名称 |
| `address` | String | 打卡地址 |
| `latGcj02` | BigDecimal | 高德纬度（GCJ-02坐标系） |
| `lngGcj02` | BigDecimal | 高德经度（GCJ-02坐标系） |
| `lat` | BigDecimal | WGS84纬度 |
| `lng` | BigDecimal | WGS84经度 |
| `createTime` | String | 打卡时间 |

> **注意**：当前版本暂不支持"轨迹点集""是否佩戴工卡""记录仪状态"字段（数据库无对应存储）。待业务系统确认后将补充。

### 6.4 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": [
    {
        "id": 1,
        "deviceCode": "DEV001",
        "deviceName": "打卡机01",
        "punchType": "上班",
        "userId": 1001,
        "nickname": "张三",
        "deptId": 100,
        "deptName": "养护一班",
        "address": "北京市西城区xx路xx号",
        "latGcj02": 39.9042,
        "lngGcj02": 116.4074,
        "lat": 39.9010,
        "lng": 116.4030,
        "createTime": "2026-06-11 08:30:00"
      }
    ],
    "total": 320
  }
}
```

---

## 8. 接口 5：工单查询

### 7.1 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/tasks/query` |
| 方法 | `GET` |
| 说明 | 获取工单全生命周期数据，含发布时间、状态、接单渠道、共同处理人 |

### 7.2 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderNo` | String | 否 | 工单号，模糊匹配 |
| `orderName` | String | 否 | 工单名称，模糊匹配 |
| `busiLine` | String | 否 | 业务线 |
| `status` | Integer | 否 | 审批状态 |
| `buzStatus` | String | 否 | 业务状态 |
| `workerId` | Long | 否 | 接单人ID |
| `startDate` | String | 否 | 发布时间起始（yyyy-MM-dd HH:mm:ss） |
| `endDate` | String | 否 | 发布时间截止（yyyy-MM-dd HH:mm:ss） |

### 7.3 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 工单ID |
| `orderNo` | String | 工单号 |
| `orderName` | String | 工单名称 |
| `orderType` | String | 工单类型：Q=快速，C=普通，O=其他 |
| `busiLine` | String | 业务线 |
| `commitDate` | String | 发布时间（工单派发时间） |
| `finishDate` | String | 完成时间 |
| `userId` | Long | 发布人ID |
| `userName` | String | 发布人姓名 |
| `workerId` | Long | 接单人ID |
| `workerName` | String | 接单人姓名 |
| `coHandlers` | Array\<String\> | 共同处理人姓名列表 |
| `woSourceName` | String | 接单渠道（小程序/人工派单等） |
| `status` | Integer | 审批状态 |
| `buzStatus` | String | 业务状态 |
| `remark` | String | 备注 |
| `photos` | Array\<PhotoVO\> | 工单附件照片 |

**PhotoVO 结构：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `busiType` | String | 业务类型：`01`=问题照片，`02`=处理中，`03`=完成 |
| `fileName` | String | 文件名 |
| `url` | String | 文件URL |

### 7.4 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": [
    {
        "id": 5001,
        "orderNo": "WO202606110001",
        "orderName": "树木修剪",
        "orderType": "C",
        "busiLine": "yl",
        "commitDate": "2026-06-11 09:00:00",
        "finishDate": null,
        "userId": 1,
        "userName": "管理员",
        "workerId": 1001,
        "workerName": "张三",
        "coHandlers": ["李四", "王五"],
        "woSourceName": "小程序",
        "status": 1,
        "buzStatus": "processing",
        "remark": "紧急处理",
        "photos": [
          {
            "busiType": "01",
            "fileName": "problem.jpg",
            "url": "https://xxx.com/file/abc.jpg"
          }
        ]
      }
    ],
    "total": 85
  }
}
```

---

## 9. 接口 6：物料查询

### 8.1 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/materials/query` |
| 方法 | `GET` |
| 说明 | 获取物料消耗记录与人机材照片数据，支持按工单筛选 |

### 8.2 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderNo` | String | 否 | 工单号，精确匹配 |
| `classifyName` | String | 否 | 物料分类名，模糊匹配 |
| `typeName` | String | 否 | 物料类型名，模糊匹配 |
| `userId` | Long | 否 | 使用人ID |
| `startDate` | String | 否 | 开始时间（yyyy-MM-dd HH:mm:ss） |
| `endDate` | String | 否 | 结束时间（yyyy-MM-dd HH:mm:ss） |

### 8.3 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 记录ID |
| `orderNo` | String | 关联工单号 |
| `materialName` | String | 物料名称 |
| `specifications` | String | 规格 |
| `userCount` | Long | 使用数量 |
| `unitName` | String | 单位 |
| `classifyName` | String | 物料分类 |
| `typeName` | String | 物料类型 |
| `typeDetailName` | String | 物料明细类型 |
| `userId` | Long | 使用人ID |
| `userName` | String | 使用人姓名 |
| `source` | Integer | 来源：1=工单，2=巡检，3=养护 |
| `createTime` | String | 上传时间 |
| `photos` | Array\<PhotoVO\> | 人机材照片（结构同工单接口） |

### 8.4 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": [
    {
        "id": 3001,
        "orderNo": "WO202606110001",
        "materialName": "高效氯氰菊酯",
        "specifications": "500ml/瓶",
        "userCount": 5,
        "unitName": "瓶",
        "classifyName": "药品",
        "typeName": "杀虫剂",
        "typeDetailName": "有机磷",
        "userId": 1001,
        "userName": "张三",
        "source": 1,
        "createTime": "2026-06-11 14:30:00",
        "photos": [
          {
            "busiType": "02",
            "fileName": "material.jpg",
            "url": "https://xxx.com/file/def.jpg"
          }
        ]
      }
    ],
    "total": 45
  }
}
```

---

## 10. 接口 7：全量工单统计

### 9.1 基本信息

| 项目 | 说明 |
|------|------|
| 路径 | `/open-api/full-order-statistics/query` |
| 方法 | `GET` |
| 说明 | 获取各公司/班组在一段时间内实际完成的工单数量、巡查记录数量、养护记录数量 |

### 9.2 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `companyId` | Long | 否 | 公司/班组ID，精确匹配 |
| `companyName` | String | 否 | 公司/班组名称，模糊匹配 |
| `type` | Integer | 否 | 类型：1=按公司，2=按班组 |
| `startDate` | String | 否 | 统计开始日期（格式：yyyy-MM-dd，返回开始日期>=该值的记录） |
| `endDate` | String | 否 | 统计结束日期（格式：yyyy-MM-dd，返回结束日期<=该值的记录） |

### 9.3 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 记录ID |
| `companyId` | Long | 公司/班组ID |
| `companyName` | String | 公司/班组名称 |
| `type` | Integer | 类型：1=按公司，2=按班组 |
| `startDate` | String | 统计开始日期 |
| `endDate` | String | 统计结束日期 |
| `workOrderCount` | Integer | 工单完成数量 |
| `inspectionCount` | Integer | 巡查记录数量 |
| `maintenanceCount` | Integer | 养护记录数量 |
| `remark` | String | 备注 |
| `createTime` | String | 创建时间 |

### 9.4 请求示例

```bash
curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/full-order-statistics/query?type=1&startDate=2026-06-01&endDate=2026-06-30" \
  -H "appId: my_app_001" \
  -H "timestamp: 1749696000000" \
  -H "nonce: f6g7h8i9j0k1l2m3" \
  -H "sign: ..."
```

### 9.5 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 1,
      "companyId": 100,
      "companyName": "养护一班",
      "type": 1,
      "startDate": "2026-06-01",
      "endDate": "2026-06-30",
      "workOrderCount": 85,
      "inspectionCount": 120,
      "maintenanceCount": 60,
      "remark": "二季度统计",
      "createTime": "2026-06-11 10:00:00"
    }
  ]
}
```

---

## 11. 错误码说明

### 11.1 签名相关错误

| code | msg | 说明 |
|------|-----|------|
| 400 | 签名不正确 | 签名验证失败（appId不存在/timestamp超时/nonce长度不足/签名不匹配） |
| 900 | 存在重复请求 | nonce 已被使用（重放攻击检测） |

### 11.2 业务接口错误

| code | msg | 说明 |
|------|-----|------|
| 1-100-020-001 | 人员查询失败 | 人员查询内部错误 |
| 1-100-020-002 | 班组查询失败 | 班组查询内部错误 |
| 1-100-020-003 | 考勤查询失败 | 考勤查询内部错误 |
| 1-100-020-004 | 工单查询失败 | 工单查询内部错误 |
| 1-100-020-005 | 物料查询失败 | 物料查询内部错误 |
| 1-100-020-006 | 团队考核查询失败 | 团队考核聚合查询内部错误 |
| 1-900-005-001 | 全量工单统计不存在 | 记录不存在 |
| 1-900-005-002 | 相同公司/班组同时间段统计已存在 | 重复数据校验 |

### 11.3 通用错误

| code | msg | 说明 |
|------|-----|------|
| 400 | 参数校验失败 | 请求参数格式或值不正确 |
| 500 | 系统内部错误 | 服务器内部异常 |

---

## 12. 附录：客户端签名代码示例

### 12.1 Java 示例

```java
import cn.hutool.crypto.digest.DigestUtil;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.core.util.RandomUtil;

import java.util.Map;
import java.util.TreeMap;

public class OpenApiClient {

    private static final String BASE_URL = "https://test.jichengshanshui.com.cn:28302";
    private static final String APP_ID = "your_app_id";
    private static final String APP_SECRET = "your_app_secret";

    public static String call(String path, Map<String, Object> params) {
        String timestamp = String.valueOf(System.currentTimeMillis());
        String nonce = RandomUtil.randomString(16);
        String sign = buildSign(params, timestamp, nonce);

        String url = BASE_URL + path;
        HttpResponse response = HttpRequest.get(url)
                .form(params)
                .header("appId", APP_ID)
                .header("timestamp", timestamp)
                .header("nonce", nonce)
                .header("sign", sign)
                .execute();
        return response.body();
    }

    private static String buildSign(Map<String, Object> params,
                                     String timestamp, String nonce) {
        StringBuilder sb = new StringBuilder();

        // 1. 排序 query 参数值
        if (params != null && !params.isEmpty()) {
            new TreeMap<>(params).values().stream()
                    .map(String::valueOf).forEach(sb::append);
        }

        // 2. header 参数值（appId, nonce, timestamp 字母序）
        sb.append(APP_ID);
        sb.append(nonce);
        sb.append(timestamp);

        // 3. 追加 appSecret + SHA256
        sb.append(APP_SECRET);
        return DigestUtil.sha256Hex(sb.toString());
    }
}
```

### 12.2 Python 示例

```python
import hashlib
import time
import random
import string
import requests

BASE_URL = "https://test.jichengshanshui.com.cn:28302"
APP_ID = "your_app_id"
APP_SECRET = "your_app_secret"

def build_sign(params, timestamp, nonce):
    parts = []
    if params:
        for key in sorted(params.keys()):
            parts.append(str(params[key]))
    parts.append(APP_ID)
    parts.append(nonce)
    parts.append(timestamp)
    parts.append(APP_SECRET)
    sign_str = "".join(parts)
    return hashlib.sha256(sign_str.encode()).hexdigest()

def call(path, params=None):
    if params is None:
        params = {}
    timestamp = str(int(time.time() * 1000))
    nonce = "".join(random.choices(string.ascii_lowercase + string.digits, k=16))
    sign = build_sign(params, timestamp, nonce)
    headers = {
        "appId": APP_ID,
        "timestamp": timestamp,
        "nonce": nonce,
        "sign": sign
    }
    response = requests.get(BASE_URL + path, params=params, headers=headers)
    return response.json()
```

### 12.3 Shell (cURL) 示例

```bash
#!/bin/bash
APP_ID="your_app_id"
APP_SECRET="your_app_secret"
TIMESTAMP=$(date +%s%3N)
NONCE=$(openssl rand -hex 16)

# 示例：/open-api/staff/query?deptId=100
# query params 排序后 values: deptId=100 → "100"
QUERY_VALUES="100"
HEADER_VALUES="${APP_ID}${NONCE}${TIMESTAMP}"
SIGN_STR="${QUERY_VALUES}${HEADER_VALUES}${APP_SECRET}"
SIGN=$(echo -n "$SIGN_STR" | openssl dgst -sha256 -hex | awk '{print $2}')

curl -X GET "https://test.jichengshanshui.com.cn:28302/open-api/staff/query?deptId=100" \
  -H "appId: ${APP_ID}" \
  -H "timestamp: ${TIMESTAMP}" \
  -H "nonce: ${NONCE}" \
  -H "sign: ${SIGN}"
```

---

> **本文档基于 2026-06-11 代码生成，如有接口变更请同步更新。**