registry/docs/设计.md

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

1. 系统架构

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)

{
  "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)

{
  "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 持久化接口（预留扩展）

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