diff --git a/README.md b/README.md index 7b9a0b2..87b8c63 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # BSM Infra Full -BSM 后端服务 Go workspace，包含 19 个独立业务模块和一个统一端口运行的 all 聚合模块。Go 版本为 1.26.5。 +BSM 后端服务 Go workspace，包含 19 个独立业务模块和一个使用独立 gRPC/HTTP 端口的 all 聚合模块。Go 版本为 1.26.5。 ## 快速开始 @@ -53,10 +53,12 @@ Services 配置决定 all 启用哪些服务；BSM_SERVICES 环境变量可临 | scripts/build-all-linux.sh | 构建 Linux amd64 独立服务 | | scripts/generate-protobuf.sh | 重新生成 protobuf | | scripts/update-all.sh | 更新全部依赖，执行后必须审阅差异 | +| scripts/api-docgen | 从 protobuf descriptor 重新生成客户端 API 文档 | ## 文档 - [Wiki 索引](wiki/README.md) +- [API 接入与模块文档](wiki/api/00-overview.md) - [系统架构](wiki/architecture.md) - [开发与运维](wiki/operations.md) - [审计报告](wiki/audit-2026-08-10.md) diff --git a/scripts/api-docgen/generate.ps1 b/scripts/api-docgen/generate.ps1 new file mode 100644 index 0000000..55612da --- /dev/null +++ b/scripts/api-docgen/generate.ps1 @@ -0,0 +1,10 @@ +$ErrorActionPreference = "Stop" +$env:GOWORK = "off" +$env:GOLANG_PROTOBUF_REGISTRATION_CONFLICT = "warn" +try { + go run . + if ($LASTEXITCODE -ne 0) { throw "API documentation generation failed" } +} finally { + Remove-Item Env:GOWORK -ErrorAction SilentlyContinue + Remove-Item Env:GOLANG_PROTOBUF_REGISTRATION_CONFLICT -ErrorAction SilentlyContinue +} diff --git a/scripts/api-docgen/generate.sh b/scripts/api-docgen/generate.sh new file mode 100755 index 0000000..9a7f0d8 --- /dev/null +++ b/scripts/api-docgen/generate.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash + +set -Eeuo pipefail + +export GOWORK=off +export GOLANG_PROTOBUF_REGISTRATION_CONFLICT=warn +go run . diff --git a/scripts/api-docgen/go.mod b/scripts/api-docgen/go.mod new file mode 100644 index 0000000..fe1a32c --- /dev/null +++ b/scripts/api-docgen/go.mod @@ -0,0 +1,50 @@ +module bsm/full/tools/api-docgen + +go 1.26.5 + +require ( + bsm/full/module/base/ads v0.0.0 + bsm/full/module/base/cloud v0.0.0 + bsm/full/module/base/cms v0.0.0 + bsm/full/module/base/feedback v0.0.0 + bsm/full/module/base/initial v0.0.0 + bsm/full/module/base/passport v0.0.0 + bsm/full/module/base/sender v0.0.0 + bsm/full/module/ec/address v0.0.0 + bsm/full/module/ec/mall v0.0.0 + bsm/full/module/ec/market v0.0.0 + bsm/full/module/ec/order v0.0.0 + bsm/full/module/finance/wallet v0.0.0 + bsm/full/module/social/feed v0.0.0 + bsm/full/module/social/group v0.0.0 + bsm/full/module/social/relation v0.0.0 + google.golang.org/protobuf v1.36.11 +) + +require ( + github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 // indirect + golang.org/x/net v0.57.0 // indirect + golang.org/x/sys v0.47.0 // indirect + golang.org/x/text v0.40.0 // indirect + google.golang.org/genproto/googleapis/api v0.0.0-20260807164820-c8921c73eeea // indirect + google.golang.org/genproto/googleapis/rpc v0.0.0-20260807164820-c8921c73eeea // indirect + google.golang.org/grpc v1.83.0 // indirect +) + +replace ( + bsm/full/module/base/ads => ../../module/base/ads + bsm/full/module/base/cloud => ../../module/base/cloud + bsm/full/module/base/cms => ../../module/base/cms + bsm/full/module/base/feedback => ../../module/base/feedback + bsm/full/module/base/initial => ../../module/base/initial + bsm/full/module/base/passport => ../../module/base/passport + bsm/full/module/base/sender => ../../module/base/sender + bsm/full/module/ec/address => ../../module/ec/address + bsm/full/module/ec/mall => ../../module/ec/mall + bsm/full/module/ec/market => ../../module/ec/market + bsm/full/module/ec/order => ../../module/ec/order + bsm/full/module/finance/wallet => ../../module/finance/wallet + bsm/full/module/social/feed => ../../module/social/feed + bsm/full/module/social/group => ../../module/social/group + bsm/full/module/social/relation => ../../module/social/relation +) diff --git a/scripts/api-docgen/go.sum b/scripts/api-docgen/go.sum new file mode 100644 index 0000000..94f8c8d --- /dev/null +++ b/scripts/api-docgen/go.sum @@ -0,0 +1,42 @@ +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8= +github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= +github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= +github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 h1:/Tnpcb2E0Pz/tN9s3bfEY2Q8ePCEX9iuS+cneUwncnw= +github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0/go.mod h1:zOBXOsUaBSjKgmH4OGzV1esUpR3oUSCPYVd2cUBjKYY= +go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= +go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= +go.opentelemetry.io/otel v1.45.0 h1:pdrWmLHofpubmArBv1LgFSv1Z0Ie/ppdZzu+kUN5EeU= +go.opentelemetry.io/otel v1.45.0/go.mod h1:XZxIqPapzEYnhNSScF5DIqXhm/rYi0FzCe2XddAwZfQ= +go.opentelemetry.io/otel/metric v1.45.0 h1:7Eg1uH7CJ5cXv9is6tnBe1FI6rj1nwUdbFypRm3br/M= +go.opentelemetry.io/otel/metric v1.45.0/go.mod h1:HAPbm1nd3p1PmFH7v2dR+6BjXxw+Lq4a2+pndMAm08s= +go.opentelemetry.io/otel/sdk v1.45.0 h1:4VVSMgQ83dUgW2aoX5f6JgLvHwIvzcuLnF9lUdCSpCw= +go.opentelemetry.io/otel/sdk v1.45.0/go.mod h1:Sr40LgXV7DsKMMJMKOhUWOgMWTfAaqvm2kF0g7ilwuA= +go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI= +go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA= +go.opentelemetry.io/otel/trace v1.45.0 h1:l/mP6Uv7oNO7/TblbhpbgMidxhq1uO/rPsikOyVhxag= +go.opentelemetry.io/otel/trace v1.45.0/go.mod h1:qoJJA2xNMnxRrdISU/kLtfUH2wNeQbiv+jhs/CxI8bc= +golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE= +golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU= +golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= +golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs= +golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY= +gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= +gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= +google.golang.org/genproto/googleapis/api v0.0.0-20260807164820-c8921c73eeea h1:Jifw/kjs/r3B0uszvls/m3c3tmZs2YHGM9C+rvxP9gY= +google.golang.org/genproto/googleapis/api v0.0.0-20260807164820-c8921c73eeea/go.mod h1:K/+WGbmBY7aNW1HDw1fJnKYo10i0DkAX6pows00dLig= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260807164820-c8921c73eeea h1:kVhQEPTpKQahD5+JSBTfBB19wcgQTTjAIn45MBqnyHk= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260807164820-c8921c73eeea/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8= +google.golang.org/grpc v1.83.0 h1:JeNZEKJFbQxArAMl+hiytHauacDNqJUllNfmIMmpqnQ= +google.golang.org/grpc v1.83.0/go.mod h1:kDyl6SKsiHKt0uylY5gtn5cEjkrIOhQOGDgIc4JGwzQ= +google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE= +google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= diff --git a/scripts/api-docgen/main.go b/scripts/api-docgen/main.go new file mode 100644 index 0000000..25766e4 --- /dev/null +++ b/scripts/api-docgen/main.go @@ -0,0 +1,301 @@ +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "os" + "path/filepath" + "sort" + "strings" + + _ "bsm/full/module/base/ads/pb" + _ "bsm/full/module/base/cloud/pb" + _ "bsm/full/module/base/cms/pb" + _ "bsm/full/module/base/feedback/pb" + _ "bsm/full/module/base/initial/pb" + _ "bsm/full/module/base/passport/pb" + _ "bsm/full/module/base/sender/pb" + _ "bsm/full/module/ec/address/pb" + _ "bsm/full/module/ec/mall/pb" + _ "bsm/full/module/ec/market/pb" + _ "bsm/full/module/ec/order/pb" + _ "bsm/full/module/finance/wallet/pb" + _ "bsm/full/module/social/feed/pb" + _ "bsm/full/module/social/group/pb" + _ "bsm/full/module/social/relation/pb" + "google.golang.org/protobuf/reflect/protoreflect" + "google.golang.org/protobuf/reflect/protoregistry" +) + +type moduleInfo struct { + Order int + Name string + Package protoreflect.FullName + Description string +} + +var modules = []moduleInfo{ + {1, "ads", "ads", "广告获取与投放内容读取。"}, + {2, "cloud", "cloud", "云端相册、书签、网盘、笔记、私密数据、分享和空间管理。"}, + {3, "cms", "cms", "站点、页面、文章、栏目和标签内容管理。"}, + {4, "feedback", "feedback", "用户反馈提交与查询。"}, + {5, "initial", "initial", "客户端初始化、基础数据和版本更新检查。"}, + {6, "passport", "passport", "账号注册、登录、验证、找回密码和账户资料管理。"}, + {7, "sender", "sender", "邮件、短信发送及验证码校验。"}, + {8, "address", "address", "用户地址库管理。"}, + {9, "mall", "mall", "商城广告、类目、运费、公告、商品、员工和店铺管理。"}, + {10, "market", "market", "市场代理商、供应商及经营数据管理。"}, + {11, "order", "order", "购物车、优惠券、订单汇总及商家订单管理。"}, + {12, "wallet", "wallet", "钱包、支付方式、支付宝与微信支付。"}, + {13, "feed", "feed", "动态发布、标签、时间线和动态设置。"}, + {14, "group", "group", "群组及成员管理。"}, + {15, "relation", "relation", "关注、好友和关系匹配。"}, +} + +func main() { + root, err := filepath.Abs(filepath.Join("..", "..")) + must(err) + outDir := filepath.Join(root, "wiki", "api") + must(os.MkdirAll(outDir, 0o755)) + + for _, module := range modules { + services := servicesFor(module.Package) + content := renderModule(module, services) + name := fmt.Sprintf("%02d-%s.md", module.Order, module.Name) + must(os.WriteFile(filepath.Join(outDir, name), content, 0o644)) + } +} + +func servicesFor(pkg protoreflect.FullName) []protoreflect.ServiceDescriptor { + var services []protoreflect.ServiceDescriptor + protoregistry.GlobalFiles.RangeFiles(func(file protoreflect.FileDescriptor) bool { + if file.Package() != pkg { + return true + } + for i := 0; i < file.Services().Len(); i++ { + services = append(services, file.Services().Get(i)) + } + return true + }) + sort.Slice(services, func(i, j int) bool { return services[i].FullName() < services[j].FullName() }) + return services +} + +func renderModule(module moduleInfo, services []protoreflect.ServiceDescriptor) []byte { + var out bytes.Buffer + fmt.Fprintf(&out, "# %s API\n\n%s\n\n", strings.ToUpper(module.Name), module.Description) + out.WriteString("> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。\n\n") + out.WriteString("## 接入方式\n\n") + fmt.Fprintf(&out, "- 动态 HTTP：`POST /rpc/%s/{Service}/{Method}`\n", module.Package) + fmt.Fprintf(&out, "- 原生 gRPC：`/%s.{Service}/{Method}`\n", module.Package) + fmt.Fprintf(&out, "- grpc-gateway：`POST /%s.{Service}/{Method}`\n", module.Package) + out.WriteString("- 鉴权：需要登录的接口通过 `Authorization: Bearer ` 传递凭证。\n") + out.WriteString("- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。\n\n") + + out.WriteString("## 服务概览\n\n") + out.WriteString("| 服务 | 方法数 | 说明 |\n|---|---:|---|\n") + for _, service := range services { + fmt.Fprintf(&out, "| `%s` | %d | %s 服务 |\n", service.Name(), service.Methods().Len(), service.Name()) + } + + schemas := map[protoreflect.FullName]protoreflect.MessageDescriptor{} + enums := map[protoreflect.FullName]protoreflect.EnumDescriptor{} + for _, service := range services { + fmt.Fprintf(&out, "\n## %s\n\n", service.Name()) + out.WriteString("| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |\n|---|---|---|---|---|\n") + for i := 0; i < service.Methods().Len(); i++ { + method := service.Methods().Get(i) + kind := "Unary" + if method.IsStreamingClient() || method.IsStreamingServer() { + kind = "Streaming（动态 HTTP 暂不支持）" + } + fmt.Fprintf(&out, "| `%s` | `POST /rpc/%s/%s/%s` | [`%s`](#%s) | [`%s`](#%s) | %s |\n", + method.Name(), module.Package, service.Name(), method.Name(), + method.Input().FullName(), anchor(method.Input().FullName()), method.Output().FullName(), anchor(method.Output().FullName()), kind) + collectMessage(method.Input(), schemas, enums) + collectMessage(method.Output(), schemas, enums) + } + + for i := 0; i < service.Methods().Len(); i++ { + method := service.Methods().Get(i) + fmt.Fprintf(&out, "\n### %s.%s\n\n", service.Name(), method.Name()) + fmt.Fprintf(&out, "- 动态 HTTP：`POST /rpc/%s/%s/%s`\n", module.Package, service.Name(), method.Name()) + fmt.Fprintf(&out, "- gRPC：`/%s/%s`\n", service.FullName(), method.Name()) + fmt.Fprintf(&out, "- 白名单键：`%s.%s`\n", service.FullName(), method.Name()) + out.WriteString("- 请求示例：\n\n```json\n") + out.Write(exampleJSON(method.Input())) + out.WriteString("\n```\n") + } + } + + messageNames := sortedMessageNames(schemas) + if len(messageNames) > 0 { + out.WriteString("\n## 消息结构\n") + } + for _, name := range messageNames { + renderMessage(&out, schemas[name], enums) + } + + enumNames := make([]string, 0, len(enums)) + for name := range enums { + enumNames = append(enumNames, string(name)) + } + sort.Strings(enumNames) + if len(enumNames) > 0 { + out.WriteString("\n## 枚举\n") + } + for _, rawName := range enumNames { + renderEnum(&out, enums[protoreflect.FullName(rawName)]) + } + return out.Bytes() +} + +func collectMessage(message protoreflect.MessageDescriptor, messages map[protoreflect.FullName]protoreflect.MessageDescriptor, enums map[protoreflect.FullName]protoreflect.EnumDescriptor) { + if _, exists := messages[message.FullName()]; exists { + return + } + messages[message.FullName()] = message + for i := 0; i < message.Fields().Len(); i++ { + field := message.Fields().Get(i) + if field.Message() != nil { + collectMessage(field.Message(), messages, enums) + } + if field.Enum() != nil { + enums[field.Enum().FullName()] = field.Enum() + } + } +} + +func renderMessage(out *bytes.Buffer, message protoreflect.MessageDescriptor, enums map[protoreflect.FullName]protoreflect.EnumDescriptor) { + fmt.Fprintf(out, "\n### %s\n\n", message.FullName()) + if message.Fields().Len() == 0 { + out.WriteString("空消息：请求时发送 `{}`。\n") + return + } + out.WriteString("| JSON 字段 | 类型 | 规则 |\n|---|---|---|\n") + for i := 0; i < message.Fields().Len(); i++ { + field := message.Fields().Get(i) + rule := "可选" + if field.Cardinality() == protoreflect.Repeated { + rule = "数组" + } + if field.IsMap() { + rule = "对象映射" + } + if field.ContainingOneof() != nil && !field.ContainingOneof().IsSynthetic() { + rule = "oneof: " + string(field.ContainingOneof().Name()) + } + fmt.Fprintf(out, "| `%s` | `%s` | %s |\n", field.JSONName(), fieldType(field), rule) + if field.Enum() != nil { + enums[field.Enum().FullName()] = field.Enum() + } + } +} + +func renderEnum(out *bytes.Buffer, enum protoreflect.EnumDescriptor) { + fmt.Fprintf(out, "\n### %s\n\n", enum.FullName()) + out.WriteString("| 名称 | 数值 |\n|---|---:|\n") + for i := 0; i < enum.Values().Len(); i++ { + value := enum.Values().Get(i) + fmt.Fprintf(out, "| `%s` | %d |\n", value.Name(), value.Number()) + } +} + +func fieldType(field protoreflect.FieldDescriptor) string { + var value string + switch field.Kind() { + case protoreflect.MessageKind, protoreflect.GroupKind: + value = string(field.Message().FullName()) + case protoreflect.EnumKind: + value = string(field.Enum().FullName()) + default: + value = field.Kind().String() + } + if field.IsMap() { + value = "map<" + fieldType(field.MapKey()) + ", " + fieldType(field.MapValue()) + ">" + } else if field.Cardinality() == protoreflect.Repeated { + value = "[]" + value + } + return value +} + +func exampleJSON(message protoreflect.MessageDescriptor) []byte { + value := exampleMessage(message, map[protoreflect.FullName]bool{}, 0) + data, err := json.MarshalIndent(value, "", " ") + must(err) + return data +} + +func exampleMessage(message protoreflect.MessageDescriptor, visiting map[protoreflect.FullName]bool, depth int) map[string]any { + if depth > 2 || visiting[message.FullName()] { + return map[string]any{} + } + visiting[message.FullName()] = true + defer delete(visiting, message.FullName()) + result := map[string]any{} + seenOneof := map[protoreflect.Name]bool{} + for i := 0; i < message.Fields().Len(); i++ { + field := message.Fields().Get(i) + if oneof := field.ContainingOneof(); oneof != nil && !oneof.IsSynthetic() { + if seenOneof[oneof.Name()] { + continue + } + seenOneof[oneof.Name()] = true + } + value := exampleField(field, visiting, depth) + if field.Cardinality() == protoreflect.Repeated && !field.IsMap() { + value = []any{value} + } + if field.IsMap() { + value = map[string]any{"key": exampleField(field.MapValue(), visiting, depth)} + } + result[field.JSONName()] = value + } + return result +} + +func exampleField(field protoreflect.FieldDescriptor, visiting map[protoreflect.FullName]bool, depth int) any { + switch field.Kind() { + case protoreflect.BoolKind: + return false + case protoreflect.StringKind: + return "string" + case protoreflect.BytesKind: + return "BASE64" + case protoreflect.Int64Kind, protoreflect.Sint64Kind, protoreflect.Sfixed64Kind, + protoreflect.Uint64Kind, protoreflect.Fixed64Kind: + return "0" + case protoreflect.Int32Kind, protoreflect.Sint32Kind, protoreflect.Sfixed32Kind, + protoreflect.Uint32Kind, protoreflect.Fixed32Kind, protoreflect.FloatKind, protoreflect.DoubleKind: + return 0 + case protoreflect.EnumKind: + if field.Enum().Values().Len() > 0 { + return string(field.Enum().Values().Get(0).Name()) + } + return 0 + case protoreflect.MessageKind, protoreflect.GroupKind: + return exampleMessage(field.Message(), visiting, depth+1) + default: + return nil + } +} + +func sortedMessageNames(messages map[protoreflect.FullName]protoreflect.MessageDescriptor) []protoreflect.FullName { + names := make([]protoreflect.FullName, 0, len(messages)) + for name := range messages { + names = append(names, name) + } + sort.Slice(names, func(i, j int) bool { return names[i] < names[j] }) + return names +} + +func anchor(name protoreflect.FullName) string { + return strings.ToLower(strings.ReplaceAll(string(name), ".", "")) +} + +func must(err error) { + if err != nil { + panic(err) + } +} diff --git a/wiki/README.md b/wiki/README.md index 46da368..a6d3bb6 100644 --- a/wiki/README.md +++ b/wiki/README.md @@ -5,5 +5,18 @@ | [系统架构](architecture.md) | 模块边界、聚合入口、请求分流和依赖注入 | | [开发与运维](operations.md) | 配置、启动、验证、构建、发布和排障 | | [审计报告](audit-2026-08-10.md) | 已修复问题、剩余风险和后续优先级 | +| [API 接入总览](api/00-overview.md) | gRPC、动态 HTTP RPC、grpc-gateway、鉴权和 JSON 规则 | + +## 客户端 API 文档 + +| 领域 | 文档 | +|---|---| +| Base gRPC | [Ads](api/01-ads.md)、[Cloud](api/02-cloud.md)、[CMS](api/03-cms.md)、[Feedback](api/04-feedback.md)、[Initial](api/05-initial.md)、[Passport](api/06-passport.md)、[Sender](api/07-sender.md) | +| EC gRPC | [Address](api/08-address.md)、[Mall](api/09-mall.md)、[Market](api/10-market.md)、[Order](api/11-order.md) | +| Finance gRPC | [Wallet](api/12-wallet.md) | +| Social gRPC | [Feed](api/13-feed.md)、[Group](api/14-group.md)、[Relation](api/15-relation.md) | +| 原生 REST | [FTS](api/16-fts-rest.md)、[Logs](api/17-logs-rest.md)、[MGT](api/18-mgt-rest.md) | + +protobuf 文档覆盖每个 service/method、动态 HTTP 路径、请求示例、消息字段和枚举。修改 `.proto` 后在 `scripts/api-docgen` 目录运行 `./generate.ps1` 或 `./generate.sh` 并提交生成结果。social 模块当前存在已知 descriptor 名称冲突，因此生成时会显示 warning。 修改模块入口、配置结构、聚合协议或发布方式时，应同步更新本目录和根 README。 diff --git a/wiki/api/00-overview.md b/wiki/api/00-overview.md new file mode 100644 index 0000000..3cdbc0d --- /dev/null +++ b/wiki/api/00-overview.md @@ -0,0 +1,93 @@ +# API 接入总览 + +本文档面向 Web、移动端和第三方客户端开发者。默认示例基于 `all` 聚合服务：gRPC 监听 `12000`，HTTP 监听 `12001`，实际地址以 `all/etc/_.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 +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 +``` + +具体方法是否允许匿名由服务实现和 gRPC interceptor 决定。客户端不应仅根据请求字段推断匿名权限。 + +## 动态 RPC 白名单 + +`all/etc/_.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。 +- 文档中的请求示例表示字段形状，不代表所有字段都必须传入；校验规则仍以服务实现为准。 + diff --git a/wiki/api/01-ads.md b/wiki/api/01-ads.md new file mode 100644 index 0000000..5771127 --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 可选 | diff --git a/wiki/api/02-cloud.md b/wiki/api/02-cloud.md new file mode 100644 index 0000000..8a92c11 --- /dev/null +++ b/wiki/api/02-cloud.md @@ -0,0 +1,1609 @@ +# CLOUD API + +云端相册、书签、网盘、笔记、私密数据、分享和空间管理。 + +> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。 + +## 接入方式 + +- 动态 HTTP：`POST /rpc/cloud/{Service}/{Method}` +- 原生 gRPC：`/cloud.{Service}/{Method}` +- grpc-gateway：`POST /cloud.{Service}/{Method}` +- 鉴权：需要登录的接口通过 `Authorization: Bearer ` 传递凭证。 +- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。 + +## 服务概览 + +| 服务 | 方法数 | 说明 | +|---|---:|---| +| `Album` | 12 | Album 服务 | +| `Bookmark` | 6 | Bookmark 服务 | +| `Disk` | 15 | Disk 服务 | +| `Note` | 10 | Note 服务 | +| `Private` | 9 | Private 服务 | +| `Share` | 5 | Share 服务 | +| `Space` | 2 | Space 服务 | + +## Album + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `CreateAlbum` | `POST /rpc/cloud/Album/CreateAlbum` | [`cloud.CreateAlbumRequest`](#cloudcreatealbumrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetAlbum` | `POST /rpc/cloud/Album/GetAlbum` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudAlbumItem`](#cloudcloudalbumitem) | Unary | +| `UpdateAlbum` | `POST /rpc/cloud/Album/UpdateAlbum` | [`cloud.CloudAlbumItem`](#cloudcloudalbumitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeleteAlbum` | `POST /rpc/cloud/Album/DeleteAlbum` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListAlbums` | `POST /rpc/cloud/Album/ListAlbums` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListAlbumsResponse`](#cloudlistalbumsresponse) | Unary | +| `SetCoverPhoto` | `POST /rpc/cloud/Album/SetCoverPhoto` | [`cloud.SetCoverPhotoRequest`](#cloudsetcoverphotorequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `UploadPhoto` | `POST /rpc/cloud/Album/UploadPhoto` | [`cloud.CloudPhotoItem`](#cloudcloudphotoitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetPhoto` | `POST /rpc/cloud/Album/GetPhoto` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudPhotoItem`](#cloudcloudphotoitem) | Unary | +| `UpdatePhoto` | `POST /rpc/cloud/Album/UpdatePhoto` | [`cloud.CloudPhotoItem`](#cloudcloudphotoitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeletePhoto` | `POST /rpc/cloud/Album/DeletePhoto` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListPhotos` | `POST /rpc/cloud/Album/ListPhotos` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListPhotosResponse`](#cloudlistphotosresponse) | Unary | +| `MovePhoto` | `POST /rpc/cloud/Album/MovePhoto` | [`cloud.MovePhotoRequest`](#cloudmovephotorequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | + +### Album.CreateAlbum + +- 动态 HTTP：`POST /rpc/cloud/Album/CreateAlbum` +- gRPC：`/cloud.Album/CreateAlbum` +- 白名单键：`cloud.Album.CreateAlbum` +- 请求示例： + +```json +{ + "cloudId": "0", + "cloudIdentity": "string", + "coverPhoto": "string", + "description": "string", + "isPrivate": false, + "name": "string" +} +``` + +### Album.GetAlbum + +- 动态 HTTP：`POST /rpc/cloud/Album/GetAlbum` +- gRPC：`/cloud.Album/GetAlbum` +- 白名单键：`cloud.Album.GetAlbum` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Album.UpdateAlbum + +- 动态 HTTP：`POST /rpc/cloud/Album/UpdateAlbum` +- gRPC：`/cloud.Album/UpdateAlbum` +- 白名单键：`cloud.Album.UpdateAlbum` +- 请求示例： + +```json +{ + "coverPhoto": "string", + "createdAt": "string", + "description": "string", + "id": "0", + "identity": "string", + "isPrivate": false, + "name": "string", + "photos": [ + { + "album": {}, + "albumId": "0", + "createdAt": "string", + "description": "string", + "filePath": "string", + "fileSize": "0", + "height": 0, + "id": "0", + "identity": "string", + "location": "string", + "mimeType": "string", + "tags": "string", + "takenAt": "string", + "title": "string", + "updatedAt": "string", + "width": 0 + } + ], + "updatedAt": "string" +} +``` + +### Album.DeleteAlbum + +- 动态 HTTP：`POST /rpc/cloud/Album/DeleteAlbum` +- gRPC：`/cloud.Album/DeleteAlbum` +- 白名单键：`cloud.Album.DeleteAlbum` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Album.ListAlbums + +- 动态 HTTP：`POST /rpc/cloud/Album/ListAlbums` +- gRPC：`/cloud.Album/ListAlbums` +- 白名单键：`cloud.Album.ListAlbums` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Album.SetCoverPhoto + +- 动态 HTTP：`POST /rpc/cloud/Album/SetCoverPhoto` +- gRPC：`/cloud.Album/SetCoverPhoto` +- 白名单键：`cloud.Album.SetCoverPhoto` +- 请求示例： + +```json +{ + "albumId": "0", + "photoId": "0" +} +``` + +### Album.UploadPhoto + +- 动态 HTTP：`POST /rpc/cloud/Album/UploadPhoto` +- gRPC：`/cloud.Album/UploadPhoto` +- 白名单键：`cloud.Album.UploadPhoto` +- 请求示例： + +```json +{ + "album": { + "coverPhoto": "string", + "createdAt": "string", + "description": "string", + "id": "0", + "identity": "string", + "isPrivate": false, + "name": "string", + "photos": [ + {} + ], + "updatedAt": "string" + }, + "albumId": "0", + "createdAt": "string", + "description": "string", + "filePath": "string", + "fileSize": "0", + "height": 0, + "id": "0", + "identity": "string", + "location": "string", + "mimeType": "string", + "tags": "string", + "takenAt": "string", + "title": "string", + "updatedAt": "string", + "width": 0 +} +``` + +### Album.GetPhoto + +- 动态 HTTP：`POST /rpc/cloud/Album/GetPhoto` +- gRPC：`/cloud.Album/GetPhoto` +- 白名单键：`cloud.Album.GetPhoto` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Album.UpdatePhoto + +- 动态 HTTP：`POST /rpc/cloud/Album/UpdatePhoto` +- gRPC：`/cloud.Album/UpdatePhoto` +- 白名单键：`cloud.Album.UpdatePhoto` +- 请求示例： + +```json +{ + "album": { + "coverPhoto": "string", + "createdAt": "string", + "description": "string", + "id": "0", + "identity": "string", + "isPrivate": false, + "name": "string", + "photos": [ + {} + ], + "updatedAt": "string" + }, + "albumId": "0", + "createdAt": "string", + "description": "string", + "filePath": "string", + "fileSize": "0", + "height": 0, + "id": "0", + "identity": "string", + "location": "string", + "mimeType": "string", + "tags": "string", + "takenAt": "string", + "title": "string", + "updatedAt": "string", + "width": 0 +} +``` + +### Album.DeletePhoto + +- 动态 HTTP：`POST /rpc/cloud/Album/DeletePhoto` +- gRPC：`/cloud.Album/DeletePhoto` +- 白名单键：`cloud.Album.DeletePhoto` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Album.ListPhotos + +- 动态 HTTP：`POST /rpc/cloud/Album/ListPhotos` +- gRPC：`/cloud.Album/ListPhotos` +- 白名单键：`cloud.Album.ListPhotos` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Album.MovePhoto + +- 动态 HTTP：`POST /rpc/cloud/Album/MovePhoto` +- gRPC：`/cloud.Album/MovePhoto` +- 白名单键：`cloud.Album.MovePhoto` +- 请求示例： + +```json +{ + "newAlbumId": "0", + "photoId": "0" +} +``` + +## Bookmark + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `CreateBookmark` | `POST /rpc/cloud/Bookmark/CreateBookmark` | [`cloud.CreateBookmarkRequest`](#cloudcreatebookmarkrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetBookmark` | `POST /rpc/cloud/Bookmark/GetBookmark` | [`base_cloud_blocks.IDRequest`](#base_cloud_blocksidrequest) | [`cloud.CloudBookmarkItem`](#cloudcloudbookmarkitem) | Unary | +| `UpdateBookmark` | `POST /rpc/cloud/Bookmark/UpdateBookmark` | [`cloud.CloudBookmarkItem`](#cloudcloudbookmarkitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeleteBookmark` | `POST /rpc/cloud/Bookmark/DeleteBookmark` | [`base_cloud_blocks.IDRequest`](#base_cloud_blocksidrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListBookmarks` | `POST /rpc/cloud/Bookmark/ListBookmarks` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListBookmarksResponse`](#cloudlistbookmarksresponse) | Unary | +| `ImportBookmarks` | `POST /rpc/cloud/Bookmark/ImportBookmarks` | [`cloud.ImportBookmarksRequest`](#cloudimportbookmarksrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | + +### Bookmark.CreateBookmark + +- 动态 HTTP：`POST /rpc/cloud/Bookmark/CreateBookmark` +- gRPC：`/cloud.Bookmark/CreateBookmark` +- 白名单键：`cloud.Bookmark.CreateBookmark` +- 请求示例： + +```json +{ + "category": "string", + "cloudId": "0", + "cloudIdentity": "string", + "description": "string", + "icon": "string", + "isPrivate": false, + "tags": "string", + "title": "string", + "url": "string" +} +``` + +### Bookmark.GetBookmark + +- 动态 HTTP：`POST /rpc/cloud/Bookmark/GetBookmark` +- gRPC：`/cloud.Bookmark/GetBookmark` +- 白名单键：`cloud.Bookmark.GetBookmark` +- 请求示例： + +```json +{ + "id": "0" +} +``` + +### Bookmark.UpdateBookmark + +- 动态 HTTP：`POST /rpc/cloud/Bookmark/UpdateBookmark` +- gRPC：`/cloud.Bookmark/UpdateBookmark` +- 白名单键：`cloud.Bookmark.UpdateBookmark` +- 请求示例： + +```json +{ + "category": "string", + "createdAt": "string", + "description": "string", + "icon": "string", + "id": "0", + "identity": "string", + "isPrivate": false, + "tags": "string", + "title": "string", + "updatedAt": "string", + "url": "string" +} +``` + +### Bookmark.DeleteBookmark + +- 动态 HTTP：`POST /rpc/cloud/Bookmark/DeleteBookmark` +- gRPC：`/cloud.Bookmark/DeleteBookmark` +- 白名单键：`cloud.Bookmark.DeleteBookmark` +- 请求示例： + +```json +{ + "id": "0" +} +``` + +### Bookmark.ListBookmarks + +- 动态 HTTP：`POST /rpc/cloud/Bookmark/ListBookmarks` +- gRPC：`/cloud.Bookmark/ListBookmarks` +- 白名单键：`cloud.Bookmark.ListBookmarks` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Bookmark.ImportBookmarks + +- 动态 HTTP：`POST /rpc/cloud/Bookmark/ImportBookmarks` +- gRPC：`/cloud.Bookmark/ImportBookmarks` +- 白名单键：`cloud.Bookmark.ImportBookmarks` +- 请求示例： + +```json +{ + "data": "string", + "format": "string" +} +``` + +## Disk + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `CreateDir` | `POST /rpc/cloud/Disk/CreateDir` | [`cloud.CreateDirRequest`](#cloudcreatedirrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetDir` | `POST /rpc/cloud/Disk/GetDir` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudDiskDirItem`](#cloudclouddiskdiritem) | Unary | +| `UpdateDir` | `POST /rpc/cloud/Disk/UpdateDir` | [`cloud.CloudDiskDirItem`](#cloudclouddiskdiritem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeleteDir` | `POST /rpc/cloud/Disk/DeleteDir` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListDirs` | `POST /rpc/cloud/Disk/ListDirs` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListDirsResponse`](#cloudlistdirsresponse) | Unary | +| `GetDirTree` | `POST /rpc/cloud/Disk/GetDirTree` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudDiskDirItem`](#cloudclouddiskdiritem) | Unary | +| `MoveDir` | `POST /rpc/cloud/Disk/MoveDir` | [`cloud.MoveDirRequest`](#cloudmovedirrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `UploadFile` | `POST /rpc/cloud/Disk/UploadFile` | [`cloud.CloudDiskFileRequest`](#cloudclouddiskfilerequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetFile` | `POST /rpc/cloud/Disk/GetFile` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudDiskFileItem`](#cloudclouddiskfileitem) | Unary | +| `UpdateFile` | `POST /rpc/cloud/Disk/UpdateFile` | [`cloud.CloudDiskFileItem`](#cloudclouddiskfileitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeleteFile` | `POST /rpc/cloud/Disk/DeleteFile` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListFiles` | `POST /rpc/cloud/Disk/ListFiles` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListFilesResponse`](#cloudlistfilesresponse) | Unary | +| `MoveFile` | `POST /rpc/cloud/Disk/MoveFile` | [`cloud.MoveFileRequest`](#cloudmovefilerequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `CopyFile` | `POST /rpc/cloud/Disk/CopyFile` | [`cloud.CopyFileRequest`](#cloudcopyfilerequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `SearchFiles` | `POST /rpc/cloud/Disk/SearchFiles` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListFilesResponse`](#cloudlistfilesresponse) | Unary | + +### Disk.CreateDir + +- 动态 HTTP：`POST /rpc/cloud/Disk/CreateDir` +- gRPC：`/cloud.Disk/CreateDir` +- 白名单键：`cloud.Disk.CreateDir` +- 请求示例： + +```json +{ + "cloudId": "0", + "cloudIdentity": "string", + "name": "string", + "parentId": "0", + "path": "string" +} +``` + +### Disk.GetDir + +- 动态 HTTP：`POST /rpc/cloud/Disk/GetDir` +- gRPC：`/cloud.Disk/GetDir` +- 白名单键：`cloud.Disk.GetDir` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Disk.UpdateDir + +- 动态 HTTP：`POST /rpc/cloud/Disk/UpdateDir` +- gRPC：`/cloud.Disk/UpdateDir` +- 白名单键：`cloud.Disk.UpdateDir` +- 请求示例： + +```json +{ + "createdAt": "string", + "files": [ + { + "createdAt": "string", + "directory": {}, + "directoryId": "0", + "hash": "string", + "id": "0", + "identity": "string", + "mimeType": "string", + "name": "string", + "originalName": "string", + "size": "0", + "storagePath": "string", + "updatedAt": "string" + } + ], + "id": "0", + "identity": "string", + "name": "string", + "parent": {}, + "parentId": "0", + "path": "string", + "subdirectories": [ + {} + ], + "updatedAt": "string" +} +``` + +### Disk.DeleteDir + +- 动态 HTTP：`POST /rpc/cloud/Disk/DeleteDir` +- gRPC：`/cloud.Disk/DeleteDir` +- 白名单键：`cloud.Disk.DeleteDir` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Disk.ListDirs + +- 动态 HTTP：`POST /rpc/cloud/Disk/ListDirs` +- gRPC：`/cloud.Disk/ListDirs` +- 白名单键：`cloud.Disk.ListDirs` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Disk.GetDirTree + +- 动态 HTTP：`POST /rpc/cloud/Disk/GetDirTree` +- gRPC：`/cloud.Disk/GetDirTree` +- 白名单键：`cloud.Disk.GetDirTree` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Disk.MoveDir + +- 动态 HTTP：`POST /rpc/cloud/Disk/MoveDir` +- gRPC：`/cloud.Disk/MoveDir` +- 白名单键：`cloud.Disk.MoveDir` +- 请求示例： + +```json +{ + "id": "0", + "newParentId": "0" +} +``` + +### Disk.UploadFile + +- 动态 HTTP：`POST /rpc/cloud/Disk/UploadFile` +- gRPC：`/cloud.Disk/UploadFile` +- 白名单键：`cloud.Disk.UploadFile` +- 请求示例： + +```json +{ + "cloudId": "0", + "cloudIdentity": "string", + "directoryId": "0", + "hash": "string", + "mimeType": "string", + "name": "string", + "originalName": "string", + "size": "0", + "storagePath": "string" +} +``` + +### Disk.GetFile + +- 动态 HTTP：`POST /rpc/cloud/Disk/GetFile` +- gRPC：`/cloud.Disk/GetFile` +- 白名单键：`cloud.Disk.GetFile` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Disk.UpdateFile + +- 动态 HTTP：`POST /rpc/cloud/Disk/UpdateFile` +- gRPC：`/cloud.Disk/UpdateFile` +- 白名单键：`cloud.Disk.UpdateFile` +- 请求示例： + +```json +{ + "createdAt": "string", + "directory": { + "createdAt": "string", + "files": [ + {} + ], + "id": "0", + "identity": "string", + "name": "string", + "parent": {}, + "parentId": "0", + "path": "string", + "subdirectories": [ + {} + ], + "updatedAt": "string" + }, + "directoryId": "0", + "hash": "string", + "id": "0", + "identity": "string", + "mimeType": "string", + "name": "string", + "originalName": "string", + "size": "0", + "storagePath": "string", + "updatedAt": "string" +} +``` + +### Disk.DeleteFile + +- 动态 HTTP：`POST /rpc/cloud/Disk/DeleteFile` +- gRPC：`/cloud.Disk/DeleteFile` +- 白名单键：`cloud.Disk.DeleteFile` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Disk.ListFiles + +- 动态 HTTP：`POST /rpc/cloud/Disk/ListFiles` +- gRPC：`/cloud.Disk/ListFiles` +- 白名单键：`cloud.Disk.ListFiles` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Disk.MoveFile + +- 动态 HTTP：`POST /rpc/cloud/Disk/MoveFile` +- gRPC：`/cloud.Disk/MoveFile` +- 白名单键：`cloud.Disk.MoveFile` +- 请求示例： + +```json +{ + "id": "0", + "newDirectoryId": "0" +} +``` + +### Disk.CopyFile + +- 动态 HTTP：`POST /rpc/cloud/Disk/CopyFile` +- gRPC：`/cloud.Disk/CopyFile` +- 白名单键：`cloud.Disk.CopyFile` +- 请求示例： + +```json +{ + "id": "0", + "newName": "string", + "targetDirectoryId": "0" +} +``` + +### Disk.SearchFiles + +- 动态 HTTP：`POST /rpc/cloud/Disk/SearchFiles` +- gRPC：`/cloud.Disk/SearchFiles` +- 白名单键：`cloud.Disk.SearchFiles` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +## Note + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `CreateNote` | `POST /rpc/cloud/Note/CreateNote` | [`cloud.CreateNoteRequest`](#cloudcreatenoterequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetNote` | `POST /rpc/cloud/Note/GetNote` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudNoteItem`](#cloudcloudnoteitem) | Unary | +| `UpdateNote` | `POST /rpc/cloud/Note/UpdateNote` | [`cloud.CloudNoteItem`](#cloudcloudnoteitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeleteNote` | `POST /rpc/cloud/Note/DeleteNote` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListNotes` | `POST /rpc/cloud/Note/ListNotes` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListNotesResponse`](#cloudlistnotesresponse) | Unary | +| `TogglePin` | `POST /rpc/cloud/Note/TogglePin` | [`cloud.TogglePinRequest`](#cloudtogglepinrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `IncrementViews` | `POST /rpc/cloud/Note/IncrementViews` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `SearchNotes` | `POST /rpc/cloud/Note/SearchNotes` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListNotesResponse`](#cloudlistnotesresponse) | Unary | +| `InsertAttachment` | `POST /rpc/cloud/Note/InsertAttachment` | [`cloud.NoteAttachmentItem`](#cloudnoteattachmentitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeleteAttachment` | `POST /rpc/cloud/Note/DeleteAttachment` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | + +### Note.CreateNote + +- 动态 HTTP：`POST /rpc/cloud/Note/CreateNote` +- gRPC：`/cloud.Note/CreateNote` +- 白名单键：`cloud.Note.CreateNote` +- 请求示例： + +```json +{ + "category": "string", + "cloudId": "0", + "cloudIdentity": "string", + "content": "string", + "isMarkdown": false, + "isPinned": false, + "isPrivate": false, + "tags": "string", + "title": "string" +} +``` + +### Note.GetNote + +- 动态 HTTP：`POST /rpc/cloud/Note/GetNote` +- gRPC：`/cloud.Note/GetNote` +- 白名单键：`cloud.Note.GetNote` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Note.UpdateNote + +- 动态 HTTP：`POST /rpc/cloud/Note/UpdateNote` +- gRPC：`/cloud.Note/UpdateNote` +- 白名单键：`cloud.Note.UpdateNote` +- 请求示例： + +```json +{ + "attachments": [ + { + "createdAt": "string", + "fileName": "string", + "filePath": "string", + "fileSize": "0", + "id": "0", + "mimeType": "string", + "noteId": "0" + } + ], + "category": "string", + "content": "string", + "createdAt": "string", + "id": "0", + "identity": "string", + "isMarkdown": false, + "isPinned": false, + "isPrivate": false, + "tags": "string", + "title": "string", + "updatedAt": "string", + "views": 0 +} +``` + +### Note.DeleteNote + +- 动态 HTTP：`POST /rpc/cloud/Note/DeleteNote` +- gRPC：`/cloud.Note/DeleteNote` +- 白名单键：`cloud.Note.DeleteNote` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Note.ListNotes + +- 动态 HTTP：`POST /rpc/cloud/Note/ListNotes` +- gRPC：`/cloud.Note/ListNotes` +- 白名单键：`cloud.Note.ListNotes` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Note.TogglePin + +- 动态 HTTP：`POST /rpc/cloud/Note/TogglePin` +- gRPC：`/cloud.Note/TogglePin` +- 白名单键：`cloud.Note.TogglePin` +- 请求示例： + +```json +{ + "id": "0", + "isPinned": false +} +``` + +### Note.IncrementViews + +- 动态 HTTP：`POST /rpc/cloud/Note/IncrementViews` +- gRPC：`/cloud.Note/IncrementViews` +- 白名单键：`cloud.Note.IncrementViews` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Note.SearchNotes + +- 动态 HTTP：`POST /rpc/cloud/Note/SearchNotes` +- gRPC：`/cloud.Note/SearchNotes` +- 白名单键：`cloud.Note.SearchNotes` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Note.InsertAttachment + +- 动态 HTTP：`POST /rpc/cloud/Note/InsertAttachment` +- gRPC：`/cloud.Note/InsertAttachment` +- 白名单键：`cloud.Note.InsertAttachment` +- 请求示例： + +```json +{ + "createdAt": "string", + "fileName": "string", + "filePath": "string", + "fileSize": "0", + "id": "0", + "mimeType": "string", + "noteId": "0" +} +``` + +### Note.DeleteAttachment + +- 动态 HTTP：`POST /rpc/cloud/Note/DeleteAttachment` +- gRPC：`/cloud.Note/DeleteAttachment` +- 白名单键：`cloud.Note.DeleteAttachment` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## Private + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `CreatePrivateData` | `POST /rpc/cloud/Private/CreatePrivateData` | [`cloud.CreatePrivateDataRequest`](#cloudcreateprivatedatarequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetPrivateData` | `POST /rpc/cloud/Private/GetPrivateData` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudPrivateItem`](#cloudcloudprivateitem) | Unary | +| `UpdatePrivateData` | `POST /rpc/cloud/Private/UpdatePrivateData` | [`cloud.CloudPrivateItem`](#cloudcloudprivateitem) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DeletePrivateData` | `POST /rpc/cloud/Private/DeletePrivateData` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListPrivateData` | `POST /rpc/cloud/Private/ListPrivateData` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListPrivateDataResponse`](#cloudlistprivatedataresponse) | Unary | +| `GetPrivateDataByType` | `POST /rpc/cloud/Private/GetPrivateDataByType` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListPrivateDataResponse`](#cloudlistprivatedataresponse) | Unary | +| `SearchPrivateData` | `POST /rpc/cloud/Private/SearchPrivateData` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListPrivateDataResponse`](#cloudlistprivatedataresponse) | Unary | +| `EncryptData` | `POST /rpc/cloud/Private/EncryptData` | [`cloud.DataRequest`](#clouddatarequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `DecryptData` | `POST /rpc/cloud/Private/DecryptData` | [`cloud.DataRequest`](#clouddatarequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | + +### Private.CreatePrivateData + +- 动态 HTTP：`POST /rpc/cloud/Private/CreatePrivateData` +- gRPC：`/cloud.Private/CreatePrivateData` +- 白名单键：`cloud.Private.CreatePrivateData` +- 请求示例： + +```json +{ + "cloudId": "0", + "cloudIdentity": "string", + "data": "string", + "dataType": "string", + "description": "string", + "isEncrypted": false, + "tags": "string", + "title": "string" +} +``` + +### Private.GetPrivateData + +- 动态 HTTP：`POST /rpc/cloud/Private/GetPrivateData` +- gRPC：`/cloud.Private/GetPrivateData` +- 白名单键：`cloud.Private.GetPrivateData` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Private.UpdatePrivateData + +- 动态 HTTP：`POST /rpc/cloud/Private/UpdatePrivateData` +- gRPC：`/cloud.Private/UpdatePrivateData` +- 白名单键：`cloud.Private.UpdatePrivateData` +- 请求示例： + +```json +{ + "createdAt": "string", + "data": "string", + "dataType": "string", + "description": "string", + "id": "0", + "identity": "string", + "isEncrypted": false, + "tags": "string", + "title": "string", + "updatedAt": "string" +} +``` + +### Private.DeletePrivateData + +- 动态 HTTP：`POST /rpc/cloud/Private/DeletePrivateData` +- gRPC：`/cloud.Private/DeletePrivateData` +- 白名单键：`cloud.Private.DeletePrivateData` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Private.ListPrivateData + +- 动态 HTTP：`POST /rpc/cloud/Private/ListPrivateData` +- gRPC：`/cloud.Private/ListPrivateData` +- 白名单键：`cloud.Private.ListPrivateData` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Private.GetPrivateDataByType + +- 动态 HTTP：`POST /rpc/cloud/Private/GetPrivateDataByType` +- gRPC：`/cloud.Private/GetPrivateDataByType` +- 白名单键：`cloud.Private.GetPrivateDataByType` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Private.SearchPrivateData + +- 动态 HTTP：`POST /rpc/cloud/Private/SearchPrivateData` +- gRPC：`/cloud.Private/SearchPrivateData` +- 白名单键：`cloud.Private.SearchPrivateData` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Private.EncryptData + +- 动态 HTTP：`POST /rpc/cloud/Private/EncryptData` +- gRPC：`/cloud.Private/EncryptData` +- 白名单键：`cloud.Private.EncryptData` +- 请求示例： + +```json +{ + "data": "string", + "key": "string" +} +``` + +### Private.DecryptData + +- 动态 HTTP：`POST /rpc/cloud/Private/DecryptData` +- gRPC：`/cloud.Private/DecryptData` +- 白名单键：`cloud.Private.DecryptData` +- 请求示例： + +```json +{ + "data": "string", + "key": "string" +} +``` + +## Share + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `CreateShare` | `POST /rpc/cloud/Share/CreateShare` | [`cloud.CreateShareRequest`](#cloudcreatesharerequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `GetShare` | `POST /rpc/cloud/Share/GetShare` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudShareItem`](#cloudcloudshareitem) | Unary | +| `DeleteShare` | `POST /rpc/cloud/Share/DeleteShare` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | +| `ListShares` | `POST /rpc/cloud/Share/ListShares` | [`base_cloud_blocks.FetchRequest`](#base_cloud_blocksfetchrequest) | [`cloud.ListSharesResponse`](#cloudlistsharesresponse) | Unary | +| `ValidateSharePassword` | `POST /rpc/cloud/Share/ValidateSharePassword` | [`cloud.ValidateSharePasswordRequest`](#cloudvalidatesharepasswordrequest) | [`base_cloud_blocks.StatusReply`](#base_cloud_blocksstatusreply) | Unary | + +### Share.CreateShare + +- 动态 HTTP：`POST /rpc/cloud/Share/CreateShare` +- gRPC：`/cloud.Share/CreateShare` +- 白名单键：`cloud.Share.CreateShare` +- 请求示例： + +```json +{ + "cloudId": "0", + "cloudIdentity": "string", + "expiresAt": "string", + "isPublic": false, + "password": "string", + "resourceId": "0", + "shareToken": "string", + "shareType": "string" +} +``` + +### Share.GetShare + +- 动态 HTTP：`POST /rpc/cloud/Share/GetShare` +- gRPC：`/cloud.Share/GetShare` +- 白名单键：`cloud.Share.GetShare` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Share.DeleteShare + +- 动态 HTTP：`POST /rpc/cloud/Share/DeleteShare` +- gRPC：`/cloud.Share/DeleteShare` +- 白名单键：`cloud.Share.DeleteShare` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Share.ListShares + +- 动态 HTTP：`POST /rpc/cloud/Share/ListShares` +- gRPC：`/cloud.Share/ListShares` +- 白名单键：`cloud.Share.ListShares` +- 请求示例： + +```json +{ + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + } +} +``` + +### Share.ValidateSharePassword + +- 动态 HTTP：`POST /rpc/cloud/Share/ValidateSharePassword` +- gRPC：`/cloud.Share/ValidateSharePassword` +- 白名单键：`cloud.Share.ValidateSharePassword` +- 请求示例： + +```json +{ + "identity": "string", + "password": "string" +} +``` + +## Space + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Get` | `POST /rpc/cloud/Space/Get` | [`base_cloud_blocks.Empty`](#base_cloud_blocksempty) | [`cloud.CloudSpace`](#cloudcloudspace) | Unary | +| `GetByKeyIdentifier` | `POST /rpc/cloud/Space/GetByKeyIdentifier` | [`base_cloud_blocks.IdentRequest`](#base_cloud_blocksidentrequest) | [`cloud.CloudSpace`](#cloudcloudspace) | Unary | + +### Space.Get + +- 动态 HTTP：`POST /rpc/cloud/Space/Get` +- gRPC：`/cloud.Space/Get` +- 白名单键：`cloud.Space.Get` +- 请求示例： + +```json +{} +``` + +### Space.GetByKeyIdentifier + +- 动态 HTTP：`POST /rpc/cloud/Space/GetByKeyIdentifier` +- gRPC：`/cloud.Space/GetByKeyIdentifier` +- 白名单键：`cloud.Space.GetByKeyIdentifier` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## 消息结构 + +### base_cloud_blocks.Empty + +空消息：请求时发送 `{}`。 + +### base_cloud_blocks.FetchRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `page_no` | `int64` | 可选 | +| `page_size` | `int64` | 可选 | +| `params` | `map` | 对象映射 | + +### base_cloud_blocks.FetchRequest.ParamsEntry + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `key` | `string` | 可选 | +| `value` | `string` | 可选 | + +### base_cloud_blocks.IDRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | + +### base_cloud_blocks.IdentRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | + +### base_cloud_blocks.StatusReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `code` | `int32` | 可选 | +| `message` | `string` | 可选 | +| `details` | `string` | 可选 | +| `timeseq` | `int64` | 可选 | + +### cloud.CloudAlbumItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `name` | `string` | 可选 | +| `description` | `string` | 可选 | +| `coverPhoto` | `string` | 可选 | +| `isPrivate` | `bool` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | +| `photos` | `[]cloud.CloudPhotoItem` | 数组 | + +### cloud.CloudBookmarkItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `url` | `string` | 可选 | +| `description` | `string` | 可选 | +| `category` | `string` | 可选 | +| `tags` | `string` | 可选 | +| `icon` | `string` | 可选 | +| `isPrivate` | `bool` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | + +### cloud.CloudDiskDirItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `parentId` | `uint64` | 可选 | +| `name` | `string` | 可选 | +| `path` | `string` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | +| `parent` | `cloud.CloudDiskDirItem` | 可选 | +| `subdirectories` | `[]cloud.CloudDiskDirItem` | 数组 | +| `files` | `[]cloud.CloudDiskFileItem` | 数组 | + +### cloud.CloudDiskFileItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `directoryId` | `uint64` | 可选 | +| `name` | `string` | 可选 | +| `originalName` | `string` | 可选 | +| `size` | `int64` | 可选 | +| `mimeType` | `string` | 可选 | +| `storagePath` | `string` | 可选 | +| `hash` | `string` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | +| `directory` | `cloud.CloudDiskDirItem` | 可选 | + +### cloud.CloudDiskFileRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `directoryId` | `uint64` | 可选 | +| `name` | `string` | 可选 | +| `originalName` | `string` | 可选 | +| `size` | `int64` | 可选 | +| `mimeType` | `string` | 可选 | +| `storagePath` | `string` | 可选 | +| `hash` | `string` | 可选 | + +### cloud.CloudNoteItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `content` | `string` | 可选 | +| `category` | `string` | 可选 | +| `tags` | `string` | 可选 | +| `isMarkdown` | `bool` | 可选 | +| `isPinned` | `bool` | 可选 | +| `isPrivate` | `bool` | 可选 | +| `views` | `int32` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | +| `attachments` | `[]cloud.NoteAttachmentItem` | 数组 | + +### cloud.CloudPhotoItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `albumId` | `uint64` | 可选 | +| `title` | `string` | 可选 | +| `description` | `string` | 可选 | +| `filePath` | `string` | 可选 | +| `fileSize` | `int64` | 可选 | +| `mimeType` | `string` | 可选 | +| `width` | `int32` | 可选 | +| `height` | `int32` | 可选 | +| `takenAt` | `string` | 可选 | +| `location` | `string` | 可选 | +| `tags` | `string` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | +| `album` | `cloud.CloudAlbumItem` | 可选 | + +### cloud.CloudPrivateItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `dataType` | `string` | 可选 | +| `title` | `string` | 可选 | +| `description` | `string` | 可选 | +| `data` | `string` | 可选 | +| `isEncrypted` | `bool` | 可选 | +| `tags` | `string` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | + +### cloud.CloudShareItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `shareType` | `string` | 可选 | +| `resourceId` | `uint64` | 可选 | +| `shareToken` | `string` | 可选 | +| `password` | `string` | 可选 | +| `expiresAt` | `string` | 可选 | +| `viewCount` | `int32` | 可选 | +| `downloadCount` | `int32` | 可选 | +| `isPublic` | `bool` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | + +### cloud.CloudSpace + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `identity` | `string` | 可选 | +| `totalStorage` | `int64` | 可选 | +| `usedStorage` | `int64` | 可选 | +| `maxStorage` | `int64` | 可选 | +| `fileCount` | `int32` | 可选 | +| `albumCount` | `int32` | 可选 | +| `photoCount` | `int32` | 可选 | +| `noteCount` | `int32` | 可选 | +| `bookmarkCount` | `int32` | 可选 | +| `privateCount` | `int32` | 可选 | +| `createdAt` | `string` | 可选 | +| `updatedAt` | `string` | 可选 | +| `cloudDiskDirs` | `[]cloud.CloudDiskDirItem` | 数组 | +| `cloudAlbums` | `[]cloud.CloudAlbumItem` | 数组 | +| `cloudNotes` | `[]cloud.CloudNoteItem` | 数组 | +| `cloudBookmarks` | `[]cloud.CloudBookmarkItem` | 数组 | +| `cloudPrivate` | `[]cloud.CloudPrivateItem` | 数组 | +| `cloudShares` | `[]cloud.CloudShareItem` | 数组 | + +### cloud.CopyFileRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `targetDirectoryId` | `uint64` | 可选 | +| `newName` | `string` | 可选 | + +### cloud.CreateAlbumRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `name` | `string` | 可选 | +| `description` | `string` | 可选 | +| `coverPhoto` | `string` | 可选 | +| `isPrivate` | `bool` | 可选 | + +### cloud.CreateBookmarkRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `url` | `string` | 可选 | +| `description` | `string` | 可选 | +| `category` | `string` | 可选 | +| `tags` | `string` | 可选 | +| `icon` | `string` | 可选 | +| `isPrivate` | `bool` | 可选 | + +### cloud.CreateDirRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `parentId` | `uint64` | 可选 | +| `name` | `string` | 可选 | +| `path` | `string` | 可选 | + +### cloud.CreateNoteRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `content` | `string` | 可选 | +| `category` | `string` | 可选 | +| `tags` | `string` | 可选 | +| `isMarkdown` | `bool` | 可选 | +| `isPinned` | `bool` | 可选 | +| `isPrivate` | `bool` | 可选 | + +### cloud.CreatePrivateDataRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `dataType` | `string` | 可选 | +| `title` | `string` | 可选 | +| `description` | `string` | 可选 | +| `data` | `string` | 可选 | +| `isEncrypted` | `bool` | 可选 | +| `tags` | `string` | 可选 | + +### cloud.CreateShareRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `cloudId` | `uint64` | 可选 | +| `cloudIdentity` | `string` | 可选 | +| `shareType` | `string` | 可选 | +| `resourceId` | `uint64` | 可选 | +| `shareToken` | `string` | 可选 | +| `password` | `string` | 可选 | +| `expiresAt` | `string` | 可选 | +| `isPublic` | `bool` | 可选 | + +### cloud.DataRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `string` | 可选 | +| `key` | `string` | 可选 | + +### cloud.ImportBookmarksRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `string` | 可选 | +| `format` | `string` | 可选 | + +### cloud.ListAlbumsResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `albums` | `[]cloud.CloudAlbumItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListBookmarksResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `bookmarks` | `[]cloud.CloudBookmarkItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListDirsResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `dirs` | `[]cloud.CloudDiskDirItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListFilesResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `files` | `[]cloud.CloudDiskFileItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListNotesResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `notes` | `[]cloud.CloudNoteItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListPhotosResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `photos` | `[]cloud.CloudPhotoItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListPrivateDataResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]cloud.CloudPrivateItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.ListSharesResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `shares` | `[]cloud.CloudShareItem` | 数组 | +| `total` | `int64` | 可选 | + +### cloud.MoveDirRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `newParentId` | `uint64` | 可选 | + +### cloud.MoveFileRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `newDirectoryId` | `uint64` | 可选 | + +### cloud.MovePhotoRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `photoId` | `uint64` | 可选 | +| `newAlbumId` | `uint64` | 可选 | + +### cloud.NoteAttachmentItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `noteId` | `uint64` | 可选 | +| `fileName` | `string` | 可选 | +| `filePath` | `string` | 可选 | +| `fileSize` | `int64` | 可选 | +| `mimeType` | `string` | 可选 | +| `createdAt` | `string` | 可选 | + +### cloud.SetCoverPhotoRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `albumId` | `uint64` | 可选 | +| `photoId` | `uint64` | 可选 | + +### cloud.TogglePinRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `uint64` | 可选 | +| `isPinned` | `bool` | 可选 | + +### cloud.ValidateSharePasswordRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `password` | `string` | 可选 | diff --git a/wiki/api/03-cms.md b/wiki/api/03-cms.md new file mode 100644 index 0000000..6d0f02d --- /dev/null +++ b/wiki/api/03-cms.md @@ -0,0 +1,1220 @@ +# CMS API + +站点、页面、文章、栏目和标签内容管理。 + +> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。 + +## 接入方式 + +- 动态 HTTP：`POST /rpc/cms/{Service}/{Method}` +- 原生 gRPC：`/cms.{Service}/{Method}` +- grpc-gateway：`POST /cms.{Service}/{Method}` +- 鉴权：需要登录的接口通过 `Authorization: Bearer ` 传递凭证。 +- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。 + +## 服务概览 + +| 服务 | 方法数 | 说明 | +|---|---:|---| +| `Category` | 4 | Category 服务 | +| `Pages` | 6 | Pages 服务 | +| `Post` | 19 | Post 服务 | +| `Site` | 5 | Site 服务 | +| `Tags` | 4 | Tags 服务 | + +## Category + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/cms/Category/Fetch` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`cms.CategoryListReply`](#cmscategorylistreply) | Unary | +| `Create` | `POST /rpc/cms/Category/Create` | [`base_cms_blocks.CmsCategoryItem`](#base_cms_blockscmscategoryitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Modify` | `POST /rpc/cms/Category/Modify` | [`cms.ModifyCategoryRequest`](#cmsmodifycategoryrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Delete` | `POST /rpc/cms/Category/Delete` | [`cms.DeleteCategoryRequest`](#cmsdeletecategoryrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | + +### Category.Fetch + +- 动态 HTTP：`POST /rpc/cms/Category/Fetch` +- gRPC：`/cms.Category/Fetch` +- 白名单键：`cms.Category.Fetch` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Category.Create + +- 动态 HTTP：`POST /rpc/cms/Category/Create` +- gRPC：`/cms.Category/Create` +- 白名单键：`cms.Category.Create` +- 请求示例： + +```json +{ + "category_key": "string", + "child": [ + {} + ], + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "parent_id": "0", + "site_identity": "string", + "title": "string", + "updated_at": "string" +} +``` + +### Category.Modify + +- 动态 HTTP：`POST /rpc/cms/Category/Modify` +- gRPC：`/cms.Category/Modify` +- 白名单键：`cms.Category.Modify` +- 请求示例： + +```json +{ + "category_key": "string", + "cover_path": "string", + "created_at": "string", + "data": [ + { + "category_key": "string", + "child": [ + {} + ], + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "parent_id": "0", + "site_identity": "string", + "title": "string", + "updated_at": "string" + } + ], + "identity": "string", + "intro": "string", + "parent_id": "0", + "site_identity": "string", + "title": "string", + "updated_at": "string" +} +``` + +### Category.Delete + +- 动态 HTTP：`POST /rpc/cms/Category/Delete` +- gRPC：`/cms.Category/Delete` +- 白名单键：`cms.Category.Delete` +- 请求示例： + +```json +{ + "identity": "string" +} +``` + +## Pages + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/cms/Pages/Fetch` | [`cms.PagesListRequest`](#cmspageslistrequest) | [`cms.PagesListReply`](#cmspageslistreply) | Unary | +| `GetByIdentity` | `POST /rpc/cms/Pages/GetByIdentity` | [`cms.GetPagesRequest`](#cmsgetpagesrequest) | [`cms.PagesItem`](#cmspagesitem) | Unary | +| `GetByKey` | `POST /rpc/cms/Pages/GetByKey` | [`cms.GetPagesByKeyRequest`](#cmsgetpagesbykeyrequest) | [`cms.PagesItem`](#cmspagesitem) | Unary | +| `Create` | `POST /rpc/cms/Pages/Create` | [`cms.PagesItem`](#cmspagesitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Modify` | `POST /rpc/cms/Pages/Modify` | [`cms.PagesItem`](#cmspagesitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Delete` | `POST /rpc/cms/Pages/Delete` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | + +### Pages.Fetch + +- 动态 HTTP：`POST /rpc/cms/Pages/Fetch` +- gRPC：`/cms.Pages/Fetch` +- 白名单键：`cms.Pages.Fetch` +- 请求示例： + +```json +{ + "keyword": "string", + "page": "0", + "size": "0", + "type": 0 +} +``` + +### Pages.GetByIdentity + +- 动态 HTTP：`POST /rpc/cms/Pages/GetByIdentity` +- gRPC：`/cms.Pages/GetByIdentity` +- 白名单键：`cms.Pages.GetByIdentity` +- 请求示例： + +```json +{ + "identity": "string" +} +``` + +### Pages.GetByKey + +- 动态 HTTP：`POST /rpc/cms/Pages/GetByKey` +- gRPC：`/cms.Pages/GetByKey` +- 白名单键：`cms.Pages.GetByKey` +- 请求示例： + +```json +{ + "key": "string" +} +``` + +### Pages.Create + +- 动态 HTTP：`POST /rpc/cms/Pages/Create` +- gRPC：`/cms.Pages/Create` +- 白名单键：`cms.Pages.Create` +- 请求示例： + +```json +{ + "accessory_data": [ + { + "created_at": "string", + "file_path": "string", + "identity": "string", + "title": "string" + } + ], + "accessory_identity_array": [ + "string" + ], + "content": "string", + "cover_path": "string", + "created_at": "string", + "description": "string", + "has_accessory": false, + "hits": "0", + "identity": "string", + "key": "string", + "post_type": 0, + "rights": "string", + "site_identity": "string", + "tags_data": [ + { + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "title": "string" + } + ], + "tags_identity_array": [ + "string" + ], + "title": "string", + "updated_at": "string" +} +``` + +### Pages.Modify + +- 动态 HTTP：`POST /rpc/cms/Pages/Modify` +- gRPC：`/cms.Pages/Modify` +- 白名单键：`cms.Pages.Modify` +- 请求示例： + +```json +{ + "accessory_data": [ + { + "created_at": "string", + "file_path": "string", + "identity": "string", + "title": "string" + } + ], + "accessory_identity_array": [ + "string" + ], + "content": "string", + "cover_path": "string", + "created_at": "string", + "description": "string", + "has_accessory": false, + "hits": "0", + "identity": "string", + "key": "string", + "post_type": 0, + "rights": "string", + "site_identity": "string", + "tags_data": [ + { + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "title": "string" + } + ], + "tags_identity_array": [ + "string" + ], + "title": "string", + "updated_at": "string" +} +``` + +### Pages.Delete + +- 动态 HTTP：`POST /rpc/cms/Pages/Delete` +- gRPC：`/cms.Pages/Delete` +- 白名单键：`cms.Pages.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## Post + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/cms/Post/Fetch` | [`cms.PostListRequest`](#cmspostlistrequest) | [`cms.PostListReply`](#cmspostlistreply) | Unary | +| `GetByIdentity` | `POST /rpc/cms/Post/GetByIdentity` | [`cms.GetPostRequest`](#cmsgetpostrequest) | [`cms.PostItem`](#cmspostitem) | Unary | +| `GetByKey` | `POST /rpc/cms/Post/GetByKey` | [`cms.GetPostByKeyRequest`](#cmsgetpostbykeyrequest) | [`cms.PostItem`](#cmspostitem) | Unary | +| `Search` | `POST /rpc/cms/Post/Search` | [`base_cms_blocks.CmsSearchRequest`](#base_cms_blockscmssearchrequest) | [`cms.PostListReply`](#cmspostlistreply) | Unary | +| `Create` | `POST /rpc/cms/Post/Create` | [`cms.PostItem`](#cmspostitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Modify` | `POST /rpc/cms/Post/Modify` | [`cms.PostItem`](#cmspostitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Delete` | `POST /rpc/cms/Post/Delete` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `IncrPostLike` | `POST /rpc/cms/Post/IncrPostLike` | [`cms.PostOpIdentityRequest`](#cmspostopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `DescPostLike` | `POST /rpc/cms/Post/DescPostLike` | [`cms.PostOpIdentityRequest`](#cmspostopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `IncrPostUnlike` | `POST /rpc/cms/Post/IncrPostUnlike` | [`cms.PostOpIdentityRequest`](#cmspostopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `DescPostUnlike` | `POST /rpc/cms/Post/DescPostUnlike` | [`cms.PostOpIdentityRequest`](#cmspostopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `CommentList` | `POST /rpc/cms/Post/CommentList` | [`cms.CommentListRequest`](#cmscommentlistrequest) | [`cms.CommentListResponse`](#cmscommentlistresponse) | Unary | +| `AddComment` | `POST /rpc/cms/Post/AddComment` | [`cms.CommentItem`](#cmscommentitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `ModifyComment` | `POST /rpc/cms/Post/ModifyComment` | [`cms.CommentItem`](#cmscommentitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `DeleteComment` | `POST /rpc/cms/Post/DeleteComment` | [`cms.DeleteCommentRequest`](#cmsdeletecommentrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `IncrCommentLike` | `POST /rpc/cms/Post/IncrCommentLike` | [`cms.CommentOpIdentityRequest`](#cmscommentopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `DescCommentLike` | `POST /rpc/cms/Post/DescCommentLike` | [`cms.CommentOpIdentityRequest`](#cmscommentopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `IncrCommentUnlike` | `POST /rpc/cms/Post/IncrCommentUnlike` | [`cms.CommentOpIdentityRequest`](#cmscommentopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `DescCommentUnlike` | `POST /rpc/cms/Post/DescCommentUnlike` | [`cms.CommentOpIdentityRequest`](#cmscommentopidentityrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | + +### Post.Fetch + +- 动态 HTTP：`POST /rpc/cms/Post/Fetch` +- gRPC：`/cms.Post/Fetch` +- 白名单键：`cms.Post.Fetch` +- 请求示例： + +```json +{ + "author_identity": "string", + "category_identity": "string", + "keyword": "string", + "page": "0", + "size": "0", + "type": 0 +} +``` + +### Post.GetByIdentity + +- 动态 HTTP：`POST /rpc/cms/Post/GetByIdentity` +- gRPC：`/cms.Post/GetByIdentity` +- 白名单键：`cms.Post.GetByIdentity` +- 请求示例： + +```json +{ + "author_identity": "string", + "identity": "string" +} +``` + +### Post.GetByKey + +- 动态 HTTP：`POST /rpc/cms/Post/GetByKey` +- gRPC：`/cms.Post/GetByKey` +- 白名单键：`cms.Post.GetByKey` +- 请求示例： + +```json +{ + "key": "string" +} +``` + +### Post.Search + +- 动态 HTTP：`POST /rpc/cms/Post/Search` +- gRPC：`/cms.Post/Search` +- 白名单键：`cms.Post.Search` +- 请求示例： + +```json +{ + "keyword": "string", + "page_no": "0", + "page_size": "0" +} +``` + +### Post.Create + +- 动态 HTTP：`POST /rpc/cms/Post/Create` +- gRPC：`/cms.Post/Create` +- 白名单键：`cms.Post.Create` +- 请求示例： + +```json +{ + "accessory_data": [ + { + "created_at": "string", + "file_path": "string", + "identity": "string", + "title": "string" + } + ], + "accessory_identity_array": [ + "string" + ], + "author": "string", + "author_identity": "string", + "category_data": [ + { + "category_key": "string", + "child": [ + {} + ], + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "parent_id": "0", + "site_identity": "string", + "title": "string", + "updated_at": "string" + } + ], + "category_identity_array": [ + "string" + ], + "comment_hits": "0", + "content": "string", + "cover_path": "string", + "created_at": "string", + "description": "string", + "extend_data": "string", + "extend_desc": "string", + "extend_img": "string", + "extend_url": "string", + "has_accessory": false, + "hash": "string", + "hits": "0", + "identity": "string", + "key": "string", + "lang": "string", + "like_hits": "0", + "owner_id": "0", + "owner_identity": "string", + "post_type": 0, + "published": "string", + "rights": "string", + "site_identity": "string", + "source_origin": "string", + "source_url": "string", + "tags_data": [ + { + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "title": "string" + } + ], + "tags_identity_array": [ + "string" + ], + "target_url": "string", + "title": "string", + "unlike_hits": "0", + "updated_at": "string" +} +``` + +### Post.Modify + +- 动态 HTTP：`POST /rpc/cms/Post/Modify` +- gRPC：`/cms.Post/Modify` +- 白名单键：`cms.Post.Modify` +- 请求示例： + +```json +{ + "accessory_data": [ + { + "created_at": "string", + "file_path": "string", + "identity": "string", + "title": "string" + } + ], + "accessory_identity_array": [ + "string" + ], + "author": "string", + "author_identity": "string", + "category_data": [ + { + "category_key": "string", + "child": [ + {} + ], + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "parent_id": "0", + "site_identity": "string", + "title": "string", + "updated_at": "string" + } + ], + "category_identity_array": [ + "string" + ], + "comment_hits": "0", + "content": "string", + "cover_path": "string", + "created_at": "string", + "description": "string", + "extend_data": "string", + "extend_desc": "string", + "extend_img": "string", + "extend_url": "string", + "has_accessory": false, + "hash": "string", + "hits": "0", + "identity": "string", + "key": "string", + "lang": "string", + "like_hits": "0", + "owner_id": "0", + "owner_identity": "string", + "post_type": 0, + "published": "string", + "rights": "string", + "site_identity": "string", + "source_origin": "string", + "source_url": "string", + "tags_data": [ + { + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "title": "string" + } + ], + "tags_identity_array": [ + "string" + ], + "target_url": "string", + "title": "string", + "unlike_hits": "0", + "updated_at": "string" +} +``` + +### Post.Delete + +- 动态 HTTP：`POST /rpc/cms/Post/Delete` +- gRPC：`/cms.Post/Delete` +- 白名单键：`cms.Post.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Post.IncrPostLike + +- 动态 HTTP：`POST /rpc/cms/Post/IncrPostLike` +- gRPC：`/cms.Post/IncrPostLike` +- 白名单键：`cms.Post.IncrPostLike` +- 请求示例： + +```json +{ + "op_identity": "string", + "post_identity": "string" +} +``` + +### Post.DescPostLike + +- 动态 HTTP：`POST /rpc/cms/Post/DescPostLike` +- gRPC：`/cms.Post/DescPostLike` +- 白名单键：`cms.Post.DescPostLike` +- 请求示例： + +```json +{ + "op_identity": "string", + "post_identity": "string" +} +``` + +### Post.IncrPostUnlike + +- 动态 HTTP：`POST /rpc/cms/Post/IncrPostUnlike` +- gRPC：`/cms.Post/IncrPostUnlike` +- 白名单键：`cms.Post.IncrPostUnlike` +- 请求示例： + +```json +{ + "op_identity": "string", + "post_identity": "string" +} +``` + +### Post.DescPostUnlike + +- 动态 HTTP：`POST /rpc/cms/Post/DescPostUnlike` +- gRPC：`/cms.Post/DescPostUnlike` +- 白名单键：`cms.Post.DescPostUnlike` +- 请求示例： + +```json +{ + "op_identity": "string", + "post_identity": "string" +} +``` + +### Post.CommentList + +- 动态 HTTP：`POST /rpc/cms/Post/CommentList` +- gRPC：`/cms.Post/CommentList` +- 白名单键：`cms.Post.CommentList` +- 请求示例： + +```json +{ + "page": "0", + "post_identity": "string", + "size": "0" +} +``` + +### Post.AddComment + +- 动态 HTTP：`POST /rpc/cms/Post/AddComment` +- gRPC：`/cms.Post/AddComment` +- 白名单键：`cms.Post.AddComment` +- 请求示例： + +```json +{ + "Cms": "string", + "comment_hits": "0", + "created_at": "string", + "identity": "string", + "like_hits": "0", + "list": [ + {} + ], + "owner_identity": "string", + "owner_name": "string", + "parent_id": "0", + "post_identity": "string", + "reply_identity": "string", + "role": "string", + "unlike_hits": "0", + "updated_at": "string" +} +``` + +### Post.ModifyComment + +- 动态 HTTP：`POST /rpc/cms/Post/ModifyComment` +- gRPC：`/cms.Post/ModifyComment` +- 白名单键：`cms.Post.ModifyComment` +- 请求示例： + +```json +{ + "Cms": "string", + "comment_hits": "0", + "created_at": "string", + "identity": "string", + "like_hits": "0", + "list": [ + {} + ], + "owner_identity": "string", + "owner_name": "string", + "parent_id": "0", + "post_identity": "string", + "reply_identity": "string", + "role": "string", + "unlike_hits": "0", + "updated_at": "string" +} +``` + +### Post.DeleteComment + +- 动态 HTTP：`POST /rpc/cms/Post/DeleteComment` +- gRPC：`/cms.Post/DeleteComment` +- 白名单键：`cms.Post.DeleteComment` +- 请求示例： + +```json +{ + "identity": "string", + "post_identity": "string" +} +``` + +### Post.IncrCommentLike + +- 动态 HTTP：`POST /rpc/cms/Post/IncrCommentLike` +- gRPC：`/cms.Post/IncrCommentLike` +- 白名单键：`cms.Post.IncrCommentLike` +- 请求示例： + +```json +{ + "comment_identity": "string", + "op_identity": "string" +} +``` + +### Post.DescCommentLike + +- 动态 HTTP：`POST /rpc/cms/Post/DescCommentLike` +- gRPC：`/cms.Post/DescCommentLike` +- 白名单键：`cms.Post.DescCommentLike` +- 请求示例： + +```json +{ + "comment_identity": "string", + "op_identity": "string" +} +``` + +### Post.IncrCommentUnlike + +- 动态 HTTP：`POST /rpc/cms/Post/IncrCommentUnlike` +- gRPC：`/cms.Post/IncrCommentUnlike` +- 白名单键：`cms.Post.IncrCommentUnlike` +- 请求示例： + +```json +{ + "comment_identity": "string", + "op_identity": "string" +} +``` + +### Post.DescCommentUnlike + +- 动态 HTTP：`POST /rpc/cms/Post/DescCommentUnlike` +- gRPC：`/cms.Post/DescCommentUnlike` +- 白名单键：`cms.Post.DescCommentUnlike` +- 请求示例： + +```json +{ + "comment_identity": "string", + "op_identity": "string" +} +``` + +## Site + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/cms/Site/Fetch` | [`base_cms_blocks.Empty`](#base_cms_blocksempty) | [`cms.SiteListReply`](#cmssitelistreply) | Unary | +| `Get` | `POST /rpc/cms/Site/Get` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`cms.SiteItem`](#cmssiteitem) | Unary | +| `Create` | `POST /rpc/cms/Site/Create` | [`cms.SiteItem`](#cmssiteitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Modify` | `POST /rpc/cms/Site/Modify` | [`cms.SiteItem`](#cmssiteitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Delete` | `POST /rpc/cms/Site/Delete` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | + +### Site.Fetch + +- 动态 HTTP：`POST /rpc/cms/Site/Fetch` +- gRPC：`/cms.Site/Fetch` +- 白名单键：`cms.Site.Fetch` +- 请求示例： + +```json +{} +``` + +### Site.Get + +- 动态 HTTP：`POST /rpc/cms/Site/Get` +- gRPC：`/cms.Site/Get` +- 白名单键：`cms.Site.Get` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Site.Create + +- 动态 HTTP：`POST /rpc/cms/Site/Create` +- gRPC：`/cms.Site/Create` +- 白名单键：`cms.Site.Create` +- 请求示例： + +```json +{ + "configs": "string", + "description": "string", + "domain": "string", + "icon_path": "string", + "id": "0", + "identity": "string", + "keywords": "string", + "seo": "string", + "theme": "string", + "title": "string" +} +``` + +### Site.Modify + +- 动态 HTTP：`POST /rpc/cms/Site/Modify` +- gRPC：`/cms.Site/Modify` +- 白名单键：`cms.Site.Modify` +- 请求示例： + +```json +{ + "configs": "string", + "description": "string", + "domain": "string", + "icon_path": "string", + "id": "0", + "identity": "string", + "keywords": "string", + "seo": "string", + "theme": "string", + "title": "string" +} +``` + +### Site.Delete + +- 动态 HTTP：`POST /rpc/cms/Site/Delete` +- gRPC：`/cms.Site/Delete` +- 白名单键：`cms.Site.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## Tags + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/cms/Tags/Fetch` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`cms.TagsListReply`](#cmstagslistreply) | Unary | +| `Create` | `POST /rpc/cms/Tags/Create` | [`base_cms_blocks.CmsTagsItem`](#base_cms_blockscmstagsitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Modify` | `POST /rpc/cms/Tags/Modify` | [`base_cms_blocks.CmsTagsItem`](#base_cms_blockscmstagsitem) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | +| `Delete` | `POST /rpc/cms/Tags/Delete` | [`base_cms_blocks.IdentRequest`](#base_cms_blocksidentrequest) | [`base_cms_blocks.StatusReply`](#base_cms_blocksstatusreply) | Unary | + +### Tags.Fetch + +- 动态 HTTP：`POST /rpc/cms/Tags/Fetch` +- gRPC：`/cms.Tags/Fetch` +- 白名单键：`cms.Tags.Fetch` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Tags.Create + +- 动态 HTTP：`POST /rpc/cms/Tags/Create` +- gRPC：`/cms.Tags/Create` +- 白名单键：`cms.Tags.Create` +- 请求示例： + +```json +{ + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "title": "string" +} +``` + +### Tags.Modify + +- 动态 HTTP：`POST /rpc/cms/Tags/Modify` +- gRPC：`/cms.Tags/Modify` +- 白名单键：`cms.Tags.Modify` +- 请求示例： + +```json +{ + "cover_path": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "title": "string" +} +``` + +### Tags.Delete + +- 动态 HTTP：`POST /rpc/cms/Tags/Delete` +- gRPC：`/cms.Tags/Delete` +- 白名单键：`cms.Tags.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## 消息结构 + +### base_cms_blocks.CmsAccessoryItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `file_path` | `string` | 可选 | +| `created_at` | `string` | 可选 | + +### base_cms_blocks.CmsCategoryItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `site_identity` | `string` | 可选 | +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `parent_id` | `int64` | 可选 | +| `title` | `string` | 可选 | +| `cover_path` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `updated_at` | `string` | 可选 | +| `child` | `[]base_cms_blocks.CmsCategoryItem` | 数组 | +| `category_key` | `string` | 可选 | + +### base_cms_blocks.CmsSearchRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `keyword` | `string` | 可选 | +| `page_no` | `int64` | 可选 | +| `page_size` | `int64` | 可选 | + +### base_cms_blocks.CmsTagsItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `cover_path` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `created_at` | `string` | 可选 | + +### base_cms_blocks.Empty + +空消息：请求时发送 `{}`。 + +### base_cms_blocks.IdentRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | + +### base_cms_blocks.StatusReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `code` | `int32` | 可选 | +| `message` | `string` | 可选 | +| `details` | `string` | 可选 | +| `timeseq` | `int64` | 可选 | + +### cms.CategoryListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]base_cms_blocks.CmsCategoryItem` | 数组 | +| `count` | `int64` | 可选 | + +### cms.CommentItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `post_identity` | `string` | 可选 | +| `parent_id` | `int64` | 可选 | +| `Cms` | `string` | 可选 | +| `reply_identity` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `updated_at` | `string` | 可选 | +| `list` | `[]cms.CommentItem` | 数组 | +| `like_hits` | `int64` | 可选 | +| `unlike_hits` | `int64` | 可选 | +| `comment_hits` | `int64` | 可选 | +| `owner_name` | `string` | 可选 | +| `owner_identity` | `string` | 可选 | +| `role` | `string` | 可选 | + +### cms.CommentListRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `post_identity` | `string` | 可选 | +| `page` | `int64` | 可选 | +| `size` | `int64` | 可选 | + +### cms.CommentListResponse + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `list` | `[]cms.CommentItem` | 数组 | +| `count` | `int64` | 可选 | + +### cms.CommentOpIdentityRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `comment_identity` | `string` | 可选 | +| `op_identity` | `string` | 可选 | + +### cms.DeleteCategoryRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | + +### cms.DeleteCommentRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `post_identity` | `string` | 可选 | + +### cms.GetPagesByKeyRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `key` | `string` | 可选 | + +### cms.GetPagesRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | + +### cms.GetPostByKeyRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `key` | `string` | 可选 | + +### cms.GetPostRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `author_identity` | `string` | 可选 | + +### cms.ModifyCategoryRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `site_identity` | `string` | 可选 | +| `identity` | `string` | 可选 | +| `parent_id` | `int64` | 可选 | +| `title` | `string` | 可选 | +| `cover_path` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `updated_at` | `string` | 可选 | +| `data` | `[]base_cms_blocks.CmsCategoryItem` | 数组 | +| `category_key` | `string` | 可选 | + +### cms.PagesItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `site_identity` | `string` | 可选 | +| `identity` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `updated_at` | `string` | 可选 | +| `post_type` | `int32` | 可选 | +| `rights` | `string` | 可选 | +| `title` | `string` | 可选 | +| `key` | `string` | 可选 | +| `description` | `string` | 可选 | +| `cover_path` | `string` | 可选 | +| `content` | `string` | 可选 | +| `has_accessory` | `bool` | 可选 | +| `accessory_identity_array` | `[]string` | 数组 | +| `accessory_data` | `[]base_cms_blocks.CmsAccessoryItem` | 数组 | +| `tags_data` | `[]base_cms_blocks.CmsTagsItem` | 数组 | +| `tags_identity_array` | `[]string` | 数组 | +| `hits` | `int64` | 可选 | + +### cms.PagesListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]cms.PagesItem` | 数组 | +| `count` | `int64` | 可选 | + +### cms.PagesListRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `page` | `int64` | 可选 | +| `size` | `int64` | 可选 | +| `keyword` | `string` | 可选 | +| `type` | `int32` | 可选 | + +### cms.PostItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `site_identity` | `string` | 可选 | +| `identity` | `string` | 可选 | +| `owner_id` | `int64` | 可选 | +| `owner_identity` | `string` | 可选 | +| `category_identity_array` | `[]string` | 数组 | +| `tags_identity_array` | `[]string` | 数组 | +| `title` | `string` | 可选 | +| `cover_path` | `string` | 可选 | +| `author` | `string` | 可选 | +| `author_identity` | `string` | 可选 | +| `content` | `string` | 可选 | +| `target_url` | `string` | 可选 | +| `source_url` | `string` | 可选 | +| `hits` | `int64` | 可选 | +| `accessory_identity_array` | `[]string` | 数组 | +| `has_accessory` | `bool` | 可选 | +| `created_at` | `string` | 可选 | +| `updated_at` | `string` | 可选 | +| `description` | `string` | 可选 | +| `like_hits` | `int64` | 可选 | +| `unlike_hits` | `int64` | 可选 | +| `comment_hits` | `int64` | 可选 | +| `post_type` | `int32` | 可选 | +| `rights` | `string` | 可选 | +| `key` | `string` | 可选 | +| `category_data` | `[]base_cms_blocks.CmsCategoryItem` | 数组 | +| `tags_data` | `[]base_cms_blocks.CmsTagsItem` | 数组 | +| `accessory_data` | `[]base_cms_blocks.CmsAccessoryItem` | 数组 | +| `lang` | `string` | 可选 | +| `source_origin` | `string` | 可选 | +| `extend_url` | `string` | 可选 | +| `extend_data` | `string` | 可选 | +| `extend_img` | `string` | 可选 | +| `extend_desc` | `string` | 可选 | +| `published` | `string` | 可选 | +| `hash` | `string` | 可选 | + +### cms.PostListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]cms.PostItem` | 数组 | +| `count` | `int64` | 可选 | + +### cms.PostListRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `page` | `int64` | 可选 | +| `size` | `int64` | 可选 | +| `author_identity` | `string` | 可选 | +| `category_identity` | `string` | 可选 | +| `keyword` | `string` | 可选 | +| `type` | `int32` | 可选 | + +### cms.PostOpIdentityRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `post_identity` | `string` | 可选 | +| `op_identity` | `string` | 可选 | + +### cms.SiteItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `description` | `string` | 可选 | +| `icon_path` | `string` | 可选 | +| `keywords` | `string` | 可选 | +| `domain` | `string` | 可选 | +| `seo` | `string` | 可选 | +| `theme` | `string` | 可选 | +| `configs` | `string` | 可选 | + +### cms.SiteListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]cms.SiteItem` | 数组 | +| `count` | `int64` | 可选 | + +### cms.TagsListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]base_cms_blocks.CmsTagsItem` | 数组 | +| `count` | `int64` | 可选 | diff --git a/wiki/api/04-feedback.md b/wiki/api/04-feedback.md new file mode 100644 index 0000000..86dff35 --- /dev/null +++ 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 ` 传递凭证。 +- 动态 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` | 可选 | diff --git a/wiki/api/05-initial.md b/wiki/api/05-initial.md new file mode 100644 index 0000000..c34205a --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 可选 | diff --git a/wiki/api/06-passport.md b/wiki/api/06-passport.md new file mode 100644 index 0000000..81adae0 --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 对象映射 | +| `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` | 对象映射 | +| `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` | 对象映射 | + +### 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` | 对象映射 | + +### passport.VerifyRequest.ArgsEntry + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `key` | `string` | 可选 | +| `value` | `string` | 可选 | diff --git a/wiki/api/07-sender.md b/wiki/api/07-sender.md new file mode 100644 index 0000000..0b9fa82 --- /dev/null +++ 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 ` 传递凭证。 +- 动态 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` | 对象映射 | + +### 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` | 对象映射 | + +### sender.SmsSendRequest.ParamtersEntry + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `key` | `string` | 可选 | +| `value` | `string` | 可选 | + +### sender.SmsVerifyRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `phone` | `string` | 可选 | +| `code` | `string` | 可选 | diff --git a/wiki/api/08-address.md b/wiki/api/08-address.md new file mode 100644 index 0000000..4475267 --- /dev/null +++ b/wiki/api/08-address.md @@ -0,0 +1,180 @@ +# ADDRESS API + +用户地址库管理。 + +> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。 + +## 接入方式 + +- 动态 HTTP：`POST /rpc/address/{Service}/{Method}` +- 原生 gRPC：`/address.{Service}/{Method}` +- grpc-gateway：`POST /address.{Service}/{Method}` +- 鉴权：需要登录的接口通过 `Authorization: Bearer ` 传递凭证。 +- 动态 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` | 可选 | diff --git a/wiki/api/09-mall.md b/wiki/api/09-mall.md new file mode 100644 index 0000000..d458b4a --- /dev/null +++ b/wiki/api/09-mall.md @@ -0,0 +1,1915 @@ +# MALL API + +商城广告、类目、运费、公告、商品、员工和店铺管理。 + +> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。 + +## 接入方式 + +- 动态 HTTP：`POST /rpc/mall/{Service}/{Method}` +- 原生 gRPC：`/mall.{Service}/{Method}` +- grpc-gateway：`POST /mall.{Service}/{Method}` +- 鉴权：需要登录的接口通过 `Authorization: Bearer ` 传递凭证。 +- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。 + +## 服务概览 + +| 服务 | 方法数 | 说明 | +|---|---:|---| +| `Ads` | 5 | Ads 服务 | +| `Category` | 4 | Category 服务 | +| `Freight` | 9 | Freight 服务 | +| `Notice` | 4 | Notice 服务 | +| `Product` | 21 | Product 服务 | +| `Staff` | 7 | Staff 服务 | +| `Store` | 10 | Store 服务 | + +## Ads + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `ByPos` | `POST /rpc/mall/Ads/ByPos` | [`mall.ByPosRequest`](#mallbyposrequest) | [`mall.AdsListReply`](#malladslistreply) | Unary | +| `Fetch` | `POST /rpc/mall/Ads/Fetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.AdsListReply`](#malladslistreply) | Unary | +| `Create` | `POST /rpc/mall/Ads/Create` | [`mall.AdsItem`](#malladsitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Modify` | `POST /rpc/mall/Ads/Modify` | [`mall.AdsItem`](#malladsitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Delete` | `POST /rpc/mall/Ads/Delete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | + +### Ads.ByPos + +- 动态 HTTP：`POST /rpc/mall/Ads/ByPos` +- gRPC：`/mall.Ads/ByPos` +- 白名单键：`mall.Ads.ByPos` +- 请求示例： + +```json +{ + "pos_key": [ + "string" + ], + "store_identity": "string" +} +``` + +### Ads.Fetch + +- 动态 HTTP：`POST /rpc/mall/Ads/Fetch` +- gRPC：`/mall.Ads/Fetch` +- 白名单键：`mall.Ads.Fetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Ads.Create + +- 动态 HTTP：`POST /rpc/mall/Ads/Create` +- gRPC：`/mall.Ads/Create` +- 白名单键：`mall.Ads.Create` +- 请求示例： + +```json +{ + "content": "string", + "created_at": "string", + "id": "0", + "pos_key": "string", + "status": "0", + "title": "string", + "to_url": "string", + "type": 0 +} +``` + +### Ads.Modify + +- 动态 HTTP：`POST /rpc/mall/Ads/Modify` +- gRPC：`/mall.Ads/Modify` +- 白名单键：`mall.Ads.Modify` +- 请求示例： + +```json +{ + "content": "string", + "created_at": "string", + "id": "0", + "pos_key": "string", + "status": "0", + "title": "string", + "to_url": "string", + "type": 0 +} +``` + +### Ads.Delete + +- 动态 HTTP：`POST /rpc/mall/Ads/Delete` +- gRPC：`/mall.Ads/Delete` +- 白名单键：`mall.Ads.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## Category + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/mall/Category/Fetch` | [`mall.CategoryFetchRequest`](#mallcategoryfetchrequest) | [`mall.CategoryReply`](#mallcategoryreply) | Unary | +| `Create` | `POST /rpc/mall/Category/Create` | [`mall.CategoryItem`](#mallcategoryitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Delete` | `POST /rpc/mall/Category/Delete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Modify` | `POST /rpc/mall/Category/Modify` | [`mall.CategoryItem`](#mallcategoryitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | + +### Category.Fetch + +- 动态 HTTP：`POST /rpc/mall/Category/Fetch` +- gRPC：`/mall.Category/Fetch` +- 白名单键：`mall.Category.Fetch` +- 请求示例： + +```json +{ + "id": "0", + "keywords": "string", + "store_identity": "string", + "types": "string" +} +``` + +### Category.Create + +- 动态 HTTP：`POST /rpc/mall/Category/Create` +- gRPC：`/mall.Category/Create` +- 白名单键：`mall.Category.Create` +- 请求示例： + +```json +{ + "categories": [ + {} + ], + "created_at": "string", + "en_title": "string", + "icon": "string", + "id": "0", + "identity": "string", + "intro": "string", + "keys": "string", + "parent_id": "0", + "paths": "string", + "sort": 0, + "status": 0, + "title": "string" +} +``` + +### Category.Delete + +- 动态 HTTP：`POST /rpc/mall/Category/Delete` +- gRPC：`/mall.Category/Delete` +- 白名单键：`mall.Category.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Category.Modify + +- 动态 HTTP：`POST /rpc/mall/Category/Modify` +- gRPC：`/mall.Category/Modify` +- 白名单键：`mall.Category.Modify` +- 请求示例： + +```json +{ + "categories": [ + {} + ], + "created_at": "string", + "en_title": "string", + "icon": "string", + "id": "0", + "identity": "string", + "intro": "string", + "keys": "string", + "parent_id": "0", + "paths": "string", + "sort": 0, + "status": 0, + "title": "string" +} +``` + +## Freight + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/mall/Freight/Fetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.FreightReply`](#mallfreightreply) | Unary | +| `Modify` | `POST /rpc/mall/Freight/Modify` | [`mall.FreightItem`](#mallfreightitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Delete` | `POST /rpc/mall/Freight/Delete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Create` | `POST /rpc/mall/Freight/Create` | [`mall.FreightItem`](#mallfreightitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Detail` | `POST /rpc/mall/Freight/Detail` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.FreightItem`](#mallfreightitem) | Unary | +| `DenyRegionFetch` | `POST /rpc/mall/Freight/DenyRegionFetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.DenyRegionReply`](#malldenyregionreply) | Unary | +| `DenyRegionCreate` | `POST /rpc/mall/Freight/DenyRegionCreate` | [`mall.DenyRegionItem`](#malldenyregionitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `DenyRegionDelete` | `POST /rpc/mall/Freight/DenyRegionDelete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `DenyRegionModify` | `POST /rpc/mall/Freight/DenyRegionModify` | [`mall.DenyRegionItem`](#malldenyregionitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | + +### Freight.Fetch + +- 动态 HTTP：`POST /rpc/mall/Freight/Fetch` +- gRPC：`/mall.Freight/Fetch` +- 白名单键：`mall.Freight.Fetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Freight.Modify + +- 动态 HTTP：`POST /rpc/mall/Freight/Modify` +- gRPC：`/mall.Freight/Modify` +- 白名单键：`mall.Freight.Modify` +- 请求示例： + +```json +{ + "cost_type": 0, + "id": "0", + "identity": "string", + "post_type": 0, + "quota": "0", + "region_type": 0, + "rules": [ + { + "count_basic": "0", + "count_extra": "0", + "freight_identity": "string", + "id": "0", + "identity": "string", + "is_default": 0, + "price_basic": "0", + "price_extra": "0", + "region": [ + { + "id": 0, + "name": "string", + "second": [ + {} + ] + } + ], + "region_str": "string", + "status": 0 + } + ], + "status": 0, + "title": "string" +} +``` + +### Freight.Delete + +- 动态 HTTP：`POST /rpc/mall/Freight/Delete` +- gRPC：`/mall.Freight/Delete` +- 白名单键：`mall.Freight.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Freight.Create + +- 动态 HTTP：`POST /rpc/mall/Freight/Create` +- gRPC：`/mall.Freight/Create` +- 白名单键：`mall.Freight.Create` +- 请求示例： + +```json +{ + "cost_type": 0, + "id": "0", + "identity": "string", + "post_type": 0, + "quota": "0", + "region_type": 0, + "rules": [ + { + "count_basic": "0", + "count_extra": "0", + "freight_identity": "string", + "id": "0", + "identity": "string", + "is_default": 0, + "price_basic": "0", + "price_extra": "0", + "region": [ + { + "id": 0, + "name": "string", + "second": [ + {} + ] + } + ], + "region_str": "string", + "status": 0 + } + ], + "status": 0, + "title": "string" +} +``` + +### Freight.Detail + +- 动态 HTTP：`POST /rpc/mall/Freight/Detail` +- gRPC：`/mall.Freight/Detail` +- 白名单键：`mall.Freight.Detail` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Freight.DenyRegionFetch + +- 动态 HTTP：`POST /rpc/mall/Freight/DenyRegionFetch` +- gRPC：`/mall.Freight/DenyRegionFetch` +- 白名单键：`mall.Freight.DenyRegionFetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Freight.DenyRegionCreate + +- 动态 HTTP：`POST /rpc/mall/Freight/DenyRegionCreate` +- gRPC：`/mall.Freight/DenyRegionCreate` +- 白名单键：`mall.Freight.DenyRegionCreate` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string", + "mall_identity": "string", + "region": [ + { + "id": 0, + "name": "string", + "second": [ + {} + ] + } + ], + "title": "string" +} +``` + +### Freight.DenyRegionDelete + +- 动态 HTTP：`POST /rpc/mall/Freight/DenyRegionDelete` +- gRPC：`/mall.Freight/DenyRegionDelete` +- 白名单键：`mall.Freight.DenyRegionDelete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Freight.DenyRegionModify + +- 动态 HTTP：`POST /rpc/mall/Freight/DenyRegionModify` +- gRPC：`/mall.Freight/DenyRegionModify` +- 白名单键：`mall.Freight.DenyRegionModify` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string", + "mall_identity": "string", + "region": [ + { + "id": 0, + "name": "string", + "second": [ + {} + ] + } + ], + "title": "string" +} +``` + +## Notice + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Fetch` | `POST /rpc/mall/Notice/Fetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.NoticeListReply`](#mallnoticelistreply) | Unary | +| `Create` | `POST /rpc/mall/Notice/Create` | [`mall.NoticeItem`](#mallnoticeitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Modify` | `POST /rpc/mall/Notice/Modify` | [`mall.NoticeItem`](#mallnoticeitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Delete` | `POST /rpc/mall/Notice/Delete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | + +### Notice.Fetch + +- 动态 HTTP：`POST /rpc/mall/Notice/Fetch` +- gRPC：`/mall.Notice/Fetch` +- 白名单键：`mall.Notice.Fetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Notice.Create + +- 动态 HTTP：`POST /rpc/mall/Notice/Create` +- gRPC：`/mall.Notice/Create` +- 白名单键：`mall.Notice.Create` +- 请求示例： + +```json +{ + "author": "string", + "content": "string", + "created_at": "string", + "identity": "string", + "status": "0", + "store_id": "0", + "store_identity": "string", + "title": "string" +} +``` + +### Notice.Modify + +- 动态 HTTP：`POST /rpc/mall/Notice/Modify` +- gRPC：`/mall.Notice/Modify` +- 白名单键：`mall.Notice.Modify` +- 请求示例： + +```json +{ + "author": "string", + "content": "string", + "created_at": "string", + "identity": "string", + "status": "0", + "store_id": "0", + "store_identity": "string", + "title": "string" +} +``` + +### Notice.Delete + +- 动态 HTTP：`POST /rpc/mall/Notice/Delete` +- gRPC：`/mall.Notice/Delete` +- 白名单键：`mall.Notice.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +## Product + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `ItemFetch` | `POST /rpc/mall/Product/ItemFetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.ListReply`](#malllistreply) | Unary | +| `ItemDetail` | `POST /rpc/mall/Product/ItemDetail` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.ProductItem`](#mallproductitem) | Unary | +| `ItemDetailBySerial` | `POST /rpc/mall/Product/ItemDetailBySerial` | [`ec_mall_blocks.StoreSerialRequest`](#ec_mall_blocksstoreserialrequest) | [`mall.ListReply`](#malllistreply) | Unary | +| `ItemDetailBySpec` | `POST /rpc/mall/Product/ItemDetailBySpec` | [`mall.DetailBySpecRequest`](#malldetailbyspecrequest) | [`mall.ListItem`](#malllistitem) | Unary | +| `ItemCreate` | `POST /rpc/mall/Product/ItemCreate` | [`mall.ProductItem`](#mallproductitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `ItemDelete` | `POST /rpc/mall/Product/ItemDelete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `ItemModify` | `POST /rpc/mall/Product/ItemModify` | [`mall.ModifyRequest`](#mallmodifyrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `ItemBatchOp` | `POST /rpc/mall/Product/ItemBatchOp` | [`mall.OpRequest`](#malloprequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SpecFetch` | `POST /rpc/mall/Product/SpecFetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.SpecReply`](#mallspecreply) | Unary | +| `SpecCreate` | `POST /rpc/mall/Product/SpecCreate` | [`mall.SpecItem`](#mallspecitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SpecModify` | `POST /rpc/mall/Product/SpecModify` | [`mall.SpecItem`](#mallspecitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SpecDelete` | `POST /rpc/mall/Product/SpecDelete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SpecDetail` | `POST /rpc/mall/Product/SpecDetail` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.SpecItem`](#mallspecitem) | Unary | +| `PhotoCreate` | `POST /rpc/mall/Product/PhotoCreate` | [`mall.PhotoItem`](#mallphotoitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `PhotoDelete` | `POST /rpc/mall/Product/PhotoDelete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `PhotoList` | `POST /rpc/mall/Product/PhotoList` | [`mall.PhotoItem`](#mallphotoitem) | [`mall.PhotoReply`](#mallphotoreply) | Unary | +| `CommentFetch` | `POST /rpc/mall/Product/CommentFetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.CommentListReply`](#mallcommentlistreply) | Unary | +| `CommentCreate` | `POST /rpc/mall/Product/CommentCreate` | [`mall.CommentItem`](#mallcommentitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `CommentRe` | `POST /rpc/mall/Product/CommentRe` | [`mall.CommentItem`](#mallcommentitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `CommentDelete` | `POST /rpc/mall/Product/CommentDelete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `CommentModify` | `POST /rpc/mall/Product/CommentModify` | [`mall.CommentItem`](#mallcommentitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | + +### Product.ItemFetch + +- 动态 HTTP：`POST /rpc/mall/Product/ItemFetch` +- gRPC：`/mall.Product/ItemFetch` +- 白名单键：`mall.Product.ItemFetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Product.ItemDetail + +- 动态 HTTP：`POST /rpc/mall/Product/ItemDetail` +- gRPC：`/mall.Product/ItemDetail` +- 白名单键：`mall.Product.ItemDetail` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Product.ItemDetailBySerial + +- 动态 HTTP：`POST /rpc/mall/Product/ItemDetailBySerial` +- gRPC：`/mall.Product/ItemDetailBySerial` +- 白名单键：`mall.Product.ItemDetailBySerial` +- 请求示例： + +```json +{ + "serial_id": [ + "string" + ], + "store_identity": "string" +} +``` + +### Product.ItemDetailBySpec + +- 动态 HTTP：`POST /rpc/mall/Product/ItemDetailBySpec` +- gRPC：`/mall.Product/ItemDetailBySpec` +- 白名单键：`mall.Product.ItemDetailBySpec` +- 请求示例： + +```json +{ + "spec_no": "string" +} +``` + +### Product.ItemCreate + +- 动态 HTTP：`POST /rpc/mall/Product/ItemCreate` +- gRPC：`/mall.Product/ItemCreate` +- 白名单键：`mall.Product.ItemCreate` +- 请求示例： + +```json +{ + "brand": "string", + "categories": [ + { + "categories": [ + {} + ], + "created_at": "string", + "en_title": "string", + "icon": "string", + "id": "0", + "identity": "string", + "intro": "string", + "keys": "string", + "parent_id": "0", + "paths": "string", + "sort": 0, + "status": 0, + "title": "string" + } + ], + "category": "string", + "category_id": [ + "0" + ], + "content": "string", + "cover_image": "string", + "created_at": "string", + "gas_types": "0", + "id": "0", + "identity": "string", + "images": [ + { + "id": "0", + "identity": "string", + "name": "string", + "product_identity": "string", + "sort": 0, + "types": "string", + "url": "string" + } + ], + "liTemplate_id": "0", + "limitation": "0", + "measuring_name": "string", + "note": "string", + "price": "0", + "putaway_time": "string", + "recent_number": "0", + "sale_total": "0", + "sell_max": "0", + "sell_min": "0", + "serial_id": "string", + "spec_id": [ + "0" + ], + "specification": [ + { + "direct_sales": "0", + "ds_tp_type": 0, + "id": "0", + "identity": "string", + "img": "string", + "keyword": "string", + "price": "0", + "product_identity": "string", + "purchasing_price": "0", + "spec_no": "string", + "stock": "0", + "stock_type": 0, + "store_identity": "string", + "supply_id": "0", + "title": "string", + "tp_type": 0, + "wholesale": "0" + } + ], + "standard_number": "string", + "status": 0, + "stock": "0", + "stock_type": "0", + "store_id": "0", + "store_identity": "string", + "supply_id": "0", + "supply_name": "string", + "template_id": 0, + "title": "string", + "wastage": "0" +} +``` + +### Product.ItemDelete + +- 动态 HTTP：`POST /rpc/mall/Product/ItemDelete` +- gRPC：`/mall.Product/ItemDelete` +- 白名单键：`mall.Product.ItemDelete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Product.ItemModify + +- 动态 HTTP：`POST /rpc/mall/Product/ItemModify` +- gRPC：`/mall.Product/ItemModify` +- 白名单键：`mall.Product.ItemModify` +- 请求示例： + +```json +{ + "identity": "string", + "status": 0 +} +``` + +### Product.ItemBatchOp + +- 动态 HTTP：`POST /rpc/mall/Product/ItemBatchOp` +- gRPC：`/mall.Product/ItemBatchOp` +- 白名单键：`mall.Product.ItemBatchOp` +- 请求示例： + +```json +{ + "identity": [ + "string" + ], + "status": 0 +} +``` + +### Product.SpecFetch + +- 动态 HTTP：`POST /rpc/mall/Product/SpecFetch` +- gRPC：`/mall.Product/SpecFetch` +- 白名单键：`mall.Product.SpecFetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Product.SpecCreate + +- 动态 HTTP：`POST /rpc/mall/Product/SpecCreate` +- gRPC：`/mall.Product/SpecCreate` +- 白名单键：`mall.Product.SpecCreate` +- 请求示例： + +```json +{ + "direct_sales": "0", + "ds_tp_type": 0, + "id": "0", + "identity": "string", + "img": "string", + "keyword": "string", + "price": "0", + "product_identity": "string", + "purchasing_price": "0", + "spec_no": "string", + "stock": "0", + "stock_type": 0, + "store_identity": "string", + "supply_id": "0", + "title": "string", + "tp_type": 0, + "wholesale": "0" +} +``` + +### Product.SpecModify + +- 动态 HTTP：`POST /rpc/mall/Product/SpecModify` +- gRPC：`/mall.Product/SpecModify` +- 白名单键：`mall.Product.SpecModify` +- 请求示例： + +```json +{ + "direct_sales": "0", + "ds_tp_type": 0, + "id": "0", + "identity": "string", + "img": "string", + "keyword": "string", + "price": "0", + "product_identity": "string", + "purchasing_price": "0", + "spec_no": "string", + "stock": "0", + "stock_type": 0, + "store_identity": "string", + "supply_id": "0", + "title": "string", + "tp_type": 0, + "wholesale": "0" +} +``` + +### Product.SpecDelete + +- 动态 HTTP：`POST /rpc/mall/Product/SpecDelete` +- gRPC：`/mall.Product/SpecDelete` +- 白名单键：`mall.Product.SpecDelete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Product.SpecDetail + +- 动态 HTTP：`POST /rpc/mall/Product/SpecDetail` +- gRPC：`/mall.Product/SpecDetail` +- 白名单键：`mall.Product.SpecDetail` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Product.PhotoCreate + +- 动态 HTTP：`POST /rpc/mall/Product/PhotoCreate` +- gRPC：`/mall.Product/PhotoCreate` +- 白名单键：`mall.Product.PhotoCreate` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string", + "name": "string", + "product_identity": "string", + "sort": 0, + "types": "string", + "url": "string" +} +``` + +### Product.PhotoDelete + +- 动态 HTTP：`POST /rpc/mall/Product/PhotoDelete` +- gRPC：`/mall.Product/PhotoDelete` +- 白名单键：`mall.Product.PhotoDelete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Product.PhotoList + +- 动态 HTTP：`POST /rpc/mall/Product/PhotoList` +- gRPC：`/mall.Product/PhotoList` +- 白名单键：`mall.Product.PhotoList` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string", + "name": "string", + "product_identity": "string", + "sort": 0, + "types": "string", + "url": "string" +} +``` + +### Product.CommentFetch + +- 动态 HTTP：`POST /rpc/mall/Product/CommentFetch` +- gRPC：`/mall.Product/CommentFetch` +- 白名单键：`mall.Product.CommentFetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Product.CommentCreate + +- 动态 HTTP：`POST /rpc/mall/Product/CommentCreate` +- gRPC：`/mall.Product/CommentCreate` +- 白名单键：`mall.Product.CommentCreate` +- 请求示例： + +```json +{ + "comment": "string", + "comment_identity": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "is_comment": false, + "nick_name": "string", + "product": "string", + "product_identity": "string", + "product_spec": "string", + "reply": "string", + "score": 0, + "spec_identity": "string", + "store_identity": "string" +} +``` + +### Product.CommentRe + +- 动态 HTTP：`POST /rpc/mall/Product/CommentRe` +- gRPC：`/mall.Product/CommentRe` +- 白名单键：`mall.Product.CommentRe` +- 请求示例： + +```json +{ + "comment": "string", + "comment_identity": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "is_comment": false, + "nick_name": "string", + "product": "string", + "product_identity": "string", + "product_spec": "string", + "reply": "string", + "score": 0, + "spec_identity": "string", + "store_identity": "string" +} +``` + +### Product.CommentDelete + +- 动态 HTTP：`POST /rpc/mall/Product/CommentDelete` +- gRPC：`/mall.Product/CommentDelete` +- 白名单键：`mall.Product.CommentDelete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Product.CommentModify + +- 动态 HTTP：`POST /rpc/mall/Product/CommentModify` +- gRPC：`/mall.Product/CommentModify` +- 白名单键：`mall.Product.CommentModify` +- 请求示例： + +```json +{ + "comment": "string", + "comment_identity": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "is_comment": false, + "nick_name": "string", + "product": "string", + "product_identity": "string", + "product_spec": "string", + "reply": "string", + "score": 0, + "spec_identity": "string", + "store_identity": "string" +} +``` + +## Staff + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `Login` | `POST /rpc/mall/Staff/Login` | [`mall.LoginRequest`](#mallloginrequest) | [`mall.LoginReply`](#mallloginreply) | Unary | +| `Fetch` | `POST /rpc/mall/Staff/Fetch` | [`ec_mall_blocks.MallFetchRequest`](#ec_mall_blocksmallfetchrequest) | [`mall.StaffListReply`](#mallstafflistreply) | Unary | +| `Create` | `POST /rpc/mall/Staff/Create` | [`mall.StaffItem`](#mallstaffitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Delete` | `POST /rpc/mall/Staff/Delete` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `GetProfile` | `POST /rpc/mall/Staff/GetProfile` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.StaffItem`](#mallstaffitem) | Unary | +| `SetProfile` | `POST /rpc/mall/Staff/SetProfile` | [`mall.StaffItem`](#mallstaffitem) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SetPassword` | `POST /rpc/mall/Staff/SetPassword` | [`mall.SetAccountRequest`](#mallsetaccountrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | + +### Staff.Login + +- 动态 HTTP：`POST /rpc/mall/Staff/Login` +- gRPC：`/mall.Staff/Login` +- 白名单键：`mall.Staff.Login` +- 请求示例： + +```json +{ + "account": "string", + "login_genre": 0, + "password": "string", + "phone": "string", + "verify_code": "string" +} +``` + +### Staff.Fetch + +- 动态 HTTP：`POST /rpc/mall/Staff/Fetch` +- gRPC：`/mall.Staff/Fetch` +- 白名单键：`mall.Staff.Fetch` +- 请求示例： + +```json +{ + "categoryId": [ + "0" + ], + "keyword": "string", + "max_price": "0", + "min_price": "0", + "page_no": "0", + "page_size": "0", + "params": { + "key": "string" + }, + "sort": "string", + "store_identity": "string" +} +``` + +### Staff.Create + +- 动态 HTTP：`POST /rpc/mall/Staff/Create` +- gRPC：`/mall.Staff/Create` +- 白名单键：`mall.Staff.Create` +- 请求示例： + +```json +{ + "account": "string", + "avatar": "string", + "created_at": "string", + "email": "string", + "id": "0", + "identity": "string", + "name": "string", + "password": "string", + "phone": "string", + "profile": "string", + "role": "string", + "status": 0 +} +``` + +### Staff.Delete + +- 动态 HTTP：`POST /rpc/mall/Staff/Delete` +- gRPC：`/mall.Staff/Delete` +- 白名单键：`mall.Staff.Delete` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Staff.GetProfile + +- 动态 HTTP：`POST /rpc/mall/Staff/GetProfile` +- gRPC：`/mall.Staff/GetProfile` +- 白名单键：`mall.Staff.GetProfile` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Staff.SetProfile + +- 动态 HTTP：`POST /rpc/mall/Staff/SetProfile` +- gRPC：`/mall.Staff/SetProfile` +- 白名单键：`mall.Staff.SetProfile` +- 请求示例： + +```json +{ + "account": "string", + "avatar": "string", + "created_at": "string", + "email": "string", + "id": "0", + "identity": "string", + "name": "string", + "password": "string", + "phone": "string", + "profile": "string", + "role": "string", + "status": 0 +} +``` + +### Staff.SetPassword + +- 动态 HTTP：`POST /rpc/mall/Staff/SetPassword` +- gRPC：`/mall.Staff/SetPassword` +- 白名单键：`mall.Staff.SetPassword` +- 请求示例： + +```json +{ + "account": "string", + "password": "string", + "password_confirmed": "string" +} +``` + +## Store + +| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 | +|---|---|---|---|---| +| `ApplyJoin` | `POST /rpc/mall/Store/ApplyJoin` | [`mall.ApplyJoinRequest`](#mallapplyjoinrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `Licensing` | `POST /rpc/mall/Store/Licensing` | [`mall.LicensingRequest`](#malllicensingrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `GetSetting` | `POST /rpc/mall/Store/GetSetting` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.StoreBasic`](#mallstorebasic) | Unary | +| `SetSetting` | `POST /rpc/mall/Store/SetSetting` | [`mall.StoreBasic`](#mallstorebasic) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SetPayment` | `POST /rpc/mall/Store/SetPayment` | [`mall.SettingRequest`](#mallsettingrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `SetEmail` | `POST /rpc/mall/Store/SetEmail` | [`mall.SettingRequest`](#mallsettingrequest) | [`ec_mall_blocks.IdentityStatusReply`](#ec_mall_blocksidentitystatusreply) | Unary | +| `GetPayment` | `POST /rpc/mall/Store/GetPayment` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.ConfigsReply`](#mallconfigsreply) | Unary | +| `GetEmail` | `POST /rpc/mall/Store/GetEmail` | [`ec_mall_blocks.IdentRequest`](#ec_mall_blocksidentrequest) | [`mall.ConfigsReply`](#mallconfigsreply) | Unary | +| `MiniCode` | `POST /rpc/mall/Store/MiniCode` | [`mall.MiniCodeRequest`](#mallminicoderequest) | [`mall.MiniCodeReply`](#mallminicodereply) | Unary | +| `Search` | `POST /rpc/mall/Store/Search` | [`mall.MallSearchRequest`](#mallmallsearchrequest) | [`mall.MallSearchReply`](#mallmallsearchreply) | Unary | + +### Store.ApplyJoin + +- 动态 HTTP：`POST /rpc/mall/Store/ApplyJoin` +- gRPC：`/mall.Store/ApplyJoin` +- 白名单键：`mall.Store.ApplyJoin` +- 请求示例： + +```json +{ + "account": "string", + "apply_remarks": "string", + "configs": "string", + "email": "string", + "intro": "string", + "logo": "string", + "name": "string", + "password": "string", + "phone": "string", + "subdomain": "string", + "template": "string", + "title": "string" +} +``` + +### Store.Licensing + +- 动态 HTTP：`POST /rpc/mall/Store/Licensing` +- gRPC：`/mall.Store/Licensing` +- 白名单键：`mall.Store.Licensing` +- 请求示例： + +```json +{ + "domain": "string", + "host": "string", + "ip": "string", + "license": "string", + "license_type": "string" +} +``` + +### Store.GetSetting + +- 动态 HTTP：`POST /rpc/mall/Store/GetSetting` +- gRPC：`/mall.Store/GetSetting` +- 白名单键：`mall.Store.GetSetting` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Store.SetSetting + +- 动态 HTTP：`POST /rpc/mall/Store/SetSetting` +- gRPC：`/mall.Store/SetSetting` +- 白名单键：`mall.Store.SetSetting` +- 请求示例： + +```json +{ + "approve": 0, + "configs": "string", + "created_at": "string", + "id": "0", + "identity": "string", + "intro": "string", + "keywords": "string", + "logo": "string", + "status": 0, + "subdomain": "string", + "template": "string", + "title": "string" +} +``` + +### Store.SetPayment + +- 动态 HTTP：`POST /rpc/mall/Store/SetPayment` +- gRPC：`/mall.Store/SetPayment` +- 白名单键：`mall.Store.SetPayment` +- 请求示例： + +```json +{ + "configs": "string", + "identity": "string" +} +``` + +### Store.SetEmail + +- 动态 HTTP：`POST /rpc/mall/Store/SetEmail` +- gRPC：`/mall.Store/SetEmail` +- 白名单键：`mall.Store.SetEmail` +- 请求示例： + +```json +{ + "configs": "string", + "identity": "string" +} +``` + +### Store.GetPayment + +- 动态 HTTP：`POST /rpc/mall/Store/GetPayment` +- gRPC：`/mall.Store/GetPayment` +- 白名单键：`mall.Store.GetPayment` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Store.GetEmail + +- 动态 HTTP：`POST /rpc/mall/Store/GetEmail` +- gRPC：`/mall.Store/GetEmail` +- 白名单键：`mall.Store.GetEmail` +- 请求示例： + +```json +{ + "id": "0", + "identity": "string" +} +``` + +### Store.MiniCode + +- 动态 HTTP：`POST /rpc/mall/Store/MiniCode` +- gRPC：`/mall.Store/MiniCode` +- 白名单键：`mall.Store.MiniCode` +- 请求示例： + +```json +{ + "types": "string" +} +``` + +### Store.Search + +- 动态 HTTP：`POST /rpc/mall/Store/Search` +- gRPC：`/mall.Store/Search` +- 白名单键：`mall.Store.Search` +- 请求示例： + +```json +{ + "keyword": "string", + "page_no": "0", + "page_size": "0" +} +``` + +## 消息结构 + +### ec_mall_blocks.IdentRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | + +### ec_mall_blocks.IdentityStatusReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `code` | `int32` | 可选 | +| `identity` | `string` | 可选 | +| `message` | `string` | 可选 | +| `timeseq` | `int64` | 可选 | + +### ec_mall_blocks.MallFetchRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `page_no` | `int64` | 可选 | +| `page_size` | `int64` | 可选 | +| `params` | `map` | 对象映射 | +| `store_identity` | `string` | 可选 | +| `keyword` | `string` | 可选 | +| `categoryId` | `[]int64` | 数组 | +| `sort` | `string` | 可选 | +| `min_price` | `int64` | 可选 | +| `max_price` | `int64` | 可选 | + +### ec_mall_blocks.MallFetchRequest.ParamsEntry + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `key` | `string` | 可选 | +| `value` | `string` | 可选 | + +### ec_mall_blocks.StoreSerialRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `store_identity` | `string` | 可选 | +| `serial_id` | `[]string` | 数组 | + +### mall.AdsItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `pos_key` | `string` | 可选 | +| `title` | `string` | 可选 | +| `content` | `string` | 可选 | +| `type` | `int32` | 可选 | +| `to_url` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `status` | `int64` | 可选 | + +### mall.AdsListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]mall.AdsItem` | 数组 | +| `count` | `int64` | 可选 | + +### mall.ApplyJoinRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `logo` | `string` | 可选 | +| `title` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `template` | `string` | 可选 | +| `configs` | `string` | 可选 | +| `subdomain` | `string` | 可选 | +| `apply_remarks` | `string` | 可选 | +| `name` | `string` | 可选 | +| `account` | `string` | 可选 | +| `phone` | `string` | 可选 | +| `email` | `string` | 可选 | +| `password` | `string` | 可选 | + +### mall.ByPosRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `pos_key` | `[]string` | 数组 | +| `store_identity` | `string` | 可选 | + +### mall.CategoriesItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `en_title` | `string` | 可选 | +| `parent_id` | `int64` | 可选 | +| `paths` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `icon` | `string` | 可选 | +| `sort` | `int32` | 可选 | +| `status` | `int32` | 可选 | +| `created_at` | `string` | 可选 | +| `categories` | `[]mall.CategoriesItem` | 数组 | +| `keys` | `string` | 可选 | + +### mall.CategoryFetchRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `types` | `string` | 可选 | +| `keywords` | `string` | 可选 | +| `id` | `int64` | 可选 | +| `store_identity` | `string` | 可选 | + +### mall.CategoryItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `en_title` | `string` | 可选 | +| `parent_id` | `int64` | 可选 | +| `paths` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `icon` | `string` | 可选 | +| `sort` | `int32` | 可选 | +| `status` | `int32` | 可选 | +| `created_at` | `string` | 可选 | +| `categories` | `[]mall.CategoryItem` | 数组 | +| `keys` | `string` | 可选 | + +### mall.CategoryReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.CategoryItem` | 数组 | + +### mall.CommentItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `nick_name` | `string` | 可选 | +| `score` | `int32` | 可选 | +| `comment` | `string` | 可选 | +| `reply` | `string` | 可选 | +| `product_identity` | `string` | 可选 | +| `store_identity` | `string` | 可选 | +| `spec_identity` | `string` | 可选 | +| `comment_identity` | `string` | 可选 | +| `product` | `string` | 可选 | +| `product_spec` | `string` | 可选 | +| `is_comment` | `bool` | 可选 | + +### mall.CommentItemRep + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `nick_name` | `string` | 可选 | +| `score` | `int32` | 可选 | +| `comment` | `string` | 可选 | +| `reply` | `string` | 可选 | +| `product_identity` | `string` | 可选 | +| `store_identity` | `string` | 可选 | +| `spec_identity` | `string` | 可选 | +| `comment_identity` | `string` | 可选 | +| `list` | `[]mall.CommentItem` | 数组 | +| `product` | `string` | 可选 | +| `product_spec` | `string` | 可选 | + +### mall.CommentListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.CommentItemRep` | 数组 | + +### mall.ConfigsReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `configs` | `string` | 可选 | + +### mall.DenyRegionItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `mall_identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `region` | `[]mall.RegionItem` | 数组 | + +### mall.DenyRegionReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.DenyRegionItem` | 数组 | + +### mall.DetailBySpecRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `spec_no` | `string` | 可选 | + +### mall.FreightAttrItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `freight_identity` | `string` | 可选 | +| `region_str` | `string` | 可选 | +| `region` | `[]mall.RegionItem` | 数组 | +| `price_basic` | `int64` | 可选 | +| `count_basic` | `int64` | 可选 | +| `count_extra` | `int64` | 可选 | +| `price_extra` | `int64` | 可选 | +| `status` | `int32` | 可选 | +| `is_default` | `int32` | 可选 | + +### mall.FreightItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `status` | `int32` | 可选 | +| `title` | `string` | 可选 | +| `post_type` | `int32` | 可选 | +| `quota` | `int64` | 可选 | +| `cost_type` | `int32` | 可选 | +| `region_type` | `int32` | 可选 | +| `rules` | `[]mall.FreightAttrItem` | 数组 | + +### mall.FreightReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.FreightItem` | 数组 | + +### mall.LicensingRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `license_type` | `string` | 可选 | +| `license` | `string` | 可选 | +| `domain` | `string` | 可选 | +| `host` | `string` | 可选 | +| `ip` | `string` | 可选 | + +### mall.ListItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `product_id` | `int64` | 可选 | +| `product` | `string` | 可选 | +| `spec_id` | `int64` | 可选 | +| `spec` | `string` | 可选 | +| `spec_no` | `string` | 可选 | +| `price` | `int64` | 可选 | +| `count` | `int64` | 可选 | +| `img` | `string` | 可选 | +| `product_identity` | `string` | 可选 | +| `serial_id` | `string` | 可选 | + +### mall.ListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.ProductItem` | 数组 | + +### mall.LoginReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `token` | `string` | 可选 | +| `identity` | `string` | 可选 | +| `store_identity` | `string` | 可选 | +| `name` | `string` | 可选 | +| `account` | `string` | 可选 | +| `role` | `string` | 可选 | +| `status` | `int32` | 可选 | +| `created_at` | `string` | 可选 | +| `store_name` | `string` | 可选 | + +### mall.LoginRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `account` | `string` | 可选 | +| `password` | `string` | 可选 | +| `phone` | `string` | 可选 | +| `verify_code` | `string` | 可选 | +| `login_genre` | `int32` | 可选 | + +### mall.MallSearchReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `list` | `[]mall.StoreBasic` | 数组 | +| `count` | `int64` | 可选 | + +### mall.MallSearchRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `page_no` | `int64` | 可选 | +| `page_size` | `int64` | 可选 | +| `keyword` | `string` | 可选 | + +### mall.MiniCodeReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `img` | `string` | 可选 | + +### mall.MiniCodeRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `types` | `string` | 可选 | + +### mall.ModifyRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `status` | `int32` | 可选 | + +### mall.NoticeItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `content` | `string` | 可选 | +| `author` | `string` | 可选 | +| `store_id` | `int64` | 可选 | +| `store_identity` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `status` | `int64` | 可选 | + +### mall.NoticeListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]mall.NoticeItem` | 数组 | +| `count` | `int64` | 可选 | + +### mall.OpRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `[]string` | 数组 | +| `status` | `int32` | 可选 | + +### mall.PhotoItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `name` | `string` | 可选 | +| `identity` | `string` | 可选 | +| `product_identity` | `string` | 可选 | +| `url` | `string` | 可选 | +| `sort` | `int32` | 可选 | +| `types` | `string` | 可选 | +| `id` | `int64` | 可选 | + +### mall.PhotoReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.PhotoItem` | 数组 | + +### mall.ProductItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `supply_id` | `int64` | 可选 | +| `category_id` | `[]int64` | 数组 | +| `title` | `string` | 可选 | +| `measuring_name` | `string` | 可选 | +| `sell_max` | `int64` | 可选 | +| `sell_min` | `int64` | 可选 | +| `wastage` | `int64` | 可选 | +| `standard_number` | `string` | 可选 | +| `brand` | `string` | 可选 | +| `stock_type` | `int64` | 可选 | +| `status` | `int32` | 可选 | +| `putaway_time` | `string` | 可选 | +| `cover_image` | `string` | 可选 | +| `content` | `string` | 可选 | +| `store_id` | `int64` | 可选 | +| `store_identity` | `string` | 可选 | +| `template_id` | `int32` | 可选 | +| `note` | `string` | 可选 | +| `images` | `[]mall.PhotoItem` | 数组 | +| `specification` | `[]mall.SpecItem` | 数组 | +| `recent_number` | `int64` | 可选 | +| `sale_total` | `int64` | 可选 | +| `created_at` | `string` | 可选 | +| `limitation` | `int64` | 可选 | +| `liTemplate_id` | `int64` | 可选 | +| `price` | `int64` | 可选 | +| `stock` | `int64` | 可选 | +| `category` | `string` | 可选 | +| `serial_id` | `string` | 可选 | +| `gas_types` | `int64` | 可选 | +| `spec_id` | `[]int64` | 数组 | +| `categories` | `[]mall.CategoriesItem` | 数组 | +| `supply_name` | `string` | 可选 | + +### mall.RegionItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int32` | 可选 | +| `name` | `string` | 可选 | +| `second` | `[]mall.RegionItem` | 数组 | + +### mall.SetAccountRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `account` | `string` | 可选 | +| `password` | `string` | 可选 | +| `password_confirmed` | `string` | 可选 | + +### mall.SettingRequest + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `identity` | `string` | 可选 | +| `configs` | `string` | 可选 | + +### mall.SpecItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `supply_id` | `int64` | 可选 | +| `product_identity` | `string` | 可选 | +| `store_identity` | `string` | 可选 | +| `title` | `string` | 可选 | +| `stock_type` | `int32` | 可选 | +| `stock` | `int64` | 可选 | +| `price` | `int64` | 可选 | +| `direct_sales` | `int64` | 可选 | +| `tp_type` | `int32` | 可选 | +| `ds_tp_type` | `int32` | 可选 | +| `img` | `string` | 可选 | +| `spec_no` | `string` | 可选 | +| `keyword` | `string` | 可选 | +| `purchasing_price` | `int64` | 可选 | +| `wholesale` | `int64` | 可选 | + +### mall.SpecReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `count` | `int64` | 可选 | +| `data` | `[]mall.SpecItem` | 数组 | + +### mall.StaffItem + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `name` | `string` | 可选 | +| `account` | `string` | 可选 | +| `password` | `string` | 可选 | +| `profile` | `string` | 可选 | +| `role` | `string` | 可选 | +| `phone` | `string` | 可选 | +| `email` | `string` | 可选 | +| `status` | `int32` | 可选 | +| `avatar` | `string` | 可选 | +| `created_at` | `string` | 可选 | + +### mall.StaffListReply + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `data` | `[]mall.StaffItem` | 数组 | +| `count` | `int64` | 可选 | + +### mall.StoreBasic + +| JSON 字段 | 类型 | 规则 | +|---|---|---| +| `id` | `int64` | 可选 | +| `identity` | `string` | 可选 | +| `logo` | `string` | 可选 | +| `title` | `string` | 可选 | +| `intro` | `string` | 可选 | +| `template` | `string` | 可选 | +| `configs` | `string` | 可选 | +| `subdomain` | `string` | 可选 | +| `created_at` | `string` | 可选 | +| `status` | `int32` | 可选 | +| `keywords` | `string` | 可选 | +| `approve` | `int32` | 可选 | diff --git a/wiki/api/10-market.md b/wiki/api/10-market.md new file mode 100644 index 0000000..6a8afda --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 对象映射 | +| `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` | 对象映射 | +| `reportStaff` | `map` | 对象映射 | + +### 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` | 数组 | diff --git a/wiki/api/11-order.md b/wiki/api/11-order.md new file mode 100644 index 0000000..ea6851c --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 可选 | diff --git a/wiki/api/12-wallet.md b/wiki/api/12-wallet.md new file mode 100644 index 0000000..0a87ea9 --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 对象映射 | +| `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` | 对象映射 | + +### 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` | 可选 | diff --git a/wiki/api/13-feed.md b/wiki/api/13-feed.md new file mode 100644 index 0000000..99efee6 --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 对象映射 | + +### 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` | 可选 | diff --git a/wiki/api/14-group.md b/wiki/api/14-group.md new file mode 100644 index 0000000..9e5e9e1 --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 可选 | diff --git a/wiki/api/15-relation.md b/wiki/api/15-relation.md new file mode 100644 index 0000000..3aab262 --- /dev/null +++ b/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 ` 传递凭证。 +- 动态 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` | 对象映射 | + +### 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` | 可选 | diff --git a/wiki/api/16-fts-rest.md b/wiki/api/16-fts-rest.md new file mode 100644 index 0000000..c19e1c9 --- /dev/null +++ b/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 +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":{}} +``` diff --git a/wiki/api/17-logs-rest.md b/wiki/api/17-logs-rest.md new file mode 100644 index 0000000..c41bb6a --- /dev/null +++ b/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` 配置，否则日志写入可能被拒绝。 + diff --git a/wiki/api/18-mgt-rest.md b/wiki/api/18-mgt-rest.md new file mode 100644 index 0000000..8a53910 --- /dev/null +++ b/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。 + diff --git a/wiki/architecture.md b/wiki/architecture.md index b966e82..29a8b93 100644 --- a/wiki/architecture.md +++ b/wiki/architecture.md @@ -23,11 +23,11 @@ 1. 校验 --workspace 并读取 etc/_.yaml。 2. 初始化共享 DB、Redis、etcd 和内存缓存。 -3. 创建统一 gRPC、grpc-gateway 和 Gin server。 +3. 创建独立端口的 gRPC server，以及承载 grpc-gateway、动态 RPC 和 Gin 的 HTTP server。 4. 按 Services 或 BSM_SERVICES 调用模块 Expose。 -5. 在一个 h2c 端口启动，并响应退出信号。 +5. 分别监听 `Server.GRPC` 和 `Server.HTTP` 配置的地址，并响应退出信号。 -请求先按 gRPC Content-Type 分流；普通请求先进入 grpc-gateway，gateway 返回 404 时回退到 Gin。 +HTTP 请求先进入 grpc-gateway；gateway 返回 404 时回退到 Gin。Gin 提供 `/rpc/{package}/{service}/{method}` 动态 JSON-to-protobuf unary 调用，以及 `/rest/{module}/...` 原生 REST 路由。动态调用通过本机 gRPC 端口进入完整 gRPC 处理链。 ## 依赖注入