docs: initialize harness coding docs

2026-06-22 22:23:17 +08:00
commit e871103760
13 changed files with 1209 additions and 0 deletions
@@ -0,0 +1,199 @@
+# 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 字段顺序。
+- 同步是否需要防并发锁。
+- 删除站点前是否需要二次确认。