docs: add comprehensive client API reference

wiki/api/00-overview.md

@@ -0,0 +1,93 @@
+# API 接入总览
+
+本文档面向 Web、移动端和第三方客户端开发者。默认示例基于 `all` 聚合服务：gRPC 监听 `12000`，HTTP 监听 `12001`，实际地址以 `all/etc/<workspace>_<runtime>.yaml` 为准。
+
+## 协议入口
+
+| 类型 | 地址格式 | 说明 |
+|---|---|---|
+| 原生 gRPC | `/{package}.{Service}/{Method}` | 高性能内部调用，使用 protobuf 二进制协议 |
+| 动态 HTTP RPC | `POST /rpc/{package}/{Service}/{Method}` | JSON 请求动态转换为 PB，再调用本机 gRPC；当前仅支持 unary |
+| grpc-gateway | `POST /{package}.{Service}/{Method}` | 由各模块生成代码注册的兼容 HTTP 路由 |
+| 原生 REST | `/rest/{module}/{path}` | FTS、Logs、MGT 的 Gin HTTP 接口 |
+
+示例：
+
+```http
+POST /rpc/passport/Login/Pwd
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{"account":"demo","password":"secret"}
+```
+
+## 动态 RPC 响应
+
+动态 RPC 无论成功或失败均返回 HTTP 200，客户端必须判断 `code`。
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "data": {}
+}
+```
+
+错误示例：
+
+```json
+{
+  "code": 7,
+  "message": "dynamic RPC method is not allowed",
+  "details": []
+}
+```
+
+`code` 使用 gRPC status code：`0=OK`、`3=InvalidArgument`、`5=NotFound`、`7=PermissionDenied`、`16=Unauthenticated`。
+
+## JSON 与 protobuf 规则
+
+- 字段采用 protobuf JSON 名称，即生成 Go 字段的 `json_name`。
+- `int64`、`uint64` 在 JSON 中建议使用字符串，避免 JavaScript 精度丢失。
+- 枚举可传枚举名称；文档的枚举章节列出允许值。
+- `bytes` 使用 Base64 字符串。
+- 未知字段会被拒绝。
+- 请求体最大 4 MiB；文件上传必须使用 FTS multipart 接口。
+
+## Header 转发
+
+动态 HTTP RPC 会向 gRPC metadata 转发：
+
+- `Authorization`
+- `X-Request-ID`
+- 其他 `X-*` Header
+
+## 鉴权说明
+
+需要身份的接口统一发送：
+
+```http
+Authorization: Bearer <token>
+```
+
+具体方法是否允许匿名由服务实现和 gRPC interceptor 决定。客户端不应仅根据请求字段推断匿名权限。
+
+## 动态 RPC 白名单
+
+`all/etc/<workspace>_<runtime>.yaml` 的 `DynamicRPC.Allow` 控制可调用范围：
+
+```yaml
+DynamicRPC:
+  Allow:
+    - passport.Login.Pwd
+    - passport.Register
+```
+
+支持完整方法名、完整服务名或 `*`。生产环境不建议使用 `*`。
+
+## 当前限制与风险
+
+- 动态 HTTP 仅支持 unary RPC，不支持 client/server/bidirectional streaming。
+- social/feed、group、relation 的公共 proto 都使用 `blocks` package，并存在 descriptor 同名冲突。客户端应按模块分别生成 SDK，暂时不要把三个模块的生成代码链接进同一 protobuf 全局 registry。
+- 文档中的请求示例表示字段形状，不代表所有字段都必须传入；校验规则仍以服务实现为准。
+