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/04-feedback.md
+++ b/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` | 可选 |