# 概要设计文档：微服务配置管理中心 (Registry)

## 1. 系统架构

```mermaid
flowchart TD
    A[浏览器 Browser] --> B[Express Web Server]
    B --> C[路由层 Router]
    C --> D[项目模块 Project Service]
    C --> E[配置模块 Config Service]
    D --> F[JSON 持久化层 Persistence]
    E --> F
    F --> G[(JSON 文件存储)]
```

## 2. 技术选型

| 层级 | 技术 | 说明 |
|------|------|------|
| 后端框架 | Express 4.x | 轻量级 HTTP 服务 |
| 前端 | 原生 HTML/CSS/JS | 无框架依赖，降低复杂度 |
| 持久化 | JSON 文件 | 当前实现，简单可靠 |
| 模板引擎 | EJS | 服务端渲染基础页面 |
| 图标 | 内联 SVG | 不依赖第三方图标库 |

## 3. 数据模型

### 3.1 项目 (Project)

```json
{
  "id": "proj-001",
  "name": "用户服务",
  "description": "用户微服务配置",
  "enableIdc": true,
  "enableEnvironment": true,
  "enableGroup": true,
  "idcMapping": "path",
  "environmentMapping": "path",
  "groupMapping": "label",
  "createdAt": "2026-07-15T10:00:00Z",
  "updatedAt": "2026-07-15T10:00:00Z"
}
```

字段说明：
- `enableXxx`：维度是否启用，创建后不可修改。
- `xxxMapping`：维度映射方式，`path` 表示作为配置存储路径前缀，`label` 表示仅作筛选标签、不进入路径。创建后可通过映射配置接口调整。

### 3.2 配置项 (ConfigItem)

```json
{
  "id": "cfg-001",
  "projectId": "proj-001",
  "path": "华北/dev/用户模块/db.host",
  "key": "db.host",
  "value": "192.168.1.100",
  "type": "string",
  "description": "数据库主机地址",
  "purpose": "指定 MySQL 数据库连接地址",
  "valueRange": "合法 IPv4 地址",
  "createdAt": "2026-07-15T10:00:00Z",
  "updatedAt": "2026-07-15T10:00:00Z"
}
```

### 3.3 配置路径构建规则

配置路径由“维度映射方式”与“嵌套键”共同决定：

```
路径模板 = [映射为 path 的维度前缀...]/嵌套键

- 维度启用且映射为 path  → 该维度值作为路径前缀
- 维度启用且映射为 label → 该维度不进入路径，仅作维度栏筛选
- 维度未启用             → 跳过
- 配置键 key 自身可用 / 嵌套多级（json 类型在展示时按 . 分割）
```

示例（机房=path、环境=path、分组=label）：
- 配置键 `db/host`，机房 `华北`，环境 `dev`，分组 `用户模块`
- 生成路径：`华北/dev/db/host`（分组作为标签筛选，不进入路径）

示例（全部映射为 path）：
- 配置键 `db.host` → 路径 `华北/dev/用户模块/db.host`

## 4. API 设计

### 4.1 项目接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/projects` | 获取项目列表 |
| GET | `/api/projects/:id` | 获取项目详情 |
| POST | `/api/projects` | 创建项目（含维度开关与映射方式） |
| PUT | `/api/projects/:id/mappings` | 更新维度映射方式（path/label） |
| DELETE | `/api/projects/:id` | 删除项目 |

### 4.2 配置接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/projects/:id/configs` | 获取项目下所有配置 |
| GET | `/api/projects/:id/configs/:configId` | 获取单个配置详情 |
| POST | `/api/projects/:id/configs` | 新增配置项 |
| PUT | `/api/projects/:id/configs/:configId` | 修改配置项 |
| DELETE | `/api/projects/:id/configs/:configId` | 删除配置项 |

### 4.3 模式接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/mode` | 获取当前模式 |
| PUT | `/api/mode` | 切换模式（plan/edit/readonly） |

## 5. 前端界面设计

### 5.1 布局结构

```
+--------------------------------------------------+
|  标题栏：应用名 | 当前项目名                      |
+--------------------------------------------------+
|  工具栏（分组）：项目 | 模式 | 配置 | 数据        |
+--------------------------------------------------+
|  维度栏：机房▼ | 环境▼ | 分组▼ | ⚙映射配置       |
+------------+-------------------------------------+
|  树形导航  |  地址栏：📍 路径 [转到][拷贝]        |
|  (左侧)    |  +-------------------------------+  |
|  📦 项目A  |  | 键名 | 值 | 类型 | 说明      |  |
|   📁 华北  |  |------+----+------+----------|  |
|    📁 dev  |  | db/host|192.|string|数据库.. |  |
|     📁 db  |  | db/port|3306|number|数据库.. |  |
|      🔑host|  +-------------------------------+  |
+------------+-------------------------------------+
|  状态栏                                            |
+--------------------------------------------------+
```

界面分区说明：
- 标题栏：仅展示应用名与当前项目名，与操作区分离。
- 工具栏：按“项目 / 模式 / 配置 / 数据”分组排列操作按钮。
- 维度栏：展示已启用维度的筛选下拉与映射方式标记，提供映射配置入口。
- 地址栏：注册表风格路径框，支持拷贝、粘贴后回车跳转到对应节点。
- 树形导航：按“path 维度前缀 + 嵌套键”逐级展开，叶子节点（🔑）为真实配置项。

### 5.2 三种模式差异化

| 功能 | 规划模式 | 编辑模式 | 只读模式 |
|------|---------|---------|---------|
| 查看配置 | ✓ | ✓ | ✓ |
| 新增/删除配置 | ✓ | ✓ | ✗ |
| 修改值 | ✗ | ✓ | ✗ |
| 修改类型/说明/用途/范围 | ✓ | ✗ | ✗ |
| 配置值校验 | 仅格式 | 格式+范围 | 不校验 |

## 6. 持久化层设计

### 6.1 存储结构

```
data/
├── projects.json          # 项目元数据
├── configs/
│   └── {projectId}.json   # 每个项目独立配置文件
└── system.json            # 系统级配置（当前模式等）
```

### 6.2 持久化接口（预留扩展）

```javascript
class PersistenceAdapter {
  async loadProjects() {}
  async saveProjects(projects) {}
  async loadConfigs(projectId) {}
  async saveConfigs(projectId, configs) {}
  async loadSystem() {}
  async saveSystem(system) {}
}
```

当前实现 `JsonFileAdapter`，后续可扩展 `SqliteAdapter`、`NacosAdapter` 等。

## 7. 目录结构

```
registry/
├── docs/
│   ├── requirements.md     # 需求文档
│   └── design.md           # 概要设计文档
├── data/                   # 持久化数据目录
├── src/
│   ├── server.js           # 服务入口
│   ├── routes/
│   │   ├── projects.js     # 项目路由
│   │   └── configs.js      # 配置路由
│   ├── services/
│   │   ├── projectService.js
│   │   └── configService.js
│   ├── persistence/
│   │   └── jsonAdapter.js  # JSON 持久化适配器
│   └── utils/
│       └── validator.js    # 配置值校验
├── public/
│   ├── index.html          # 主页面
│   ├── css/
│   │   └── style.css       # 样式
│   └── js/
│       ├── app.js          # 主逻辑
│       ├── tree.js         # 树形组件
│       └── api.js          # API 调用封装
├── package.json
└── README.md
```