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

UrbanLifeline 到 Pigx 迁移文档总览

📋 文档清单

本目录包含了 UrbanLifeline 系统迁移到 Pigx 平台所需的全部技术文档。

核心文档

文档名称	文件路径	说明
需求文档	requirements.md	定义迁移需求，明确创建 pigx-dify 模块
设计文档	design.md	技术设计方案，包含 pigx-dify 模块架构
任务清单	tasks.md	详细的迁移任务列表，包含 AI 模块迁移步骤

技术指南

文档名称	文件路径	用途
权限映射表	permission-mapping.md	权限标识从 urbanLifeline 到 pigx 的映射对照
权限注解转换指南	permission-annotation-guide.md	@PreAuthorize 到 @pms.hasPermission 的转换方法
用户服务配置指南	security-config-guide.md	SecurityUtils 和 RemoteUserService 的使用说明
数据库迁移脚本	database-migration-script.md	PostgreSQL 到 MySQL 的完整迁移 SQL
租户隔离指南	tenant-isolation-guide.md	多租户字段添加和隔离实现方案
Dify模块架构	pigx-dify-architecture.md	新建 pigx-dify 模块的详细架构设计

🎯 迁移要点总结

1. 核心变更

• ✅ 创建独立的 pigx-dify 模块承载 AI 功能
• ✅ 保留原有 Dify API 集成方式
• ✅ 权限体系完全适配 pigx（@pms.hasPermission）
• ✅ 所有业务表添加 tenant_id 实现多租户隔离
• ✅ 数据库从 PostgreSQL 迁移到 MySQL

2. 模块分布

模块	目标位置	状态
工单 (workcase)	pigx-app-server-biz	待迁移
招标 (bidding)	pigx-app-server-biz	待迁移
平台管理 (platform)	pigx-app-server-biz	待迁移
AI功能 (ai)	pigx-dify（新建）	待迁移
消息 (message)	pigx-app-server-biz	待迁移

3. 关键技术适配

权限转换

// 原系统
@PreAuthorize("hasAuthority('workcase:ticket:create')")

// 新系统
@PreAuthorize("@pms.hasPermission('workcase_ticket_add')")

用户信息获取

// 原系统
JwtUtils.getUserId()

// 新系统
SecurityUtils.getUser().getId()

响应格式

// 原系统
ResultDomain.success(data)

// 新系统
R.ok(data)

📝 使用指南

第一步：理解需求和设计

1. 阅读 requirements.md 了解迁移需求
2. 阅读 design.md 理解技术方案
3. 查看 pigx-dify-architecture.md 了解 AI 模块设计

第二步：准备迁移

1. 使用 tasks.md 作为任务清单
2. 参考 permission-mapping.md 准备权限映射
3. 阅读 database-migration-script.md 准备数据库

第三步：执行迁移

1. 按照 permission-annotation-guide.md 转换权限注解
2. 根据 security-config-guide.md 配置用户服务
3. 使用 tenant-isolation-guide.md 实现租户隔离

第四步：验证测试

1. 验证权限控制正确性
2. 测试租户数据隔离
3. 确认 Dify 集成正常
4. 检查所有功能模块

🔧 工具和脚本

批量权限转换

# 权限注解批量替换
find . -name "*.java" -exec sed -i \
  's/@PreAuthorize("hasAuthority(\x27\([^:]*\):\([^:]*\):\([^x27]*\)\x27)")/@PreAuthorize("@pms.hasPermission(\x27\1_\2_\3\x27)")/g' {} \;

数据库迁移

-- 执行顺序
1. 创建 MySQL 数据库结构
2. 添加 tenant_id 字段
3. 迁移业务数据
4. 建立用户映射关系
5. 验证数据完整性

📊 迁移进度跟踪

使用 tasks.md 中的任务清单跟踪进度：

• 基础设施准备
• 权限体系迁移
• 数据库迁移
• 后端代码迁移
• 前端页面迁移
• 集成测试
• 上线部署

🚨 重要提醒

1. 数据备份：迁移前必须完整备份所有数据
2. 权限测试：每个模块迁移后都要测试权限控制
3. 租户隔离：确保所有查询都包含租户条件
4. Dify配置：保存好 Dify API Key 和配置信息
5. 回滚方案：准备好回滚脚本和流程

📞 支持与反馈

如有问题，请参考相应的技术指南文档，或联系技术支持团队。

---

最后更新时间：2024年