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

Requirements Document

Introduction

本文档定义了将 urbanLifelineServ 和 urbanLifelineWeb 项目的业务功能迁移到 pigx-ai 和 pigx-ai-ui 平台的需求规范。

核心原则：

• 只迁移业务功能代码（招标、工单、平台管理、AI、消息等）
• 人员、部门、权限、认证等基础设施完全使用 pigx 原生实现
• 数据库从 PostgreSQL 迁移到 MySQL
• 前端从微前端架构合并到 pigx-ai-ui 单体应用

Glossary

• Business_Module: 需要迁移的业务模块（bidding, workcase, platform, ai, message）
• pigx-app-server: pigx 平台的业务服务模块，用于承载迁移的业务功能
• pigx-dify: 新建的 pigx 平台 AI 模块，用于承载原 urbanLifeline 的 AI 功能和 Dify 集成
• pigx-knowledge: pigx 平台原有的 AI 知识库模块（不使用）
• PigxUser: pigx 原生的用户实体，迁移后的业务代码需要使用此用户模型
• R: pigx 统一响应格式
• DifyApiClient: 与 Dify 平台交互的客户端，保留在 pigx-dify 模块中

Requirements

Requirement 1: 招标模块迁移 (bidding)

User Story: As a 业务用户, I want to 在 pigx 平台上使用招标功能, so that 可以进行招标项目管理。

Acceptance Criteria

1. WHEN Business_Module 迁移 bidding 服务 THEN pigx-app-server SHALL 包含招标业务的 Controller、Service、Mapper 层代码
2. WHEN Business_Module 处理招标用户关联 THEN pigx-app-server SHALL 使用 PigxUser 替代原有的 User 实体
3. WHEN Business_Module 迁移招标数据表 THEN Database_Migrator SHALL 将 PostgreSQL 表结构转换为 MySQL 并添加 tenant_id 租户字段
4. WHEN Business_Module 迁移招标前端页面 THEN pigx-ai-ui SHALL 在 src/views/bidding 目录下包含所有招标页面组件
5. WHEN Business_Module 处理招标 API 调用 THEN pigx-ai-ui SHALL 使用 pigx 的 request 工具和统一响应格式

Requirement 2: 工单模块迁移 (workcase)

User Story: As a 业务用户, I want to 在 pigx 平台上使用工单功能, so that 可以进行工单流转和处理。

Acceptance Criteria

1. WHEN Business_Module 迁移 workcase 服务 THEN pigx-app-server SHALL 包含工单业务的完整代码
2. WHEN Business_Module 处理工单分配 THEN pigx-app-server SHALL 通过 pigx-upms 的 RemoteUserService 获取用户信息
3. WHEN Business_Module 处理工单流程 THEN pigx-app-server SHALL 评估是否集成 pigx-flow 工作流引擎
4. WHEN Business_Module 迁移工单数据表 THEN Database_Migrator SHALL 将表结构转换为 MySQL 并关联 pigx 的 sys_user 表
5. WHEN Business_Module 迁移工单前端页面 THEN pigx-ai-ui SHALL 在 src/views/workcase 目录下包含所有工单页面
6. WHEN Business_Module 处理 Jitsi 视频会议集成 THEN pigx-app-server SHALL 保留视频会议功能并适配 pigx 认证

Requirement 3: 平台管理模块迁移 (platform)

User Story: As a 管理员, I want to 在 pigx 平台上使用平台管理功能, so that 可以进行业务配置和管理。

Acceptance Criteria

1. WHEN Business_Module 迁移 platform 服务 THEN pigx-app-server SHALL 包含平台管理业务代码
2. WHEN Business_Module 处理平台配置 THEN pigx-app-server SHALL 使用 pigx 的配置管理机制
3. WHEN Business_Module 迁移平台数据表 THEN Database_Migrator SHALL 将表结构转换为 MySQL
4. WHEN Business_Module 迁移平台前端页面 THEN pigx-ai-ui SHALL 在 src/views/platform 目录下包含管理页面

Requirement 4: AI 模块迁移 (创建新的 pigx-dify 模块)

User Story: As a 用户, I want to 在 pigx 平台上使用 AI 功能, so that 可以使用智能问答和知识库。

Acceptance Criteria

1. WHEN Business_Module 迁移 ai 服务 THEN 新建的 pigx-dify 模块 SHALL 承载所有 AI 业务逻辑
2. WHEN Business_Module 处理 AI 对话 THEN pigx-dify SHALL 保留原有的 Dify API 集成方式
3. WHEN Business_Module 处理 Dify 集成 THEN pigx-dify SHALL 包含 DifyApiClient 和相关配置管理
4. WHEN Business_Module 迁移 AI 数据表 THEN Database_Migrator SHALL 将 tb_agent、tb_chat、tb_chat_message、tb_knowledge 等表转换为 MySQL
5. WHEN Business_Module 迁移 AI 前端页面 THEN pigx-ai-ui SHALL 在 src/views/dify 目录下包含 AI 对话界面
6. WHEN Business_Module 处理聊天记录 THEN pigx-dify SHALL 保持原有的 tb_chat 和 tb_chat_message 表结构
7. WHEN Business_Module 处理知识库 THEN pigx-dify SHALL 保持与 Dify Dataset API 的集成

