docs: add comprehensive client API reference

wiki/api/17-logs-rest.md

@@ -0,0 +1,49 @@
+# Logs REST API
+
+集中日志写入、检索和统计。基础路径：`/rest/logs`。
+
+## 路由
+
+| 方法 | 路径 | 请求 | 响应数据 |
+|---|---|---|---|
+| GET | `/rest/logs/ping` | 无 | `{"message":"Pong"}` |
+| POST | `/rest/logs/create` | `LogData[]` | 空字符串 |
+| POST | `/rest/logs/fetch` | 查询对象 | `{data,total}` |
+| POST | `/rest/logs/total` | `{service}` | 按 level 聚合结果 |
+
+## LogData
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | uint | 日志 ID；创建时通常省略 |
+| `created_at` | RFC3339 string | 创建时间；创建时通常省略 |
+| `service` | string | 服务名 |
+| `op_id` | uint | 操作人 ID |
+| `op_name` | string | 操作人名称 |
+| `ip` | string | 操作 IP |
+| `data_type` | string | 数据类型 |
+| `level` | uint | `1=信息`、`2=警告`、`3=错误` |
+| `content` | string | 日志内容 |
+| `hmac` | string | 完整性校验值 |
+| `encry` | bool | 是否加密；不写入数据库字段 |
+
+创建示例：
+
+```json
+[
+  {
+    "service": "passport",
+    "op_id": 1001,
+    "op_name": "client",
+    "ip": "203.0.113.10",
+    "data_type": "login",
+    "level": 1,
+    "content": "login success"
+  }
+]
+```
+
+查询支持 `op_name`、`service`、`op_ip`、`level`、`page`、`size`。当前实现的分页变量未从请求对象赋值，因此实际使用默认 `page=1,size=50`；客户端不要依赖自定义分页，修复后文档需同步更新。
+
+安全限制：当前 `/create` 实现拒绝来自 loopback 和常见私网网段的请求。部署在内网反向代理之后时需要确认 `ClientIP` 配置，否则日志写入可能被拒绝。
+