shangeyao opened a new issue, #4414:
URL: https://github.com/apache/streampark/issues/4414
## 背景与动机
当前 `streampark-console-webapp` 基于 **Vue 3 + Vite 4 + Ant Design Vue 3**
构建，代码结构继承自 vue-vben-admin 模板，存在以下问题：
| 问题 | 现状 |
|------|------|
| UI 框架耦合 | 约 **150+ 文件**直接依赖 `ant-design-vue`，图标大量使用
`@ant-design/icons-vue` |
| 抽象层过重 | 自研 `BasicTable` / `BasicForm` / `BasicModal` / `BasicDrawer`
等封装层，与 Ant Design API 深度绑定 |
| 样式体系混杂 | **WindiCSS + Less + Ant Design 主题变量** 三套并存，维护成本高 |
| 构建工具偏旧 | Vite 4.4、Node 限制
`<=18`，部分插件（`vite-plugin-theme`、`vite-plugin-windicss`）已停止维护 |
| 代码规模大 | 约 **625 个源文件 / ~68,000 行**，175+ 页面组件，179+ 通用组件 |
**重构目标**：以 Naive UI 为核心，建立更轻量、可维护的前端架构，同时保持与后端 API 的完全兼容，不影响现有用户工作流。
---
## 重构范围
### ✅ 包含（In Scope）
- UI 组件库：`ant-design-vue` → `naive-ui`
- 构建工具链升级：Vite 5/6、TypeScript 5.x、Node 20 LTS
- 样式方案：WindiCSS + Less → **UnoCSS**（或 Naive UI 原生 CSS Variables）
- 布局系统重写：侧边栏、顶栏、多 Tab、面包屑
- 通用组件层重建：Table、Form、Modal、Drawer、Tree 等
- 全部业务页面迁移（见模块清单）
- i18n 保留（vue-i18n），适配 Naive UI 国际化
- E2E 测试用例同步更新（`streampark-e2e` 约 21 个 Page Object）
- Maven 构建集成验证（`-Pwebapp` profile）
### ❌ 不包含（Out of Scope）
- 后端 API 变更
- 数据库 / 权限模型变更
- Flink / Spark 业务逻辑变更
- 新增功能（纯迁移，不做功能扩展）
---
## 目标技术栈
```yaml
Runtime:
- Vue 3.5+ (Composition API + <script setup>)
- TypeScript 5.x
- Pinia 2.x (保留)
UI:
- naive-ui (latest stable)
- @vicons/ionicons5 或 @iconify/vue (替代 @ant-design/icons-vue)
- UnoCSS (替代 WindiCSS)
Build:
- Vite 5/6
- vue-tsc
- ESLint 9 + Prettier
保留:
- vue-router 4
- vue-i18n 9
- axios (HTTP 层)
- monaco-editor (SQL/YAML 编辑器)
- dayjs / lodash-es
```
---
## 迁移策略
推荐 **「新壳 + 分模块迁移」** 策略，而非一次性全量重写：
```
Phase 0: 脚手架
└── 新建 streampark-console-webapp-v2/ 或在 feature 分支上重建 src/
Phase 1: 基础设施
└── 布局 / 路由 / 权限 / HTTP / i18n / 主题
Phase 2: 通用组件
└── SpTable / SpForm / SpModal / SpDrawer / SpPage
Phase 3~6: 业务模块（按优先级）
└── 系统管理 → 设置 → 资源 → Flink → Spark
Phase 7: 切换 & 清理
└── E2E 通过 → 替换旧 webapp → 删除 Ant Design 依赖
```
> **关键原则**：API 层（`src/api/`）和 TypeScript 类型定义尽量复用，只改视图层和组件层。
---
## Ant Design Vue → Naive UI 组件映射
| Ant Design Vue | Naive UI | 迁移复杂度 | 备注 |
|---|---|---|---|
| `Table` | `n-data-table` | 🔴 高 | 列定义、分页、排序 API 差异大 |
| `Form` / `FormItem` | `n-form` / `n-form-item` | 🔴 高 | 校验规则格式不同 |
| `Modal` | `n-modal` | 🟡 中 | 需重写 `useModal` hook |
| `Drawer` | `n-drawer` | 🟡 中 | |
| `Select` | `n-select` | 🟡 中 | 远程搜索模式需适配 |
| `Input` / `InputNumber` | `n-input` / `n-input-number` | 🟢 低 | |
| `Switch` | `n-switch` | 🟢 低 | |
| `Tag` | `n-tag` | 🟢 低 | |
| `Tabs` | `n-tabs` | 🟡 中 | |
| `Tree` | `n-tree` | 🔴 高 | 角色权限树需重点测试 |
| `Alert` | `n-alert` | 🟢 低 | |
| `message` | `useMessage()` | 🟡 中 | 全局 hook 重写 |
| `notification` | `useNotification()` | 🟡 中 | |
| `Modal.confirm` | `useDialog()` | 🟡 中 | |
| `Descriptions` | `n-descriptions` | 🟢 低 | |
| `Timeline` | `n-timeline` | 🟢 低 | |
| `Progress` | `n-progress` | 🟢 低 | |
| `Upload` | `n-upload` | 🔴 高 | 文件上传逻辑需重写 |
| `Dropdown` / `Menu` | `n-dropdown` | 🟡 中 | |
| `Tooltip` | `n-tooltip` | 🟢 低 | |
| `Spin` | `n-spin` | 🟢 低 | |
| `Empty` | `n-empty` | 🟢 低 | |
| `Card` | `n-card` | 🟢 低 | |
| `Badge` | `n-badge` | 🟢 低 | |
| `Radio` / `RadioGroup` | `n-radio` / `n-radio-group` | 🟢 低 | |
| `Divider` | `n-divider` | 🟢 低 | |
| `Space` | `n-space` | 🟢 低 | |
| `List` | `n-list` | 🟢 低 | |
| `Typography` | 原生 / `n-text` | 🟢 低 | |
| `Layout` | `n-layout` | 🟡 中 | 整体布局重写 |
---
## 分阶段实施计划
### Phase 0 — 项目脚手架（1 周）
- [ ] 初始化 Vite 5/6 + Vue 3 + TypeScript 项目结构
- [ ] 配置 UnoCSS、ESLint、Prettier
- [ ] 集成 Naive UI（按需引入 + 主题配置）
- [ ] 配置 `unplugin-vue-components` 自动导入 Naive UI 组件
- [ ] 搭建 CI lint / type-check 流水线
- [ ] 确定目录结构规范
**建议目录结构：**
```
src/
├── api/ # 复用现有 API 层
├── assets/
├── components/ # 通用业务组件 (SpTable, SpForm...)
├── composables/ # 组合式函数 (useTable, useForm...)
├── layouts/ # 布局 (DefaultLayout, BlankLayout)
├── locales/ # i18n (复用现有翻译文件)
├── router/ # 路由 + 守卫
├── stores/ # Pinia stores
├── styles/ # 全局样式 + Naive UI 主题覆盖
├── utils/ # 工具函数
└── views/ # 业务页面
├── auth/
├── system/
├── setting/
├── resource/
├── flink/
└── spark/
```
### Phase 1 — 核心基础设施（2 周）
- [ ] **布局系统**
- [ ] `DefaultLayout`：侧边栏 + 顶栏 + 内容区 + 多 Tab
- [ ] `BlankLayout`：登录页
- [ ] 响应式 / 侧边栏折叠 / 暗色模式
- [ ] **路由 & 权限**
- [ ] 保留 `PermissionModeEnum.BACK` 后端菜单模式
- [ ] 迁移路由守卫（`permissionGuard`、`ssoGuard`、`stateGuard`）
- [ ] 动态路由注册逻辑
- [ ] **HTTP 层**
- [ ] 复用 `defHttp` / axios 拦截器
- [ ] 统一错误处理 → Naive UI `useMessage`
- [ ] **全局 Hooks**
- [ ] `useMessage` / `useDialog` / `useNotification`（替代 Ant Design 版本）
- [ ] `useI18n`（保留）
- [ ] `useLoading`
- [ ] **登录页**
- [ ] 登录表单 + 团队选择 Modal
- [ ] SSO 登录支持
- [ ] Session 超时处理
### Phase 2 — 通用组件层（2~3 周）
重建以下核心抽象（**简化设计，避免过度封装**）：
| 组件 | 说明 | 替代 |
|------|------|------|
| `SpTable` | 数据表格 + 搜索表单 + 分页 + 操作列 | `BasicTable` |
| `SpForm` | Schema 驱动表单 | `BasicForm` |
| `SpModal` | 命令式 Modal | `BasicModal` + `useModal` |
| `SpDrawer` | 命令式 Drawer | `BasicDrawer` + `useDrawer` |
| `SpPage` | 页面容器（标题 + 操作区 + 内容） | `PageWrapper` |
| `SpIcon` | 统一图标组件 | `Icon` (Iconify) |
| `SpMonacoEditor` | Monaco 编辑器封装 | 保留现有 |
| `SpDescription` | 详情描述列表 | `Description` |
**设计原则：**
- 优先使用 Naive UI 原生 API，减少中间抽象
- Composable 优于 HOC/Render Function
- 废弃 TSX render 函数模式（`useFlinkRender.tsx` 等），改为 `<script setup>` + 模板
### Phase 3 — 系统管理模块（1~2 周）
| 页面 | 路径 | 复杂度 |
|------|------|--------|
| 用户管理 | `/system/user` | 中 |
| 角色管理 | `/system/role` | 高（权限树） |
| 团队管理 | `/system/team` | 低 |
| 成员管理 | `/system/member` | 中 |
| Token 管理 | `/system/token` | 低 |
### Phase 4 — 设置 & 资源模块（2 周）
| 模块 | 页面 |
|------|------|
| 设置 | 系统设置、Flink Home、Flink Cluster、Flink Gateway、Yarn Queue、告警、外部链接 |
| 资源 | 项目管理、资源上传、变量管理 |
### Phase 5 — Flink 模块（3~4 周）⚠️ 最复杂
| 页面 | 说明 | 复杂度 |
|------|------|--------|
| Flink Home | 环境管理 | 中 |
| Flink Cluster | 集群管理 | 中 |
| Flink Gateway | 网关管理 | 中 |
| **Flink Application 列表** | 表格 + 多操作 | 高 |
| **Flink Application 创建/编辑** | 多步骤表单 + 动态 Schema | 🔴 极高 |
| **Flink Application 详情** | Tab + SQL 编辑器 + 构建/部署 | 🔴 极高 |
| Pod Template | YAML 编辑 | 高 |
| Hadoop Conf | 配置抽屉 | 中 |
**重点关注：**
- `FlinkSql.vue` — Monaco Editor 集成
- `useCreateAndEditSchema.ts` — 动态表单 Schema（~500 行）
- `AppDetail/DetailTab.vue` — 多 Tab 详情页
- `Mergely.vue` — SQL Diff 对比
- 应用生命周期操作（启动/停止/取消/Savepoint）
### Phase 6 — Spark 模块（2~3 周）
结构与 Flink 类似，可复用 Phase 5 中建立的 patterns：
- Spark Home、Spark Application（列表/创建/编辑/详情）
- Spark SQL 编辑器、构建抽屉
### Phase 7 — 收尾 & 切换（1~2 周）
- [ ] 全量 E2E 测试迁移与通过
- [ ] 性能对比（Bundle Size、FCP、LCP）
- [ ] 浏览器兼容性验证
- [ ] 暗色模式 / 主题切换验证
- [ ] 国际化完整性检查（中/英）
- [ ] Maven `-Pwebapp,dist` 构建验证
- [ ] Docker 镜像构建验证
- [ ] 删除旧 Ant Design 依赖和废弃代码
- [ ] 更新 AGENTS.md 前端规范
- [ ] 更新开发者文档
---
## 业务模块文件规模参考
```
views/
├── base/ ~10 files (登录、异常、锁屏)
├── system/ ~15 files (用户/角色/团队/成员/Token)
├── setting/ ~20 files (系统/Flink/告警/队列/外链)
├── resource/ ~20 files (项目/上传/变量)
├── flink/ ~80 files ⚠️ 最大模块
└── spark/ ~30 files
components/ ~179 files (需评估哪些可删除)
api/ ~60 files (基本复用)
locales/ ~55 files (基本复用)
store/ ~9 files (基本复用)
```
---
## 风险与应对
| 风险 | 影响 | 应对策略 |
|------|------|----------|
| Flink 应用表单复杂度极高 | 延期 | Phase 5 预留 buffer，优先完成简单模块验证 pattern |
| E2E 测试大量依赖 Ant Design DOM 结构 | 测试失败 | 同步维护 E2E Page Object，每完成一个模块即更新 |
| Naive UI DataTable 与 Ant Design Table API 差异 | 重构工作量大 | 建立 `SpTable`
适配层，统一列定义格式 |
| 权限树组件迁移 | 角色管理功能回归 | Phase 3 重点测试，保留 Tree 数据转换逻辑 |
| Monaco Editor 集成 | SQL 编辑功能 | 编辑器层与 UI 框架无关，直接迁移 |
| 社区贡献者熟悉 Ant Design | 协作摩擦 | 提供组件迁移对照文档 + Storybook/示例页 |
| 迁移期间双版本维护 | 资源浪费 | 尽量缩短 Phase 3~6 并行窗口，feature flag 控制 |
---
## 测试策略
1. **单元测试**：通用组件（SpTable、SpForm）核心逻辑
2. **E2E 测试**：迁移 `streampark-e2e` 全部 Page Object（21 个页面类）
3. **视觉回归**：关键页面截图对比（可选 Chromatic / Percy）
4. **手动测试清单**：
- [ ] 登录 / 登出 / SSO / Session 超时
- [ ] 权限控制（不同角色菜单可见性）
- [ ] Flink 应用完整生命周期（创建 → 构建 → 部署 → 启动 → 停止 → 删除）
- [ ] SQL 编辑 / 格式化 / 校验 / Diff
- [ ] 文件上传 / 下载
- [ ] 暗色模式切换
- [ ] 中英文切换
---
## 验收标准
- [ ] 零 Ant Design Vue 依赖
- [ ] 全部 E2E 测试通过
- [ ] `pnpm build` 产物体积 ≤ 现有 110%（允许合理浮动）
- [ ] Lighthouse Performance ≥ 80
- [ ] 所有现有功能行为一致（无 regression）
- [ ] TypeScript 严格模式无 error
- [ ] ESLint 零 warning
- [ ] Maven `-Pwebapp,dist` 构建成功
---
## 预估工时
| Phase | 内容 | 预估 |
|-------|------|------|
| 0 | 脚手架 | 1 周 |
| 1 | 基础设施 | 2 周 |
| 2 | 通用组件 | 2~3 周 |
| 3 | 系统管理 | 1~2 周 |
| 4 | 设置 & 资源 | 2 周 |
| 5 | Flink | 3~4 周 |
| 6 | Spark | 2~3 周 |
| 7 | 收尾 | 1~2 周 |
| **合计** | | **14~19 周（1 人全职）** |
> 建议拆分为 **8~10 个独立 PR**，每个 Phase 或子模块一个 PR，便于 review 和 rollback。
---
## 子 Issue 拆分建议
- [Console][Frontend] Phase 0: Naive UI 项目脚手架
- [Console][Frontend] Phase 1: 布局 & 路由 & 权限基础设施
- [Console][Frontend] Phase 2: 通用组件层 (SpTable/SpForm/SpModal)
- [Console][Frontend] Phase 3: 系统管理模块迁移
- [Console][Frontend] Phase 4: 设置 & 资源模块迁移
- [Console][Frontend] Phase 5a: Flink Home/Cluster/Gateway 迁移
- [Console][Frontend] Phase 5b: Flink Application 列表 & 表单迁移
- [Console][Frontend] Phase 5c: Flink Application 详情 & SQL 编辑器迁移
- [Console][Frontend] Phase 6: Spark 模块迁移
- [Console][Frontend] Phase 7: E2E 迁移 & 旧代码清理
- [Console][Frontend] 组件迁移对照文档 & 开发者指南
---
## 需社区讨论的问题
1. **是否在 `main` 分支直接重构，还是新建 `streampark-console-webapp-v2` 目录？**
2. **是否需要同步升级 Vue 3.5 新特性（如 `defineModel`）？**
3. **暗色模式是否为 MVP 必须项？**
4. **是否需要引入 Storybook 做组件文档？**
5. **Spark 模块是否为可选（`-Pspark` profile）— 是否降低优先级？**
6. **是否需要保持与现有 UI 视觉一致，还是允许重新设计？**
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
