# 开发指南

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

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

## 简介
本开发指南面向 Pro-IVIEW V3 的开发者，目标是帮助你在本地快速搭建开发环境、理解项目架构与构建流程、掌握调试与测试方法，并遵循统一的代码规范与贡献流程。项目采用 Vue 3 + Vite + pnpm workspace + Turborepo 的现代化前端工程化方案，支持多 UI 适配器（view-ui-plus、element-plus）与向后兼容层，具备良好的可维护性与扩展性。

## 项目结构
项目采用 Monorepo 结构，使用 pnpm workspace 管理多包；Turborepo 提供跨包构建缓存与流水线控制；Vite 负责库与示例应用的构建与开发服务器。

```mermaid
graph TB
Root["根目录<br/>package.json / turbo.json / pnpm-workspace.yaml"] --> Core["@pro-iview/core<br/>核心包"]
Root --> AdapterView["@pro-iview/view-ui-plus<br/>适配器"]
Root --> AdapterEle["@pro-iview/element-plus<br/>适配器"]
Root --> Compat["pro_iview_v3<br/>向后兼容包"]
Core --> CoreBuild["Vite 构建配置"]
AdapterView --> AdapterViewBuild["Vite 构建配置"]
AdapterEle --> AdapterEleBuild["Vite 构建配置"]
Compat --> CompatBuild["Vite 构建配置"]
Root --> ViteCfg["根 Vite 配置"]
Root --> Turbo["Turborepo 管道"]
Root --> Workspace["pnpm 工作区"]
```

