📅 Phase 3 · 共享实体 & 高级能力

让数据共享可见、变更可控

Phase 2 建立了能力依赖网络，Phase 3 让共享数据实体化——定义集群级共享实体、建立项目引用关系、实现 L3 级联影响分析、支持能力版本多版本共存。

📅 Phase 3 开始 ⏱️ 4 周（24 工作日） 📋 24 个任务 🎯 7 张线框图

核心目标

💡 Phase 3 的核心交付

集群级共享实体定义、项目数据模型引用共享实体、L3 级联影响分析（实体→项目→能力→上游）、能力版本多版本共存（创建/发布/弃用/回滚/对比）、集群级文档导出。

📦 共享实体

集群级统一数据模型，不属于任何单一项目。项目通过引用声明使用关系。

🔗 影响分析

L3 级联：修改实体字段 → 影响哪些项目 → 影响哪些能力 → 影响哪些上游系统。

🔄 版本管理

能力多版本共存，消费者绑定到特定版本，支持回滚和版本对比。

明确边界：本阶段不做

⚠️ 范围控制

不做的事	原因	推迟到
自动依赖检测	数据基础不具备	Phase 4+
集群模板	需要真实使用数据	Phase 4
一键部署	超出原型阶段	远期
跨集群关系	单集群尚未稳定	Phase 5+

共享实体

数据模型

共享实体是集群级别的统一数据模型，不属于任何单一项目。与现有项目的实体无关——项目通过 sharedEntityRefs 声明"我引用了这个共享实体"。

{
  id: 'shared-user',
  name: 'User',
  label: '用户',
  description: '集群内统一用户模型',
  clusterId: 'cluster-xxx',
  fields: [
    {name: 'id', type: 'id', required: true, label: '主键'},
    {name: 'name', type: 'string', required: true, label: '姓名'},
    {name: 'email', type: 'string', required: false, label: '邮箱'},
    {name: 'createdAt', type: 'datetime', required: true}
  ],
  relations: [
    {fromEntity: 'User', toEntity: 'Order', type: '1:N', label: '拥有订单'}
  ]
}

项目引用关系

📐 版本管理策略

与能力不同，共享实体不支持版本管理。修改共享实体字段时，通过影响分析（L3 级联）通知所有引用项目，由项目团队决定何时升级。如需"灰度"修改，可通过新增字段（而非修改现有字段）实现向后兼容。

项目通过 sharedEntityRefs 字段声明引用了哪些共享实体：

// 项目数据模型中引用共享实体
{
  dataModel: {
    entities: [
      {name: 'OrderItem', fields: [...]},        // 私有实体
      {name: 'Shipping', fields: [...]},         // 私有实体
      {name: 'User', ref: 'cluster:User', fields: []}  // 引用共享实体
    ],
    sharedEntityRefs: ['User', 'Product']  // 引用的共享实体列表
  }
}

影响分析（L3 级联）

修改共享实体字段时，级联分析影响范围：

// L3 级联影响链
修改 User.email 字段（类型: string → string | null）
  │
  ├─→ L1: 直接影响
  │   └─→ 订单系统（引用 User 实体）
  │
  ├─→ L2: 能力影响
  │   └─→ 用户认证能力（依赖订单系统的 User 数据）
  │
  └─→ L3: 上游影响
      └─→ 客服系统（消费用户认证能力）
      └─→ 营销系统（消费用户认证能力）

影响分析可视化

以树形结构展示影响链，支持展开/折叠每一级。每个节点显示影响等级（🔴高/🟡中/🟢低）。

能力版本管理（完整版）

功能	说明
创建新版本	基于当前版本复制 schema，保存为 draft 状态
发布版本	draft → stable，通知所有消费者，更新 schema
弃用版本	stable → deprecated，设置弃用时间，不再接受新消费者
回滚	将旧版本重新设为 stable，当前版本设为 deprecated
版本对比	并排显示两个版本的 schema diff，高亮变更字段
影响分析	切换版本前，分析哪些消费者会受影响（基于 schema diff）

版本状态流

draft ──发布──→ stable ──弃用──→ deprecated
                     │
                     └──回滚──→ stable（旧版本）

集群文档导出

导出内容（不含各项目自己的 PRD/交接文档）：

导出项	内容
集群总览	层结构 + 项目分布 + 统计数字
共享实体清单	所有共享实体定义（字段 + 关系）
能力注册表	所有已注册能力（含版本信息）
依赖关系图	跨层依赖（可导出为图片/SVG）

线框图（7 张）

1️⃣ 共享实体定义

集群工作台的新 Tab，定义和管理集群级共享实体。

集群工作台 · 共享实体 Tab

任务 1.1-1.3Day 1-5

总览

分层架构

能力依赖

共享实体

文档

共享实体（3 个）

👤 User（用户）

5 个字段 · 1 个关系 · 被 3 个项目引用

stable

📦 Product（商品）

4 个字段 · 被 2 个项目引用

stable

2️⃣ 项目引用配置

在项目数据模型中配置引用哪些共享实体。

项目数据模型 · 共享实体引用

任务 1.4-1.5Day 6-7

引用的共享实体

👤 User 📦 Product

字段映射（可选）

