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 迁移顺序（按优先级）

#### 第一阶段：基础设施 (已完成)
- [x] API 定义迁移
- [x] 基础工单管理页面

#### 第二阶段：工单核心功能
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 调用适配
```typescript
// 源代码
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 响应格式适配
```typescript
// 源代码 (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 文件上传适配
```typescript
// 源代码
import { fileAPI } from 'shared/api/file'
await fileAPI.uploadFile({ file, module, optsn })

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

### 3.4 WebSocket 适配
```typescript
// 源代码 (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 集成测试

## 六、当前进度

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

### 进行中
- [ ] 管理后台页面 (overview, customerChat, log)

### 待开始
- [ ] 视频会议功能
- [ ] 客服管理
- [ ] 日志管理
- [ ] AI 功能（最后）