# Registry 模块设计文档

## 概述

kit 的 registry 模块用于对接 Registry 配置管理中心（`D:\workbench\registry`），提供命令行方式管理微服务配置。

Registry 是一个基于 REST API 的配置管理系统，支持项目隔离、三维配置（机房/环境/分组）、规划/编辑/只读三种模式。

## 对接方式

kit 通过 HTTP 请求调用 Registry REST API，使用 Node 内置 `http`/`https` 模块，不引入新依赖。

## 配置存储

registry 的连接信息复用 kit 已有的 `kit config` 机制：

```shell
kit config registryUrl http://bh.vps.honor3.com:8008
kit config registryToken abc123
```

## 命令设计

### 配置管理

复用 `kit config`，无需新增命令。

### 项目与配置操作

| 命令 | 说明 | 示例 |
|------|------|------|
| `kit registry list` | 列出所有项目（含详情） | `kit registry list` |
| `kit registry config <project>[:path]` | 查看/设置配置项 | 见下方 |

#### `kit registry list`

列出 Registry 上所有项目，输出项目名称、ID、维度启用状态、配置数量。

```shell
$ kit registry list

ID                    名称                      维度
proj-abc-123          CommonExternalService     IDC=✓ Env=✓ Group=✓
proj-def-456          OrderService              IDC=✗ Env=✓ Group=✓

共 2 个项目
```

#### `kit registry config <project>[:path]`

三种用法：

**1. 查看配置列表**（不指定 key）

```shell
# 查看整个项目
kit registry config CommonExternalService

# 查看路径下的配置
kit registry config CommonExternalService:data/windows
```

输出：

```
路径                              值                          类型
CF_API_TOKEN                      ****                        string
CF_R2_BUCKET                      store                       string
CF_R2_PUBLIC_URL                  https://pub-xxx.r2.dev      string
```

**2. 获取单个值**（指定 key）

```shell
kit registry config CommonExternalService:CF_R2_BUCKET
# 输出: store
```

**3. 设置值**（指定 key + value）

```shell
kit registry config CommonExternalService:CF_R2_BUCKET my-new-bucket
```

### 导入导出

| 命令 | 说明 | 示例 |
|------|------|------|
| `kit registry export <project>[:path] [file]` | 导出为 JSON | `kit registry export CommonExternalService:data ./backup.json` |
| `kit registry import <project>[:path] <file>` | 从 JSON 导入 | `kit registry import CommonExternalService:data ./backup.json` |

#### `project:path` 语法

`project:path` 中的 `path` 对应 Registry 中配置的路径前缀（由维度映射 + key 构成）。

| 语法 | 含义 |
|------|------|
| `proj` | 整个项目的所有配置 |
| `proj:data` | 路径以 `data` 开头的配置 |
| `proj:data/windows` | 路径以 `data/windows` 开头的配置 |
| `proj:data/windows/kit.exe` | 精确匹配单个配置 |

#### export 示例

```shell
# 导出整个项目
kit registry export CommonExternalService ./backup.json

# 仅导出 data/windows 下的配置
kit registry export CommonExternalService:data/windows ./backup-windows.json
```

导出文件格式：

```json
{
  "project": "CommonExternalService",
  "path": "data/windows",
  "exportedAt": "2026-09-11T02:00:00Z",
  "configs": [
    {
      "key": "kit.exe",
      "value": "...",
      "type": "string",
      "description": "Windows 二进制下载地址",
      "idc": "",
      "environment": "",
      "group": ""
    }
  ]
}
```

#### import 示例

```shell
# 从备份文件导入整个项目
kit registry import CommonExternalService ./backup.json

# 将备份导入到指定路径下
kit registry import CommonExternalService:data/windows ./backup-windows.json
```

import 行为：
- 已存在的 key（按路径匹配）→ 更新 value
- 不存在的 key → 新增
- 远程有但本地没有的 → 保留不动（不删除）

## API 映射

| kit 命令 | Registry API |
|----------|-------------|
| `kit registry list` | `GET /api/projects` |
| `kit registry config <project>` | `GET /api/projects/:id/configs` |
| `kit registry config <project>:<key>` | `GET /api/projects/:id/configs` → 按 path 匹配 |
| `kit registry config <project>:<key> <value>` | `GET` → 匹配后 `PUT` 或 `POST` |
| `kit registry export` | `GET /api/projects/:id/configs` → 写文件 |
| `kit registry import` | 读文件 → 逐项 `PUT`/`POST` |

## 文件结构

```
kit/src/registry/
├── index.js          # 命令注册入口
├── client.js         # HTTP 客户端（调用 Registry API）
└── sync.js           # export/import 逻辑
```

## 错误处理

- 未配置 `registryUrl` → 提示 `请先运行 kit config registryUrl <url>`
- 连接失败 → 输出 `Registry 不可达: <url>`
- 认证失败 → 输出 `认证失败，请检查 registryToken`
- 项目不存在 → 输出 `项目不存在: <name>`
- 只读模式下写入 → 输出 `Registry 当前为只读模式`