# API 合约

> 本文定义 Go + Gin 后端 API 的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。

## 通用约定

- 传输：HTTP JSON，同源 `/api/*`。
- 鉴权：MVP 无账号。
- 请求体和响应体编码：UTF-8 JSON。
- 时间格式：ISO 8601 字符串；钉钉原始时间戳字段保留原值。
- 分页参数：`page` 从 1 开始，`size` 默认 20，最大 200。

通用错误响应：

```json
{
  "error": {
    "code": "bad_request",
    "message": "请求参数不正确"
  }
}
```

## 健康检查

### `GET /api/health`

```json
{
  "ok": true
}
```

## 站点

### `GET /api/sites`

返回站点列表。不得返回 `app_secret` 明文。

```json
{
  "items": [
    {
      "id": 1,
      "code": "meizhou",
      "name": "梅州",
      "has_secret": true,
      "updated_at": "2026-06-22T21:00:00+08:00"
    }
  ]
}
```

### `POST /api/sites`

```json
{
  "code": "meizhou",
  "name": "梅州",
  "app_key": "example",
  "app_secret": "example"
}
```

### `PUT /api/sites/{site_id}`

更新站点名称、app_key、app_secret。未提交的 secret 保持不变。

### `DELETE /api/sites/{site_id}`

删除站点及其 token、部门、人员、同步日志。

## 同步

### `POST /api/sites/{site_id}/sync/full`

触发指定站点全量同步。

成功响应：

```json
{
  "log_id": 10,
  "status": "success",
  "departments": 120,
  "users": 3500
}
```

失败时返回 4xx / 5xx，并写入同步日志。

### `POST /api/sites/{site_id}/sync/token`

手动刷新 token。响应不返回 token 明文。

```json
{
  "status": "success",
  "expires_at": "2026-06-22T23:00:00+08:00"
}
```

### `GET /api/sync/logs`

查询同步日志。参数：`site_id`、`status`、`page`、`size`。

## 部门

### `GET /api/sites/{site_id}/departments`

返回平铺部门列表，前端组装树。

```json
{
  "items": [
    {
      "dept_id": 1,
      "parent_id": 0,
      "name": "总部"
    }
  ]
}
```

## 人员

### `GET /api/sites/{site_id}/users`

参数：

- `keyword`：匹配姓名、手机号、工号。
- `dept_id`：按主部门筛选。
- `active`：`1` 或 `0`。
- `page`：页码。
- `size`：每页数量。

```json
{
  "items": [
    {
      "userid": "u001",
      "name": "张三",
      "mobile": "138****0000",
      "title": "工程师",
      "job_number": "A001",
      "dept_id": 1,
      "dept_name": "研发部",
      "active": 1
    }
  ],
  "page": 1,
  "size": 20,
  "total": 1
}
```

### `GET /api/sites/{site_id}/users/{userid}`

返回单个人员详情。默认不脱敏；如后续增加权限，再调整。

## 导出

### `GET /api/sites/{site_id}/export/users`

参数：

- `format`：`json` 或 `csv`。
- 其余筛选参数同 `GET /users`。

响应：

- `format=json`：`application/json; charset=utf-8`
- `format=csv`：`text/csv; charset=utf-8`

## 统计

### `GET /api/stats`

```json
{
  "sites": [
    {
      "site_id": 1,
      "site_name": "梅州",
      "department_count": 120,
      "user_count": 3500,
      "last_sync_at": "2026-06-22T21:00:00+08:00",
      "last_sync_status": "success"
    }
  ]
}
```

## 待实现时确认

- 手机号列表页是否默认脱敏。
- CSV 字段顺序。
- 同步是否需要防并发锁。
- 删除站点前是否需要二次确认。