docs: add comprehensive client API reference

wiki/api/01-ads.md

@@ -0,0 +1,63 @@
+# ADS API
+
+广告获取与投放内容读取。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/ads/{Service}/{Method}`
+- 原生 gRPC：`/ads.{Service}/{Method}`
+- grpc-gateway：`POST /ads.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Fetch` | 1 | Fetch 服务 |
+
+## Fetch
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `ByPos` | `POST /rpc/ads/Fetch/ByPos` | [`ads.ByPosRequest`](#adsbyposrequest) | [`ads.ByPosReply`](#adsbyposreply) | Unary |
+
+### Fetch.ByPos
+
+- 动态 HTTP：`POST /rpc/ads/Fetch/ByPos`
+- gRPC：`/ads.Fetch/ByPos`
+- 白名单键：`ads.Fetch.ByPos`
+- 请求示例：
+
+```json
+{
+  "key": "string"
+}
+```
+
+## 消息结构
+
+### ads.AdsItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `title` | `string` | 可选 |
+| `content` | `string` | 可选 |
+| `type` | `int32` | 可选 |
+| `toUrl` | `string` | 可选 |
+| `created` | `string` | 可选 |
+
+### ads.ByPosReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `[]ads.AdsItem` | 数组 |
+
+### ads.ByPosRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |