feat: 维度映射/嵌套配置/地址栏导航/界面分区重构

2026-07-16 09:01:47 +08:00
commit 5bff1a186f
19 changed files with 4186 additions and 0 deletions
@@ -0,0 +1,215 @@
+# 概要设计文档：微服务配置管理中心 (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
+```
@@ -0,0 +1,74 @@
+# 需求文档：微服务配置管理中心 (Registry)
+
+## 1. 项目背景
+
+在微服务架构中，配置管理是核心基础设施之一。不同项目、不同环境、不同机房的配置散落在各处，缺乏统一的管理界面和规范。本系统旨在提供一个类 Windows 注册表风格的 Web 管理界面，实现配置的集中化、可视化、规范化管理。
+
+## 2. 功能需求
+
+### 2.1 项目管理
+
+- **FR-1-1**：支持创建项目，项目创建时需指定项目名称、描述、以及是否启用机房/环境/分组维度
+- **FR-1-2**：项目创建后，维度开关（机房/环境/分组）不可修改，只能通过项目转换机制处理
+- **FR-1-3**：支持查看项目列表、项目详情
+- **FR-1-4**：支持删除项目（级联删除所有关联配置）
+
+### 2.2 配置维度
+
+- **FR-2-1**：机房维度——用于隔离不同物理/云区域（如华北机房、华南机房）
+- **FR-2-2**：环境维度——用于隔离不同运行阶段（如开发、测试、生产）
+- **FR-2-3**：分组维度——用于项目内业务分组（如用户模块、订单模块）
+- **FR-2-4**：维度启用后可在维度栏直接展示与筛选，不直接硬编码进配置路径
+- **FR-2-5**：每个维度可配置映射方式——`path`（作为配置存储路径前缀）或 `label`（仅作筛选标签，不进入路径），默认 `path`
+- **FR-2-6**：映射方式创建后可通过映射配置入口调整（维度启用开关仍不可改）
+
+### 2.3 配置项管理
+
+- **FR-3-1**：配置以路径形式组织，类似注册表键值结构；路径 = 映射为 path 的维度前缀 + 嵌套键
+- **FR-3-6**：配置键支持嵌套，以 `/` 分割；json 类型在展示时自动按 `.` 分割
+- **FR-3-7**：提供配置导航地址栏，显示当前路径，可拷贝、可粘贴后回车跳转到对应目录（类似 Windows 注册表地址栏）
+- **FR-3-2**：每个配置项支持类型指定：string、number、boolean、json
+- **FR-3-3**：每个配置项必须有说明（description），用于文档化配置用途
+- **FR-3-4**：支持配置项的新增、修改、删除
+- **FR-3-5**：配置值根据类型进行格式校验
+
+### 2.4 三种工作模式
+
+- **FR-4-1**：规划模式——定义配置结构，包括字段名、类型、用途、值范围约束，类似"配置 Schema 设计"
+- **FR-4-2**：编辑模式——在规划好的结构基础上填写实际配置值
+- **FR-4-3**：只读模式——仅可查看配置，不可修改，用于日常查阅和审计
+
+### 2.5 持久化方案
+
+- **FR-5-1**：支持 JSON 文件持久化（当前版本实现）
+- **FR-5-2**：预留扩展接口，后续支持 XML、YAML、SQLite、MySQL、Nacos
+- **FR-5-3**：配置文件支持导出下载
+- **FR-5-4**：配置文件支持导入合并
+
+### 2.6 界面要求
+
+- **FR-6-1**：左侧树形导航，按“path 维度前缀 + 嵌套键”逐级展开，视觉风格参考 Windows 注册表编辑器
+- **FR-6-2**：右侧详情面板，顶部为配置导航地址栏，下方展示选中节点的配置项列表
+- **FR-6-3**：每个配置项展示：键名、值、类型、说明
+- **FR-6-4**：标题栏（应用名+当前项目）与工具栏分离；工具栏按项目/模式/配置/数据分组
+- **FR-6-5**：维度栏独立展示已启用维度的筛选器与映射方式，并提供映射配置入口
+
+## 3. 非功能需求
+
+- **NFR-1**：技术栈：Node.js + Express 后端，原生 HTML/CSS/JS 前端
+- **NFR-2**：后续对接 SSO 单点登录，当前版本暂不实现认证
+- **NFR-3**：界面响应式，支持主流浏览器
+- **NFR-4**：配置数据实时写入持久化存储，保证数据一致性
+
+## 4. 术语定义
+
+| 术语 | 说明 |
+|------|------|
+| 项目 (Project) | 配置管理的顶层隔离单元，对应一个微服务或应用 |
+| 机房 (IDC) | 物理或云区域标识，如华北、华南、华东 |
+| 环境 (Environment) | 运行阶段标识，如 dev、test、prod |
+| 分组 (Group) | 业务模块分组，如 user、order、payment |
+| 配置路径 (Path) | 注册表风格的层级路径，如 `project/idc/env/group/key` |
+| 规划模式 | Schema 设计模式，定义配置结构 |
+| 编辑模式 | 配置值填写模式 |
+| 只读模式 | 查看模式，禁止修改 |