docs: add comprehensive client API reference

2026-08-11 19:09:29 +08:00
parent 5b5f6f8f00
commit 2d1deb54f0
27 changed files with 10727 additions and 4 deletions
--- a/wiki/api/07-sender.md
+++ b/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` | 可选 |