urbanLifeline/.kiro/specs/urbanlifeline-to-pigx-migration/tasks.md

Implementation Plan: urbanLifeline 业务功能迁移到 pigx-ai

Overview

将 urbanLifelineServ 和 urbanLifelineWeb 的业务功能迁移到 pigx-ai 平台，完全使用 pigx 原生的用户权限体系，只迁移业务代码和数据。

Tasks

• 1. 数据库迁移准备

  • 分析源项目 PostgreSQL 表结构
  • 生成 MySQL DDL 转换脚本
  • 为所有业务表添加 tenant_id 字段
  • Requirements: 8.1, 8.2, 8.4

• 1.1 编写数据库转换脚本

  • 已完成 database-migration-script.md 文档
  • 包含工单、AI、招标、消息模块的完整 MySQL DDL
  • Validates: Requirements 8.1, 8.2, 8.3, 8.4

• 2. 权限和菜单规划

  • 设计业务功能的权限标识规范
  • 规划前端路由路径
  • 定义菜单层级结构
  • Requirements: 10.2, 11.3

• 2.1 创建权限标识映射表

  • 已完成 permission-mapping.md 文档
  • 包含完整的权限映射和菜单配置 SQL
  • Requirements: 11.1, 11.2

• 2.2 编写权限注解转换指南

  • 已完成 permission-annotation-guide.md 文档
  • 包含 @PreAuthorize 到 @pms.hasPermission 转换规则
  • Requirements: 11.1, 11.2

• 2.3 配置 SecurityUtils 和 RemoteUserService

  • 已完成 security-config-guide.md 文档
  • 包含完整的使用示例和最佳实践
  • Requirements: 11.4, 11.5

• 2.4 配置业务功能菜单

  • 在 pigx sys_menu 表中执行菜单配置 SQL（ID从10000开始）
  • 配置对应的权限标识和路由路径
  • Requirements: 10.2, 11.3

• 2.5 分配角色权限

  • 已在 permission-mapping.md 中提供完整的角色权限分配 SQL
  • 管理员角色分配所有业务权限（menu_id 10000-15000）
  • 普通用户角色分配查看权限
  • 执行时需在 MySQL 中运行 sys_role_menu 插入语句
  • Requirements: 10.3, 11.3

• 3. 后端基础架构搭建

  • 创建 pigx-workcase、pigx-bidding、pigx-dify 三个独立模块
  • 每个模块包含 api 和 biz 子模块
  • 配置 Maven 依赖和模块引用
  • Requirements: 1.1, 2.1, 3.1, 5.1

• 4. 工单模块迁移 (pigx-workcase)

• 4.1 迁移工单实体和 Mapper

  • 已创建 TbWorkcase、TbChatRoom、TbChatRoomMessage、TbChatRoomMember、TbWorkcaseProcess、TbVideoMeeting 实体
  • 使用 pigx 标准格式：@TenantTable、Model、createBy/updateBy/delFlag
  • 已创建对应的 Mapper 接口
  • Requirements: 2.1, 2.4

• 4.2 迁移工单 Service 层

  • 已创建 TbWorkcaseService、TbChatRoomService、TbChatRoomMessageService、TbChatRoomMemberService、TbWorkcaseProcessService、TbVideoMeetingService、TbCustomerServiceService
  • TbChatRoomService 包含完整业务逻辑：创建聊天室、关闭聊天室、成员管理、消息管理、客服分配、服务评分
  • TbVideoMeetingService 包含完整业务逻辑：创建会议、加入会议、开始/结束会议、权限验证
  • TbCustomerServiceService 包含客服管理：获取可用客服、更新状态、工作量管理
  • 已创建对应的 ServiceImpl 实现类
  • Requirements: 2.1, 2.2

• 4.3 迁移工单 Controller 层

  • 已创建 TbWorkcaseController、TbChatRoomController、TbVideoMeetingController、TbCustomerServiceController
  • TbChatRoomController 包含完整的聊天室功能：成员管理、消息管理、客服分配、服务评分
  • TbVideoMeetingController 包含完整的会议功能：创建、加入、开始、结束会议
  • TbCustomerServiceController 包含客服人员管理功能
  • 使用 @HasPermission 权限注解
  • 响应格式使用 R
  • Requirements: 2.1, 11.1, 11.4

