# UrbanLifeline 到 Pigx 迁移文档总览

## 📋 文档清单

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

### 核心文档

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

### 技术指南

| 文档名称 | 文件路径 | 用途 |
|---------|---------|------|
| **权限映射表** | [permission-mapping.md](./permission-mapping.md) | 权限标识从 urbanLifeline 到 pigx 的映射对照 |
| **权限注解转换指南** | [permission-annotation-guide.md](./permission-annotation-guide.md) | @PreAuthorize 到 @pms.hasPermission 的转换方法 |
| **用户服务配置指南** | [security-config-guide.md](./security-config-guide.md) | SecurityUtils 和 RemoteUserService 的使用说明 |
| **数据库迁移脚本** | [database-migration-script.md](./database-migration-script.md) | PostgreSQL 到 MySQL 的完整迁移 SQL |
| **租户隔离指南** | [tenant-isolation-guide.md](./tenant-isolation-guide.md) | 多租户字段添加和隔离实现方案 |
| **Dify模块架构** | [pigx-dify-architecture.md](./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. 关键技术适配

#### 权限转换
```java
// 原系统
@PreAuthorize("hasAuthority('workcase:ticket:create')")

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

#### 用户信息获取
```java
// 原系统
JwtUtils.getUserId()

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

#### 响应格式
```java
// 原系统
ResultDomain.success(data)

// 新系统
R.ok(data)
```

## 📝 使用指南

### 第一步：理解需求和设计
1. 阅读 [requirements.md](./requirements.md) 了解迁移需求
2. 阅读 [design.md](./design.md) 理解技术方案
3. 查看 [pigx-dify-architecture.md](./pigx-dify-architecture.md) 了解 AI 模块设计

### 第二步：准备迁移
1. 使用 [tasks.md](./tasks.md) 作为任务清单
2. 参考 [permission-mapping.md](./permission-mapping.md) 准备权限映射
3. 阅读 [database-migration-script.md](./database-migration-script.md) 准备数据库

### 第三步：执行迁移
1. 按照 [permission-annotation-guide.md](./permission-annotation-guide.md) 转换权限注解
2. 根据 [security-config-guide.md](./security-config-guide.md) 配置用户服务
3. 使用 [tenant-isolation-guide.md](./tenant-isolation-guide.md) 实现租户隔离

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

## 🔧 工具和脚本

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

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

## 📊 迁移进度跟踪

使用 [tasks.md](./tasks.md) 中的任务清单跟踪进度：
- [ ] 基础设施准备
- [ ] 权限体系迁移
- [ ] 数据库迁移
- [ ] 后端代码迁移
- [ ] 前端页面迁移
- [ ] 集成测试
- [ ] 上线部署

## 🚨 重要提醒

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

## 📞 支持与反馈

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

---
*最后更新时间：2024年*