从「项目库」
到「集群管理」
本阶段聚焦于集群功能的基础设施搭建：工作台侧边栏重构、集群 CRUD、项目形态双形态支持、服务详情页（无界面项目新形态）、分层架构图静态展示。
核心目标
用户能创建集群、把现有项目加入集群指定层、能创建不同形态的项目（page-based / service-only）、能看到分层架构图。能力编辑、依赖建模、共享实体等更高级功能留给 Phase 2-4。
工作台侧边栏新增"集群列表"，与"项目库"并列。用户能在两个库之间切换。
完整的集群生命周期：创建（含层定义）、编辑、删除、查询。
page-based 项目进入现有工作台，service-only 项目进入新的服务详情页。
静态展示集群的层结构和项目分布，跨层依赖线先预留（Phase 2 动态）。
无界面项目的新形态：服务描述、技术栈、API 契约、运行时配置。
1 个测试集群（4 层、6 项目），包含 2 个真实项目和 4 个 mock 服务项目。
明确边界：本阶段不做
为了避免 Phase 1 失控，以下功能明确推迟到后续阶段：
| 不做的事 | 原因 | 推迟到 |
|---|---|---|
| 能力编辑 UI | 依赖 apiContract 派生能力的设计验证 | Phase 2 |
| 依赖建模 | 需要先有"能力"概念作为依赖目标 | Phase 2 |
| 共享实体定义 | 需要先有项目归属基础 | Phase 3 |
| 能力版本管理 | v1.2 列为可选功能 | Phase 3（可选） |
| 集群模板 | 需要在有真实使用数据后设计 | Phase 4 |
| 自动依赖检测 | 现有 ref: 仅 3 处，数据基础不足 | Phase 5+ |
| 跨层依赖线（动态） | 需要先有依赖数据 | Phase 2 |
| 服务依赖图、部署拓扑图 | 需要先稳定服务详情页形态 | Phase 2 |
排期总览
22 个任务分 4 周完成，每周五天工作日，外加 2 天缓冲用于联调与意外处理。
基础设施
数据模型 · 集群 CRUD · 侧边栏重构
集群工作台
多 Tab 框架 · 分层架构图 · 服务详情页
服务形态 + 测试
运行时配置 · 新建对话框 · 测试数据
联调 & 打磨
端到端测试 · UI 打磨 · 文档
任务甘特图
并行关系
| 并行组 | Day | 任务 | 依赖 |
|---|---|---|---|
| 串行 | 1-2 | 1.1 schema 扩展 → 1.2 Project 扩展 | 无外部依赖 |
| 串行 | 2-3 | 2.1 → 2.2 cluster CRUD | 依赖 1.2 |
| 并行 A | 3 | 3.1-3.2 项目归属 RPC | 依赖 2.1 |
| 并行 B | 4-5 | 4.1-4.4 侧边栏重构 | 依赖 2.2 |
| 并行 C | 6-7 | 5.1-5.2 集群工作台框架 | 依赖 4.x |
| 并行 D | 8-10 | 6.x 分层架构图 + 7.x 服务详情页 | 依赖 5.x |
| 并行 E | 11-14 | 8.x 服务运行时 + 9.x 新建对话框 | 依赖 7.x |
| 串行 | 15 | 10.1-10.3 测试数据 | 依赖 8.x, 9.x |
| 串行 | 16-20 | 11-13 联调/打磨/文档 | 依赖 10.x |
线框图（8 张）
以下线框图展示 Phase 1 关键页面的 UI 设计。
1️⃣ 新建项目对话框（类型选择）
用户点击"新建项目"后的第一个对话框，选择项目类型（单一项目 / 项目集群）。
选择项目类型。集群适合管理多个关联项目的复杂架构（如企业级业务平台）。
单一项目创建流程不变；项目集群进入下一步的"集群配置向导"。双类型用并排卡片选择，比下拉框更直观。
2️⃣ 集群创建向导（层结构）
用户选择"项目集群"后进入的向导，定义层数和每层名称。
层数动态调整（+ / - 按钮）。每层有预设的默认名称和描述，用户可修改。Phase 4 会增加"从模板创建"选项。
3️⃣ 集群列表页
工作台侧边栏切换到"集群列表"后的页面，显示所有集群卡片。
卡片网格布局，每张卡片显示：名称、统计、缩略分层图、最后更新时间。测试数据用 `__test_` 前缀 + ⚠️ 标识。
4️⃣ 集群工作台（总览 Tab）
点击集群卡片进入的工作台，显示统计和分层摘要。
顶部 4 个统计数字。分层摘要用行列表，每层一个 row，项目按形态区分颜色。点击项目跳转到对应项目工作台（page-based → 现有 / service-only → 服务详情页）。
5️⃣ 分层架构图（静态）
集群工作台的"分层架构"Tab，按层展示项目分布（双形态）。
每个项目卡片用不同颜色区分形态：🟦 蓝色 = page-based（有界面），🟧 橙色 = service-only（无界面）。跨层依赖线在 Phase 1 用占位符，Phase 2 接入实际依赖数据。
6️⃣ 服务详情页（service-only 项目）
无界面项目的新工作台形态。
顶部服务标识用 ⚙️ 区分于有界面项目的 🖥️。能力/API 契约/运行时 Tab 是服务详情页的核心。Phase 1 实现总览 + API 契约（从现有数据读取），其他 Tab 留空待 Phase 2-3 填充。
7️⃣ 服务运行时配置（编辑）
用户编辑 service-only 项目的运行时信息。
运行时配置类似 K8s 部署清单：类型、技术栈、端口、健康检查、镜像、副本、资源。所有字段都可选，用户可填写任意子集。
8️⃣ 项目迁移到集群的确认弹窗
把现有项目加入集群时的二次确认，防止误操作。
项目加入集群后将发生变化，请确认：
- 项目将在工作台"项目库"中显示为"🔗 已加入集群"
- 项目仍可独立编辑，原工作台功能不受影响
- 集群工作台"总览/分层架构"中可看到该项目
- 可随时"从集群移除"恢复为独立项目
必须让用户在弹窗中确认两件事：① 选择项目形态（page-based / service-only）② 选择目标层。明确告知"加入后的变化"，降低误操作。
任务清单（22 项）
📅 Week 1 · 基础设施（Day 1-5）
| # | 任务 | Day | 工作 | 依赖 | 状态 |
|---|---|---|---|---|---|
| 1.1 | schema 扩展（新增 type 字段支持） | Day 1 上 | 0.5 天 | 无 | 就绪 |
| 1.2 | Project 字段扩展（clusterId/layerId/projectType） | Day 1 下 | 0.5 天 | 1.1 | 就绪 |
| 2.1 | proto_cluster_create RPC | Day 2 上 | 0.5 天 | 1.2 | 就绪 |
| 2.2 | cluster CRUD RPCs（update/delete/get/list） | Day 2 下 - Day 3 上 | 1 天 | 2.1 | 就绪 |
| 3.1 | proto_project_set_type RPC | Day 3 下 | 0.5 天 | 1.2 | 就绪 |
| 3.2 | proto_project_set_cluster / remove_cluster RPCs | Day 3 下 | 1 天 | 2.1 | 就绪 |
| 4.1 | 侧边栏"集群列表"入口 | Day 4 上 | 0.5 天 | 2.2 | 就绪 |
| 4.2 | 集群列表页 UI（网格 + 卡片） | Day 4 下 | 1 天 | 2.2 | 就绪 |
| 4.3 | 集群卡片显示分层缩略图 | Day 5 上 | 0.5 天 | 4.2 | 就绪 |
| 4.4 | "返回项目库"导航 | Day 5 下 | 0.5 天 | 4.1 | 就绪 |
📅 Week 2 · 集群工作台（Day 6-10）
| # | 任务 | Day | 工作 | 依赖 | 状态 |
|---|---|---|---|---|---|
| 5.1 | 集群工作台多 Tab 框架 | Day 6 | 1 天 | 4.2 | 就绪 |
| 5.2 | "总览" Tab（统计 + 分层摘要） | Day 7 | 1 天 | 5.1 | 就绪 |
| 6.1 | 分层架构图基础渲染 | Day 8 | 1 天 | 5.2 | 就绪 |
| 6.2 | 项目卡片双形态样式 | Day 9 上 | 0.5 天 | 6.1 | 就绪 |
| 6.3 | 跨层依赖线（静态） | Day 9 下 | 0.5 天 | 6.1 | 就绪 |
| 7.1 | 服务详情页主框架 | Day 10 上 | 0.5 天 | 5.1 | 就绪 |
| 7.2 | 总览 Tab（服务描述 + 技术栈 + 健康度） | Day 10 中 | 0.5 天 | 7.1 | 就绪 |
| 7.3 | API 契约 Tab（从 apiContract 读取） | Day 10 下 | 0.5 天 | 7.1 | 就绪 |
📅 Week 3 · 服务形态 + 测试数据（Day 11-15）
| # | 任务 | Day | 工作 | 依赖 | 状态 |
|---|---|---|---|---|---|
| 8.1 | proto_service_update_runtime RPC | Day 11 上 | 0.5 天 | 1.2 | 就绪 |
| 8.2 | proto_service_update_api_contract RPC | Day 11 下 | 0.5 天 | 1.2 | 就绪 |
| 8.3 | 服务运行时 Tab UI（编辑表单） | Day 12 | 1 天 | 8.1 | 就绪 |
| 9.1 | 新建项目对话框：类型选择 | Day 13 上 | 0.5 天 | 2.1 | 就绪 |
| 9.2 | "单一项目"流程：保持现有 | Day 13 中 | 0.5 天 | 9.1 | 就绪 |
| 9.3 | "项目集群"流程：层数 + 命名 | Day 14 | 1 天 | 9.1 | 就绪 |
| 10.1 | 创建测试集群（含 4 层） | Day 15 上 | 0.5 天 | 全部 | 就绪 |
| 10.2 | 添加旅行票根到 L4（page-based） | Day 15 中 | 0.5 天 | 10.1 | 就绪 |
| 10.3 | 创建 2-3 个 service-only 项目（mock） | Day 15 下 | 0.5 天 | 10.2 | 就绪 |
📅 Week 4 · 联调 & 打磨（Day 16-20）
| # | 任务 | Day | 工作 | 依赖 | 状态 |
|---|---|---|---|---|---|
| 11.1 | 端到端测试 | Day 16 | 1 天 | 10.3 | 就绪 |
| 11.2 | 修复发现的问题 | Day 17 | 1 天 | 11.1 | 就绪 |
| 12.1 | 视觉一致性 | Day 18 上 | 0.5 天 | 11.2 | 就绪 |
| 12.2 | 交互动画 | Day 18 下 | 0.5 天 | 11.2 | 就绪 |
| 12.3 | 响应式适配 | Day 19 | 1 天 | 11.2 | 就绪 |
| 13.1 | 用户文档 | Day 20 上 | 0.5 天 | 12.3 | 就绪 |
| 13.2 | 内部演示录制 | Day 20 下 | 0.5 天 | 13.1 | 就绪 |
完成标准（Definition of Done）
| # | 验收项 | 验证方式 |
|---|---|---|
| 1 | 工作台侧边栏有两个 Tab：📁 项目库、🏢 集群列表 | UI 检查 |
| 2 | 能创建集群并定义层结构（自定义层数 + 每层名称） | 创建测试集群 A，4 层 |
| 3 | 能把现有项目（旅行票根）加入集群指定层 | 添加到 L4 |
| 4 | 能创建新项目时选择加入现有集群 | 新建项目 → 加入 L3 |
| 5 | page-based 项目进入现有工作台（无变化） | 点击旅行票根 |
| 6 | service-only 项目进入新的服务详情页 | 点击"用户中心服务" |
| 7 | 集群工作台多 Tab 框架正常 | UI 检查 |
| 8 | 分层架构图渲染正确（4 层 + 项目卡片） | UI 检查 |
| 9 | 项目卡片区分 page-based（🖥️ 蓝）vs service-only（⚙️ 橙） | UI 检查 |
| 10 | 服务详情页 API 契约 Tab 能显示现有 endpoints | 旅行票根 20 个 endpoints |
| 11 | 至少 1 个测试集群数据（4 层、6 项目）可演示 | __test_ 测试集群 |
| 12 | 用户文档完成 | docs/cluster-user-guide.md |
| 13 | 无 P0/P1 Bug 残留 | 端到端测试 |
| 14 | 所有 RPC 测试通过 | 单元测试 |
风险与缓解
| 风险 | 概率 | 影响 | 缓解措施 |
|---|---|---|---|
| 现有项目加入集群后丢失"项目库"中的位置 | 中 | 中 | 项目库中显示"🔗 已加入集群 XXX"，点击跳转 |
| service-only 形态不直观 | 中 | 中 | 服务详情页用技术栈 + 健康度视觉表达 |
| 分层架构图无依赖数据时显得空 | 高 | 低 | 显示"暂未建立依赖"提示，引导 Phase 2 |
| 测试数据被误删 | 低 | 中 | 测试集群用 `__test_` 前缀 |
| proto_load 性能下降（项目数增加） | 低 | 中 | 集群元数据轻量化，按需读取 |