• 4.4 迁移视频会议功能

  • 已创建 TbVideoMeetingService 和 TbVideoMeetingServiceImpl
  • 包含创建会议、加入会议、开始会议、结束会议、获取活跃会议等功能
  • 会议访问权限验证（基于聊天室成员）
  • 注：Jitsi JWT Token 生成需要后续配置 Jitsi 服务器参数
  • Requirements: 2.6

• 4.5 迁移聊天室 WebSocket 功能

  • 已创建 ChatRoomWebSocketMessage、ChatRoomNotificationMessage 消息类
  • 已创建 ChatRoomMessageHandler、ChatRoomNotificationHandler 消息处理器
  • 已创建 ChatRoomWebSocketService 用于主动推送消息
  • 使用 pigx-common-websocket 进行实时推送
  • 配置 WebSocket 路径为 /ws/chat
  • Requirements: 2.1, 5.2

• 4.6 迁移 Jitsi JWT Token 生成功能

  • 已创建 JitsiProperties 配置类
  • 已创建 JitsiTokenService 接口和 JitsiTokenServiceImpl 实现
  • 已创建 JitsiTokenController 提供 Token 生成、验证、URL 构建 API
  • 支持一键生成会议信息（房间名+Token+URL）
  • 使用 jjwt 0.12.x 版本 API
  • Requirements: 2.6

• 4.7 迁移词云管理功能

  • 已创建 TbWordCloud 实体类
  • 已创建 TbWordCloudMapper 接口和 XML 映射文件
  • 已创建 TbWordCloudService 接口和 TbWordCloudServiceImpl 实现
  • 已创建 TbWordCloudController 提供词云 CRUD 和词频增加 API
  • 支持词频自动累加（同一天、同一分类的相同词条）
  • Requirements: 2.1

• 5. AI 模块迁移（pigx-dify 模块）

• 5.1 创建 pigx-dify 模块结构

  • 已创建 pigx-dify-api 和 pigx-dify-biz 子模块
  • 已配置 Maven 依赖和模块引用
  • 已创建启动类和配置文件
  • Requirements: 4.1

• 5.2 迁移 AI 实体和数据层

  • 已创建 TbAgent、TbChat、TbChatMessage、TbKnowledge、TbKnowledgeFile、TbKnowledgeFileLog、PromptCard 实体
  • 使用 pigx 标准格式
  • 已创建对应的 Mapper 接口
  • Requirements: 4.4, 4.6

• 5.3 迁移 Dify API 客户端

  • 已创建 DifyApiClient 完整功能（知识库管理、文档管理、对话、工作流、模型管理）
  • 已创建 DifyProperties 配置类
  • 已创建 DifyException 异常类
  • 已创建 StreamCallback 回调接口
  • 已创建所有 DTO 类（ChatRequest/Response、Dataset*、Document*、Retrieval*、Workflow*、Conversation*、MessageHistory*、EmbeddingModel*、RerankModel*、DifyFileInfo）
  • 支持流式响应和阻塞调用两种模式
  • 已配置 OkHttp 依赖
  • 已更新 application.yml 添加 Dify 配置
  • Requirements: 4.2, 4.3

• 5.4 迁移 AI 业务逻辑

  • 已创建 TbAgentService、TbChatService、TbKnowledgeService 等服务接口和实现类
  • Requirements: 4.1, 4.2

• 5.5 迁移 AI Controller 层

  • 已创建 TbAgentController、TbChatController、TbKnowledgeController
  • 使用 @HasPermission 权限注解
  • Requirements: 4.1, 11.1

• 5.6 配置 Dify 集成

  • 已配置 DifyProperties 包含完整配置（API地址、密钥、超时、上传、知识库）
  • 已在 application.yml 中添加 Dify 配置项
  • 配置支持环境变量覆盖
  • Requirements: 4.3, 4.7

• 6. 招标模块迁移 (pigx-bidding)

• 6.1 迁移招标实体和数据层

  • 已创建 TbBiddingProject、TbBiddingDocument、TbBiddingRequirement、TbBidResponse、TbProcessNode 实体
  • 已创建对应的 Mapper 接口
  • Requirements: 1.1, 1.3