图示来源
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [vite.config.js:11-99](file://vite.config.js#L11-L99)
- [packages/core/vite.config.js:1-30](file://packages/core/vite.config.js#L1-L30)
- [packages/adapters/element-plus/vite.config.js:1-24](file://packages/adapters/element-plus/vite.config.js#L1-L24)
- [packages/compat/vite.config.js:1-24](file://packages/compat/vite.config.js#L1-L24)

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

## 核心组件
- 根包与入口
  - 根入口文件导出版本号、国际化、语言切换与全局组件注册等能力，用于传统浏览器或旧项目集成。
  - 关键路径参考：[packages/index.js:1-69](file://packages/index.js#L1-L69)
- 核心包 @pro-iview/core
  - 提供无 UI 依赖的核心组件与适配器注入机制，支持 ES 与 UMD 两种产物格式。
  - 关键路径参考：[packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)，[packages/core/vite.config.js:1-30](file://packages/core/vite.config.js#L1-L30)
- 适配器包
  - @pro-iview/view-ui-plus：将核心组件映射到 view-ui-plus 组件。
  - @pro-iview/element-plus：将核心组件映射到 element-plus 组件。
  - 关键路径参考：[packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)，[packages/adapters/element-plus/vite.config.js:1-24](file://packages/adapters/element-plus/vite.config.js#L1-L24)
- 向后兼容包 pro_iview_v3
  - 封装 core + view-ui-plus 适配器，保持 v1.x API 不变，便于老项目平滑升级。
  - 关键路径参考：[packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)，[packages/compat/vite.config.js:1-24](file://packages/compat/vite.config.js#L1-L24)

章节来源
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/adapters/element-plus/vite.config.js:1-24](file://packages/adapters/element-plus/vite.config.js#L1-L24)
- [packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)
- [packages/compat/vite.config.js:1-24](file://packages/compat/vite.config.js#L1-L24)

## 架构总览
项目采用“核心包 + 适配器 + 向后兼容”的三层架构，通过 UI 适配器模式实现核心逻辑与 UI 库解耦，支持多 UI 库切换与统一 API。

```mermaid
graph TB
App["应用入口<br/>index.html / main.js"] --> Core["@pro-iview/core"]
Core --> AdapterView["@pro-iview/view-ui-plus"]
Core --> AdapterEle["@pro-iview/element-plus"]
Core --> Compat["pro_iview_v3<br/>向后兼容"]
subgraph "构建与运行"
Vite["Vite 开发/构建"]
Turbo["Turborepo 缓存"]
Pnpm["pnpm 工作区"]
end
App --> Vite
Core --> Vite
AdapterView --> Vite
AdapterEle --> Vite
Compat --> Vite
Pnpm --> Turbo
Turbo --> Vite
```

图示来源
- [index.html:1-12](file://index.html#L1-L12)
- [vite.config.js:11-99](file://vite.config.js#L11-L99)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)

章节来源
- [ARCHITECTURE_SUMMARY.md:122-174](file://ARCHITECTURE_SUMMARY.md#L122-L174)
- [ARCHITECTURE_SUMMARY.md:280-296](file://ARCHITECTURE_SUMMARY.md#L280-L296)

## 详细组件分析

### 构建与多包管理
- 根 Vite 配置
  - 以 packages/index.js 为库入口，输出 UMD/ES 产物，按模式区分外部依赖，启用压缩与复制本地化资源。
  - 关键路径参考：[vite.config.js:11-99](file://vite.config.js#L11-L99)
- 核心包 Vite 配置
  - 输出 ES 与 UMD 产物，外部化 vue，提供别名 @ 指向 src。
  - 关键路径参考：[packages/core/vite.config.js:1-30](file://packages/core/vite.config.js#L1-L30)
- 适配器 Vite 配置
  - 分别针对 element-plus 与 view-ui-plus 的适配器进行库构建，外部化 vue 与对应 UI 库。
  - 关键路径参考：[packages/adapters/element-plus/vite.config.js:1-24](file://packages/adapters/element-plus/vite.config.js#L1-L24)
- Turborepo 管道
  - 定义 build 任务依赖链与缓存输出目录，dev 任务持久化与不缓存。
  - 关键路径参考：[turbo.json:1-18](file://turbo.json#L1-L18)
- pnpm 工作区
  - 声明 packages/core、packages/adapters/*、packages/compat 为工作区包。
  - 关键路径参考：[pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)

```mermaid
flowchart TD
Start(["开始"]) --> LoadWorkspace["加载 pnpm 工作区配置"]
LoadWorkspace --> LoadTurbo["加载 Turborepo 管道"]
LoadTurbo --> BuildRoot["根 Vite 构建库产物"]
BuildRoot --> BuildCore["核心包 Vite 构建"]
BuildRoot --> BuildAdapters["适配器 Vite 构建"]
BuildRoot --> BuildCompat["兼容包 Vite 构建"]
BuildCore --> Cache["写入构建缓存"]
BuildAdapters --> Cache
BuildCompat --> Cache
Cache --> End(["结束"])
```

图示来源
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [vite.config.js:11-99](file://vite.config.js#L11-L99)
- [packages/core/vite.config.js:1-30](file://packages/core/vite.config.js#L1-L30)
- [packages/adapters/element-plus/vite.config.js:1-24](file://packages/adapters/element-plus/vite.config.js#L1-L24)
- [packages/compat/vite.config.js:1-24](file://packages/compat/vite.config.js#L1-L24)

章节来源
- [vite.config.js:11-99](file://vite.config.js#L11-L99)
- [packages/core/vite.config.js:1-30](file://packages/core/vite.config.js#L1-L30)
- [packages/adapters/element-plus/vite.config.js:1-24](file://packages/adapters/element-plus/vite.config.js#L1-L24)
- [packages/compat/vite.config.js:1-24](file://packages/compat/vite.config.js#L1-L24)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)

### 适配器模式与依赖注入
- UI 适配器接口
  - 定义统一的 UI 组件与消息 API 接口，核心包通过注入机制获取适配器实例。
  - 关键路径参考：[ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- 使用方式
  - 新方式：分别引入 @pro-iview/core 与 @pro-iview/view-ui-plus 或 element-plus 适配器。
  - 向后兼容：直接使用 pro_iview_v3 插件，保持 API 不变。
  - 关键路径参考：[ARCHITECTURE_SUMMARY.md:158-174](file://ARCHITECTURE_SUMMARY.md#L158-L174)

```mermaid
sequenceDiagram
participant App as "应用"
participant Core as "@pro-iview/core"
participant Adapter as "UI 适配器"
participant UI as "UI 库"
App->>Core : "安装核心包"
App->>Adapter : "选择适配器(view-ui-plus/element-plus)"
App->>Core : "provide/inject 注入适配器"
Core->>Adapter : "useUIAdapter() 获取组件"
Adapter->>UI : "映射到具体 UI 组件"
UI-->>Core : "返回组件实例"
Core-->>App : "渲染组件"
```

图示来源
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- [ARCHITECTURE_SUMMARY.md:158-174](file://ARCHITECTURE_SUMMARY.md#L158-L174)

章节来源
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- [ARCHITECTURE_SUMMARY.md:158-174](file://ARCHITECTURE_SUMMARY.md#L158-L174)

### 入口与全局能力
- 全局属性与插件注册
  - 通过 install 方法注册全局组件、指令、国际化与第三方工具库（axios、dayjs、lodash）。
  - 关键路径参考：[packages/index.js:12-42](file://packages/index.js#L12-L42)
- 国际化与语言切换
  - 提供 locale/i18n/lang 方法，支持切换语言包。
  - 关键路径参考：[packages/index.js:49-57](file://packages/index.js#L49-L57)

```mermaid
flowchart TD
Install["install(app, opts)"] --> GlobalProps["设置全局属性$http/$dayjs/$lodash"]
GlobalProps --> Locale["应用 locale/i18n"]
Locale --> Register["遍历注册全局组件"]
Register --> Directives["注册自定义指令"]
Directives --> ClickAway["集成 vue3-click-away"]
ClickAway --> Done["完成安装"]
```

图示来源
- [packages/index.js:12-42](file://packages/index.js#L12-L42)

章节来源
- [packages/index.js:12-42](file://packages/index.js#L12-L42)
- [packages/index.js:49-57](file://packages/index.js#L49-L57)

## 依赖分析
- 根包依赖与脚本
  - 根 package.json 定义了开发与构建脚本，使用 pnpm 作为包管理器，声明核心运行时依赖与开发依赖。
  - 关键路径参考：[package.json:1-47](file://package.json#L1-L47)
- 核心包依赖
  - @pro-iview/core 声明对 vue 的 peer 依赖，内部依赖若干工具库。
  - 关键路径参考：[packages/core/package.json:23-46](file://packages/core/package.json#L23-L46)
- 适配器依赖
  - @pro-iview/view-ui-plus 对应 UI 库为 peer 依赖；element-plus 适配器同理。
  - 关键路径参考：[packages/adapters/view-ui-plus/package.json:23-34](file://packages/adapters/view-ui-plus/package.json#L23-L34)
- 发布与忽略规则
  - .npmignore 控制发布内容，.gitignore 控制版本控制忽略项。
  - 关键路径参考：[.npmignore:1-13](file://.npmignore#L1-L13)，[.gitignore:1-25](file://.gitignore#L1-L25)

```mermaid
graph LR
RootPkg["根 package.json"] --> CorePkg["@pro-iview/core/package.json"]
RootPkg --> AdapterVP["@pro-iview/view-ui-plus/package.json"]
RootPkg --> AdapterEP["@pro-iview/element-plus/vite.config.js"]
RootPkg --> CompatPkg["pro_iview_v3/package.json"]
RootPkg -. 发布忽略 .-> NpmIgnore[".npmignore"]
RootPkg -. 版控忽略 .-> GitIgnore[".gitignore"]
```

图示来源
- [package.json:1-47](file://package.json#L1-L47)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)
- [.npmignore:1-13](file://.npmignore#L1-L13)
- [.gitignore:1-25](file://.gitignore#L1-L25)

章节来源
- [package.json:1-47](file://package.json#L1-L47)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)
- [.npmignore:1-13](file://.npmignore#L1-L13)
- [.gitignore:1-25](file://.gitignore#L1-L25)

## 性能考虑
- 构建优化
  - 生产构建启用压缩（移除 console 与 debugger），减少包体体积。
  - 关键路径参考：[vite.config.js:72-78](file://vite.config.js#L72-L78)
- 外部化依赖
  - 将 vue、axios、lodash-es 等常用库外部化，避免重复打包，降低体积。
  - 关键路径参考：[vite.config.js:27-58](file://vite.config.js#L27-L58)
- 缓存与增量构建
  - Turborepo 管道定义输出目录与依赖链，提升跨包构建效率。
  - 关键路径参考：[turbo.json:4-12](file://turbo.json#L4-L12)

章节来源
- [vite.config.js:27-78](file://vite.config.js#L27-L78)
- [turbo.json:4-12](file://turbo.json#L4-L12)

## 故障排查指南
- 依赖安装失败
  - 确认使用 pnpm 并执行安装命令；检查 pnpm 版本与工作区配置。
  - 关键路径参考：[package.json:46](file://package.json#L46)，[pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- 构建产物缺失或路径异常
  - 检查根 Vite 配置中的 outDir 与 env 变量；确认各子包 vite.config 是否正确。
  - 关键路径参考：[vite.config.js:23](file://vite.config.js#L23)，[packages/core/vite.config.js:10-15](file://packages/core/vite.config.js#L10-L15)
- 适配器未生效
  - 确认在应用中正确安装核心包并注入对应适配器；检查 peer 依赖版本匹配。
  - 关键路径参考：[ARCHITECTURE_SUMMARY.md:158-174](file://ARCHITECTURE_SUMMARY.md#L158-L174)，[packages/adapters/view-ui-plus/package.json:30-34](file://packages/adapters/view-ui-plus/package.json#L30-L34)
- 开发服务器代理无效
  - 检查 Vite 代理配置与目标地址可达性。
  - 关键路径参考：[vite.config.js:89-96](file://vite.config.js#L89-L96)

章节来源
- [package.json:46](file://package.json#L46)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [vite.config.js:23](file://vite.config.js#L23)
- [packages/core/vite.config.js:10-15](file://packages/core/vite.config.js#L10-L15)
- [ARCHITECTURE_SUMMARY.md:158-174](file://ARCHITECTURE_SUMMARY.md#L158-L174)
- [packages/adapters/view-ui-plus/package.json:30-34](file://packages/adapters/view-ui-plus/package.json#L30-L34)
- [vite.config.js:89-96](file://vite.config.js#L89-L96)

## 结论
本指南系统梳理了 Pro-IVIEW V3 的开发环境、Monorepo 架构、构建流程与调试方法。建议在开发过程中严格遵循工作区与构建配置，优先使用 Turborepo 提升效率，并通过适配器模式实现 UI 解耦与多端复用。

## 附录

### 开发环境搭建
- Node.js 与包管理器
  - 使用 pnpm 作为包管理器，版本由根 package.json 指定。
  - 关键路径参考：[package.json:46](file://package.json#L46)
- 安装依赖
  - 在仓库根目录执行安装命令，等待 pnpm 完成工作区安装。
  - 关键路径参考：[pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- 启动开发
  - 执行根脚本启动开发服务，或进入子包单独开发。
  - 关键路径参考：[package.json:8-18](file://package.json#L8-L18)

章节来源
- [package.json:8-18](file://package.json#L8-L18)
- [package.json:46](file://package.json#L46)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)

### 代码规范与提交规范
- 本仓库未提供 ESLint 与 Prettier 配置文件，请根据团队约定补充以下文件：
  - ESLint 配置：如 .eslintrc.* 或 eslint.config.js
  - Prettier 配置：如 .prettierrc 或 prettier.config.js
  - Git 提交规范：如 conventional commits 或 cz-conventional-changelog
- 本节为通用指导，不直接分析具体文件，故不附加章节来源。

### 测试策略与工具配置
- 本仓库未提供测试相关配置与脚本，请根据团队约定补充以下文件：
  - 测试框架：如 vitest/jest
  - 测试入口与环境：如 test setup 文件
  - 测试脚本：在 package.json 中新增 test 脚本
- 本节为通用指导，不直接分析具体文件，故不附加章节来源。

### 调试技巧
- 浏览器调试
  - 使用 Vite 开发服务器访问示例页面，结合 Vue DevTools 观察组件树与状态。
  - 关键路径参考：[index.html:1-12](file://index.html#L1-L12)
- 适配器调试
  - 在应用中打印 useUIAdapter 返回值，确认组件映射是否正确。
  - 关键路径参考：[ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- 性能分析
  - 使用浏览器性能面板记录构建与运行阶段的耗时；结合 Turborepo 缓存命中情况评估增量构建收益。
  - 关键路径参考：[turbo.json:4-12](file://turbo.json#L4-L12)

章节来源
- [index.html:1-12](file://index.html#L1-L12)
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- [turbo.json:4-12](file://turbo.json#L4-L12)

### 贡献指南与 PR 流程
- 本仓库未提供贡献指南与 PR 模板，请根据团队约定补充以下文件：
  - CONTRIBUTING.md：开发流程、分支规范、PR 描述模板
  - .github/PULL_REQUEST_TEMPLATE.md：PR 模板
- 本节为通用指导，不直接分析具体文件，故不附加章节来源。

### 开发最佳实践
- Monorepo 最佳实践
  - 使用 pnpm workspace 管理依赖，避免重复安装；通过 Turborepo 管理构建顺序与缓存。
  - 关键路径参考：[pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)，[turbo.json:1-18](file://turbo.json#L1-L18)
- 适配器扩展
  - 新增 UI 适配器时，遵循统一接口定义，确保组件映射与消息 API 一致。
  - 关键路径参考：[ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- 构建与发布
  - 严格区分 dev 与 prod 构建配置；确保外部化依赖与全局变量映射正确。
  - 关键路径参考：[vite.config.js:27-78](file://vite.config.js#L27-L78)

章节来源
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- [vite.config.js:27-78](file://vite.config.js#L27-L78)