共享实体字段	项目字段
User.id	User.id（自动映射）
User.name	User.nickname（手动映射）

3️⃣ 影响分析面板

修改共享实体字段时，展示 L3 级联影响链。

影响分析 · 修改 User.email

任务 2.1-2.3Day 8-14

变更内容：User.email 字段类型从 string 改为 string | null

🔴 L1: 直接影响（1 个项目）

└─→ 订单系统（引用 User.email）

🟡 L2: 能力影响（1 个能力）

└─→ 用户认证能力（依赖 User.email 校验登录）

🟢 L3: 上游影响（2 个系统）

└─→ 客服系统（消费用户认证能力）

└─→ 营销系统（消费用户认证能力）

⚠️ 本次变更影响 1 个项目、1 个能力、2 个上游系统

4️⃣ 能力版本管理

能力支持多版本共存，消费者绑定到特定版本。

能力版本管理 · 用户认证

任务 3.1-3.3Day 15-18

当前版本：v2.0 (stable)

v2.0 stable · 2026-06-01 · 消费者：订单系统、客服系统

新增短信登录、微信登录；token 拆分为 access/refresh

v1.0 deprecated · 2025-01-15 · 无活跃消费者

v2.1-beta beta · 2026-09-01 · 消费者：无

5️⃣ 版本对比

并排显示两个版本的 schema diff，高亮变更字段。

版本对比 · v1.0 vs v2.0

任务 3.4Day 19

v1.0

input:
  username: string
  password: string
output:
  token: string
  expiresIn: number

v2.0

input:
  loginType: enum(password,sms,wechat)
  credential: string
output:
  accessToken: string
  refreshToken: string
  expiresIn: number

⚠️ 破坏性变更：input 字段完全变更，output 新增 refreshToken。需要同步修改 2 个消费者。

6️⃣ 文档导出配置

选择要导出的内容和格式。

集群文档导出

任务 4.1-4.2Day 20-21

7️⃣ 导出预览

预览导出内容，确认后下载。

导出预览

任务 4.3Day 22

# 企业级业务平台 · 集群文档

## 1. 集群总览
- 4 层 · 12 个项目 · 28 个能力 · 45 条依赖

## 2. 共享实体清单
### 2.1 User（用户）
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | id | ✓ | 主键 |
| name | string | ✓ | 姓名 |
| email | string | | 邮箱 |

## 3. 能力注册表
### 3.1 用户认证（cap-user-auth）
- 类型：api_service
- 版本：v2.0 (stable)
- 消费者：订单系统、客服系统

## 4. 依赖关系图
[依赖关系图 SVG]

任务清单（24 项）

📅 Week 1 · 共享实体（Day 1-5）

#	任务	Day	工作	依赖
1.1	共享实体数据模型	D1	1 天	-
1.2	sharedEntity CRUD RPC	D2	1 天	1.1
1.3	共享实体定义 UI	D3-4	2 天	1.2
1.4	项目 sharedEntityRefs 配置	D5	1 天	1.2

📅 Week 2 · 影响分析（Day 6-10）

#	任务	Day	工作	依赖
2.1	影响分析引擎（L1: 实体→项目）	D6-7	2 天	1.4
2.2	影响分析引擎（L2+L3: 能力→上游）	D8-9	2 天	2.1
2.3	影响分析可视化（树形结构）	D10	1 天	2.2

📅 Week 3 · 能力版本管理（Day 11-15）

#	任务	Day	工作	依赖
3.1	能力版本数据结构	D11	1 天	-
3.2	版本 CRUD RPC	D12	1 天	3.1
3.3	版本管理 UI（创建/发布/弃用/回滚）	D13-14	2 天	3.2
3.4	版本对比 UI	D15	1 天	3.3

📅 Week 4 · 文档导出 + 联调（Day 16-20）

#	任务	Day	工作	依赖
4.1	文档导出引擎	D16-17	2 天	-
4.2	导出配置 UI	D18	1 天	4.1
4.3	导出预览 UI	D19	1 天	4.2
4.4	端到端测试 + 文档	D20	1 天	4.3

完成标准（Definition of Done）

✅ Phase 3 完成时，以下必须全部满足

#	验收项	验证方式
1	可创建/编辑/删除集群级共享实体	UI 检查
2	共享实体支持字段定义 + 关系定义	创建测试实体
3	项目可配置 sharedEntityRefs 引用共享实体	配置测试
4	影响分析 L1: 显示哪些项目引用了实体	修改测试实体
5	影响分析 L2: 显示哪些能力依赖该项目	修改测试实体
6	影响分析 L3: 显示哪些上游系统受影响	修改测试实体
7	能力版本支持创建/发布/弃用/回滚	创建测试版本
8	版本对比显示 schema diff	对比测试
9	版本切换前显示影响分析	切换测试
10	集群文档导出包含总览+实体+能力+依赖	导出测试
11	导出格式支持 Markdown	导出测试
12	文档完成	docs/
13	无 P0/P1 Bug 残留	端到端测试

风险与缓解

风险	概率	影响	缓解措施
共享实体粒度难以统一	中	中	提供推荐模板，允许自定义调整
影响分析性能（大数据量）	低	中	缓存 + 异步计算
版本管理复杂度高	中	低	提供默认版本策略，简化操作