Requirement 5: 消息模块迁移 (message)

User Story: As a 用户, I want to 在 pigx 平台上接收消息通知, so that 可以及时了解业务动态。

Acceptance Criteria

1. WHEN Business_Module 迁移 message 服务 THEN pigx-app-server SHALL 包含消息通知业务代码
2. WHEN Business_Module 处理消息推送 THEN pigx-app-server SHALL 使用 pigx-common-websocket 进行实时推送
3. WHEN Business_Module 处理微信通知 THEN pigx-app-server SHALL 保留微信消息推送功能
4. WHEN Business_Module 迁移消息数据表 THEN Database_Migrator SHALL 将表结构转换为 MySQL

Requirement 6: 文件服务适配

User Story: As a 用户, I want to 上传和下载文件, so that 可以管理业务相关的文件资源。

Acceptance Criteria

1. WHEN Business_Module 处理文件上传 THEN pigx-app-server SHALL 使用 pigx-common-oss 进行文件存储
2. WHEN Business_Module 处理文件访问 THEN pigx-app-server SHALL 适配 pigx 的文件访问 URL 格式
3. IF Business_Module 有自定义文件处理逻辑 THEN pigx-app-server SHALL 在 OSS 基础上扩展实现

Requirement 7: 定时任务适配

User Story: As a 系统管理员, I want to 管理定时任务, so that 可以执行周期性业务处理。

Acceptance Criteria

1. WHEN Business_Module 迁移 crontab 任务 THEN pigx-visual/xxl-job SHALL 包含迁移后的定时任务
2. WHEN Business_Module 处理任务调度 THEN XXL-Job SHALL 替代原有的调度机制
3. WHEN Business_Module 处理任务执行 THEN pigx-app-server SHALL 提供任务执行的 HTTP 接口

Requirement 8: 数据库迁移

User Story: As a DBA, I want to 将业务数据迁移到 MySQL, so that 数据可以在 pigx 平台运行。

Acceptance Criteria

1. WHEN Database_Migrator 处理业务表 THEN Migration_System SHALL 生成 MySQL DDL 脚本
2. WHEN Database_Migrator 处理数据类型 THEN Migration_System SHALL 正确映射 PostgreSQL 类型到 MySQL
3. WHEN Database_Migrator 处理用户关联 THEN Migration_System SHALL 将原 user_id 映射到 pigx 的 sys_user.user_id
4. WHEN Database_Migrator 处理租户支持 THEN Migration_System SHALL 为业务表添加 tenant_id 字段
5. WHEN Database_Migrator 执行数据迁移 THEN Migration_System SHALL 保证业务数据完整性

Requirement 9: 前端共享组件迁移

User Story: As a 前端开发者, I want to 迁移共享组件到 pigx-ai-ui, so that 业务页面可以复用这些组件。

Acceptance Criteria

1. WHEN Frontend_Migrator 处理 shared 组件 THEN pigx-ai-ui SHALL 在 src/components/urban 目录下包含迁移的组件
2. WHEN Frontend_Migrator 处理组件依赖 THEN pigx-ai-ui SHALL 更新导入路径使用 pigx 的工具函数
3. WHEN Frontend_Migrator 处理样式 THEN pigx-ai-ui SHALL 合并样式并避免与 pigx 样式冲突
4. WHEN Frontend_Migrator 处理 API 调用 THEN 组件 SHALL 使用 pigx 的 request 工具

Requirement 10: 路由和菜单配置

User Story: As a 管理员, I want to 在 pigx 菜单中看到迁移的功能, so that 可以访问业务功能。

Acceptance Criteria

1. WHEN Frontend_Migrator 处理路由 THEN pigx-ai-ui SHALL 在路由配置中添加业务模块路由
2. WHEN Admin 配置菜单 THEN pigx-upms SHALL 在 sys_menu 表中添加业务功能菜单
3. WHEN Admin 配置权限 THEN pigx-upms SHALL 为业务功能配置相应的权限标识

Requirement 11: 权限模型适配

User Story: As a 系统管理员, I want to 在 pigx 权限体系中配置业务功能权限, so that 可以控制用户对迁移功能的访问。

Acceptance Criteria

1. WHEN Business_Module 迁移权限注解 THEN pigx-app-server SHALL 将 @PreAuthorize 替换为 @HasPermission
2. WHEN Business_Module 处理权限标识 THEN pigx-app-server SHALL 使用 pigx 权限命名规范 (module_action 格式)
3. WHEN Admin 配置业务权限 THEN pigx-upms SHALL 在 sys_menu 表中添加对应的权限菜单项
4. WHEN Business_Module 获取用户信息 THEN pigx-app-server SHALL 使用 SecurityUtils.getUser() 获取 PigxUser
5. WHEN Business_Module 调用用户服务 THEN pigx-app-server SHALL 通过 RemoteUserService 进行 Feign 调用
6. IF Business_Module 需要数据权限控制 THEN pigx-app-server SHALL 利用 pigx 的租户和部门隔离机制