full/wiki/api/05-initial.md

# 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 <token>` 传递凭证。
- 动态 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` | 可选 |