urbanLifeline/.kiro/specs/urbanlifeline-to-pigx-migration/frontend-migration-plan.md

Workcase 前端迁移计划

一、依赖分析

1.1 对 shared 模块的依赖

API 依赖

• shared/api - 基础 axios 封装和 TokenManager
• shared/api/file - 文件上传下载 API (fileAPI)
• shared/api/ai - AI 相关 API (aiChatAPI, agentAPI, aiKnowledgeAPI)

组件依赖

• shared/components - FileUpload, FileHistory, IframeView
• shared/components/ai/knowledge - DocumentSegment (知识库文档分段组件)
• shared/layouts - BlankLayout, SubSidebarLayout

类型依赖

• shared/types - BaseDTO, BaseVO, ResultDomain, PageRequest, PageParam
• shared/types - TbSysFileDTO, MenuItem, TbSysViewDTO
• shared/types - AI 相关类型 (TbChat, TbKnowledge, TbKnowledgeFileLog, DifyFileInfo)

1.2 内部模块结构

Views 结构

views/
├── admin/                    # 管理后台页面
│   ├── agent/               # AI 智能体管理 (→ dify 模块)
│   ├── customerChat/        # 客服对话管理
│   ├── knowledge/           # 知识库管理 (→ dify 模块)
│   ├── log/                 # 日志管理
│   │   ├── knowledgeLog/   # 知识库日志 (→ dify 模块)
│   │   ├── systemLog/      # 系统日志
│   │   └── workcaseLog/    # 工单日志
│   ├── overview/            # 概览页面
│   └── workcase/            # 工单管理
└── public/                  # 公共页面
    ├── AIChat/             # AI 对话 (→ dify 模块)
    ├── ChatRoom/           # 聊天室
    ├── JitsiMeeting/       # 视频会议
    ├── Login/              # 登录页 (pigx 已有)
    └── workcase/           # 工单详情

Components 结构

components/
└── workcase/
    └── WorkcaseAssign.vue  # 工单指派组件

API 结构

api/
└── workcase/
    ├── workcase.ts         # 工单 API
    └── workcaseChat.ts     # 聊天室 API

Types 结构

types/
└── workcase/
    ├── workcase.ts         # 工单类型
    ├── chatRoom.ts         # 聊天室类型
    ├── customer.ts         # 客服类型
    ├── conversation.ts     # 对话类型
    └── wordCloud.ts        # 词云类型

二、迁移策略

2.1 迁移顺序（按优先级）

第一阶段：基础设施 (已完成)

• API 定义迁移
• 基础工单管理页面

第二阶段：工单核心功能

1. 工单组件

   • WorkcaseAssign.vue (工单指派组件)
   • WorkcaseDetail (工单详情组件)

2. 工单管理页面

   • admin/workcase/WorkcaseView.vue (工单列表)
   • admin/overview/OverviewView.vue (概览页面)
   • admin/log/workcaseLog/ (工单日志)

第三阶段：聊天室功能

1. 聊天室核心

   • public/ChatRoom/chatRoom/ChatRoom.vue (聊天室主组件)
   • public/ChatRoom/ChatMessage/ (消息组件)
   • public/ChatRoom/ChatRoomView.vue (聊天室视图)

2. 客服管理

   • admin/customerChat/CustomerChatView.vue (客服对话管理)

3. 视频会议

   • public/JitsiMeeting/JitsiMeetingView.vue (视频会议)
   • public/ChatRoom/MeetingCard/ (会议卡片)
   • public/ChatRoom/MeetingCreate/ (创建会议)

第四阶段：AI 功能 (最后迁移，归入 dify 模块)

1. AI 对话

   • public/AIChat/AIChatView.vue
   • public/AIChat/components/

2. 智能体管理

   • admin/agent/AgentView.vue

3. 知识库管理

   • admin/knowledge/KnowLedgeView.vue
   • admin/log/knowledgeLog/KnowledgeLogView.vue

2.2 共享依赖处理

pigx 已有的功能（直接使用）

• 登录认证 (Login)
• 用户管理
• 权限管理
• 文件上传下载 (Upload 组件)
• 基础布局 (Layout)

需要适配的 shared 组件

1. FileUpload → 使用 pigx 的 Upload/index.vue
2. FileHistory → 需要迁移或使用 pigx 的文件管理
3. IframeView → 简单组件，可直接迁移
4. DocumentSegment → AI 知识库专用，归入 dify 模块

需要适配的 API

1. fileAPI → 适配 pigx 的文件服务 API
2. aiChatAPI, agentAPI, aiKnowledgeAPI → 归入 dify 模块

2.3 目录结构映射

源目录 → 目标目录

