376 lines
8.8 KiB
Markdown
376 lines
8.8 KiB
Markdown
# 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: <JWT>` 传递裸 JWT，不添加 `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`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"keyword": "string"
|
||
}
|
||
```
|
||
|
||
### Basic.Fetch
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Basic/Fetch`
|
||
- gRPC：`/group.Basic/Fetch`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
### Basic.Get
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Basic/Get`
|
||
- gRPC：`/group.Basic/Get`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"id": "0",
|
||
"identity": "string"
|
||
}
|
||
```
|
||
|
||
### Basic.Create
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Basic/Create`
|
||
- gRPC：`/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`
|
||
- 请求示例：
|
||
|
||
```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`
|
||
- 请求示例：
|
||
|
||
```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`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"id": "0",
|
||
"identity": "string"
|
||
}
|
||
```
|
||
|
||
### Member.DoJoin
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Member/DoJoin`
|
||
- gRPC：`/group.Member/DoJoin`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"id": "0",
|
||
"identity": "string",
|
||
"message": "string"
|
||
}
|
||
```
|
||
|
||
### Member.JoinFetch
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Member/JoinFetch`
|
||
- gRPC：`/group.Member/JoinFetch`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
### Member.JoinDoHandle
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Member/JoinDoHandle`
|
||
- gRPC：`/group.Member/JoinDoHandle`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"direction": "string",
|
||
"groupIdentity": "string",
|
||
"identity": "string"
|
||
}
|
||
```
|
||
|
||
### Member.DoSetManager
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Member/DoSetManager`
|
||
- gRPC：`/group.Member/DoSetManager`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"direction": "string",
|
||
"groupIdentity": "string",
|
||
"identity": "string"
|
||
}
|
||
```
|
||
|
||
### Member.DoKick
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Member/DoKick`
|
||
- gRPC：`/group.Member/DoKick`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"direction": "string",
|
||
"groupIdentity": "string",
|
||
"identity": "string"
|
||
}
|
||
```
|
||
|
||
### Member.DoQuit
|
||
|
||
- 动态 HTTP：`POST /rpc/group/Member/DoQuit`
|
||
- gRPC：`/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` | 可选 |
|