• 6.2 迁移招标业务逻辑

  • 已创建 TbBiddingProjectService、TbBiddingDocumentService 等服务接口和实现类
  • Requirements: 1.1, 1.2

• 6.3 迁移招标 API 接口

  • 已创建 TbBiddingProjectController、TbBiddingDocumentController
  • 使用 @HasPermission 权限注解
  • Requirements: 1.1, 1.5

• 7. 平台管理模块迁移 (platform)

• 7.1 迁移平台管理功能

  • 源项目 platform 模块只有启动类，无实际业务代码
  • 平台配置功能可使用 pigx 的 sys_config 表和配置管理功能
  • Requirements: 3.1, 3.2

• 7.2 迁移平台数据表

  • 无需迁移，使用 pigx 现有的配置管理表
  • Requirements: 3.3

• 8. 消息模块迁移 (message)

• 8.1 迁移消息实体和数据层

  • 源项目消息模块主要是邮件/短信发送功能，大部分方法为 TODO 状态
  • pigx 已有完善的消息通知功能（pigx-common-sms、pigx-common-mail）
  • 直接使用 pigx 现有的消息功能即可
  • Requirements: 5.1, 5.4

• 8.2 迁移消息通知功能

  • 使用 pigx-common-websocket 进行实时推送（已在 pigx-workcase 中实现）
  • 使用 pigx-common-sms 进行短信发送
  • 使用 pigx-common-mail 进行邮件发送
  • Requirements: 5.1, 5.2

• 8.3 保留微信通知功能

  • pigx 已有微信公众号/小程序消息推送功能
  • 可通过 pigx-mp 模块实现微信消息推送
  • Requirements: 5.3

• 9. 文件服务适配

• 9.1 替换文件上传逻辑

  • 已在 pigx-workcase-biz、pigx-dify-biz、pigx-bidding-biz 中添加 pigx-common-oss 依赖
  • 使用 pigx 的 OssTemplate 进行文件上传/下载
  • 文件访问 URL 通过 pigx 网关统一管理
  • Requirements: 6.1, 6.2

• 10. 定时任务迁移

• 10.1 迁移定时任务到 XXL-Job

  • 源项目无定时任务需要迁移
  • 如需添加定时任务，可使用 pigx-visual/xxl-job 进行配置
  • Requirements: 7.1, 7.2, 7.3

• 11. 前端页面迁移

• 11.1 迁移工单前端页面

  • ✅ 已创建 API 层 (workcase.ts, chat.ts)
  • ✅ 已创建类型定义 (workcase.ts, chatRoom.ts, customer.ts, conversation.ts, wordCloud.ts)
  • ✅ 已创建工单列表页面 (views/workcase/index.vue)
  • ✅ 已创建工单指派组件 (components/workcase/WorkcaseAssign.vue)
  • ✅ 已创建工单详情组件 (views/workcase/detail/WorkcaseDetail.vue)
  • ✅ 已创建聊天室消息组件 (views/workcase/chatRoom/ChatMessage.vue)
  • 适配 pigx 的 request 工具和响应格式
  • Requirements: 2.5

• 11.2 迁移 AI 前端页面

  • 将 AI 相关页面迁移到 pigx-ai-ui/src/views/dify 目录
  • 包括智能体管理、对话界面、知识库管理
  • 适配 pigx 的 request 工具和响应格式
  • Requirements: 4.5

• 11.3 迁移招标前端页面

  • 将 bidding 页面迁移到 pigx-ai-ui/src/views/urban/bidding
  • 适配 pigx 的 request 工具
  • Requirements: 1.4

• 11.4 迁移平台管理前端页面

  • 将 platform 页面迁移到 pigx-ai-ui/src/views/urban/platform
  • Requirements: 3.4

• 11.5 迁移共享组件

  • 将 shared 包组件迁移到 pigx-ai-ui/src/components/urban
  • 更新导入路径使用 pigx 工具函数
  • Requirements: 9.1, 9.2