urbanLifelineWeb/packages/workcase/
├── src/api/workcase/          → pigx-ai-ui/src/api/workcase/
├── src/components/workcase/   → pigx-ai-ui/src/components/workcase/
├── src/views/admin/workcase/  → pigx-ai-ui/src/views/workcase/admin/
├── src/views/admin/customerChat/ → pigx-ai-ui/src/views/workcase/customerChat/
├── src/views/admin/overview/  → pigx-ai-ui/src/views/workcase/overview/
├── src/views/admin/log/       → pigx-ai-ui/src/views/workcase/log/
├── src/views/public/ChatRoom/ → pigx-ai-ui/src/views/workcase/chatRoom/
├── src/views/public/JitsiMeeting/ → pigx-ai-ui/src/views/workcase/meeting/
├── src/views/public/workcase/ → pigx-ai-ui/src/views/workcase/detail/
└── src/types/workcase/        → pigx-ai-ui/src/types/workcase/

# AI 相关 (归入 dify 模块)
├── src/views/admin/agent/     → pigx-ai-ui/src/views/dify/agent/
├── src/views/admin/knowledge/ → pigx-ai-ui/src/views/dify/knowledge/
├── src/views/public/AIChat/   → pigx-ai-ui/src/views/dify/chat/
└── src/views/admin/log/knowledgeLog/ → pigx-ai-ui/src/views/dify/log/

三、技术适配要点

3.1 API 调用适配

// 源代码
import { api } from 'shared/api'
const res = await api.post('/urban-lifeline/workcase', data)

// 目标代码
import request from '@/utils/request'
const res = await request({
  url: '/workcase/workcase',
  method: 'post',
  data
})

3.2 响应格式适配

// 源代码 (ResultDomain)
interface ResultDomain<T> {
  code: number
  message: string
  success: boolean
  data?: T
  dataList?: T[]
  pageDomain?: PageDomain<T>
}

// 目标代码 (pigx R<T>)
// pigx 使用 code === 0 表示成功
if (res.code === 0) {
  // res.data 包含数据
}

3.3 文件上传适配

// 源代码
import { fileAPI } from 'shared/api/file'
await fileAPI.uploadFile({ file, module, optsn })

// 目标代码
import { uploadFile } from '@/api/admin/file'
await uploadFile(formData)

3.4 WebSocket 适配

// 源代码 (SockJS + STOMP)
const wsUrl = `${protocol}//${host}/${API_BASE_URL}/urban-lifeline/workcase/ws/chat-sockjs`
stompClient = new Client({
  webSocketFactory: () => new SockJS(wsUrl)
})

// 目标代码 (需要适配 pigx 的 WebSocket 配置)
// pigx 可能使用不同的 WebSocket 实现

3.5 组件库适配

• Element Plus 版本可能不同，需要检查 API 变化
• 图标库：源代码使用 lucide-vue-next，pigx 使用 Element Plus Icons
• 需要统一图标使用方式

四、迁移检查清单

4.1 功能完整性

• 工单 CRUD
• 工单指派/转派
• 工单流程记录
• 聊天室功能
• 实时消息推送 (WebSocket)
• 视频会议集成
• 客服管理
• 文件上传下载
• 词云统计

4.2 权限控制

• 页面访问权限
• 按钮操作权限
• 数据权限（租户隔离）

4.3 用户体验

• 响应式布局
• 加载状态
• 错误提示
• 空状态展示
• 分页功能

4.4 性能优化

• 列表虚拟滚动（如需要）
• 图片懒加载
• 防抖节流
• 请求缓存

五、注意事项

5.1 不要迁移的内容

• Login 页面（pigx 已有完整的登录系统）
• 用户管理相关页面（使用 pigx 原生功能）
• 权限管理相关页面（使用 pigx 原生功能）

5.2 需要重点测试的功能

• WebSocket 实时通信
• 文件上传下载
• 视频会议集成
• 多租户数据隔离
• 权限控制

5.3 AI 功能迁移注意

• AI 对话、智能体、知识库功能最后迁移
• 这些功能归入 dify 模块，不放在 workcase 模块
• 需要与 Dify API 集成测试

六、当前进度

已完成

• API 定义 (workcase.ts, chat.ts)
• 类型定义 (workcase.ts, chatRoom.ts, customer.ts, conversation.ts, wordCloud.ts)
• 基础工单列表页面 (index.vue)
• 工单指派组件 (WorkcaseAssign.vue)
• 工单详情组件 (WorkcaseDetail.vue)
• 聊天室消息组件 (ChatMessage.vue)

进行中

• 管理后台页面 (overview, customerChat, log)

待开始

• 视频会议功能
• 客服管理
• 日志管理
• AI 功能（最后）