docs: add comprehensive client API reference

2026-08-11 19:09:29 +08:00
parent 5b5f6f8f00
commit 2d1deb54f0
27 changed files with 10727 additions and 4 deletions
--- a/wiki/api/08-address.md
+++ b/wiki/api/08-address.md
@@ -0,0 +1,180 @@
+# ADDRESS API
+
+用户地址库管理。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/address/{Service}/{Method}`
+- 原生 gRPC：`/address.{Service}/{Method}`
+- grpc-gateway：`POST /address.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Library` | 5 | Library 服务 |
+
+## Library
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Create` | `POST /rpc/address/Library/Create` | [`address.AddressCreateRequest`](#addressaddresscreaterequest) | [`address.StatusReply`](#addressstatusreply) | Unary |
+| `Modify` | `POST /rpc/address/Library/Modify` | [`address.AddressItem`](#addressaddressitem) | [`address.StatusReply`](#addressstatusreply) | Unary |
+| `Get` | `POST /rpc/address/Library/Get` | [`address.IdentRequest`](#addressidentrequest) | [`address.AddressItem`](#addressaddressitem) | Unary |
+| `Fetch` | `POST /rpc/address/Library/Fetch` | [`address.IdentRequest`](#addressidentrequest) | [`address.AddressListReply`](#addressaddresslistreply) | Unary |
+| `Delete` | `POST /rpc/address/Library/Delete` | [`address.AddressDeleteRequest`](#addressaddressdeleterequest) | [`address.StatusReply`](#addressstatusreply) | Unary |
+
+### Library.Create
+
+- 动态 HTTP：`POST /rpc/address/Library/Create`
+- gRPC：`/address.Library/Create`
+- 白名单键：`address.Library.Create`
+- 请求示例：
+
+```json
+{
+  "area": "string",
+  "city": "string",
+  "contact": "string",
+  "country": "string",
+  "detail": "string",
+  "name": "string",
+  "phone": "string",
+  "pics": "string",
+  "province": "string",
+  "status": 0
+}
+```
+
+### Library.Modify
+
+- 动态 HTTP：`POST /rpc/address/Library/Modify`
+- gRPC：`/address.Library/Modify`
+- 白名单键：`address.Library.Modify`
+- 请求示例：
+
+```json
+{
+  "area": "string",
+  "city": "string",
+  "contact": "string",
+  "country": "string",
+  "detail": "string",
+  "id": "0",
+  "identity": "string",
+  "name": "string",
+  "phone": "string",
+  "pics": "string",
+  "province": "string",
+  "status": 0
+}
+```
+
+### Library.Get
+
+- 动态 HTTP：`POST /rpc/address/Library/Get`
+- gRPC：`/address.Library/Get`
+- 白名单键：`address.Library.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Library.Fetch
+
+- 动态 HTTP：`POST /rpc/address/Library/Fetch`
+- gRPC：`/address.Library/Fetch`
+- 白名单键：`address.Library.Fetch`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Library.Delete
+
+- 动态 HTTP：`POST /rpc/address/Library/Delete`
+- gRPC：`/address.Library/Delete`
+- 白名单键：`address.Library.Delete`
+- 请求示例：
+
+```json
+{
+  "id": [
+    "0"
+  ]
+}
+```
+
+## 消息结构
+
+### address.AddressCreateRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `phone` | `string` | 可选 |
+| `country` | `string` | 可选 |
+| `province` | `string` | 可选 |
+| `city` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `detail` | `string` | 可选 |
+| `contact` | `string` | 可选 |
+| `name` | `string` | 可选 |
+| `pics` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### address.AddressDeleteRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `[]int64` | 数组 |
+
+### address.AddressItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `country` | `string` | 可选 |
+| `province` | `string` | 可选 |
+| `city` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `detail` | `string` | 可选 |
+| `contact` | `string` | 可选 |
+| `name` | `string` | 可选 |
+| `pics` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### address.AddressListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `[]address.AddressItem` | 数组 |
+
+### address.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### address.StatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `identity` | `string` | 可选 |
+| `message` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |