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。
+- 文档中的请求示例表示字段形状，不代表所有字段都必须传入；校验规则仍以服务实现为准。
+

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` | 可选 |

wiki/api/04-feedback.md

@@ -0,0 +1,307 @@
+# FEEDBACK API
+
+用户反馈提交与查询。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/feedback/{Service}/{Method}`
+- 原生 gRPC：`/feedback.{Service}/{Method}`
+- grpc-gateway：`POST /feedback.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Method` | 6 | Method 服务 |
+
+## Method
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `List` | `POST /rpc/feedback/Method/List` | [`feedback.ListRequest`](#feedbacklistrequest) | [`feedback.ListReply`](#feedbacklistreply) | Unary |
+| `Get` | `POST /rpc/feedback/Method/Get` | [`feedback.GetRequest`](#feedbackgetrequest) | [`feedback.GetReply`](#feedbackgetreply) | Unary |
+| `Add` | `POST /rpc/feedback/Method/Add` | [`feedback.AddRequest`](#feedbackaddrequest) | [`feedback.AddReply`](#feedbackaddreply) | Unary |
+| `Modify` | `POST /rpc/feedback/Method/Modify` | [`feedback.ModifyRequest`](#feedbackmodifyrequest) | [`feedback.StatusReply`](#feedbackstatusreply) | Unary |
+| `Delete` | `POST /rpc/feedback/Method/Delete` | [`feedback.DeleteRequest`](#feedbackdeleterequest) | [`feedback.StatusReply`](#feedbackstatusreply) | Unary |
+| `Remark` | `POST /rpc/feedback/Method/Remark` | [`feedback.RemarkRequest`](#feedbackremarkrequest) | [`feedback.StatusReply`](#feedbackstatusreply) | Unary |
+
+### Method.List
+
+- 动态 HTTP：`POST /rpc/feedback/Method/List`
+- gRPC：`/feedback.Method/List`
+- 白名单键：`feedback.Method.List`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "category": "string",
+  "email": "string",
+  "page": "0",
+  "phone": "string",
+  "size": "0",
+  "status": 0,
+  "store_identity": "string",
+  "user_identity": "string",
+  "user_name": "string"
+}
+```
+
+### Method.Get
+
+- 动态 HTTP：`POST /rpc/feedback/Method/Get`
+- gRPC：`/feedback.Method/Get`
+- 白名单键：`feedback.Method.Get`
+- 请求示例：
+
+```json
+{
+  "identity": "string"
+}
+```
+
+### Method.Add
+
+- 动态 HTTP：`POST /rpc/feedback/Method/Add`
+- gRPC：`/feedback.Method/Add`
+- 白名单键：`feedback.Method.Add`
+- 请求示例：
+
+```json
+{
+  "accessories": [
+    {
+      "file_path": "string",
+      "identity": "string",
+      "item_identity": "string",
+      "title": "string"
+    }
+  ],
+  "agency": "string",
+  "category": "string",
+  "content": "string",
+  "email": "string",
+  "images": [
+    {
+      "identity": "string",
+      "itemIdentity": "string",
+      "url": "string"
+    }
+  ],
+  "phone": "string",
+  "status": 0,
+  "store_identity": "string",
+  "title": "string",
+  "user_identity": "string",
+  "user_name": "string"
+}
+```
+
+### Method.Modify
+
+- 动态 HTTP：`POST /rpc/feedback/Method/Modify`
+- gRPC：`/feedback.Method/Modify`
+- 白名单键：`feedback.Method.Modify`
+- 请求示例：
+
+```json
+{
+  "accessories": [
+    {
+      "file_path": "string",
+      "identity": "string",
+      "item_identity": "string",
+      "title": "string"
+    }
+  ],
+  "agency": "string",
+  "category": "string",
+  "content": "string",
+  "email": "string",
+  "identity": "string",
+  "images": [
+    {
+      "identity": "string",
+      "itemIdentity": "string",
+      "url": "string"
+    }
+  ],
+  "phone": "string",
+  "status": 0,
+  "store_identity": "string",
+  "title": "string",
+  "user_identity": "string",
+  "user_name": "string"
+}
+```
+
+### Method.Delete
+
+- 动态 HTTP：`POST /rpc/feedback/Method/Delete`
+- gRPC：`/feedback.Method/Delete`
+- 白名单键：`feedback.Method.Delete`
+- 请求示例：
+
+```json
+{
+  "identity": "string"
+}
+```
+
+### Method.Remark
+
+- 动态 HTTP：`POST /rpc/feedback/Method/Remark`
+- gRPC：`/feedback.Method/Remark`
+- 白名单键：`feedback.Method.Remark`
+- 请求示例：
+
+```json
+{
+  "identity": "string",
+  "remark": "string",
+  "status": 0
+}
+```
+
+## 消息结构
+
+### feedback.AddReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+
+### feedback.AddRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `user_identity` | `string` | 可选 |
+| `user_name` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `title` | `string` | 可选 |
+| `content` | `string` | 可选 |
+| `images` | `[]feedback.FeedbackImage` | 数组 |
+| `category` | `string` | 可选 |
+| `accessories` | `[]feedback.FeedbackAccessory` | 数组 |
+| `email` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `store_identity` | `string` | 可选 |
+| `agency` | `string` | 可选 |
+
+### feedback.DeleteRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+
+### feedback.FeedbackAccessory
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `item_identity` | `string` | 可选 |
+| `title` | `string` | 可选 |
+| `file_path` | `string` | 可选 |
+
+### feedback.FeedbackImage
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `itemIdentity` | `string` | 可选 |
+| `url` | `string` | 可选 |
+
+### feedback.FeedbackItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `user_identity` | `string` | 可选 |
+| `user_name` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `created_at` | `string` | 可选 |
+| `updated_at` | `string` | 可选 |
+| `title` | `string` | 可选 |
+| `content` | `string` | 可选 |
+| `images` | `[]feedback.FeedbackImage` | 数组 |
+| `remark` | `string` | 可选 |
+| `category` | `string` | 可选 |
+| `accessories` | `[]feedback.FeedbackAccessory` | 数组 |
+| `email` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `store_identity` | `string` | 可选 |
+| `agency` | `string` | 可选 |
+
+### feedback.GetReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `record` | `feedback.FeedbackItem` | 可选 |
+| `exists` | `bool` | 可选 |
+
+### feedback.GetRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+
+### feedback.ListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `count` | `int64` | 可选 |
+| `list` | `[]feedback.FeedbackItem` | 数组 |
+
+### feedback.ListRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `page` | `int64` | 可选 |
+| `size` | `int64` | 可选 |
+| `user_identity` | `string` | 可选 |
+| `user_name` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `category` | `string` | 可选 |
+| `email` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `store_identity` | `string` | 可选 |
+| `agency` | `string` | 可选 |
+
+### feedback.ModifyRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `user_identity` | `string` | 可选 |
+| `user_name` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `title` | `string` | 可选 |
+| `content` | `string` | 可选 |
+| `images` | `[]feedback.FeedbackImage` | 数组 |
+| `category` | `string` | 可选 |
+| `accessories` | `[]feedback.FeedbackAccessory` | 数组 |
+| `email` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `store_identity` | `string` | 可选 |
+| `agency` | `string` | 可选 |
+
+### feedback.RemarkRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `remark` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### feedback.StatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `message` | `string` | 可选 |
+| `details` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |

wiki/api/05-initial.md

@@ -0,0 +1,247 @@
+# INITIAL API
+
+客户端初始化、基础数据和版本更新检查。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/initial/{Service}/{Method}`
+- 原生 gRPC：`/initial.{Service}/{Method}`
+- grpc-gateway：`POST /initial.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Check` | 3 | Check 服务 |
+| `Data` | 3 | Data 服务 |
+
+## Check
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Hello` | `POST /rpc/initial/Check/Hello` | [`initial.Crc`](#initialcrc) | [`initial.StatusReply`](#initialstatusreply) | Unary |
+| `Config` | `POST /rpc/initial/Check/Config` | [`initial.ConfigRequest`](#initialconfigrequest) | [`initial.ConfigReply`](#initialconfigreply) | Unary |
+| `Updates` | `POST /rpc/initial/Check/Updates` | [`initial.CheckForUpdatesRequest`](#initialcheckforupdatesrequest) | [`initial.CheckForUpdatesReply`](#initialcheckforupdatesreply) | Unary |
+
+### Check.Hello
+
+- 动态 HTTP：`POST /rpc/initial/Check/Hello`
+- gRPC：`/initial.Check/Hello`
+- 白名单键：`initial.Check.Hello`
+- 请求示例：
+
+```json
+{
+  "code": "string"
+}
+```
+
+### Check.Config
+
+- 动态 HTTP：`POST /rpc/initial/Check/Config`
+- gRPC：`/initial.Check/Config`
+- 白名单键：`initial.Check.Config`
+- 请求示例：
+
+```json
+{
+  "app": "string",
+  "os": "string"
+}
+```
+
+### Check.Updates
+
+- 动态 HTTP：`POST /rpc/initial/Check/Updates`
+- gRPC：`/initial.Check/Updates`
+- 白名单键：`initial.Check.Updates`
+- 请求示例：
+
+```json
+{
+  "app": "string",
+  "arch": "string",
+  "os": "string",
+  "version": "string"
+}
+```
+
+## Data
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Country` | `POST /rpc/initial/Data/Country` | [`initial.Empty`](#initialempty) | [`initial.CountryReply`](#initialcountryreply) | Unary |
+| `Areas` | `POST /rpc/initial/Data/Areas` | [`initial.AreasRequest`](#initialareasrequest) | [`initial.AreasReply`](#initialareasreply) | Unary |
+| `Datas` | `POST /rpc/initial/Data/Datas` | [`initial.Empty`](#initialempty) | [`initial.DatasReply`](#initialdatasreply) | Unary |
+
+### Data.Country
+
+- 动态 HTTP：`POST /rpc/initial/Data/Country`
+- gRPC：`/initial.Data/Country`
+- 白名单键：`initial.Data.Country`
+- 请求示例：
+
+```json
+{}
+```
+
+### Data.Areas
+
+- 动态 HTTP：`POST /rpc/initial/Data/Areas`
+- gRPC：`/initial.Data/Areas`
+- 白名单键：`initial.Data.Areas`
+- 请求示例：
+
+```json
+{
+  "countryCode": "string",
+  "countryId": 0,
+  "showTown": false
+}
+```
+
+### Data.Datas
+
+- 动态 HTTP：`POST /rpc/initial/Data/Datas`
+- gRPC：`/initial.Data/Datas`
+- 白名单键：`initial.Data.Datas`
+- 请求示例：
+
+```json
+{}
+```
+
+## 消息结构
+
+### initial.AreasItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `string` | 可选 |
+| `pid` | `string` | 可选 |
+| `deep` | `int32` | 可选 |
+| `name` | `string` | 可选 |
+| `pinyinPrefix` | `string` | 可选 |
+| `pinyin` | `string` | 可选 |
+| `extId` | `string` | 可选 |
+| `extName` | `string` | 可选 |
+
+### initial.AreasReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `areas` | `[]initial.AreasItem` | 数组 |
+
+### initial.AreasRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `countryId` | `int32` | 可选 |
+| `countryCode` | `string` | 可选 |
+| `showTown` | `bool` | 可选 |
+
+### initial.CheckForUpdatesReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `version` | `string` | 可选 |
+| `summary` | `string` | 可选 |
+| `files` | `string` | 可选 |
+| `pubdate` | `string` | 可选 |
+
+### initial.CheckForUpdatesRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `app` | `string` | 可选 |
+| `os` | `string` | 可选 |
+| `arch` | `string` | 可选 |
+| `version` | `string` | 可选 |
+
+### initial.ConfigItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `Identity` | `string` | 可选 |
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+| `version` | `int64` | 可选 |
+
+### initial.ConfigReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `[]initial.ConfigItem` | 数组 |
+
+### initial.ConfigRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `app` | `string` | 可选 |
+| `os` | `string` | 可选 |
+
+### initial.CountryItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `uint32` | 可选 |
+| `Iso2` | `string` | 可选 |
+| `Iso3` | `string` | 可选 |
+| `numCode` | `string` | 可选 |
+| `phoneCode` | `string` | 可选 |
+| `currency` | `string` | 可选 |
+| `currencySymbol` | `string` | 可选 |
+| `region` | `string` | 可选 |
+| `timezones` | `string` | 可选 |
+| `translations` | `string` | 可选 |
+| `name` | `string` | 可选 |
+| `localName` | `string` | 可选 |
+| `enabled` | `bool` | 可选 |
+| `sortOrder` | `int32` | 可选 |
+
+### initial.CountryReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `countries` | `[]initial.CountryItem` | 数组 |
+
+### initial.Crc
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `string` | 可选 |
+
+### initial.DatasItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `dataType` | `string` | 可选 |
+| `key` | `string` | 可选 |
+| `title` | `string` | 可选 |
+| `remark` | `string` | 可选 |
+| `icon` | `string` | 可选 |
+
+### initial.DatasReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `datas` | `[]initial.DatasItem` | 数组 |
+
+### initial.Empty
+
+空消息：请求时发送 `{}`。
+
+### initial.StatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `message` | `string` | 可选 |
+| `details` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |

wiki/api/06-passport.md

@@ -0,0 +1,578 @@
+# PASSPORT API
+
+账号注册、登录、验证、找回密码和账户资料管理。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/passport/{Service}/{Method}`
+- 原生 gRPC：`/passport.{Service}/{Method}`
+- grpc-gateway：`POST /passport.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Account` | 6 | Account 服务 |
+| `Forget` | 2 | Forget 服务 |
+| `Login` | 3 | Login 服务 |
+| `Register` | 2 | Register 服务 |
+| `Verify` | 2 | Verify 服务 |
+
+## Account
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Get` | `POST /rpc/passport/Account/Get` | [`base_passport_blocks.Empty`](#base_passport_blocksempty) | [`passport.GetFullReply`](#passportgetfullreply) | Unary |
+| `SetData` | `POST /rpc/passport/Account/SetData` | [`passport.SetDataRequest`](#passportsetdatarequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+| `SetPassword` | `POST /rpc/passport/Account/SetPassword` | [`passport.SetPasswordRequest`](#passportsetpasswordrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+| `TagCreate` | `POST /rpc/passport/Account/TagCreate` | [`passport.TagItem`](#passporttagitem) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+| `TagRemove` | `POST /rpc/passport/Account/TagRemove` | [`base_passport_blocks.IdentRequest`](#base_passport_blocksidentrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+| `Statistics` | `POST /rpc/passport/Account/Statistics` | [`passport.StatisticsRequest`](#passportstatisticsrequest) | [`passport.StatisticsReply`](#passportstatisticsreply) | Unary |
+
+### Account.Get
+
+- 动态 HTTP：`POST /rpc/passport/Account/Get`
+- gRPC：`/passport.Account/Get`
+- 白名单键：`passport.Account.Get`
+- 请求示例：
+
+```json
+{}
+```
+
+### Account.SetData
+
+- 动态 HTTP：`POST /rpc/passport/Account/SetData`
+- gRPC：`/passport.Account/SetData`
+- 白名单键：`passport.Account.SetData`
+- 请求示例：
+
+```json
+{
+  "area": "string",
+  "avatar": "string",
+  "birthday": "string",
+  "city": "string",
+  "country": "string",
+  "cover": "string",
+  "level": 0,
+  "nickname": "string",
+  "province": "string",
+  "score": 0,
+  "sex": 0,
+  "sign": "string"
+}
+```
+
+### Account.SetPassword
+
+- 动态 HTTP：`POST /rpc/passport/Account/SetPassword`
+- gRPC：`/passport.Account/SetPassword`
+- 白名单键：`passport.Account.SetPassword`
+- 请求示例：
+
+```json
+{
+  "newPassword": "string",
+  "oldPassword": "string"
+}
+```
+
+### Account.TagCreate
+
+- 动态 HTTP：`POST /rpc/passport/Account/TagCreate`
+- gRPC：`/passport.Account/TagCreate`
+- 白名单键：`passport.Account.TagCreate`
+- 请求示例：
+
+```json
+{
+  "icon": "string",
+  "name": "string"
+}
+```
+
+### Account.TagRemove
+
+- 动态 HTTP：`POST /rpc/passport/Account/TagRemove`
+- gRPC：`/passport.Account/TagRemove`
+- 白名单键：`passport.Account.TagRemove`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Account.Statistics
+
+- 动态 HTTP：`POST /rpc/passport/Account/Statistics`
+- gRPC：`/passport.Account/Statistics`
+- 白名单键：`passport.Account.Statistics`
+- 请求示例：
+
+```json
+{
+  "field": [
+    "string"
+  ]
+}
+```
+
+## Forget
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Verify` | `POST /rpc/passport/Forget/Verify` | [`passport.ForgetVerifyRequest`](#passportforgetverifyrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+| `Reset` | `POST /rpc/passport/Forget/Reset` | [`passport.ForgetResetRequest`](#passportforgetresetrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+
+### Forget.Verify
+
+- 动态 HTTP：`POST /rpc/passport/Forget/Verify`
+- gRPC：`/passport.Forget/Verify`
+- 白名单键：`passport.Forget.Verify`
+- 请求示例：
+
+```json
+{
+  "code": "string",
+  "phone": "string"
+}
+```
+
+### Forget.Reset
+
+- 动态 HTTP：`POST /rpc/passport/Forget/Reset`
+- gRPC：`/passport.Forget/Reset`
+- 白名单键：`passport.Forget.Reset`
+- 请求示例：
+
+```json
+{
+  "identity": "string",
+  "password": "string"
+}
+```
+
+## Login
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Pwd` | `POST /rpc/passport/Login/Pwd` | [`passport.LoginByPwdRequest`](#passportloginbypwdrequest) | [`passport.LoginReply`](#passportloginreply) | Unary |
+| `Code` | `POST /rpc/passport/Login/Code` | [`passport.LoginByCodeRequest`](#passportloginbycoderequest) | [`passport.LoginReply`](#passportloginreply) | Unary |
+| `Quick` | `POST /rpc/passport/Login/Quick` | [`passport.LoginByCodeRequest`](#passportloginbycoderequest) | [`passport.LoginReply`](#passportloginreply) | Unary |
+
+### Login.Pwd
+
+- 动态 HTTP：`POST /rpc/passport/Login/Pwd`
+- gRPC：`/passport.Login/Pwd`
+- 白名单键：`passport.Login.Pwd`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "password": "string"
+}
+```
+
+### Login.Code
+
+- 动态 HTTP：`POST /rpc/passport/Login/Code`
+- gRPC：`/passport.Login/Code`
+- 白名单键：`passport.Login.Code`
+- 请求示例：
+
+```json
+{
+  "agencyId": "0",
+  "code": "string",
+  "country": "string",
+  "owner_id": "0",
+  "owner_identity": "string",
+  "phone": "string",
+  "staffId": "0"
+}
+```
+
+### Login.Quick
+
+- 动态 HTTP：`POST /rpc/passport/Login/Quick`
+- gRPC：`/passport.Login/Quick`
+- 白名单键：`passport.Login.Quick`
+- 请求示例：
+
+```json
+{
+  "agencyId": "0",
+  "code": "string",
+  "country": "string",
+  "owner_id": "0",
+  "owner_identity": "string",
+  "phone": "string",
+  "staffId": "0"
+}
+```
+
+## Register
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Pwd` | `POST /rpc/passport/Register/Pwd` | [`passport.RegisterRequest`](#passportregisterrequest) | [`passport.RegisterReply`](#passportregisterreply) | Unary |
+| `Code` | `POST /rpc/passport/Register/Code` | [`passport.RegisterRequest`](#passportregisterrequest) | [`passport.RegisterReply`](#passportregisterreply) | Unary |
+
+### Register.Pwd
+
+- 动态 HTTP：`POST /rpc/passport/Register/Pwd`
+- gRPC：`/passport.Register/Pwd`
+- 白名单键：`passport.Register.Pwd`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "agencyId": "0",
+  "code": "string",
+  "country": "string",
+  "email": "string",
+  "owner_id": "0",
+  "owner_identity": "string",
+  "password": "string",
+  "phone": "string",
+  "staffId": "0"
+}
+```
+
+### Register.Code
+
+- 动态 HTTP：`POST /rpc/passport/Register/Code`
+- gRPC：`/passport.Register/Code`
+- 白名单键：`passport.Register.Code`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "agencyId": "0",
+  "code": "string",
+  "country": "string",
+  "email": "string",
+  "owner_id": "0",
+  "owner_identity": "string",
+  "password": "string",
+  "phone": "string",
+  "staffId": "0"
+}
+```
+
+## Verify
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Request` | `POST /rpc/passport/Verify/Request` | [`passport.VerifyRequest`](#passportverifyrequest) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+| `JumioCallback` | `POST /rpc/passport/Verify/JumioCallback` | [`passport.JumioCallbackPayload`](#passportjumiocallbackpayload) | [`base_passport_blocks.StatusReply`](#base_passport_blocksstatusreply) | Unary |
+
+### Verify.Request
+
+- 动态 HTTP：`POST /rpc/passport/Verify/Request`
+- gRPC：`/passport.Verify/Request`
+- 白名单键：`passport.Verify.Request`
+- 请求示例：
+
+```json
+{
+  "args": {
+    "key": "string"
+  },
+  "provider": "string"
+}
+```
+
+### Verify.JumioCallback
+
+- 动态 HTTP：`POST /rpc/passport/Verify/JumioCallback`
+- gRPC：`/passport.Verify/JumioCallback`
+- 白名单键：`passport.Verify.JumioCallback`
+- 请求示例：
+
+```json
+{
+  "callbackDate": "string",
+  "clientIp": "string",
+  "customerInternalReference": "string",
+  "document": {
+    "issuingCountry": "string",
+    "number": "string",
+    "status": "string",
+    "type": "string"
+  },
+  "faceMap": {
+    "similarity": 0,
+    "status": "string"
+  },
+  "personalInformation": {
+    "dateOfBirth": "string",
+    "firstName": "string",
+    "lastName": "string",
+    "nationality": "string"
+  },
+  "scanReference": "string",
+  "verificationStatus": {
+    "reason": "string",
+    "state": "string"
+  }
+}
+```
+
+## 消息结构
+
+### base_passport_blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### base_passport_blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### base_passport_blocks.StatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `message` | `string` | 可选 |
+| `details` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### base_passport_blocks.VerifyStatus
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `emailVerify` | `int32` | 可选 |
+| `phoneVerify` | `int32` | 可选 |
+| `faceVerify` | `int32` | 可选 |
+| `documentVerify` | `int32` | 可选 |
+| `kycVerify` | `int32` | 可选 |
+
+### passport.Document
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `status` | `string` | 可选 |
+| `type` | `string` | 可选 |
+| `issuingCountry` | `string` | 可选 |
+| `number` | `string` | 可选 |
+
+### passport.FaceMap
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `status` | `string` | 可选 |
+| `similarity` | `float` | 可选 |
+
+### passport.ForgetResetRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `password` | `string` | 可选 |
+
+### passport.ForgetVerifyRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `phone` | `string` | 可选 |
+| `code` | `string` | 可选 |
+
+### passport.GetFullReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `account` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `email` | `string` | 可选 |
+| `rights` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+| `avatar` | `string` | 可选 |
+| `birthday` | `string` | 可选 |
+| `sex` | `int32` | 可选 |
+| `country` | `string` | 可选 |
+| `province` | `string` | 可选 |
+| `city` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `sign` | `string` | 可选 |
+| `cover` | `string` | 可选 |
+| `score` | `int32` | 可选 |
+| `level` | `int32` | 可选 |
+| `verifyStatus` | `base_passport_blocks.VerifyStatus` | 可选 |
+| `tags` | `[]passport.TagItem` | 数组 |
+
+### passport.JumioCallbackPayload
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `scanReference` | `string` | 可选 |
+| `customerInternalReference` | `string` | 可选 |
+| `verificationStatus` | `passport.VerificationStatus` | 可选 |
+| `document` | `passport.Document` | 可选 |
+| `personalInformation` | `passport.PersonalInformation` | 可选 |
+| `faceMap` | `passport.FaceMap` | 可选 |
+| `callbackDate` | `string` | 可选 |
+| `clientIp` | `string` | 可选 |
+
+### passport.LoginByCodeRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `country` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `code` | `string` | 可选 |
+| `agencyId` | `int64` | 可选 |
+| `staffId` | `int64` | 可选 |
+| `owner_id` | `int64` | 可选 |
+| `owner_identity` | `string` | 可选 |
+
+### passport.LoginByPwdRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `account` | `string` | 可选 |
+| `password` | `string` | 可选 |
+
+### passport.LoginReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `token` | `string` | 可选 |
+| `extend` | `map<string, string>` | 对象映射 |
+| `verifyStatus` | `base_passport_blocks.VerifyStatus` | 可选 |
+
+### passport.LoginReply.ExtendEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### passport.PersonalInformation
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `firstName` | `string` | 可选 |
+| `lastName` | `string` | 可选 |
+| `dateOfBirth` | `string` | 可选 |
+| `nationality` | `string` | 可选 |
+
+### passport.RegisterReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `token` | `string` | 可选 |
+| `extend` | `map<string, string>` | 对象映射 |
+| `verifyStatus` | `base_passport_blocks.VerifyStatus` | 可选 |
+
+### passport.RegisterReply.ExtendEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### passport.RegisterRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `country` | `string` | 可选 |
+| `email` | `string` | 可选 |
+| `account` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `password` | `string` | 可选 |
+| `code` | `string` | 可选 |
+| `agencyId` | `int64` | 可选 |
+| `staffId` | `int64` | 可选 |
+| `owner_id` | `int64` | 可选 |
+| `owner_identity` | `string` | 可选 |
+
+### passport.SetDataRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `nickname` | `string` | 可选 |
+| `avatar` | `string` | 可选 |
+| `birthday` | `string` | 可选 |
+| `sex` | `int32` | 可选 |
+| `country` | `string` | 可选 |
+| `province` | `string` | 可选 |
+| `city` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `sign` | `string` | 可选 |
+| `cover` | `string` | 可选 |
+| `score` | `int32` | 可选 |
+| `level` | `int32` | 可选 |
+
+### passport.SetPasswordRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `oldPassword` | `string` | 可选 |
+| `newPassword` | `string` | 可选 |
+
+### passport.StatisticsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `Data` | `map<string, int64>` | 对象映射 |
+
+### passport.StatisticsReply.DataEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `int64` | 可选 |
+
+### passport.StatisticsRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `field` | `[]string` | 数组 |
+
+### passport.TagItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `name` | `string` | 可选 |
+| `icon` | `string` | 可选 |
+
+### passport.VerificationStatus
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `state` | `string` | 可选 |
+| `reason` | `string` | 可选 |
+
+### passport.VerifyRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `provider` | `string` | 可选 |
+| `args` | `map<string, string>` | 对象映射 |
+
+### passport.VerifyRequest.ArgsEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |

wiki/api/07-sender.md

@@ -0,0 +1,142 @@
+# SENDER API
+
+邮件、短信发送及验证码校验。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/sender/{Service}/{Method}`
+- 原生 gRPC：`/sender.{Service}/{Method}`
+- grpc-gateway：`POST /sender.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Mail` | 1 | Mail 服务 |
+| `Sms` | 2 | Sms 服务 |
+
+## Mail
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Send` | `POST /rpc/sender/Mail/Send` | [`sender.SendMailRequest`](#sendersendmailrequest) | [`sender.SendMailReply`](#sendersendmailreply) | Unary |
+
+### Mail.Send
+
+- 动态 HTTP：`POST /rpc/sender/Mail/Send`
+- gRPC：`/sender.Mail/Send`
+- 白名单键：`sender.Mail.Send`
+- 请求示例：
+
+```json
+{
+  "isGenCode": false,
+  "paramters": {
+    "key": "string"
+  },
+  "provider": "string",
+  "templateKey": "string",
+  "to": "string"
+}
+```
+
+## Sms
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Send` | `POST /rpc/sender/Sms/Send` | [`sender.SmsSendRequest`](#sendersmssendrequest) | [`sender.SmsReply`](#sendersmsreply) | Unary |
+| `Verify` | `POST /rpc/sender/Sms/Verify` | [`sender.SmsVerifyRequest`](#sendersmsverifyrequest) | [`sender.SmsReply`](#sendersmsreply) | Unary |
+
+### Sms.Send
+
+- 动态 HTTP：`POST /rpc/sender/Sms/Send`
+- gRPC：`/sender.Sms/Send`
+- 白名单键：`sender.Sms.Send`
+- 请求示例：
+
+```json
+{
+  "isGenCode": false,
+  "paramters": {
+    "key": "string"
+  },
+  "phone": "string",
+  "provider": "string",
+  "signName": "string",
+  "templateCode": "string"
+}
+```
+
+### Sms.Verify
+
+- 动态 HTTP：`POST /rpc/sender/Sms/Verify`
+- gRPC：`/sender.Sms/Verify`
+- 白名单键：`sender.Sms.Verify`
+- 请求示例：
+
+```json
+{
+  "code": "string",
+  "phone": "string"
+}
+```
+
+## 消息结构
+
+### sender.SendMailReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `string` | 可选 |
+
+### sender.SendMailRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `provider` | `string` | 可选 |
+| `templateKey` | `string` | 可选 |
+| `to` | `string` | 可选 |
+| `isGenCode` | `bool` | 可选 |
+| `paramters` | `map<string, string>` | 对象映射 |
+
+### sender.SendMailRequest.ParamtersEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### sender.SmsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `reply` | `string` | 可选 |
+
+### sender.SmsSendRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `provider` | `string` | 可选 |
+| `signName` | `string` | 可选 |
+| `templateCode` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `isGenCode` | `bool` | 可选 |
+| `paramters` | `map<string, string>` | 对象映射 |
+
+### sender.SmsSendRequest.ParamtersEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### sender.SmsVerifyRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `phone` | `string` | 可选 |
+| `code` | `string` | 可选 |

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` | 可选 |

wiki/api/10-market.md

@@ -0,0 +1,593 @@
+# MARKET API
+
+市场代理商、供应商及经营数据管理。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/market/{Service}/{Method}`
+- 原生 gRPC：`/market.{Service}/{Method}`
+- grpc-gateway：`POST /market.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Agency` | 9 | Agency 服务 |
+| `Data` | 5 | Data 服务 |
+| `Supply` | 5 | Supply 服务 |
+
+## Agency
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Login` | `POST /rpc/market/Agency/Login` | [`market.LoginRequest`](#marketloginrequest) | [`ec_market_blocks.MarketLoginReply`](#ec_market_blocksmarketloginreply) | Unary |
+| `Create` | `POST /rpc/market/Agency/Create` | [`market.MarketAgenctyItem`](#marketmarketagenctyitem) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+| `Get` | `POST /rpc/market/Agency/Get` | [`ec_market_blocks.IdentRequest`](#ec_market_blocksidentrequest) | [`market.MarketAgenctyItem`](#marketmarketagenctyitem) | Unary |
+| `Fetch` | `POST /rpc/market/Agency/Fetch` | [`ec_market_blocks.MarketFetchRequest`](#ec_market_blocksmarketfetchrequest) | [`market.AgencyReply`](#marketagencyreply) | Unary |
+| `Modify` | `POST /rpc/market/Agency/Modify` | [`market.MarketAgenctyItem`](#marketmarketagenctyitem) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+| `Delete` | `POST /rpc/market/Agency/Delete` | [`ec_market_blocks.IdentRequest`](#ec_market_blocksidentrequest) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+| `SetPassword` | `POST /rpc/market/Agency/SetPassword` | [`market.SetPasswordRequest`](#marketsetpasswordrequest) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+| `Pending` | `POST /rpc/market/Agency/Pending` | [`ec_market_blocks.MarketFetchRequest`](#ec_market_blocksmarketfetchrequest) | [`market.AgencyReply`](#marketagencyreply) | Unary |
+| `Approve` | `POST /rpc/market/Agency/Approve` | [`market.ApproveRequest`](#marketapproverequest) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+
+### Agency.Login
+
+- 动态 HTTP：`POST /rpc/market/Agency/Login`
+- gRPC：`/market.Agency/Login`
+- 白名单键：`market.Agency.Login`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "password": "string",
+  "verify": "string"
+}
+```
+
+### Agency.Create
+
+- 动态 HTTP：`POST /rpc/market/Agency/Create`
+- gRPC：`/market.Agency/Create`
+- 白名单键：`market.Agency.Create`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "agency_type": 0,
+  "approve": 0,
+  "area": "string",
+  "avatar": "string",
+  "commission_rate": 0,
+  "country": "string",
+  "created_at": "string",
+  "email": "string",
+  "id_after": "string",
+  "id_before": "string",
+  "id_name": "string",
+  "identity": "string",
+  "name": "string",
+  "org_name": "string",
+  "org_photo": "string",
+  "password": "string",
+  "phone": "string",
+  "remark": "string",
+  "status": 0
+}
+```
+
+### Agency.Get
+
+- 动态 HTTP：`POST /rpc/market/Agency/Get`
+- gRPC：`/market.Agency/Get`
+- 白名单键：`market.Agency.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Agency.Fetch
+
+- 动态 HTTP：`POST /rpc/market/Agency/Fetch`
+- gRPC：`/market.Agency/Fetch`
+- 白名单键：`market.Agency.Fetch`
+- 请求示例：
+
+```json
+{
+  "approve": 0,
+  "identity": "string",
+  "keyword": "string",
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  },
+  "status": 0
+}
+```
+
+### Agency.Modify
+
+- 动态 HTTP：`POST /rpc/market/Agency/Modify`
+- gRPC：`/market.Agency/Modify`
+- 白名单键：`market.Agency.Modify`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "agency_type": 0,
+  "approve": 0,
+  "area": "string",
+  "avatar": "string",
+  "commission_rate": 0,
+  "country": "string",
+  "created_at": "string",
+  "email": "string",
+  "id_after": "string",
+  "id_before": "string",
+  "id_name": "string",
+  "identity": "string",
+  "name": "string",
+  "org_name": "string",
+  "org_photo": "string",
+  "password": "string",
+  "phone": "string",
+  "remark": "string",
+  "status": 0
+}
+```
+
+### Agency.Delete
+
+- 动态 HTTP：`POST /rpc/market/Agency/Delete`
+- gRPC：`/market.Agency/Delete`
+- 白名单键：`market.Agency.Delete`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Agency.SetPassword
+
+- 动态 HTTP：`POST /rpc/market/Agency/SetPassword`
+- gRPC：`/market.Agency/SetPassword`
+- 白名单键：`market.Agency.SetPassword`
+- 请求示例：
+
+```json
+{
+  "identity": "string",
+  "new_password": "string",
+  "old_password": "string"
+}
+```
+
+### Agency.Pending
+
+- 动态 HTTP：`POST /rpc/market/Agency/Pending`
+- gRPC：`/market.Agency/Pending`
+- 白名单键：`market.Agency.Pending`
+- 请求示例：
+
+```json
+{
+  "approve": 0,
+  "identity": "string",
+  "keyword": "string",
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  },
+  "status": 0
+}
+```
+
+### Agency.Approve
+
+- 动态 HTTP：`POST /rpc/market/Agency/Approve`
+- gRPC：`/market.Agency/Approve`
+- 白名单键：`market.Agency.Approve`
+- 请求示例：
+
+```json
+{
+  "approve": 0,
+  "identity": "string"
+}
+```
+
+## Data
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Overview` | `POST /rpc/market/Data/Overview` | [`ec_market_blocks.Empty`](#ec_market_blocksempty) | [`market.OverviewReply`](#marketoverviewreply) | Unary |
+| `MemberFetch` | `POST /rpc/market/Data/MemberFetch` | [`ec_market_blocks.MarketFetchRequest`](#ec_market_blocksmarketfetchrequest) | [`market.DataReply`](#marketdatareply) | Unary |
+| `MemberDetails` | `POST /rpc/market/Data/MemberDetails` | [`ec_market_blocks.IdentRequest`](#ec_market_blocksidentrequest) | [`market.KeyVal`](#marketkeyval) | Unary |
+| `OrderFetch` | `POST /rpc/market/Data/OrderFetch` | [`ec_market_blocks.MarketFetchRequest`](#ec_market_blocksmarketfetchrequest) | [`market.DataReply`](#marketdatareply) | Unary |
+| `OrderDetails` | `POST /rpc/market/Data/OrderDetails` | [`ec_market_blocks.IdentRequest`](#ec_market_blocksidentrequest) | [`market.KeyVal`](#marketkeyval) | Unary |
+
+### Data.Overview
+
+- 动态 HTTP：`POST /rpc/market/Data/Overview`
+- gRPC：`/market.Data/Overview`
+- 白名单键：`market.Data.Overview`
+- 请求示例：
+
+```json
+{}
+```
+
+### Data.MemberFetch
+
+- 动态 HTTP：`POST /rpc/market/Data/MemberFetch`
+- gRPC：`/market.Data/MemberFetch`
+- 白名单键：`market.Data.MemberFetch`
+- 请求示例：
+
+```json
+{
+  "approve": 0,
+  "identity": "string",
+  "keyword": "string",
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  },
+  "status": 0
+}
+```
+
+### Data.MemberDetails
+
+- 动态 HTTP：`POST /rpc/market/Data/MemberDetails`
+- gRPC：`/market.Data/MemberDetails`
+- 白名单键：`market.Data.MemberDetails`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Data.OrderFetch
+
+- 动态 HTTP：`POST /rpc/market/Data/OrderFetch`
+- gRPC：`/market.Data/OrderFetch`
+- 白名单键：`market.Data.OrderFetch`
+- 请求示例：
+
+```json
+{
+  "approve": 0,
+  "identity": "string",
+  "keyword": "string",
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  },
+  "status": 0
+}
+```
+
+### Data.OrderDetails
+
+- 动态 HTTP：`POST /rpc/market/Data/OrderDetails`
+- gRPC：`/market.Data/OrderDetails`
+- 白名单键：`market.Data.OrderDetails`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+## Supply
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Create` | `POST /rpc/market/Supply/Create` | [`market.MarketSupplyItem`](#marketmarketsupplyitem) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+| `Get` | `POST /rpc/market/Supply/Get` | [`ec_market_blocks.IdentRequest`](#ec_market_blocksidentrequest) | [`market.MarketSupplyItem`](#marketmarketsupplyitem) | Unary |
+| `Fetch` | `POST /rpc/market/Supply/Fetch` | [`ec_market_blocks.MarketFetchRequest`](#ec_market_blocksmarketfetchrequest) | [`market.SupplyReply`](#marketsupplyreply) | Unary |
+| `Modify` | `POST /rpc/market/Supply/Modify` | [`market.MarketSupplyItem`](#marketmarketsupplyitem) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+| `Delete` | `POST /rpc/market/Supply/Delete` | [`ec_market_blocks.IdentRequest`](#ec_market_blocksidentrequest) | [`ec_market_blocks.IdentityStatusReply`](#ec_market_blocksidentitystatusreply) | Unary |
+
+### Supply.Create
+
+- 动态 HTTP：`POST /rpc/market/Supply/Create`
+- gRPC：`/market.Supply/Create`
+- 白名单键：`market.Supply.Create`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "avatar": "string",
+  "commission_rate": 0,
+  "id": 0,
+  "id_after": "string",
+  "id_before": "string",
+  "id_name": "string",
+  "identity": "string",
+  "name": "string",
+  "org_name": "string",
+  "org_photo": "string",
+  "password": "string",
+  "phone": "string",
+  "remark": "string",
+  "status": 0
+}
+```
+
+### Supply.Get
+
+- 动态 HTTP：`POST /rpc/market/Supply/Get`
+- gRPC：`/market.Supply/Get`
+- 白名单键：`market.Supply.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Supply.Fetch
+
+- 动态 HTTP：`POST /rpc/market/Supply/Fetch`
+- gRPC：`/market.Supply/Fetch`
+- 白名单键：`market.Supply.Fetch`
+- 请求示例：
+
+```json
+{
+  "approve": 0,
+  "identity": "string",
+  "keyword": "string",
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  },
+  "status": 0
+}
+```
+
+### Supply.Modify
+
+- 动态 HTTP：`POST /rpc/market/Supply/Modify`
+- gRPC：`/market.Supply/Modify`
+- 白名单键：`market.Supply.Modify`
+- 请求示例：
+
+```json
+{
+  "account": "string",
+  "avatar": "string",
+  "commission_rate": 0,
+  "id": 0,
+  "id_after": "string",
+  "id_before": "string",
+  "id_name": "string",
+  "identity": "string",
+  "name": "string",
+  "org_name": "string",
+  "org_photo": "string",
+  "password": "string",
+  "phone": "string",
+  "remark": "string",
+  "status": 0
+}
+```
+
+### Supply.Delete
+
+- 动态 HTTP：`POST /rpc/market/Supply/Delete`
+- gRPC：`/market.Supply/Delete`
+- 白名单键：`market.Supply.Delete`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+## 消息结构
+
+### ec_market_blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### ec_market_blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### ec_market_blocks.IdentityStatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `identity` | `string` | 可选 |
+| `message` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### ec_market_blocks.MarketFetchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `page_no` | `int64` | 可选 |
+| `page_size` | `int64` | 可选 |
+| `params` | `map<string, string>` | 对象映射 |
+| `identity` | `string` | 可选 |
+| `keyword` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `approve` | `int32` | 可选 |
+
+### ec_market_blocks.MarketFetchRequest.ParamsEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### ec_market_blocks.MarketLoginReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `token` | `string` | 可选 |
+| `identity` | `string` | 可选 |
+| `market_identity` | `string` | 可选 |
+| `name` | `string` | 可选 |
+| `account` | `string` | 可选 |
+| `role` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `created_at` | `string` | 可选 |
+| `market_name` | `string` | 可选 |
+
+### market.AgencyReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `count` | `int64` | 可选 |
+| `data` | `[]market.MarketAgenctyItem` | 数组 |
+
+### market.ApproveRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `approve` | `int32` | 可选 |
+| `identity` | `string` | 可选 |
+
+### market.DataReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `count` | `int64` | 可选 |
+| `data` | `[]market.KeyVal` | 数组 |
+
+### market.KeyVal
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `val` | `string` | 可选 |
+
+### market.LoginRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `account` | `string` | 可选 |
+| `password` | `string` | 可选 |
+| `verify` | `string` | 可选 |
+
+### market.MarketAgenctyItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `created_at` | `string` | 可选 |
+| `name` | `string` | 可选 |
+| `avatar` | `string` | 可选 |
+| `account` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `password` | `string` | 可选 |
+| `org_name` | `string` | 可选 |
+| `org_photo` | `string` | 可选 |
+| `id_name` | `string` | 可选 |
+| `id_before` | `string` | 可选 |
+| `id_after` | `string` | 可选 |
+| `remark` | `string` | 可选 |
+| `commission_rate` | `int32` | 可选 |
+| `agency_type` | `int32` | 可选 |
+| `status` | `int32` | 可选 |
+| `email` | `string` | 可选 |
+| `country` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `approve` | `int32` | 可选 |
+
+### market.MarketSupplyItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `name` | `string` | 可选 |
+| `avatar` | `string` | 可选 |
+| `commission_rate` | `int32` | 可选 |
+| `account` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `password` | `string` | 可选 |
+| `org_name` | `string` | 可选 |
+| `org_photo` | `string` | 可选 |
+| `id_name` | `string` | 可选 |
+| `id_before` | `string` | 可选 |
+| `id_after` | `string` | 可选 |
+| `remark` | `string` | 可选 |
+| `identity` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `id` | `int32` | 可选 |
+
+### market.OverviewReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total_approve` | `int64` | 可选 |
+| `total_month` | `int64` | 可选 |
+| `total_all` | `int64` | 可选 |
+| `total_staff` | `int64` | 可选 |
+| `reportMonth` | `map<string, int64>` | 对象映射 |
+| `reportStaff` | `map<string, int64>` | 对象映射 |
+
+### market.OverviewReply.ReportMonthEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `int64` | 可选 |
+
+### market.OverviewReply.ReportStaffEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `int64` | 可选 |
+
+### market.SetPasswordRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `old_password` | `string` | 可选 |
+| `new_password` | `string` | 可选 |
+
+### market.SupplyReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `count` | `int64` | 可选 |
+| `data` | `[]market.MarketSupplyItem` | 数组 |

wiki/api/11-order.md

@@ -0,0 +1,837 @@
+# ORDER API
+
+购物车、优惠券、订单汇总及商家订单管理。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/order/{Service}/{Method}`
+- 原生 gRPC：`/order.{Service}/{Method}`
+- grpc-gateway：`POST /order.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Cart` | 4 | Cart 服务 |
+| `Coupon` | 1 | Coupon 服务 |
+| `Mgt` | 7 | Mgt 服务 |
+| `Summary` | 10 | Summary 服务 |
+
+## Cart
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Fetch` | `POST /rpc/order/Cart/Fetch` | [`order.CartGetRequest`](#ordercartgetrequest) | [`order.CartGetReply`](#ordercartgetreply) | Unary |
+| `Create` | `POST /rpc/order/Cart/Create` | [`order.CartAddRequest`](#ordercartaddrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `Modify` | `POST /rpc/order/Cart/Modify` | [`order.CartSetRequest`](#ordercartsetrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `Delete` | `POST /rpc/order/Cart/Delete` | [`order.CartDelRequest`](#ordercartdelrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+
+### Cart.Fetch
+
+- 动态 HTTP：`POST /rpc/order/Cart/Fetch`
+- gRPC：`/order.Cart/Fetch`
+- 白名单键：`order.Cart.Fetch`
+- 请求示例：
+
+```json
+{
+  "car_identity": "string",
+  "passport": "string",
+  "passport_identity": "string"
+}
+```
+
+### Cart.Create
+
+- 动态 HTTP：`POST /rpc/order/Cart/Create`
+- gRPC：`/order.Cart/Create`
+- 白名单键：`order.Cart.Create`
+- 请求示例：
+
+```json
+{
+  "cart_identity": "string",
+  "number": 0,
+  "passport_identity": "string",
+  "product_args": "string",
+  "product_id": "0",
+  "product_identity": "string",
+  "spec_id": "0"
+}
+```
+
+### Cart.Modify
+
+- 动态 HTTP：`POST /rpc/order/Cart/Modify`
+- gRPC：`/order.Cart/Modify`
+- 白名单键：`order.Cart.Modify`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string",
+  "number": 0,
+  "unit_price": "0",
+  "updates": [
+    {
+      "id": "0",
+      "number": "0"
+    }
+  ]
+}
+```
+
+### Cart.Delete
+
+- 动态 HTTP：`POST /rpc/order/Cart/Delete`
+- gRPC：`/order.Cart/Delete`
+- 白名单键：`order.Cart.Delete`
+- 请求示例：
+
+```json
+{
+  "id": [
+    "0"
+  ]
+}
+```
+
+## Coupon
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `ByStatus` | `POST /rpc/order/Coupon/ByStatus` | [`order.Status`](#orderstatus) | [`order.CouponListReply`](#ordercouponlistreply) | Unary |
+
+### Coupon.ByStatus
+
+- 动态 HTTP：`POST /rpc/order/Coupon/ByStatus`
+- gRPC：`/order.Coupon/ByStatus`
+- 白名单键：`order.Coupon.ByStatus`
+- 请求示例：
+
+```json
+{
+  "status": 0
+}
+```
+
+## Mgt
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `OrderCreate` | `POST /rpc/order/Mgt/OrderCreate` | [`order.CreateOrderRequest`](#ordercreateorderrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `OrderModify` | `POST /rpc/order/Mgt/OrderModify` | [`ec_order_blocks.OrderSummaryItem`](#ec_order_blocksordersummaryitem) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `OrderGet` | `POST /rpc/order/Mgt/OrderGet` | [`ec_order_blocks.OrderIdentRequest`](#ec_order_blocksorderidentrequest) | [`order.OrderGetReply`](#orderordergetreply) | Unary |
+| `OrderListByStore` | `POST /rpc/order/Mgt/OrderListByStore` | [`order.OrderListByStoreRequest`](#orderorderlistbystorerequest) | [`order.OrderListByStoreReply`](#orderorderlistbystorereply) | Unary |
+| `OrderCancel` | `POST /rpc/order/Mgt/OrderCancel` | [`ec_order_blocks.OrderIdentRequest`](#ec_order_blocksorderidentrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `OrderReturnable` | `POST /rpc/order/Mgt/OrderReturnable` | [`ec_order_blocks.OrderIdentRequest`](#ec_order_blocksorderidentrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `OrderApprove` | `POST /rpc/order/Mgt/OrderApprove` | [`ec_order_blocks.OrderIdentRequest`](#ec_order_blocksorderidentrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+
+### Mgt.OrderCreate
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderCreate`
+- gRPC：`/order.Mgt/OrderCreate`
+- 白名单键：`order.Mgt.OrderCreate`
+- 请求示例：
+
+```json
+{
+  "address_identity": "string",
+  "args": "string",
+  "delivery_time": "string",
+  "partner_id": 0,
+  "spec": [
+    {
+      "number": 0,
+      "product_identity": "string"
+    }
+  ]
+}
+```
+
+### Mgt.OrderModify
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderModify`
+- gRPC：`/order.Mgt/OrderModify`
+- 白名单键：`order.Mgt.OrderModify`
+- 请求示例：
+
+```json
+{
+  "addr": "string",
+  "address": "string",
+  "address_identity": "string",
+  "approve": 0,
+  "area": "string",
+  "brand": "string",
+  "car_identity": "string",
+  "city": "string",
+  "contact": "string",
+  "county": "string",
+  "coupon_amount": "0",
+  "created": "string",
+  "delivery_address": "string",
+  "delivery_identity": "string",
+  "delivery_time": "string",
+  "details": [
+    {
+      "cover_image": "string",
+      "gas_types": "0",
+      "id": "0",
+      "number": "0",
+      "product_args": "string",
+      "product_id": "0",
+      "product_identity": "string",
+      "sales_price": "0",
+      "spec": "string",
+      "spec_id": "0",
+      "spec_no": "string",
+      "title": "string",
+      "total_price": "0",
+      "type": "0",
+      "unit_price": "0"
+    }
+  ],
+  "id": "0",
+  "identity": "string",
+  "license_number": "string",
+  "logistics_fee": "0",
+  "logistics_number": "string",
+  "member_name": "string",
+  "member_phone": "string",
+  "order_no": "string",
+  "partner_id": "0",
+  "pay_amount": "0",
+  "pay_remark": "string",
+  "pay_time": "string",
+  "pay_trade_no": "string",
+  "pay_type": 0,
+  "phone": "string",
+  "province": "string",
+  "refund_price": "0",
+  "remark": "string",
+  "status": 0,
+  "total_price": "0",
+  "trans_price": "0",
+  "updated": "string",
+  "version": "string"
+}
+```
+
+### Mgt.OrderGet
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderGet`
+- gRPC：`/order.Mgt/OrderGet`
+- 白名单键：`order.Mgt.OrderGet`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "approve": 0,
+  "id": "0",
+  "identity": "string",
+  "reason": "string",
+  "storeIdentity": "string"
+}
+```
+
+### Mgt.OrderListByStore
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderListByStore`
+- gRPC：`/order.Mgt/OrderListByStore`
+- 白名单键：`order.Mgt.OrderListByStore`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "keyword": "string",
+  "order_status": [
+    0
+  ],
+  "page_no": "0",
+  "page_size": "0",
+  "partner_id": "0",
+  "pay_type": 0,
+  "status": 0,
+  "storeIdentity": "string"
+}
+```
+
+### Mgt.OrderCancel
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderCancel`
+- gRPC：`/order.Mgt/OrderCancel`
+- 白名单键：`order.Mgt.OrderCancel`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "approve": 0,
+  "id": "0",
+  "identity": "string",
+  "reason": "string",
+  "storeIdentity": "string"
+}
+```
+
+### Mgt.OrderReturnable
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderReturnable`
+- gRPC：`/order.Mgt/OrderReturnable`
+- 白名单键：`order.Mgt.OrderReturnable`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "approve": 0,
+  "id": "0",
+  "identity": "string",
+  "reason": "string",
+  "storeIdentity": "string"
+}
+```
+
+### Mgt.OrderApprove
+
+- 动态 HTTP：`POST /rpc/order/Mgt/OrderApprove`
+- gRPC：`/order.Mgt/OrderApprove`
+- 白名单键：`order.Mgt.OrderApprove`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "approve": 0,
+  "id": "0",
+  "identity": "string",
+  "reason": "string",
+  "storeIdentity": "string"
+}
+```
+
+## Summary
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `QuickCreateByProduct` | `POST /rpc/order/Summary/QuickCreateByProduct` | [`order.QuickCreateByProductRequest`](#orderquickcreatebyproductrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `Submit` | `POST /rpc/order/Summary/Submit` | [`order.SubmitRequest`](#ordersubmitrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `Check` | `POST /rpc/order/Summary/Check` | [`ec_order_blocks.Empty`](#ec_order_blocksempty) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `Get` | `POST /rpc/order/Summary/Get` | [`ec_order_blocks.OrderIdentRequest`](#ec_order_blocksorderidentrequest) | [`order.SummaryGetReply`](#ordersummarygetreply) | Unary |
+| `List` | `POST /rpc/order/Summary/List` | [`order.SummaryListRequest`](#ordersummarylistrequest) | [`order.SummaryListReply`](#ordersummarylistreply) | Unary |
+| `Confirm` | `POST /rpc/order/Summary/Confirm` | [`order.ConfirmRequest`](#orderconfirmrequest) | [`order.ConfirmReply`](#orderconfirmreply) | Unary |
+| `Cancel` | `POST /rpc/order/Summary/Cancel` | [`order.CancelRequest`](#ordercancelrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `SimulatePay` | `POST /rpc/order/Summary/SimulatePay` | [`order.SimulatePayRequest`](#ordersimulatepayrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `SimulateShipments` | `POST /rpc/order/Summary/SimulateShipments` | [`order.SimulateShipmentsRequest`](#ordersimulateshipmentsrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+| `SimulateReceiving` | `POST /rpc/order/Summary/SimulateReceiving` | [`ec_order_blocks.OrderIdentRequest`](#ec_order_blocksorderidentrequest) | [`ec_order_blocks.OrderStatusReply`](#ec_order_blocksorderstatusreply) | Unary |
+
+### Summary.QuickCreateByProduct
+
+- 动态 HTTP：`POST /rpc/order/Summary/QuickCreateByProduct`
+- gRPC：`/order.Summary/QuickCreateByProduct`
+- 白名单键：`order.Summary.QuickCreateByProduct`
+- 请求示例：
+
+```json
+{
+  "address_identity": "string",
+  "args": "string",
+  "delivery_address": "string",
+  "delivery_time": "string",
+  "member_identity": "string",
+  "number": 0,
+  "partner_id": 0,
+  "product_identity": "string",
+  "spec_identity": "string",
+  "store_identity": "string"
+}
+```
+
+### Summary.Submit
+
+- 动态 HTTP：`POST /rpc/order/Summary/Submit`
+- gRPC：`/order.Summary/Submit`
+- 白名单键：`order.Summary.Submit`
+- 请求示例：
+
+```json
+{
+  "address": {
+    "area": "string",
+    "city": "string",
+    "contact": "string",
+    "country": "string",
+    "detail": "string",
+    "email": "string",
+    "phone": "string",
+    "province": "string",
+    "zipCode": "string"
+  },
+  "address_identity": "string",
+  "delivery_time": "string",
+  "id": [
+    "string"
+  ],
+  "partner_id": 0,
+  "store_identity": "string"
+}
+```
+
+### Summary.Check
+
+- 动态 HTTP：`POST /rpc/order/Summary/Check`
+- gRPC：`/order.Summary/Check`
+- 白名单键：`order.Summary.Check`
+- 请求示例：
+
+```json
+{}
+```
+
+### Summary.Get
+
+- 动态 HTTP：`POST /rpc/order/Summary/Get`
+- gRPC：`/order.Summary/Get`
+- 白名单键：`order.Summary.Get`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "approve": 0,
+  "id": "0",
+  "identity": "string",
+  "reason": "string",
+  "storeIdentity": "string"
+}
+```
+
+### Summary.List
+
+- 动态 HTTP：`POST /rpc/order/Summary/List`
+- gRPC：`/order.Summary/List`
+- 白名单键：`order.Summary.List`
+- 请求示例：
+
+```json
+{
+  "order_status": 0,
+  "page_no": "0",
+  "page_size": "0",
+  "pay_type": 0
+}
+```
+
+### Summary.Confirm
+
+- 动态 HTTP：`POST /rpc/order/Summary/Confirm`
+- gRPC：`/order.Summary/Confirm`
+- 白名单键：`order.Summary.Confirm`
+- 请求示例：
+
+```json
+{
+  "address_identity": "string",
+  "coupon_identity": "string",
+  "logistics_fee": 0,
+  "order_no": "string",
+  "remark": "string"
+}
+```
+
+### Summary.Cancel
+
+- 动态 HTTP：`POST /rpc/order/Summary/Cancel`
+- gRPC：`/order.Summary/Cancel`
+- 白名单键：`order.Summary.Cancel`
+- 请求示例：
+
+```json
+{
+  "order_no": "string",
+  "type": "string"
+}
+```
+
+### Summary.SimulatePay
+
+- 动态 HTTP：`POST /rpc/order/Summary/SimulatePay`
+- gRPC：`/order.Summary/SimulatePay`
+- 白名单键：`order.Summary.SimulatePay`
+- 请求示例：
+
+```json
+{
+  "identity": [
+    "string"
+  ]
+}
+```
+
+### Summary.SimulateShipments
+
+- 动态 HTTP：`POST /rpc/order/Summary/SimulateShipments`
+- gRPC：`/order.Summary/SimulateShipments`
+- 白名单键：`order.Summary.SimulateShipments`
+- 请求示例：
+
+```json
+{
+  "car_identity": "string",
+  "identity": "string",
+  "item_idetity": "string",
+  "member_identity": "string"
+}
+```
+
+### Summary.SimulateReceiving
+
+- 动态 HTTP：`POST /rpc/order/Summary/SimulateReceiving`
+- gRPC：`/order.Summary/SimulateReceiving`
+- 白名单键：`order.Summary.SimulateReceiving`
+- 请求示例：
+
+```json
+{
+  "agency": "string",
+  "approve": 0,
+  "id": "0",
+  "identity": "string",
+  "reason": "string",
+  "storeIdentity": "string"
+}
+```
+
+## 消息结构
+
+### ec_order_blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### ec_order_blocks.OrderDetails
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `product_id` | `int64` | 可选 |
+| `spec_no` | `string` | 可选 |
+| `spec` | `string` | 可选 |
+| `type` | `int64` | 可选 |
+| `title` | `string` | 可选 |
+| `cover_image` | `string` | 可选 |
+| `sales_price` | `int64` | 可选 |
+| `product_args` | `string` | 可选 |
+| `number` | `int64` | 可选 |
+| `unit_price` | `int64` | 可选 |
+| `spec_id` | `int64` | 可选 |
+| `product_identity` | `string` | 可选 |
+| `gas_types` | `int64` | 可选 |
+| `total_price` | `int64` | 可选 |
+
+### ec_order_blocks.OrderIdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `reason` | `string` | 可选 |
+| `approve` | `int32` | 可选 |
+| `agency` | `string` | 可选 |
+| `storeIdentity` | `string` | 可选 |
+
+### ec_order_blocks.OrderStatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `identity` | `string` | 可选 |
+| `message` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+| `reason` | `string` | 可选 |
+
+### ec_order_blocks.OrderSummaryItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `order_no` | `string` | 可选 |
+| `partner_id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `total_price` | `int64` | 可选 |
+| `trans_price` | `int64` | 可选 |
+| `refund_price` | `int64` | 可选 |
+| `logistics_fee` | `int64` | 可选 |
+| `coupon_amount` | `int64` | 可选 |
+| `remark` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `logistics_number` | `string` | 可选 |
+| `address_identity` | `string` | 可选 |
+| `county` | `string` | 可选 |
+| `province` | `string` | 可选 |
+| `city` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `address` | `string` | 可选 |
+| `contact` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `delivery_time` | `string` | 可选 |
+| `delivery_identity` | `string` | 可选 |
+| `pay_type` | `int32` | 可选 |
+| `pay_amount` | `int64` | 可选 |
+| `pay_trade_no` | `string` | 可选 |
+| `pay_time` | `string` | 可选 |
+| `pay_remark` | `string` | 可选 |
+| `created` | `string` | 可选 |
+| `updated` | `string` | 可选 |
+| `details` | `[]ec_order_blocks.OrderDetails` | 数组 |
+| `addr` | `string` | 可选 |
+| `car_identity` | `string` | 可选 |
+| `delivery_address` | `string` | 可选 |
+| `brand` | `string` | 可选 |
+| `version` | `string` | 可选 |
+| `license_number` | `string` | 可选 |
+| `member_name` | `string` | 可选 |
+| `member_phone` | `string` | 可选 |
+| `approve` | `int32` | 可选 |
+
+### order.CancelRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `order_no` | `string` | 可选 |
+| `type` | `string` | 可选 |
+
+### order.CartAddRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `cart_identity` | `string` | 可选 |
+| `passport_identity` | `string` | 可选 |
+| `product_identity` | `string` | 可选 |
+| `product_id` | `int64` | 可选 |
+| `product_args` | `string` | 可选 |
+| `number` | `int32` | 可选 |
+| `spec_id` | `int64` | 可选 |
+
+### order.CartDelRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `[]int64` | 数组 |
+
+### order.CartGetReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `[]order.CartItem` | 数组 |
+| `car_identity` | `string` | 可选 |
+
+### order.CartGetRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `car_identity` | `string` | 可选 |
+| `passport_identity` | `string` | 可选 |
+| `passport` | `string` | 可选 |
+
+### order.CartItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `product_id` | `int64` | 可选 |
+| `title` | `string` | 可选 |
+| `cover_image` | `string` | 可选 |
+| `sales_price` | `int64` | 可选 |
+| `product_identity` | `string` | 可选 |
+| `product_args` | `string` | 可选 |
+| `number` | `int32` | 可选 |
+| `unit_price` | `int64` | 可选 |
+| `total_price` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### order.CartSetRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `number` | `int32` | 可选 |
+| `unit_price` | `int64` | 可选 |
+| `id` | `int64` | 可选 |
+| `updates` | `[]order.Updates` | 数组 |
+
+### order.ConfirmReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total_price` | `int64` | 可选 |
+
+### order.ConfirmRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `order_no` | `string` | 可选 |
+| `address_identity` | `string` | 可选 |
+| `coupon_identity` | `string` | 可选 |
+| `remark` | `string` | 可选 |
+| `logistics_fee` | `double` | 可选 |
+
+### order.CouponItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `title` | `string` | 可选 |
+| `intro` | `string` | 可选 |
+| `amount` | `string` | 可选 |
+| `started` | `string` | 可选 |
+| `expired` | `string` | 可选 |
+| `status` | `string` | 可选 |
+
+### order.CouponListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `[]order.CouponItem` | 数组 |
+
+### order.CreateOrderRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `partner_id` | `int32` | 可选 |
+| `args` | `string` | 可选 |
+| `address_identity` | `string` | 可选 |
+| `delivery_time` | `string` | 可选 |
+| `spec` | `[]order.SpecList` | 数组 |
+
+### order.OrderAddress
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `country` | `string` | 可选 |
+| `province` | `string` | 可选 |
+| `city` | `string` | 可选 |
+| `area` | `string` | 可选 |
+| `detail` | `string` | 可选 |
+| `contact` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `email` | `string` | 可选 |
+| `zipCode` | `string` | 可选 |
+
+### order.OrderGetReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `summary` | `ec_order_blocks.OrderSummaryItem` | 可选 |
+
+### order.OrderListByStoreReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `count` | `int32` | 可选 |
+| `data` | `[]ec_order_blocks.OrderSummaryItem` | 数组 |
+
+### order.OrderListByStoreRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `pay_type` | `int32` | 可选 |
+| `order_status` | `[]int32` | 数组 |
+| `page_no` | `int64` | 可选 |
+| `page_size` | `int64` | 可选 |
+| `partner_id` | `int64` | 可选 |
+| `agency` | `string` | 可选 |
+| `storeIdentity` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+| `keyword` | `string` | 可选 |
+
+### order.QuickCreateByProductRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `partner_id` | `int32` | 可选 |
+| `store_identity` | `string` | 可选 |
+| `product_identity` | `string` | 可选 |
+| `number` | `int32` | 可选 |
+| `args` | `string` | 可选 |
+| `address_identity` | `string` | 可选 |
+| `delivery_time` | `string` | 可选 |
+| `spec_identity` | `string` | 可选 |
+| `member_identity` | `string` | 可选 |
+| `delivery_address` | `string` | 可选 |
+
+### order.SimulatePayRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `[]string` | 数组 |
+
+### order.SimulateShipmentsRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `item_idetity` | `string` | 可选 |
+| `member_identity` | `string` | 可选 |
+| `car_identity` | `string` | 可选 |
+
+### order.SpecList
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `number` | `int32` | 可选 |
+| `product_identity` | `string` | 可选 |
+
+### order.Status
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `status` | `int32` | 可选 |
+
+### order.SubmitRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `[]string` | 数组 |
+| `partner_id` | `int32` | 可选 |
+| `store_identity` | `string` | 可选 |
+| `address_identity` | `string` | 可选 |
+| `delivery_time` | `string` | 可选 |
+| `address` | `order.OrderAddress` | 可选 |
+
+### order.SummaryGetReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `summary` | `ec_order_blocks.OrderSummaryItem` | 可选 |
+
+### order.SummaryListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `count` | `int32` | 可选 |
+| `data` | `[]ec_order_blocks.OrderSummaryItem` | 数组 |
+
+### order.SummaryListRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `pay_type` | `int32` | 可选 |
+| `order_status` | `int32` | 可选 |
+| `page_no` | `int64` | 可选 |
+| `page_size` | `int64` | 可选 |
+
+### order.Updates
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `number` | `int64` | 可选 |

wiki/api/12-wallet.md

@@ -0,0 +1,843 @@
+# WALLET API
+
+钱包、支付方式、支付宝与微信支付。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/wallet/{Service}/{Method}`
+- 原生 gRPC：`/wallet.{Service}/{Method}`
+- grpc-gateway：`POST /wallet.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Alipay` | 4 | Alipay 服务 |
+| `Basic` | 8 | Basic 服务 |
+| `Payment` | 6 | Payment 服务 |
+| `Wechat` | 5 | Wechat 服务 |
+
+## Alipay
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `WapPay` | `POST /rpc/wallet/Alipay/WapPay` | [`wallet.AlipayTradeWapPayRequest`](#walletalipaytradewappayrequest) | [`wallet.AlipayTradeWapPayReply`](#walletalipaytradewappayreply) | Unary |
+| `PagePay` | `POST /rpc/wallet/Alipay/PagePay` | [`wallet.AlipayTradePagePayRequest`](#walletalipaytradepagepayrequest) | [`wallet.AlipayTradePagePayReply`](#walletalipaytradepagepayreply) | Unary |
+| `AppPay` | `POST /rpc/wallet/Alipay/AppPay` | [`wallet.AlipayTradeAppPayRequest`](#walletalipaytradeapppayrequest) | [`wallet.AlipayTradeAppPayReply`](#walletalipaytradeapppayreply) | Unary |
+| `Transfer` | `POST /rpc/wallet/Alipay/Transfer` | [`wallet.AlipayUniTransferRequest`](#walletalipayunitransferrequest) | [`wallet.AlipayUniTransferReply`](#walletalipayunitransferreply) | Unary |
+
+### Alipay.WapPay
+
+- 动态 HTTP：`POST /rpc/wallet/Alipay/WapPay`
+- gRPC：`/wallet.Alipay/WapPay`
+- 白名单键：`wallet.Alipay.WapPay`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "notifyUrl": "string",
+  "quitUrl": "string",
+  "userIdentification": "string"
+}
+```
+
+### Alipay.PagePay
+
+- 动态 HTTP：`POST /rpc/wallet/Alipay/PagePay`
+- gRPC：`/wallet.Alipay/PagePay`
+- 白名单键：`wallet.Alipay.PagePay`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "notifyUrl": "string",
+  "returnUrl": "string",
+  "userIdentification": "string"
+}
+```
+
+### Alipay.AppPay
+
+- 动态 HTTP：`POST /rpc/wallet/Alipay/AppPay`
+- gRPC：`/wallet.Alipay/AppPay`
+- 白名单键：`wallet.Alipay.AppPay`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "notifyUrl": "string",
+  "userIdentification": "string"
+}
+```
+
+### Alipay.Transfer
+
+- 动态 HTTP：`POST /rpc/wallet/Alipay/Transfer`
+- gRPC：`/wallet.Alipay/Transfer`
+- 白名单键：`wallet.Alipay.Transfer`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "fee": "0",
+  "userIdentification": "string"
+}
+```
+
+## Basic
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `GetWallet` | `POST /rpc/wallet/Basic/GetWallet` | [`wallet.GetWalletRequest`](#walletgetwalletrequest) | [`wallet.GetWalletReply`](#walletgetwalletreply) | Unary |
+| `SetPayPassword` | `POST /rpc/wallet/Basic/SetPayPassword` | [`wallet.SetPayPasswordRequest`](#walletsetpaypasswordrequest) | [`finance_wallet_blocks.StatusReply`](#finance_wallet_blocksstatusreply) | Unary |
+| `BindPaymentId` | `POST /rpc/wallet/Basic/BindPaymentId` | [`wallet.BindPaymentIDRequest`](#walletbindpaymentidrequest) | [`finance_wallet_blocks.StatusReply`](#finance_wallet_blocksstatusreply) | Unary |
+| `Transactions` | `POST /rpc/wallet/Basic/Transactions` | [`wallet.TransactionsRequest`](#wallettransactionsrequest) | [`wallet.TransactionsReply`](#wallettransactionsreply) | Unary |
+| `AddBankCard` | `POST /rpc/wallet/Basic/AddBankCard` | [`wallet.AddBankCardRequest`](#walletaddbankcardrequest) | [`finance_wallet_blocks.StatusReply`](#finance_wallet_blocksstatusreply) | Unary |
+| `GetBankCard` | `POST /rpc/wallet/Basic/GetBankCard` | [`wallet.FinanceEmpty`](#walletfinanceempty) | [`wallet.GetBankCardReply`](#walletgetbankcardreply) | Unary |
+| `RmBankCard` | `POST /rpc/wallet/Basic/RmBankCard` | [`wallet.RmBankCardRequest`](#walletrmbankcardrequest) | [`finance_wallet_blocks.StatusReply`](#finance_wallet_blocksstatusreply) | Unary |
+| `ApplyCash` | `POST /rpc/wallet/Basic/ApplyCash` | [`wallet.ApplyCashRequest`](#walletapplycashrequest) | [`finance_wallet_blocks.StatusReply`](#finance_wallet_blocksstatusreply) | Unary |
+
+### Basic.GetWallet
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/GetWallet`
+- gRPC：`/wallet.Basic/GetWallet`
+- 白名单键：`wallet.Basic.GetWallet`
+- 请求示例：
+
+```json
+{
+  "isTotalAllIn": false,
+  "isTotalAllOut": false,
+  "isTotalMonthIn": false,
+  "isTotalMonthOut": false,
+  "isTotalTodayIn": false,
+  "isTotalTodayOut": false
+}
+```
+
+### Basic.SetPayPassword
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/SetPayPassword`
+- gRPC：`/wallet.Basic/SetPayPassword`
+- 白名单键：`wallet.Basic.SetPayPassword`
+- 请求示例：
+
+```json
+{
+  "passportIdentity": "string",
+  "password": "string"
+}
+```
+
+### Basic.BindPaymentId
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/BindPaymentId`
+- gRPC：`/wallet.Basic/BindPaymentId`
+- 白名单键：`wallet.Basic.BindPaymentId`
+- 请求示例：
+
+```json
+{
+  "authCode": "string",
+  "payType": 0
+}
+```
+
+### Basic.Transactions
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/Transactions`
+- gRPC：`/wallet.Basic/Transactions`
+- 白名单键：`wallet.Basic.Transactions`
+- 请求示例：
+
+```json
+{
+  "end": "string",
+  "page": "0",
+  "pageSize": "0",
+  "start": "string",
+  "tradeType": "0",
+  "transType": "0"
+}
+```
+
+### Basic.AddBankCard
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/AddBankCard`
+- gRPC：`/wallet.Basic/AddBankCard`
+- 白名单键：`wallet.Basic.AddBankCard`
+- 请求示例：
+
+```json
+{
+  "cardNo": "string",
+  "cardOwner": "string",
+  "idCard": "string",
+  "phone": "string",
+  "walletIdentity": "string"
+}
+```
+
+### Basic.GetBankCard
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/GetBankCard`
+- gRPC：`/wallet.Basic/GetBankCard`
+- 白名单键：`wallet.Basic.GetBankCard`
+- 请求示例：
+
+```json
+{}
+```
+
+### Basic.RmBankCard
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/RmBankCard`
+- gRPC：`/wallet.Basic/RmBankCard`
+- 白名单键：`wallet.Basic.RmBankCard`
+- 请求示例：
+
+```json
+{
+  "identity": "string"
+}
+```
+
+### Basic.ApplyCash
+
+- 动态 HTTP：`POST /rpc/wallet/Basic/ApplyCash`
+- gRPC：`/wallet.Basic/ApplyCash`
+- 白名单键：`wallet.Basic.ApplyCash`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "channel": 0,
+  "remark": "string"
+}
+```
+
+## Payment
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Hello` | `POST /rpc/wallet/Payment/Hello` | [`finance_wallet_blocks.Empty`](#finance_wallet_blocksempty) | [`wallet.PaymentReply`](#walletpaymentreply) | Unary |
+| `Way` | `POST /rpc/wallet/Payment/Way` | [`wallet.WayRequest`](#walletwayrequest) | [`wallet.WayReply`](#walletwayreply) | Unary |
+| `Get` | `POST /rpc/wallet/Payment/Get` | [`finance_wallet_blocks.IdentRequest`](#finance_wallet_blocksidentrequest) | [`wallet.PaymentItem`](#walletpaymentitem) | Unary |
+| `ByOrder` | `POST /rpc/wallet/Payment/ByOrder` | [`wallet.OrderRequest`](#walletorderrequest) | [`wallet.PaymentReply`](#walletpaymentreply) | Unary |
+| `ByCharge` | `POST /rpc/wallet/Payment/ByCharge` | [`wallet.ChargeRequest`](#walletchargerequest) | [`wallet.PaymentReply`](#walletpaymentreply) | Unary |
+| `Callback` | `POST /rpc/wallet/Payment/Callback` | [`wallet.CallbackRequest`](#walletcallbackrequest) | [`finance_wallet_blocks.StatusReply`](#finance_wallet_blocksstatusreply) | Unary |
+
+### Payment.Hello
+
+- 动态 HTTP：`POST /rpc/wallet/Payment/Hello`
+- gRPC：`/wallet.Payment/Hello`
+- 白名单键：`wallet.Payment.Hello`
+- 请求示例：
+
+```json
+{}
+```
+
+### Payment.Way
+
+- 动态 HTTP：`POST /rpc/wallet/Payment/Way`
+- gRPC：`/wallet.Payment/Way`
+- 白名单键：`wallet.Payment.Way`
+- 请求示例：
+
+```json
+{
+  "platform": "string"
+}
+```
+
+### Payment.Get
+
+- 动态 HTTP：`POST /rpc/wallet/Payment/Get`
+- gRPC：`/wallet.Payment/Get`
+- 白名单键：`wallet.Payment.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Payment.ByOrder
+
+- 动态 HTTP：`POST /rpc/wallet/Payment/ByOrder`
+- gRPC：`/wallet.Payment/ByOrder`
+- 白名单键：`wallet.Payment.ByOrder`
+- 请求示例：
+
+```json
+{
+  "args": "string",
+  "desc": "string",
+  "openId": "string",
+  "orderNo": "string",
+  "password": "string",
+  "payChannel": 0,
+  "payType": "string"
+}
+```
+
+### Payment.ByCharge
+
+- 动态 HTTP：`POST /rpc/wallet/Payment/ByCharge`
+- gRPC：`/wallet.Payment/ByCharge`
+- 白名单键：`wallet.Payment.ByCharge`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "desc": "string",
+  "openId": "string",
+  "payChannel": 0,
+  "payType": "string",
+  "remark": "string"
+}
+```
+
+### Payment.Callback
+
+- 动态 HTTP：`POST /rpc/wallet/Payment/Callback`
+- gRPC：`/wallet.Payment/Callback`
+- 白名单键：`wallet.Payment.Callback`
+- 请求示例：
+
+```json
+{
+  "callbackMsg": "string",
+  "callbackStatus": false,
+  "id": "0",
+  "identity": "string"
+}
+```
+
+## Wechat
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `JsapiPreOrder` | `POST /rpc/wallet/Wechat/JsapiPreOrder` | [`wallet.WxpayJSAPIPreOrderRequest`](#walletwxpayjsapipreorderrequest) | [`wallet.WxpayJSAPIPreOrderReply`](#walletwxpayjsapipreorderreply) | Unary |
+| `AppPreOrder` | `POST /rpc/wallet/Wechat/AppPreOrder` | [`wallet.WxpayAppPreOrderRequest`](#walletwxpayapppreorderrequest) | [`wallet.WxpayAppPreOrderReply`](#walletwxpayapppreorderreply) | Unary |
+| `NativePreOrder` | `POST /rpc/wallet/Wechat/NativePreOrder` | [`wallet.WxpayNativePreOrderRequest`](#walletwxpaynativepreorderrequest) | [`wallet.WxpayNativePreOrderReply`](#walletwxpaynativepreorderreply) | Unary |
+| `Transfer` | `POST /rpc/wallet/Wechat/Transfer` | [`wallet.WxpayTransferRequest`](#walletwxpaytransferrequest) | [`wallet.WxpayTransferReply`](#walletwxpaytransferreply) | Unary |
+| `WxCallback` | `POST /rpc/wallet/Wechat/WxCallback` | [`wallet.WxCallBackRequest`](#walletwxcallbackrequest) | [`wallet.CallBackReply`](#walletcallbackreply) | Unary |
+
+### Wechat.JsapiPreOrder
+
+- 动态 HTTP：`POST /rpc/wallet/Wechat/JsapiPreOrder`
+- gRPC：`/wallet.Wechat/JsapiPreOrder`
+- 白名单键：`wallet.Wechat.JsapiPreOrder`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "authCode": "string",
+  "description": "string",
+  "notifyUrl": "string",
+  "orderNo": "string",
+  "userIdentification": "string"
+}
+```
+
+### Wechat.AppPreOrder
+
+- 动态 HTTP：`POST /rpc/wallet/Wechat/AppPreOrder`
+- gRPC：`/wallet.Wechat/AppPreOrder`
+- 白名单键：`wallet.Wechat.AppPreOrder`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "notifyUrl": "string",
+  "userIdentification": "string"
+}
+```
+
+### Wechat.NativePreOrder
+
+- 动态 HTTP：`POST /rpc/wallet/Wechat/NativePreOrder`
+- gRPC：`/wallet.Wechat/NativePreOrder`
+- 白名单键：`wallet.Wechat.NativePreOrder`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "notifyUrl": "string",
+  "userIdentification": "string"
+}
+```
+
+### Wechat.Transfer
+
+- 动态 HTTP：`POST /rpc/wallet/Wechat/Transfer`
+- gRPC：`/wallet.Wechat/Transfer`
+- 白名单键：`wallet.Wechat.Transfer`
+- 请求示例：
+
+```json
+{
+  "amount": "0",
+  "description": "string",
+  "fee": "0",
+  "transferName": "string",
+  "userIdentification": "string"
+}
+```
+
+### Wechat.WxCallback
+
+- 动态 HTTP：`POST /rpc/wallet/Wechat/WxCallback`
+- gRPC：`/wallet.Wechat/WxCallback`
+- 白名单键：`wallet.Wechat.WxCallback`
+- 请求示例：
+
+```json
+{
+  "SignInfo": {
+    "actCode": "string",
+    "activityId": "string",
+    "cardId": "string",
+    "code": "string",
+    "hallBelongMchId": "0",
+    "hallCode": "string",
+    "transactionId": "string"
+  },
+  "createTime": "string",
+  "eventType": "string",
+  "id": "string",
+  "resource": {
+    "algorithm": "string",
+    "associatedData": "string",
+    "ciphertext": "string",
+    "nonce": "string",
+    "originalType": "string"
+  },
+  "resourceType": "string",
+  "summary": "string"
+}
+```
+
+## 消息结构
+
+### finance_wallet_blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### finance_wallet_blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### finance_wallet_blocks.StatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int32` | 可选 |
+| `message` | `string` | 可选 |
+| `details` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### wallet.AddBankCardRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `walletIdentity` | `string` | 可选 |
+| `cardNo` | `string` | 可选 |
+| `cardOwner` | `string` | 可选 |
+| `idCard` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+
+### wallet.AlipayTradeAppPayReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `payParam` | `string` | 可选 |
+
+### wallet.AlipayTradeAppPayRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+| `notifyUrl` | `string` | 可选 |
+
+### wallet.AlipayTradePagePayReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `payUrl` | `string` | 可选 |
+
+### wallet.AlipayTradePagePayRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+| `notifyUrl` | `string` | 可选 |
+| `returnUrl` | `string` | 可选 |
+
+### wallet.AlipayTradeWapPayReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `payUrl` | `string` | 可选 |
+
+### wallet.AlipayTradeWapPayRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+| `notifyUrl` | `string` | 可选 |
+| `quitUrl` | `string` | 可选 |
+
+### wallet.AlipayUniTransferReply
+
+空消息：请求时发送 `{}`。
+
+### wallet.AlipayUniTransferRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `fee` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+
+### wallet.ApplyCashRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `channel` | `int32` | 可选 |
+| `amount` | `int64` | 可选 |
+| `remark` | `string` | 可选 |
+
+### wallet.BankCardInfo
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `bankNumber` | `string` | 可选 |
+| `bankName` | `string` | 可选 |
+| `cardOwner` | `string` | 可选 |
+| `idCard` | `string` | 可选 |
+| `phone` | `string` | 可选 |
+| `bindId` | `string` | 可选 |
+| `bankType` | `string` | 可选 |
+| `bank` | `string` | 可选 |
+| `created` | `string` | 可选 |
+
+### wallet.BindPaymentIDRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `payType` | `int32` | 可选 |
+| `authCode` | `string` | 可选 |
+
+### wallet.CallBackReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `string` | 可选 |
+| `message` | `string` | 可选 |
+
+### wallet.CallbackRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `callbackStatus` | `bool` | 可选 |
+| `callbackMsg` | `string` | 可选 |
+
+### wallet.ChargeRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `amount` | `int64` | 可选 |
+| `remark` | `string` | 可选 |
+| `payChannel` | `int32` | 可选 |
+| `payType` | `string` | 可选 |
+| `desc` | `string` | 可选 |
+| `openId` | `string` | 可选 |
+
+### wallet.FinanceEmpty
+
+空消息：请求时发送 `{}`。
+
+### wallet.GetBankCardReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `[]wallet.BankCardInfo` | 数组 |
+
+### wallet.GetWalletReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `passportIdentity` | `string` | 可选 |
+| `walletIdentity` | `string` | 可选 |
+| `balance` | `int64` | 可选 |
+| `withdrawalBalance` | `int64` | 可选 |
+| `status` | `int32` | 可选 |
+| `alipayId` | `string` | 可选 |
+| `alipayName` | `string` | 可选 |
+| `wxpayId` | `string` | 可选 |
+| `wxpayName` | `string` | 可选 |
+| `total` | `map<string, int64>` | 对象映射 |
+| `created` | `string` | 可选 |
+
+### wallet.GetWalletReply.TotalEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `int64` | 可选 |
+
+### wallet.GetWalletRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `isTotalTodayIn` | `bool` | 可选 |
+| `isTotalTodayOut` | `bool` | 可选 |
+| `isTotalMonthIn` | `bool` | 可选 |
+| `isTotalMonthOut` | `bool` | 可选 |
+| `isTotalAllIn` | `bool` | 可选 |
+| `isTotalAllOut` | `bool` | 可选 |
+
+### wallet.OrderRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `orderNo` | `string` | 可选 |
+| `payChannel` | `int32` | 可选 |
+| `payType` | `string` | 可选 |
+| `password` | `string` | 可选 |
+| `args` | `string` | 可选 |
+| `desc` | `string` | 可选 |
+| `openId` | `string` | 可选 |
+
+### wallet.PaymentItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `orderNo` | `string` | 可选 |
+| `tradeNo` | `string` | 可选 |
+| `type` | `int32` | 可选 |
+| `payChannel` | `int32` | 可选 |
+| `payType` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `args` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### wallet.PaymentReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `code` | `int64` | 可选 |
+| `result` | `map<string, string>` | 对象映射 |
+
+### wallet.PaymentReply.ResultEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### wallet.RmBankCardRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+
+### wallet.SetPayPasswordRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `passportIdentity` | `string` | 可选 |
+| `password` | `string` | 可选 |
+
+### wallet.Transaction
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `transType` | `int32` | 可选 |
+| `tradeType` | `int32` | 可选 |
+| `inTradeNo` | `string` | 可选 |
+| `outTradeNo` | `string` | 可选 |
+| `money` | `int64` | 可选 |
+| `fee` | `int64` | 可选 |
+| `payChannel` | `int32` | 可选 |
+| `payType` | `string` | 可选 |
+| `created` | `string` | 可选 |
+| `remark` | `string` | 可选 |
+
+### wallet.TransactionsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int64` | 可选 |
+| `records` | `[]wallet.Transaction` | 数组 |
+
+### wallet.TransactionsRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `transType` | `int64` | 可选 |
+| `tradeType` | `int64` | 可选 |
+| `start` | `string` | 可选 |
+| `end` | `string` | 可选 |
+| `page` | `int64` | 可选 |
+| `pageSize` | `int64` | 可选 |
+
+### wallet.WayItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `ident` | `string` | 可选 |
+| `title` | `string` | 可选 |
+| `intro` | `string` | 可选 |
+| `args` | `string` | 可选 |
+
+### wallet.WayReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `way` | `[]wallet.WayItem` | 数组 |
+
+### wallet.WayRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `platform` | `string` | 可选 |
+
+### wallet.WxCallBackRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `string` | 可选 |
+| `createTime` | `string` | 可选 |
+| `resourceType` | `string` | 可选 |
+| `eventType` | `string` | 可选 |
+| `summary` | `string` | 可选 |
+| `resource` | `wallet.WxCallBackResource` | 可选 |
+| `SignInfo` | `wallet.WxCallBackSignInfo` | 可选 |
+
+### wallet.WxCallBackResource
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `originalType` | `string` | 可选 |
+| `algorithm` | `string` | 可选 |
+| `ciphertext` | `string` | 可选 |
+| `associatedData` | `string` | 可选 |
+| `nonce` | `string` | 可选 |
+
+### wallet.WxCallBackSignInfo
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `transactionId` | `string` | 可选 |
+| `actCode` | `string` | 可选 |
+| `hallCode` | `string` | 可选 |
+| `hallBelongMchId` | `int64` | 可选 |
+| `cardId` | `string` | 可选 |
+| `code` | `string` | 可选 |
+| `activityId` | `string` | 可选 |
+
+### wallet.WxpayAppPreOrderReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `prepayId` | `string` | 可选 |
+| `appId` | `string` | 可选 |
+| `mchId` | `string` | 可选 |
+
+### wallet.WxpayAppPreOrderRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+| `notifyUrl` | `string` | 可选 |
+
+### wallet.WxpayJSAPIPreOrderReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `prepayId` | `string` | 可选 |
+| `appId` | `string` | 可选 |
+| `timestamp` | `string` | 可选 |
+| `nonceStr` | `string` | 可选 |
+| `signType` | `string` | 可选 |
+| `sign` | `string` | 可选 |
+
+### wallet.WxpayJSAPIPreOrderRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `authCode` | `string` | 可选 |
+| `description` | `string` | 可选 |
+| `notifyUrl` | `string` | 可选 |
+| `orderNo` | `string` | 可选 |
+
+### wallet.WxpayNativePreOrderReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `codeUrl` | `string` | 可选 |
+
+### wallet.WxpayNativePreOrderRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+| `notifyUrl` | `string` | 可选 |
+
+### wallet.WxpayTransferReply
+
+空消息：请求时发送 `{}`。
+
+### wallet.WxpayTransferRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `userIdentification` | `string` | 可选 |
+| `amount` | `int64` | 可选 |
+| `fee` | `int64` | 可选 |
+| `description` | `string` | 可选 |
+| `transferName` | `string` | 可选 |

wiki/api/13-feed.md

@@ -0,0 +1,470 @@
+# FEED API
+
+动态发布、标签、时间线和动态设置。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/feed/{Service}/{Method}`
+- 原生 gRPC：`/feed.{Service}/{Method}`
+- grpc-gateway：`POST /feed.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Post` | 8 | Post 服务 |
+| `Setting` | 2 | Setting 服务 |
+| `Tag` | 3 | Tag 服务 |
+| `Timeline` | 4 | Timeline 服务 |
+
+## Post
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Fetch` | `POST /rpc/feed/Post/Fetch` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FeedPostListReply`](#blocksfeedpostlistreply) | Unary |
+| `Create` | `POST /rpc/feed/Post/Create` | [`blocks.FeedPostItem`](#blocksfeedpostitem) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Change` | `POST /rpc/feed/Post/Change` | [`blocks.FeedPostItem`](#blocksfeedpostitem) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Remove` | `POST /rpc/feed/Post/Remove` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `CommentList` | `POST /rpc/feed/Post/CommentList` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`feed.CommentListReply`](#feedcommentlistreply) | Unary |
+| `AddComment` | `POST /rpc/feed/Post/AddComment` | [`feed.CommentItem`](#feedcommentitem) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DeleteComment` | `POST /rpc/feed/Post/DeleteComment` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Action` | `POST /rpc/feed/Post/Action` | [`feed.PostActionRequest`](#feedpostactionrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Post.Fetch
+
+- 动态 HTTP：`POST /rpc/feed/Post/Fetch`
+- gRPC：`/feed.Post/Fetch`
+- 白名单键：`feed.Post.Fetch`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Post.Create
+
+- 动态 HTTP：`POST /rpc/feed/Post/Create`
+- gRPC：`/feed.Post/Create`
+- 白名单键：`feed.Post.Create`
+- 请求示例：
+
+```json
+{
+  "attachs": [
+    {
+      "attachType": "string",
+      "identity": "string",
+      "url": "string"
+    }
+  ],
+  "cntComment": "0",
+  "cntLike": "0",
+  "cntUnlike": "0",
+  "content": "string",
+  "feedId": "0",
+  "feedIdentity": "string",
+  "identity": "string",
+  "isOpen": false,
+  "tags": [
+    {
+      "content": "string",
+      "key": "string"
+    }
+  ]
+}
+```
+
+### Post.Change
+
+- 动态 HTTP：`POST /rpc/feed/Post/Change`
+- gRPC：`/feed.Post/Change`
+- 白名单键：`feed.Post.Change`
+- 请求示例：
+
+```json
+{
+  "attachs": [
+    {
+      "attachType": "string",
+      "identity": "string",
+      "url": "string"
+    }
+  ],
+  "cntComment": "0",
+  "cntLike": "0",
+  "cntUnlike": "0",
+  "content": "string",
+  "feedId": "0",
+  "feedIdentity": "string",
+  "identity": "string",
+  "isOpen": false,
+  "tags": [
+    {
+      "content": "string",
+      "key": "string"
+    }
+  ]
+}
+```
+
+### Post.Remove
+
+- 动态 HTTP：`POST /rpc/feed/Post/Remove`
+- gRPC：`/feed.Post/Remove`
+- 白名单键：`feed.Post.Remove`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Post.CommentList
+
+- 动态 HTTP：`POST /rpc/feed/Post/CommentList`
+- gRPC：`/feed.Post/CommentList`
+- 白名单键：`feed.Post.CommentList`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Post.AddComment
+
+- 动态 HTTP：`POST /rpc/feed/Post/AddComment`
+- gRPC：`/feed.Post/AddComment`
+- 白名单键：`feed.Post.AddComment`
+- 请求示例：
+
+```json
+{
+  "content": "string",
+  "feedIdentity": "string",
+  "identity": "string",
+  "postIdentity": "string",
+  "subComment": [
+    {}
+  ]
+}
+```
+
+### Post.DeleteComment
+
+- 动态 HTTP：`POST /rpc/feed/Post/DeleteComment`
+- gRPC：`/feed.Post/DeleteComment`
+- 白名单键：`feed.Post.DeleteComment`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Post.Action
+
+- 动态 HTTP：`POST /rpc/feed/Post/Action`
+- gRPC：`/feed.Post/Action`
+- 白名单键：`feed.Post.Action`
+- 请求示例：
+
+```json
+{
+  "actionOp": "string",
+  "actionType": "string",
+  "identity": "string"
+}
+```
+
+## Setting
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Info` | `POST /rpc/feed/Setting/Info` | [`blocks.Empty`](#blocksempty) | [`blocks.Empty`](#blocksempty) | Unary |
+| `Rights` | `POST /rpc/feed/Setting/Rights` | [`blocks.Empty`](#blocksempty) | [`blocks.Empty`](#blocksempty) | Unary |
+
+### Setting.Info
+
+- 动态 HTTP：`POST /rpc/feed/Setting/Info`
+- gRPC：`/feed.Setting/Info`
+- 白名单键：`feed.Setting.Info`
+- 请求示例：
+
+```json
+{}
+```
+
+### Setting.Rights
+
+- 动态 HTTP：`POST /rpc/feed/Setting/Rights`
+- gRPC：`/feed.Setting/Rights`
+- 白名单键：`feed.Setting.Rights`
+- 请求示例：
+
+```json
+{}
+```
+
+## Tag
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `List` | `POST /rpc/feed/Tag/List` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`feed.TagListReply`](#feedtaglistreply) | Unary |
+| `Create` | `POST /rpc/feed/Tag/Create` | [`feed.AddTagRequest`](#feedaddtagrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `PostList` | `POST /rpc/feed/Tag/PostList` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FeedPostListReply`](#blocksfeedpostlistreply) | Unary |
+
+### Tag.List
+
+- 动态 HTTP：`POST /rpc/feed/Tag/List`
+- gRPC：`/feed.Tag/List`
+- 白名单键：`feed.Tag.List`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Tag.Create
+
+- 动态 HTTP：`POST /rpc/feed/Tag/Create`
+- gRPC：`/feed.Tag/Create`
+- 白名单键：`feed.Tag.Create`
+- 请求示例：
+
+```json
+{
+  "tags": [
+    "string"
+  ]
+}
+```
+
+### Tag.PostList
+
+- 动态 HTTP：`POST /rpc/feed/Tag/PostList`
+- gRPC：`/feed.Tag/PostList`
+- 白名单键：`feed.Tag.PostList`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+## Timeline
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Recommend` | `POST /rpc/feed/Timeline/Recommend` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FeedPostListReply`](#blocksfeedpostlistreply) | Unary |
+| `Friend` | `POST /rpc/feed/Timeline/Friend` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FeedPostListReply`](#blocksfeedpostlistreply) | Unary |
+| `Follow` | `POST /rpc/feed/Timeline/Follow` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FeedPostListReply`](#blocksfeedpostlistreply) | Unary |
+| `Hot` | `POST /rpc/feed/Timeline/Hot` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FeedPostListReply`](#blocksfeedpostlistreply) | Unary |
+
+### Timeline.Recommend
+
+- 动态 HTTP：`POST /rpc/feed/Timeline/Recommend`
+- gRPC：`/feed.Timeline/Recommend`
+- 白名单键：`feed.Timeline.Recommend`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Timeline.Friend
+
+- 动态 HTTP：`POST /rpc/feed/Timeline/Friend`
+- gRPC：`/feed.Timeline/Friend`
+- 白名单键：`feed.Timeline.Friend`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Timeline.Follow
+
+- 动态 HTTP：`POST /rpc/feed/Timeline/Follow`
+- gRPC：`/feed.Timeline/Follow`
+- 白名单键：`feed.Timeline.Follow`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Timeline.Hot
+
+- 动态 HTTP：`POST /rpc/feed/Timeline/Hot`
+- gRPC：`/feed.Timeline/Hot`
+- 白名单键：`feed.Timeline.Hot`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+## 消息结构
+
+### blocks.DataStatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### blocks.FeedAttachItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `attachType` | `string` | 可选 |
+| `url` | `string` | 可选 |
+
+### blocks.FeedPostItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `content` | `string` | 可选 |
+| `feedId` | `int64` | 可选 |
+| `feedIdentity` | `string` | 可选 |
+| `isOpen` | `bool` | 可选 |
+| `cntUnlike` | `int64` | 可选 |
+| `cntComment` | `int64` | 可选 |
+| `cntLike` | `int64` | 可选 |
+| `attachs` | `[]blocks.FeedAttachItem` | 数组 |
+| `tags` | `[]blocks.FeedTagItem` | 数组 |
+
+### blocks.FeedPostListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `list` | `[]blocks.FeedPostItem` | 数组 |
+| `cnt` | `int64` | 可选 |
+
+### blocks.FeedTagItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `content` | `string` | 可选 |
+
+### blocks.FetchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `page_no` | `int64` | 可选 |
+| `page_size` | `int64` | 可选 |
+| `params` | `map<string, string>` | 对象映射 |
+
+### blocks.FetchRequest.ParamsEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### feed.AddTagRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `tags` | `[]string` | 数组 |
+
+### feed.CommentItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `postIdentity` | `string` | 可选 |
+| `feedIdentity` | `string` | 可选 |
+| `content` | `string` | 可选 |
+| `subComment` | `[]feed.CommentItem` | 数组 |
+
+### feed.CommentListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `list` | `[]feed.CommentItem` | 数组 |
+| `total` | `int64` | 可选 |
+
+### feed.PostActionRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `actionOp` | `string` | 可选 |
+| `actionType` | `string` | 可选 |
+| `identity` | `string` | 可选 |
+
+### feed.TagListReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `tags` | `[]blocks.FeedTagItem` | 数组 |
+| `total` | `int64` | 可选 |

wiki/api/14-group.md

@@ -0,0 +1,388 @@
+# GROUP API
+
+群组及成员管理。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/group/{Service}/{Method}`
+- 原生 gRPC：`/group.{Service}/{Method}`
+- grpc-gateway：`POST /group.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Basic` | 6 | Basic 服务 |
+| `Member` | 7 | Member 服务 |
+
+## Basic
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Search` | `POST /rpc/group/Basic/Search` | [`blocks.SearchRequest`](#blockssearchrequest) | [`group.GroupsReply`](#groupgroupsreply) | Unary |
+| `Fetch` | `POST /rpc/group/Basic/Fetch` | [`blocks.Empty`](#blocksempty) | [`group.GroupsReply`](#groupgroupsreply) | Unary |
+| `Get` | `POST /rpc/group/Basic/Get` | [`blocks.IdentRequest`](#blocksidentrequest) | [`group.GroupItem`](#groupgroupitem) | Unary |
+| `Create` | `POST /rpc/group/Basic/Create` | [`group.GroupItem`](#groupgroupitem) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Modify` | `POST /rpc/group/Basic/Modify` | [`group.GroupItem`](#groupgroupitem) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Disband` | `POST /rpc/group/Basic/Disband` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Basic.Search
+
+- 动态 HTTP：`POST /rpc/group/Basic/Search`
+- gRPC：`/group.Basic/Search`
+- 白名单键：`group.Basic.Search`
+- 请求示例：
+
+```json
+{
+  "keyword": "string"
+}
+```
+
+### Basic.Fetch
+
+- 动态 HTTP：`POST /rpc/group/Basic/Fetch`
+- gRPC：`/group.Basic/Fetch`
+- 白名单键：`group.Basic.Fetch`
+- 请求示例：
+
+```json
+{}
+```
+
+### Basic.Get
+
+- 动态 HTTP：`POST /rpc/group/Basic/Get`
+- gRPC：`/group.Basic/Get`
+- 白名单键：`group.Basic.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Basic.Create
+
+- 动态 HTTP：`POST /rpc/group/Basic/Create`
+- gRPC：`/group.Basic/Create`
+- 白名单键：`group.Basic.Create`
+- 请求示例：
+
+```json
+{
+  "avatar": "string",
+  "background": "string",
+  "createdAt": "string",
+  "creatorId": "0",
+  "cretorIdentity": "string",
+  "enableSearchByName": false,
+  "enableSearchByNumber": false,
+  "id": "0",
+  "identity": "string",
+  "introduce": "string",
+  "master": [
+    "string"
+  ],
+  "memberLimit": 0,
+  "memberTotal": 0,
+  "name": "string",
+  "notice": "string",
+  "number": "0",
+  "tags": [
+    "string"
+  ]
+}
+```
+
+### Basic.Modify
+
+- 动态 HTTP：`POST /rpc/group/Basic/Modify`
+- gRPC：`/group.Basic/Modify`
+- 白名单键：`group.Basic.Modify`
+- 请求示例：
+
+```json
+{
+  "avatar": "string",
+  "background": "string",
+  "createdAt": "string",
+  "creatorId": "0",
+  "cretorIdentity": "string",
+  "enableSearchByName": false,
+  "enableSearchByNumber": false,
+  "id": "0",
+  "identity": "string",
+  "introduce": "string",
+  "master": [
+    "string"
+  ],
+  "memberLimit": 0,
+  "memberTotal": 0,
+  "name": "string",
+  "notice": "string",
+  "number": "0",
+  "tags": [
+    "string"
+  ]
+}
+```
+
+### Basic.Disband
+
+- 动态 HTTP：`POST /rpc/group/Basic/Disband`
+- gRPC：`/group.Basic/Disband`
+- 白名单键：`group.Basic.Disband`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+## Member
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Fetch` | `POST /rpc/group/Member/Fetch` | [`blocks.IdentRequest`](#blocksidentrequest) | [`group.GroupMemberReply`](#groupgroupmemberreply) | Unary |
+| `DoJoin` | `POST /rpc/group/Member/DoJoin` | [`group.DoJoinRequest`](#groupdojoinrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `JoinFetch` | `POST /rpc/group/Member/JoinFetch` | [`blocks.Empty`](#blocksempty) | [`group.JoinFetchReply`](#groupjoinfetchreply) | Unary |
+| `JoinDoHandle` | `POST /rpc/group/Member/JoinDoHandle` | [`group.GroupOPRequest`](#groupgroupoprequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoSetManager` | `POST /rpc/group/Member/DoSetManager` | [`group.GroupOPRequest`](#groupgroupoprequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoKick` | `POST /rpc/group/Member/DoKick` | [`group.GroupOPRequest`](#groupgroupoprequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoQuit` | `POST /rpc/group/Member/DoQuit` | [`group.GroupOPRequest`](#groupgroupoprequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Member.Fetch
+
+- 动态 HTTP：`POST /rpc/group/Member/Fetch`
+- gRPC：`/group.Member/Fetch`
+- 白名单键：`group.Member.Fetch`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Member.DoJoin
+
+- 动态 HTTP：`POST /rpc/group/Member/DoJoin`
+- gRPC：`/group.Member/DoJoin`
+- 白名单键：`group.Member.DoJoin`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string",
+  "message": "string"
+}
+```
+
+### Member.JoinFetch
+
+- 动态 HTTP：`POST /rpc/group/Member/JoinFetch`
+- gRPC：`/group.Member/JoinFetch`
+- 白名单键：`group.Member.JoinFetch`
+- 请求示例：
+
+```json
+{}
+```
+
+### Member.JoinDoHandle
+
+- 动态 HTTP：`POST /rpc/group/Member/JoinDoHandle`
+- gRPC：`/group.Member/JoinDoHandle`
+- 白名单键：`group.Member.JoinDoHandle`
+- 请求示例：
+
+```json
+{
+  "direction": "string",
+  "groupIdentity": "string",
+  "identity": "string"
+}
+```
+
+### Member.DoSetManager
+
+- 动态 HTTP：`POST /rpc/group/Member/DoSetManager`
+- gRPC：`/group.Member/DoSetManager`
+- 白名单键：`group.Member.DoSetManager`
+- 请求示例：
+
+```json
+{
+  "direction": "string",
+  "groupIdentity": "string",
+  "identity": "string"
+}
+```
+
+### Member.DoKick
+
+- 动态 HTTP：`POST /rpc/group/Member/DoKick`
+- gRPC：`/group.Member/DoKick`
+- 白名单键：`group.Member.DoKick`
+- 请求示例：
+
+```json
+{
+  "direction": "string",
+  "groupIdentity": "string",
+  "identity": "string"
+}
+```
+
+### Member.DoQuit
+
+- 动态 HTTP：`POST /rpc/group/Member/DoQuit`
+- gRPC：`/group.Member/DoQuit`
+- 白名单键：`group.Member.DoQuit`
+- 请求示例：
+
+```json
+{
+  "direction": "string",
+  "groupIdentity": "string",
+  "identity": "string"
+}
+```
+
+## 消息结构
+
+### blocks.DataStatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### blocks.SearchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `keyword` | `string` | 可选 |
+
+### group.ApplyJoinGroupItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `groupId` | `int64` | 可选 |
+| `from` | `group.PassportInfoDetailCard` | 可选 |
+| `message` | `string` | 可选 |
+| `createdAt` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### group.DoJoinRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `message` | `string` | 可选 |
+
+### group.GroupItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `number` | `int64` | 可选 |
+| `avatar` | `string` | 可选 |
+| `name` | `string` | 可选 |
+| `introduce` | `string` | 可选 |
+| `creatorId` | `int64` | 可选 |
+| `cretorIdentity` | `string` | 可选 |
+| `memberLimit` | `int32` | 可选 |
+| `master` | `[]string` | 数组 |
+| `notice` | `string` | 可选 |
+| `background` | `string` | 可选 |
+| `tags` | `[]string` | 数组 |
+| `memberTotal` | `int32` | 可选 |
+| `enableSearchByNumber` | `bool` | 可选 |
+| `enableSearchByName` | `bool` | 可选 |
+| `createdAt` | `string` | 可选 |
+
+### group.GroupMemberReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `members` | `[]group.PassportInfoSimpleCard` | 数组 |
+
+### group.GroupOPRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `groupIdentity` | `string` | 可选 |
+| `direction` | `string` | 可选 |
+
+### group.GroupsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `groups` | `[]group.GroupItem` | 数组 |
+
+### group.JoinFetchReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `applys` | `[]group.ApplyJoinGroupItem` | 数组 |
+
+### group.PassportInfoDetailCard
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+| `remarkName` | `string` | 可选 |
+| `popular` | `int32` | 可选 |
+| `avatar` | `string` | 可选 |
+| `birthday` | `string` | 可选 |
+| `sex` | `int32` | 可选 |
+| `province` | `int32` | 可选 |
+| `city` | `int32` | 可选 |
+| `area` | `int32` | 可选 |
+| `sign` | `string` | 可选 |
+| `tags` | `[]string` | 数组 |
+| `foreignStatus` | `int32` | 可选 |
+
+### group.PassportInfoSimpleCard
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+| `remarkName` | `string` | 可选 |
+| `avatar` | `string` | 可选 |
+| `sex` | `int32` | 可选 |
+| `role` | `int32` | 可选 |

wiki/api/15-relation.md

@@ -0,0 +1,599 @@
+# RELATION API
+
+关注、好友和关系匹配。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/relation/{Service}/{Method}`
+- 原生 gRPC：`/relation.{Service}/{Method}`
+- grpc-gateway：`POST /relation.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Follow` | 4 | Follow 服务 |
+| `Friend` | 17 | Friend 服务 |
+| `Match` | 4 | Match 服务 |
+
+## Follow
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Doing` | `POST /rpc/relation/Follow/Doing` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Undo` | `POST /rpc/relation/Follow/Undo` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `State` | `POST /rpc/relation/Follow/State` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Fetch` | `POST /rpc/relation/Follow/Fetch` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FetchRelationItemReply`](#blocksfetchrelationitemreply) | Unary |
+
+### Follow.Doing
+
+- 动态 HTTP：`POST /rpc/relation/Follow/Doing`
+- gRPC：`/relation.Follow/Doing`
+- 白名单键：`relation.Follow.Doing`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Follow.Undo
+
+- 动态 HTTP：`POST /rpc/relation/Follow/Undo`
+- gRPC：`/relation.Follow/Undo`
+- 白名单键：`relation.Follow.Undo`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Follow.State
+
+- 动态 HTTP：`POST /rpc/relation/Follow/State`
+- gRPC：`/relation.Follow/State`
+- 白名单键：`relation.Follow.State`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Follow.Fetch
+
+- 动态 HTTP：`POST /rpc/relation/Follow/Fetch`
+- gRPC：`/relation.Follow/Fetch`
+- 白名单键：`relation.Follow.Fetch`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+## Friend
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Search` | `POST /rpc/relation/Friend/Search` | [`blocks.SearchRequest`](#blockssearchrequest) | [`relation.PartFriendReply`](#relationpartfriendreply) | Unary |
+| `Fetch` | `POST /rpc/relation/Friend/Fetch` | [`blocks.VersionRequest`](#blocksversionrequest) | [`relation.FriendsReply`](#relationfriendsreply) | Unary |
+| `Get` | `POST /rpc/relation/Friend/Get` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.RelationItem`](#blocksrelationitem) | Unary |
+| `ModifyNickname` | `POST /rpc/relation/Friend/ModifyNickname` | [`relation.ModifyNicknameRequest`](#relationmodifynicknamerequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoPopular` | `POST /rpc/relation/Friend/DoPopular` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `UndoPopular` | `POST /rpc/relation/Friend/UndoPopular` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Delete` | `POST /rpc/relation/Friend/Delete` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyFetch` | `POST /rpc/relation/Friend/ApplyFetch` | [`blocks.VersionRequest`](#blocksversionrequest) | [`relation.ApplyFetchReply`](#relationapplyfetchreply) | Unary |
+| `ApplyGet` | `POST /rpc/relation/Friend/ApplyGet` | [`blocks.IdentRequest`](#blocksidentrequest) | [`relation.FriendApplyGetReply`](#relationfriendapplygetreply) | Unary |
+| `ApplyDo` | `POST /rpc/relation/Friend/ApplyDo` | [`relation.ApplyDoRequest`](#relationapplydorequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyDoMessage` | `POST /rpc/relation/Friend/ApplyDoMessage` | [`relation.ApplyMessageRequest`](#relationapplymessagerequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyDoPass` | `POST /rpc/relation/Friend/ApplyDoPass` | [`relation.ApplyDoPassRequest`](#relationapplydopassrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyDoReject` | `POST /rpc/relation/Friend/ApplyDoReject` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `TagFetch` | `POST /rpc/relation/Friend/TagFetch` | [`blocks.Empty`](#blocksempty) | [`relation.FriendTagsReply`](#relationfriendtagsreply) | Unary |
+| `TagMemberFetch` | `POST /rpc/relation/Friend/TagMemberFetch` | [`blocks.IdentRequest`](#blocksidentrequest) | [`relation.PartFriendReply`](#relationpartfriendreply) | Unary |
+| `TagDoCreate` | `POST /rpc/relation/Friend/TagDoCreate` | [`relation.TagDoCreateRequest`](#relationtagdocreaterequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `TagDoUpdate` | `POST /rpc/relation/Friend/TagDoUpdate` | [`relation.TagDoUpdateRequest`](#relationtagdoupdaterequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Friend.Search
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Search`
+- gRPC：`/relation.Friend/Search`
+- 白名单键：`relation.Friend.Search`
+- 请求示例：
+
+```json
+{
+  "keyword": "string"
+}
+```
+
+### Friend.Fetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Fetch`
+- gRPC：`/relation.Friend/Fetch`
+- 白名单键：`relation.Friend.Fetch`
+- 请求示例：
+
+```json
+{
+  "version": "0"
+}
+```
+
+### Friend.Get
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Get`
+- gRPC：`/relation.Friend/Get`
+- 白名单键：`relation.Friend.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.ModifyNickname
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ModifyNickname`
+- gRPC：`/relation.Friend/ModifyNickname`
+- 白名单键：`relation.Friend.ModifyNickname`
+- 请求示例：
+
+```json
+{
+  "identity": "string",
+  "nickname": "string"
+}
+```
+
+### Friend.DoPopular
+
+- 动态 HTTP：`POST /rpc/relation/Friend/DoPopular`
+- gRPC：`/relation.Friend/DoPopular`
+- 白名单键：`relation.Friend.DoPopular`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.UndoPopular
+
+- 动态 HTTP：`POST /rpc/relation/Friend/UndoPopular`
+- gRPC：`/relation.Friend/UndoPopular`
+- 白名单键：`relation.Friend.UndoPopular`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.Delete
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Delete`
+- gRPC：`/relation.Friend/Delete`
+- 白名单键：`relation.Friend.Delete`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.ApplyFetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyFetch`
+- gRPC：`/relation.Friend/ApplyFetch`
+- 白名单键：`relation.Friend.ApplyFetch`
+- 请求示例：
+
+```json
+{
+  "version": "0"
+}
+```
+
+### Friend.ApplyGet
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyGet`
+- gRPC：`/relation.Friend/ApplyGet`
+- 白名单键：`relation.Friend.ApplyGet`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.ApplyDo
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDo`
+- gRPC：`/relation.Friend/ApplyDo`
+- 白名单键：`relation.Friend.ApplyDo`
+- 请求示例：
+
+```json
+{
+  "body": "string",
+  "toId": "0",
+  "toIdentity": "string"
+}
+```
+
+### Friend.ApplyDoMessage
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDoMessage`
+- gRPC：`/relation.Friend/ApplyDoMessage`
+- 白名单键：`relation.Friend.ApplyDoMessage`
+- 请求示例：
+
+```json
+{
+  "applyId": "0",
+  "body": "string"
+}
+```
+
+### Friend.ApplyDoPass
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDoPass`
+- gRPC：`/relation.Friend/ApplyDoPass`
+- 白名单键：`relation.Friend.ApplyDoPass`
+- 请求示例：
+
+```json
+{
+  "applyIdentity": "string",
+  "friendRelationId": "0",
+  "friendRelationIdentity": "string"
+}
+```
+
+### Friend.ApplyDoReject
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDoReject`
+- gRPC：`/relation.Friend/ApplyDoReject`
+- 白名单键：`relation.Friend.ApplyDoReject`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.TagFetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagFetch`
+- gRPC：`/relation.Friend/TagFetch`
+- 白名单键：`relation.Friend.TagFetch`
+- 请求示例：
+
+```json
+{}
+```
+
+### Friend.TagMemberFetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagMemberFetch`
+- gRPC：`/relation.Friend/TagMemberFetch`
+- 白名单键：`relation.Friend.TagMemberFetch`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.TagDoCreate
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagDoCreate`
+- gRPC：`/relation.Friend/TagDoCreate`
+- 白名单键：`relation.Friend.TagDoCreate`
+- 请求示例：
+
+```json
+{
+  "friendIdentity": [
+    "string"
+  ],
+  "tagName": "string"
+}
+```
+
+### Friend.TagDoUpdate
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagDoUpdate`
+- gRPC：`/relation.Friend/TagDoUpdate`
+- 白名单键：`relation.Friend.TagDoUpdate`
+- 请求示例：
+
+```json
+{
+  "direction": "string",
+  "friendIdentity": "string",
+  "tagIdentity": "string"
+}
+```
+
+## Match
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Fetch` | `POST /rpc/relation/Match/Fetch` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FetchRelationItemReply`](#blocksfetchrelationitemreply) | Unary |
+| `Get` | `POST /rpc/relation/Match/Get` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.RelationItem`](#blocksrelationitem) | Unary |
+| `DoJoin` | `POST /rpc/relation/Match/DoJoin` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoIgnore` | `POST /rpc/relation/Match/DoIgnore` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Match.Fetch
+
+- 动态 HTTP：`POST /rpc/relation/Match/Fetch`
+- gRPC：`/relation.Match/Fetch`
+- 白名单键：`relation.Match.Fetch`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Match.Get
+
+- 动态 HTTP：`POST /rpc/relation/Match/Get`
+- gRPC：`/relation.Match/Get`
+- 白名单键：`relation.Match.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Match.DoJoin
+
+- 动态 HTTP：`POST /rpc/relation/Match/DoJoin`
+- gRPC：`/relation.Match/DoJoin`
+- 白名单键：`relation.Match.DoJoin`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Match.DoIgnore
+
+- 动态 HTTP：`POST /rpc/relation/Match/DoIgnore`
+- gRPC：`/relation.Match/DoIgnore`
+- 白名单键：`relation.Match.DoIgnore`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+## 消息结构
+
+### blocks.DataStatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### blocks.FetchRelationItemReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int64` | 可选 |
+| `data` | `[]blocks.RelationItem` | 数组 |
+
+### blocks.FetchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `page_no` | `int64` | 可选 |
+| `page_size` | `int64` | 可选 |
+| `params` | `map<string, string>` | 对象映射 |
+
+### blocks.FetchRequest.ParamsEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### blocks.RelationItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+| `remarkName` | `string` | 可选 |
+| `popular` | `int32` | 可选 |
+| `avatar` | `string` | 可选 |
+| `birthday` | `string` | 可选 |
+| `sex` | `int32` | 可选 |
+| `province` | `int32` | 可选 |
+| `city` | `int32` | 可选 |
+| `area` | `int32` | 可选 |
+| `sign` | `string` | 可选 |
+| `tags` | `[]string` | 数组 |
+| `foreignStatus` | `int32` | 可选 |
+
+### blocks.SearchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `keyword` | `string` | 可选 |
+
+### blocks.VersionRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `version` | `int64` | 可选 |
+
+### relation.ApplyDoPassRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `friendRelationId` | `int64` | 可选 |
+| `friendRelationIdentity` | `string` | 可选 |
+| `applyIdentity` | `string` | 可选 |
+
+### relation.ApplyDoRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `toId` | `int64` | 可选 |
+| `toIdentity` | `string` | 可选 |
+| `body` | `string` | 可选 |
+
+### relation.ApplyFetchReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `applys` | `[]relation.ApplyItem` | 数组 |
+
+### relation.ApplyItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `from` | `blocks.RelationItem` | 可选 |
+| `message` | `relation.MessageItem` | 可选 |
+| `createdAt` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### relation.ApplyMessageRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `applyId` | `int64` | 可选 |
+| `body` | `string` | 可选 |
+
+### relation.FriendApplyGetReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `blocks.RelationItem` | 可选 |
+| `message` | `[]relation.MessageItem` | 数组 |
+
+### relation.FriendTagsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int64` | 可选 |
+| `data` | `[]relation.TagItem` | 数组 |
+
+### relation.FriendsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `tags` | `[]relation.TagItem` | 数组 |
+| `friends` | `[]blocks.RelationItem` | 数组 |
+
+### relation.MessageItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `relationIdentity` | `string` | 可选 |
+| `body` | `string` | 可选 |
+| `createdAt` | `string` | 可选 |
+
+### relation.ModifyNicknameRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+
+### relation.PartFriendReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `friends` | `[]blocks.RelationItem` | 数组 |
+
+### relation.TagDoCreateRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `tagName` | `string` | 可选 |
+| `friendIdentity` | `[]string` | 数组 |
+
+### relation.TagDoUpdateRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `tagIdentity` | `string` | 可选 |
+| `friendIdentity` | `string` | 可选 |
+| `direction` | `string` | 可选 |
+
+### relation.TagItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `friendTotal` | `int64` | 可选 |
+| `tagName` | `string` | 可选 |

wiki/api/16-fts-rest.md

@@ -0,0 +1,33 @@
+# FTS REST API
+
+文件上传与文件服务配置。基础路径：`/rest/fts`。
+
+## 路由
+
+| 方法 | 路径 | 鉴权 | 请求 | 说明 |
+|---|---|---|---|---|
+| GET | `/rest/fts/ping` | 否 | 无 | 健康检查，返回 Pong |
+| GET | `/rest/fts/config` | 否 | 无 | 获取上传字段、大小和扩展名限制 |
+| POST | `/rest/fts/uploader` | Bearer Token | `multipart/form-data` | 上传文件到 local 或 MinIO |
+
+## 上传文件
+
+```http
+POST /rest/fts/uploader
+Authorization: Bearer <token>
+Content-Type: multipart/form-data
+```
+
+| 表单字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `provider` | string | 是 | `local` 或 `minio`，服务端转为小写 |
+| `bucket` | string | 是 | 存储桶或本地目录分类，服务端转为小写 |
+| `file` | file | 是 | 默认字段名；实际由配置 `Fts.FtsConfig.InputKey` 决定 |
+
+服务端校验文件大小和扩展名，计算 SHA-256，并保存文件记录。默认开发配置最大 5 GiB，允许的扩展名见 `/rest/fts/config`。
+
+成功数据为文件记录，常用字段：`identity`、`name`、`ext`、`size`、`hash`、`status` 以及最终访问地址。响应使用项目统一结构：
+
+```json
+{"code":0,"message":"success","data":{}}
+```

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` 配置，否则日志写入可能被拒绝。
+

wiki/api/18-mgt-rest.md

@@ -0,0 +1,132 @@
+# MGT REST API
+
+后台用户、应用、角色、权限和部门管理。基础路径：`/rest/mgt`。除匿名接口外均需 Bearer Token；标记“管理员”的路由还会执行管理员权限检查。
+
+## 匿名接口
+
+| 方法 | 路径 | 请求类型 | 说明 |
+|---|---|---|---|
+| GET | `/rest/mgt/ping` | 无 | 健康检查 |
+| GET | `/rest/mgt/session` | 无 | Session 演示接口 |
+| POST | `/rest/mgt/login` | `LoginRequest` | 登录并获取 token |
+| POST | `/rest/mgt/refresh` | 当前凭证 | 刷新登录状态 |
+| POST | `/rest/mgt/reset` | `ForgetPwdRequest` | 使用短信验证码重置密码 |
+
+## 用户接口
+
+| 路径后缀 | 请求类型 | 权限 | 说明 |
+|---|---|---|---|
+| `/user/role` | `FetchBase` | 登录 | 获取用户角色 |
+| `/user/app` | `FetchBase` | 登录 | 获取用户应用 |
+| `/user/pmn` | `FetchBase` | 登录 | 获取用户权限 |
+| `/user/pmn_tree` | `FetchBase` | 登录 | 获取用户权限树 |
+| `/user/create` | `UserRequest` | 管理员 | 创建用户 |
+| `/user/del`、`/user/detail`、`/user/fetch` | `UserRequest` | 管理员 | 删除、详情和查询 |
+| `/user/modify` | `UserRequest` | 管理员 | 修改用户 |
+| `/user/list` | `FetchBase` | 管理员 | 用户列表 |
+| `/user/set_role`、`/user/del_role` | `UserRoleRequest` | 管理员 | 设置或移除角色 |
+| `/user/set_pmn`、`/user/modify_pmn`、`/user/del_pmn` | `AddPmnRequest` | 管理员 | 设置、修改或移除权限 |
+
+表内接口均为 POST，完整路径在后缀前加 `/rest/mgt`。
+
+## 应用接口
+
+全部为管理员 POST 接口，基础路径 `/rest/mgt/app`。
+
+| 后缀 | 请求类型 | 说明 |
+|---|---|---|
+| `/create`、`/modify` | `ApplicationRequest` | 创建、修改应用 |
+| `/del`、`/detail`、`/fetch` | `ApplicationRequest` | 删除、详情、查询 |
+| `/user`、`/role`、`/pmn` | `FetchBase` | 获取应用关联用户、角色、权限 |
+
+## 角色接口
+
+全部为管理员 POST 接口，基础路径 `/rest/mgt/role`。
+
+| 后缀 | 请求类型 | 说明 |
+|---|---|---|
+| `/create`、`/modify` | `RoleReq` | 创建、修改角色 |
+| `/del`、`/detail`、`/fetch` | `RoleReq` | 删除、详情、查询 |
+| `/user`、`/app`、`/pmn`、`/pmn_tree` | `FetchBase` | 获取关联对象 |
+| `/set_pmn`、`/modify_pmn`、`/del_pmn` | `AddPmnRequest` | 管理角色权限 |
+
+## 权限接口
+
+全部为管理员 POST 接口，基础路径 `/rest/mgt/pmn`。
+
+| 后缀 | 请求类型 | 说明 |
+|---|---|---|
+| `/create`、`/modify` | `PermissionRequest` | 创建、修改权限或菜单 |
+| `/del`、`/detail`、`/fetch` | `PermissionRequest` | 删除、详情、查询 |
+| `/sort` | `SortPmnRequest[]` | 批量排序 |
+| `/user`、`/role` | `FetchBase` | 获取关联用户或角色 |
+
+## 部门接口
+
+全部为管理员 POST 接口，基础路径 `/rest/mgt/dpt`。
+
+| 后缀 | 请求类型 | 说明 |
+|---|---|---|
+| `/create`、`/modify` | `DptReq` | 创建、修改部门 |
+| `/del`、`/detail`、`/fetch`、`/list`、`/fetch_tree` | `DptReq` | 删除、详情、分页、列表或树 |
+| `/set_pmn`、`/modify_pmn`、`/del_pmn` | `AddPmnRequest` | 管理部门权限 |
+| `/pmn`、`/pmn_tree`、`/user` | `FetchBase` | 获取部门权限、权限树或用户 |
+| `/set_user`、`/del_user` | `DptUserRequest` | 批量移入或移出用户 |
+
+## 请求结构
+
+### FetchBase
+
+`page:int`、`size:int`、`id:uint`、`keyword:string`、`identity:string`、`status:int8`、`workspace:string`。
+
+### LoginRequest
+
+`account`、`password`、`phone`、`phone_code`、`workspace`、`app_id`、`app_key`，均为字符串。账号密码或手机验证码的有效组合由登录逻辑决定。
+
+### ForgetPwdRequest
+
+`account`、`code`、`password`、`phone` 均必填；密码至少 6 位。
+
+### UserRequest
+
+继承 `FetchBase`，增加 `account`、`name`、`password`、`phone`、`email`、`avatar`、`roles`。
+
+### UserRoleRequest
+
+```json
+{"user_id":1,"role_id":[1,2]}
+```
+
+### ApplicationRequest
+
+继承 `FetchBase`，增加 `title`、`workspace`、`description`。
+
+### RoleReq
+
+继承 `FetchBase`，增加 `name`、`description`。
+
+### PermissionRequest
+
+继承 `FetchBase`，增加 `title`、`title_en`、`code`、`workspace`、`description`、`parent_id`、`menu_path`、`menu_icon`、`type`、`component`、`sort_key`、`order_desc`、`is_web_page`、`is_new_tab`、`is_full`、`hide_menu`、`web_url`。`type` 取值为 `1=菜单`、`2=按钮`。
+
+### AddPmnRequest
+
+```json
+{"workspace":"default","id":1,"list":[10,11]}
+```
+
+### SortPmnRequest
+
+```json
+[{"pmn_id":10,"sort_key":1},{"pmn_id":11,"sort_key":2}]
+```
+
+### DptReq / DptUserRequest
+
+- `DptReq`：继承 `FetchBase`，增加 `name`、`leader_id`、`parent_id`、`tree`。
+- `DptUserRequest`：`dpt_id:uint`、`user_ids:uint[]`，均必填。
+
+## 通用响应
+
+接口使用 SDK 统一响应包装，常见数据结构包括：登录 `LoginResp`、分页 `{total,data,page,size}`、创建 `{id,identity}`。客户端必须同时判断 HTTP 状态和响应中的业务 code。
+