full/wiki/api/14-group.md

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