dingding_hrm/docs/api.md

API 合约

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

通用约定

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

通用错误响应：

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

健康检查

GET /api/health

{
  "ok": true
}

站点

GET /api/sites

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

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

POST /api/sites

{
  "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

触发指定站点全量同步。

成功响应：

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

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

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

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

{
  "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

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

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

人员

GET /api/sites/{site_id}/users

参数：

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

{
  "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

{
  "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 字段顺序。
• 同步是否需要防并发锁。
• 删除站点前是否需要二次确认。