200 lines
3.2 KiB
Markdown
200 lines
3.2 KiB
Markdown
# 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 字段顺序。
|
||
- 同步是否需要防并发锁。
|
||
- 删除站点前是否需要二次确认。
|