• 11.6 适配 API 调用

  • 创建 pigx-ai-ui/src/api/urban 目录
  • 创建 workcase.ts、bidding.ts、platform.ts API 定义
  • 创建 pigx-ai-ui/src/api/dify 目录
  • 创建 agent.ts、chat.ts、knowledge.ts API 定义
  • 使用 pigx 的 request 工具和 R 响应格式
  • 更新 API 路径为 pigx 网关规则
  • Requirements: 1.5, 9.4

• 12. 数据迁移执行

• 12.1 执行数据库 DDL 脚本

  • 在 MySQL 中执行 database-migration-script.md 中的建表语句
  • 验证表结构正确性
  • Requirements: 8.1, 8.2

• 12.2 执行业务数据迁移

  • 运行数据迁移脚本
  • 验证数据完整性
  • Requirements: 8.5

• 13. 集成测试和验证

• 13.1 后端编译验证

  • 确保所有迁移代码可以通过编译
  • 验证 Maven 依赖正确
  • Requirements: 所有后端需求

• 13.2 端到端功能测试

  • 测试所有迁移功能的完整流程
  • 验证权限控制正确性
  • Requirements: 所有需求

• 13.3 租户隔离验证

  • 验证多租户数据隔离正确性
  • Requirements: 8.4, 11.6

• 14. 最终验收

  • 确保所有功能正常运行
  • 确认权限控制有效
  • 验证多租户数据隔离

Notes

• 任务 1、2.1、2.2、2.3 的文档已完成，可直接使用
• 重点关注权限适配和用户服务调用的正确性
• 已创建三个独立模块：pigx-workcase、pigx-bidding、pigx-dify
• 每个模块包含 api 和 biz 子模块，遵循 pigx 架构规范
• 实体类使用 pigx 标准格式：@TenantTable、Model、createBy/updateBy/delFlag
• 前端迁移需要适配 pigx-ai-ui 的技术栈（Vue3 + TypeScript + Element Plus）
• 数据库迁移脚本已在 database-migration-script.md 中准备好

已创建的文件

pigx-ai-ui 前端已迁移文件

API 层

• src/api/workcase/workcase.ts - 工单管理 API
• src/api/workcase/chat.ts - 聊天室、客服、视频会议 API

类型定义

• src/types/workcase/workcase.ts - 工单相关类型
• src/types/workcase/chatRoom.ts - 聊天室相关类型
• src/types/workcase/customer.ts - 客服相关类型
• src/types/workcase/conversation.ts - 对话相关类型
• src/types/workcase/wordCloud.ts - 词云相关类型

组件

• src/components/workcase/WorkcaseAssign.vue - 工单指派组件

页面

• src/views/workcase/index.vue - 工单列表页面
• src/views/workcase/detail/WorkcaseDetail.vue - 工单详情组件
• src/views/workcase/detail/WorkcaseDetail.scss - 工单详情样式
• src/views/workcase/chatRoom/ChatMessage.vue - 聊天室消息组件

导出文件

• src/views/workcase/chatRoom/index.ts
• src/views/workcase/detail/index.ts
• Entity: TbWorkcase, TbChatRoom, TbChatRoomMessage, TbChatRoomMember, TbWorkcaseProcess, TbVideoMeeting, TbCustomerService, TbWordCloud
• Mapper: TbWorkcaseMapper, TbChatRoomMapper, TbChatRoomMessageMapper, TbChatRoomMemberMapper, TbWorkcaseProcessMapper, TbVideoMeetingMapper, TbCustomerServiceMapper, TbWordCloudMapper
• Service: TbWorkcaseService, TbChatRoomService（含完整业务逻辑）, TbChatRoomMessageService, TbChatRoomMemberService, TbWorkcaseProcessService, TbVideoMeetingService（含完整业务逻辑）, TbCustomerServiceService, TbWordCloudService, JitsiTokenService
• Controller: TbWorkcaseController, TbChatRoomController（含成员/消息/客服分配API）, TbVideoMeetingController（含创建/加入/开始/结束会议API）, TbCustomerServiceController, TbWordCloudController, JitsiTokenController
• WebSocket: ChatRoomWebSocketMessage, ChatRoomNotificationMessage, ChatRoomMessageHandler, ChatRoomNotificationHandler, ChatRoomWebSocketService
• Config: JitsiProperties, application.yml (port: 7070, WebSocket: /ws/chat)
• Application: PigxWorkcaseApplication

