# 包架构设计

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [pnpm-workspace.yaml](file://pnpm-workspace.yaml)
- [turbo.json](file://turbo.json)
- [ARCHITECTURE_SUMMARY.md](file://ARCHITECTURE_SUMMARY.md)
- [README.md](file://README.md)
- [packages/core/package.json](file://packages/core/package.json)
- [packages/adapters/view-ui-plus/package.json](file://packages/adapters/view-ui-plus/package.json)
- [packages/adapters/element-plus/package.json](file://packages/adapters/element-plus/package.json)
- [packages/compat/package.json](file://packages/compat/package.json)
- [packages/core/vite.config.js](file://packages/core/vite.config.js)
- [packages/core/src/index.js](file://packages/core/src/index.js)
- [packages/compat/index.js](file://packages/compat/index.js)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本文件面向 Pro-IVIEW V3 的包架构设计，系统阐述其采用的 Monorepo 架构、工作区与包管理策略、包间依赖与版本管理、构建系统（Turborepo）设计与优化、发布与版本控制策略，并提供扩展新包与维护现有包的实践指南。同时，结合仓库中的实际配置文件，给出架构图与可操作的配置示例路径。

## 项目结构
Pro-IVIEW V3 采用 Monorepo 管理多包，以 pnpm workspace 作为工作区管理工具，以 Turborepo 作为构建管道与缓存引擎。顶层 package.json 提供统一脚本与依赖，各子包位于 packages 目录下，分别承担核心能力、UI 适配器与向后兼容封装。

- 顶层配置
  - 根 package.json：定义脚本（如 dev、build、build:core、build:adapter:view、build:adapter:element）、依赖与包管理器版本锁定。
  - pnpm-workspace.yaml：声明工作区包集合，包含 core、adapters 下的所有包与 compat。
  - turbo.json：定义构建流水线（build、dev），设置输出目录与缓存行为。
  - ARCHITECTURE_SUMMARY.md：架构改造总结与包结构说明。
  - README.md：项目简介与特性清单。

- 包组织
  - packages/core：核心能力与 UI 适配器注入机制，提供统一插件安装与组件注册。
  - packages/adapters/view-ui-plus：基于 view-ui-plus 的 UI 适配器实现。
  - packages/adapters/element-plus：基于 element-plus 的 UI 适配器实现。
  - packages/compat：向后兼容包，自动集成 core 与 view-ui-plus 适配器，保持旧版 API。

```mermaid
graph TB
root["根工作区<br/>package.json / pnpm-workspace.yaml / turbo.json"]
core["@pro-iview/core<br/>核心包"]
adapter_view["@pro-iview/view-ui-plus<br/>适配器"]
adapter_element["@pro-iview/element-plus<br/>适配器"]
compat_pkg["pro_iview_v3<br/>向后兼容包"]
root --> core
root --> adapter_view
root --> adapter_element
root --> compat_pkg
compat_pkg --> core
compat_pkg --> adapter_view
```

**图表来源**
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

**章节来源**
- [package.json:8-19](file://package.json#L8-L19)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [ARCHITECTURE_SUMMARY.md:59-120](file://ARCHITECTURE_SUMMARY.md#L59-L120)
- [README.md:1-18](file://README.md#L1-L18)

## 核心组件
本节聚焦核心包与适配器的关键职责与交互方式。

- @pro-iview/core
  - 职责：提供统一插件安装、组件注册、国际化、指令、UI 适配器注入等能力；内部聚合 components、mixin、libs、locale、directive 等模块。
  - 关键入口：packages/core/src/index.js，提供 install 方法与 provideUIAdapter 注入适配器。
  - 构建配置：packages/core/vite.config.js，定义库打包格式（es/umi）、外部化 vue、别名 @ 指向 src。
  - 包元数据：packages/core/package.json，定义 exports、main/module、typings、peerDependencies。

- @pro-iview/view-ui-plus 与 @pro-iview/element-plus
  - 职责：实现 UIAdapter 接口，将核心组件所需 UI 组件映射到具体 UI 库（view-ui-plus 或 element-plus）。
  - 包元数据：各自 package.json，声明 peerDependencies（对应 UI 库版本范围）。

- pro_iview_v3（向后兼容）
  - 职责：自动安装 view-ui-plus 并注入 @pro-iview/view-ui-plus 适配器，透传 core 的所有能力，保持旧版 API 不变。
  - 实现：packages/compat/index.js，组合 Core 与 Adapter 并导出统一接口。

**章节来源**
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [packages/core/package.json:8-18](file://packages/core/package.json#L8-L18)
- [packages/adapters/view-ui-plus/package.json:8-14](file://packages/adapters/view-ui-plus/package.json#L8-L14)
- [packages/adapters/element-plus/package.json:8-14](file://packages/adapters/element-plus/package.json#L8-L14)
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

## 架构总览
Pro-IVIEW V3 的架构围绕“核心包 + UI 适配器 + 向后兼容层”的三层设计展开，通过依赖注入实现核心逻辑与 UI 库的解耦，支持多 UI 库切换与零成本升级。

```mermaid
graph TB
subgraph "应用层"
App["应用实例<br/>Vue App"]
end
subgraph "核心层"
Core["@pro-iview/core<br/>插件安装/组件注册/适配器注入"]
end
subgraph "适配器层"
AdapterView["@pro-iview/view-ui-plus"]
AdapterElement["@pro-iview/element-plus"]
end
subgraph "UI 库层"
ViewUIPlus["view-ui-plus"]
ElementPlus["element-plus"]
end
App --> Core
Core --> AdapterView
Core --> AdapterElement
AdapterView --> ViewUIPlus
AdapterElement --> ElementPlus
```

**图表来源**
- [packages/core/src/index.js:26-31](file://packages/core/src/index.js#L26-L31)
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)

## 详细组件分析

### 核心包（@pro-iview/core）分析
- 设计要点
  - 插件安装：install 方法中注册全局组件、指令、国际化、全局属性，并注入 UI 适配器。
  - 适配器注入：通过 provideUIAdapter 将适配器注入到应用上下文，供组件消费。
  - 构建产物：ES 与 UMD 双格式，外部化 vue，便于浏览器与模块环境使用。
- 数据流
  - 应用调用 app.use(Core, { adapter })，Core.install 完成注册与适配器注入。
  - 组件通过 useUIAdapter 获取 UI 组件，实现与 UI 库解耦。

```mermaid
sequenceDiagram
participant App as "应用实例"
participant Core as "@pro-iview/core"
participant Adapter as "UI 适配器"
participant UI as "UI 库"
App->>Core : 调用 app.use(Core, { adapter })
Core->>Core : install(app, opts)
Core->>Adapter : provideUIAdapter(adapter)
Core->>App : 注册全局组件/指令/国际化
App->>UI : 安装 UI 库
Note over Core,Adapter : 适配器已注入，组件可通过 useUIAdapter 获取 UI 组件
```

**图表来源**
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/core/src/index.js:26-31](file://packages/core/src/index.js#L26-L31)

**章节来源**
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [packages/core/package.json:8-18](file://packages/core/package.json#L8-L18)

### 适配器（view-ui-plus 与 element-plus）分析
- 设计要点
  - 适配器实现：在各自 src/index.js 中提供 UIAdapter 的具体实现，映射核心组件所需的 UI 组件与 API。
  - 版本对齐：peerDependencies 明确 UI 库版本范围，避免运行时冲突。
- 交互流程
  - 应用安装 UI 库后，将适配器注入核心包，组件通过依赖注入获取 UI 组件。

```mermaid
flowchart TD
Start(["选择 UI 适配器"]) --> CheckView{"是否选择 view-ui-plus?"}
CheckView --> |是| UseView["@pro-iview/view-ui-plus"]
CheckView --> |否| UseElement["@pro-iview/element-plus"]
UseView --> Inject["provideUIAdapter(adapter)"]
UseElement --> Inject
Inject --> Components["组件通过 useUIAdapter 获取 UI 组件"]
```

**图表来源**
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)
- [packages/core/src/index.js:26-31](file://packages/core/src/index.js#L26-L31)

**章节来源**
- [packages/adapters/view-ui-plus/package.json:8-14](file://packages/adapters/view-ui-plus/package.json#L8-L14)
- [packages/adapters/element-plus/package.json:8-14](file://packages/adapters/element-plus/package.json#L8-L14)

### 向后兼容包（pro_iview_v3）分析
- 设计要点
  - 自动装配：在 install 中自动安装 view-ui-plus，并注入 @pro-iview/view-ui-plus 适配器。
  - 透传能力：导出 core 的全部能力，保持旧版 API 与使用方式一致。
- 适用场景
  - 老项目平滑升级，无需修改业务代码即可继续使用。

```mermaid
sequenceDiagram
participant App as "应用实例"
participant Compat as "pro_iview_v3"
participant Core as "@pro-iview/core"
participant Adapter as "@pro-iview/view-ui-plus"
participant ViewUI as "view-ui-plus"
App->>Compat : 调用 app.use(Compat)
Compat->>ViewUI : app.use(ViewUI)
Compat->>Core : Core.install(app, { adapter : Adapter })
Core-->>App : 完成注册与适配器注入
```

**图表来源**
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

**章节来源**
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

## 依赖分析
- 工作区与包管理
  - pnpm workspace：声明工作区包含 core、adapters/*、compat，支持本地包互引用（workspace:*）。
  - 根 package.json：集中管理脚本与依赖，使用 pnpm 作为包管理器。
- 包间依赖
  - compat 依赖 @pro-iview/core 与 @pro-iview/view-ui-plus（workspace:*），并显式依赖 view-ui-plus 与 vue。
  - adapters 仅依赖 vue，peerDependencies 指定 UI 库版本范围。
  - core 依赖 vue 与若干工具库，peerDependencies 指定 vue 版本范围。
- 版本管理
  - 所有包 version 均为 2.0.0，遵循语义化版本；通过统一版本号简化发布与维护。

```mermaid
graph LR
Root["根 package.json"]
CorePkg["@pro-iview/core/package.json"]
CompatPkg["pro_iview_v3/package.json"]
AdapterVP["@pro-iview/view-ui-plus/package.json"]
AdapterEP["@pro-iview/element-plus/package.json"]
Root --> CorePkg
Root --> AdapterVP
Root --> AdapterEP
Root --> CompatPkg
CompatPkg --> CorePkg
CompatPkg --> AdapterVP
```

**图表来源**
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

**章节来源**
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)
- [packages/core/package.json:43-45](file://packages/core/package.json#L43-L45)
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)

## 性能考虑
- 构建缓存与增量构建
  - turbo.json 中 pipeline.build 设置 dependsOn 与输出目录，利用缓存避免重复构建。
  - dev 任务持久化且不缓存，适合本地开发体验。
- 产物体积与加载
  - core 产出 ES 与 UMD 双格式，外部化 vue，减少重复打包与体积。
  - 适配器仅导出必要组件映射，避免冗余依赖。
- 开发体验
  - 根脚本统一入口，按需过滤构建（如 build:core、build:adapter:view 等），提升迭代效率。

**章节来源**
- [turbo.json:4-16](file://turbo.json#L4-L16)
- [packages/core/vite.config.js:16-23](file://packages/core/vite.config.js#L16-L23)
- [package.json:10-15](file://package.json#L10-L15)

## 故障排查指南
- 本地开发与构建
  - 安装依赖与构建：参考架构总结中的安装与构建步骤，确认 pnpm install 与 pnpm build 正常执行。
  - 按需构建：使用 build:core、build:adapter:view、build:adapter:element 精准定位问题包。
- 适配器注入失败
  - 确认 app.use(Core, { adapter }) 已正确传入 adapter；检查 provideUIAdapter 是否被调用。
- UI 库版本不匹配
  - 检查 adapters 的 peerDependencies 与项目中 UI 库版本是否满足范围要求。
- 兼容包使用异常
  - 确认 compat 在 install 中先安装 UI 库再注入适配器；核对导出的 API 与 core 一致。

**章节来源**
- [ARCHITECTURE_SUMMARY.md:179-209](file://ARCHITECTURE_SUMMARY.md#L179-L209)
- [packages/core/src/index.js:26-31](file://packages/core/src/index.js#L26-L31)
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)

## 结论
Pro-IVIEW V3 通过 Monorepo 与 Turborepo 的组合，实现了核心能力与 UI 库的解耦、多 UI 库的灵活切换以及向后兼容的平滑升级。该架构具备清晰的包边界、稳定的依赖关系与高效的构建缓存机制，适合长期演进与团队协作。

## 附录

### 构建系统与优化策略
- Turborepo 管道
  - build：继承上游依赖构建顺序，输出 dist 与 lib 目录，启用缓存加速。
  - dev：持久化任务，禁用缓存，保证开发响应速度。
- Vite 构建
  - core：双格式输出、外部化 vue、别名 @ 指向 src，便于调试与复用。
- 脚本入口
  - 根 package.json 提供统一命令，按包过滤构建，便于 CI/CD 与本地开发。

**章节来源**
- [turbo.json:4-16](file://turbo.json#L4-L16)
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [package.json:8-19](file://package.json#L8-L19)

### 发布与版本控制策略
- 版本同步
  - 所有包 version 固定为 2.0.0，发布时保持一致，降低依赖解析复杂度。
- 发布建议
  - 使用 pnpm workspaces 的本地链接能力进行联调；统一版本号变更后批量发布。
  - 为每个包维护独立的 changelog，记录破坏性变更与依赖更新。

**章节来源**
- [package.json:3](file://package.json#L3)
- [packages/core/package.json:3](file://packages/core/package.json#L3)
- [packages/adapters/view-ui-plus/package.json:3](file://packages/adapters/view-ui-plus/package.json#L3)
- [packages/adapters/element-plus/package.json:3](file://packages/adapters/element-plus/package.json#L3)
- [packages/compat/package.json:3](file://packages/compat/package.json#L3)

### 扩展指南：新增包与维护
- 新增包步骤
  - 在 packages 下创建新包目录，编写 package.json（name、version、exports、peerDependencies 等）。
  - 如为适配器，实现 UIAdapter 接口并在 src/index.js 导出；如为核心扩展，提供 install 与组件注册。
  - 在 pnpm-workspace.yaml 中加入新包路径，或使用通配符适配多包结构。
  - 在根 package.json 中补充必要的构建/开发脚本。
- 维护建议
  - 保持 exports 字段与产物目录一致，确保 ESM/CJS/Types 正确导出。
  - 严格遵守 peerDependencies 的 UI 库版本范围，避免运行时冲突。
  - 使用 turbo 的按包过滤构建，快速定位问题并加速迭代。

**章节来源**
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [packages/adapters/view-ui-plus/package.json:8-14](file://packages/adapters/view-ui-plus/package.json#L8-L14)
- [packages/adapters/element-plus/package.json:8-14](file://packages/adapters/element-plus/package.json#L8-L14)
- [package.json:8-19](file://package.json#L8-L19)