聊天室功能已迁移的API：

• 聊天室CRUD：创建、查询、修改、关闭、删除
• 成员管理：添加成员、移除成员、获取成员列表、获取未读数、更新已读状态
• 消息管理：发送消息、分页查询消息、删除消息
• 客服分配：自动分配客服到聊天室
• 服务评分：提交聊天室服务评分

视频会议功能已迁移的API：

• 会议CRUD：创建、查询、删除
• 会议操作：获取会议信息、加入会议、开始会议、结束会议
• 聊天室关联：获取聊天室当前活跃会议

客服人员管理已迁移的API：

• 客服CRUD：新增、查询、修改、删除
• 状态管理：更新客服在线状态
• 可用客服：获取可接待客服列表

WebSocket 实时推送功能：

• 消息类型：chat_message（聊天消息）、chat_notification（通知消息）
• 通知类型：member_join（成员加入）、member_leave（成员离开）、typing（正在输入）、room_closed（聊天室关闭）
• ChatRoomWebSocketService：主动推送消息、广播到聊天室、发送给指定用户

Jitsi JWT Token 功能：

• 生成 JWT Token：支持主持人/普通成员角色
• 验证 Token：检查 Token 有效性和过期时间
• 构建 iframe URL：包含默认配置和自定义配置
• 生成房间名：基于工单ID生成唯一房间名
• 一键生成会议信息：房间名+Token+URL

词云管理功能：

• 词云CRUD：新增、查询、修改、删除
• 词频累加：同一天、同一分类的相同词条自动累加词频
• 分页查询：支持按词语、分类、日期筛选

pigx-dify 模块

• Entity: TbAgent, TbChat, TbChatMessage, TbKnowledge, TbKnowledgeFile, TbKnowledgeFileLog, PromptCard
• Mapper: TbAgentMapper, TbChatMapper, TbChatMessageMapper, TbKnowledgeMapper, TbKnowledgeFileMapper, TbKnowledgeFileLogMapper
• Service: TbAgentService, TbChatService, TbChatMessageService, TbKnowledgeService, TbKnowledgeFileService, TbKnowledgeFileLogService
• Controller: TbAgentController, TbChatController, TbKnowledgeController
• Client: DifyApiClient（完整的 Dify API 客户端）
• Client DTO: ChatRequest, ChatResponse, DatasetCreateRequest, DatasetCreateResponse, DatasetDetailResponse, DatasetListResponse, DatasetUpdateRequest, DocumentListResponse, DocumentStatusResponse, DocumentUploadRequest, DocumentUploadResponse, RetrievalModel, RetrievalRequest, RetrievalResponse, WorkflowRunRequest, WorkflowRunResponse, ConversationListResponse, ConversationVariablesResponse, MessageHistoryResponse, EmbeddingModelResponse, RerankModelResponse, DifyFileInfo
• Callback: StreamCallback（流式响应回调接口）
• Exception: DifyException
• Config: DifyProperties, application.yml (port: 7080, Dify API 配置)
• Application: PigxDifyApplication

Dify API 客户端功能：

• 知识库管理：创建、查询、更新、删除知识库
• 文档管理：上传文档、查询文档列表、查询文档状态、删除文档
• 知识库检索：从知识库检索相关内容
• 对话功能：流式对话、阻塞式对话、停止对话、消息反馈
• 工作流：执行工作流（阻塞模式）
• 对话历史：获取消息历史、对话列表、对话变量
• 模型管理：获取嵌入模型列表、Rerank模型列表
• 通用HTTP：GET、POST、PATCH、DELETE 方法

pigx-bidding 模块

• Entity: TbBiddingProject, TbBiddingDocument, TbBiddingRequirement, TbBidResponse, TbProcessNode
• Mapper: TbBiddingProjectMapper, TbBiddingDocumentMapper, TbBiddingRequirementMapper, TbBidResponseMapper, TbProcessNodeMapper
• Service: TbBiddingProjectService, TbBiddingDocumentService, TbBiddingRequirementService, TbBidResponseService, TbProcessNodeService
• Controller: TbBiddingProjectController, TbBiddingDocumentController
• Application: PigxBiddingApplication
• Config: application.yml (port: 7090)