pos-system/docs/vi/guides/iam-migration.md

# Hướng Dẫn Migration: Auth Service → IAM Service

Tài liệu này hướng dẫn cách migrate từ `auth-service` sang `iam-service`.

## Tổng Quan

IAM Service là phiên bản mở rộng của Auth Service với các tính năng bổ sung về Identity Management, Access Management, và Governance & Compliance. Tất cả các API endpoints của Auth Service vẫn được giữ nguyên để đảm bảo backward compatibility.

### Migration Process Flow

```mermaid
graph TD
 Start([ Bắt đầu Migration]) --> Backup[ Step 1: Backup<br/>Database & Code]
 Backup --> Update[ Step 2: Update Codebase<br/>Package refs, Env vars]
 Update --> Migrate[ Step 3: Run Prisma Migration<br/>Add IAM models]
 Migrate --> Deploy{ Deployment Strategy}

 Deploy -->|Khuyến nghị| BlueGreen[ Blue-Green Deployment]
 Deploy -->|Dễ dàng hơn| InPlace[ In-Place Migration]

 BlueGreen --> DeployNew[Deploy IAM Service mới]
 DeployNew --> Verify1[ Verify hoạt động]
 Verify1 --> Switch[ Switch traffic]
 Switch --> Monitor1[ Monitor]
 Monitor1 --> Success{Thành công?}

 InPlace --> DeployBoth[Deploy cả 2 service]
 DeployBoth --> GradualRoute[ Gradually route traffic]
 GradualRoute --> Monitor2[ Monitor]
 Monitor2 --> Success

 Success -->|Yes| Cleanup[ Decommission Auth Service]
 Success -->|No| Rollback[⏮ Rollback]

 Cleanup --> Complete([ Migration Hoàn Thành])
 Rollback --> End([ Migration Failed])

 style Start fill:#1a472a,stroke:#2d8659,stroke-width:3px,color:#fff
 style Complete fill:#1a472a,stroke:#2d8659,stroke-width:3px,color:#fff
 style End fill:#4a1a1a,stroke:#8b2e2e,stroke-width:3px,color:#fff
 style Backup fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Update fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Migrate fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Deploy fill:#4a2c5f,stroke:#6b4391,color:#fff
 style BlueGreen fill:#2d5016,stroke:#4a7c2c,color:#fff
 style InPlace fill:#5f4a1e,stroke:#8b7030,color:#fff
 style DeployNew fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Verify1 fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Switch fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Monitor1 fill:#1e3a5f,stroke:#2e5984,color:#fff
 style DeployBoth fill:#1e3a5f,stroke:#2e5984,color:#fff
 style GradualRoute fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Monitor2 fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Success fill:#4a2c5f,stroke:#6b4391,color:#fff
 style Cleanup fill:#1e3a5f,stroke:#2e5984,color:#fff
 style Rollback fill:#4a1a1a,stroke:#8b2e2e,color:#fff
```

### Architecture Evolution

```mermaid
graph TB
 subgraph Before["Auth Service (Trước)"]
 AuthAPI[ Authentication APIs<br/>/api/v1/auth/*]
 RBACAPI[ RBAC APIs<br/>/api/v1/rbac/*]
 MFAAPI[ MFA APIs<br/>/api/v1/mfa/*]
 SessionAPI[ Session APIs<br/>/api/v1/sessions/*]
 OIDCAPI[ OIDC APIs<br/>/api/v1/oidc/*]
 end

 subgraph After["IAM Service (Sau)"]
 AuthAPI2[ Authentication APIs<br/>/api/v1/auth/*<br/> Giữ nguyên]
 RBACAPI2[ RBAC APIs<br/>/api/v1/rbac/*<br/> Giữ nguyên]
 MFAAPI2[ MFA APIs<br/>/api/v1/mfa/*<br/> Giữ nguyên]
 SessionAPI2[ Session APIs<br/>/api/v1/sessions/*<br/> Giữ nguyên]
 OIDCAPI2[ OIDC APIs<br/>/api/v1/oidc/*<br/> Giữ nguyên]

 IdentityAPI[ Identity Management<br/>/api/v1/identity/*<br/> MỚI]
 AccessAPI[ Access Management<br/>/api/v1/access/*<br/> MỚI]
 GovernanceAPI[ Governance<br/>/api/v1/governance/*<br/> MỚI]
 end

 Before -.->|Backward Compatible<br/>Migration| After

 style Before fill:#2d2d2d,stroke:#4a4a4a,color:#fff
 style After fill:#1a472a,stroke:#2d8659,color:#fff
 style AuthAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style RBACAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style MFAAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style SessionAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style OIDCAPI fill:#1e3a5f,stroke:#2e5984,color:#fff
 style AuthAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style RBACAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style MFAAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style SessionAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style OIDCAPI2 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style IdentityAPI fill:#4a2c5f,stroke:#6b4391,color:#fff
 style AccessAPI fill:#4a2c5f,stroke:#6b4391,color:#fff
 style GovernanceAPI fill:#4a2c5f,stroke:#6b4391,color:#fff
```

## Backward Compatibility

 **Tất cả các endpoints hiện tại vẫn hoạt động bình thường:**

- `/api/v1/auth/*` - Authentication endpoints
- `/api/v1/rbac/*` - RBAC endpoints
- `/api/v1/mfa/*` - MFA endpoints
- `/api/v1/sessions/*` - Session management endpoints
- `/api/v1/oidc/*` - OIDC endpoints

Không có breaking changes. Các clients hiện tại có thể tiếp tục sử dụng các endpoints này mà không cần thay đổi.

## Các Thay Đổi

### 1. Service Name

- **Cũ**: `auth-service`
- **Mới**: `iam-service`

### 2. Package Name

- **Cũ**: `@goodgo/auth-service`
- **Mới**: `@goodgo/iam-service`

### 3. Database Schema

Database schema được mở rộng với các models mới nhưng **không xóa hoặc thay đổi** các models hiện có:

**Models mới được thêm:**
- `Organization` - Quản lý tổ chức
- `Group` - Quản lý nhóm
- `GroupMember` - Thành viên nhóm
- `GroupPermission` - Quyền nhóm
- `UserProfile` - Profile mở rộng
- `IdentityVerification` - Xác thực danh tính
- `AccessRequest` - Yêu cầu truy cập
- `AccessReview` - Đánh giá truy cập
- `ComplianceReport` - Báo cáo tuân thủ
- `PolicyTemplate` - Template policy
- `RiskScore` - Điểm rủi ro

**User model được mở rộng:**
- Thêm field `organizationId` (optional)
- Thêm các relations mới (optional)

### 4. API Endpoints Mới

#### Identity Management
- `/api/v1/identity/users/*` - User lifecycle management
- `/api/v1/identity/users/:id/profile` - Profile management
- `/api/v1/identity/verification/*` - Identity verification
- `/api/v1/identity/organizations/*` - Organization management
- `/api/v1/identity/groups/*` - Group management

#### Access Management
- `/api/v1/access/requests/*` - Access requests
- `/api/v1/access/reviews/*` - Access reviews
- `/api/v1/access/analytics/*` - Access analytics

#### Governance
- `/api/v1/governance/compliance/*` - Compliance reports
- `/api/v1/governance/policies/*` - Policy governance
- `/api/v1/governance/risk/*` - Risk management
- `/api/v1/governance/reports/*` - Reporting dashboard

### 5. Environment Variables

Một số biến môi trường mới có thể được thêm trong tương lai cho các tính năng IAM nâng cao (email service, SMS service, file storage), nhưng không ảnh hưởng đến các biến hiện tại.

### 6. Deployment Configuration

**Docker Compose:**
- Service name: `auth-service` → `iam-service`
- Container name: `auth-service-local` → `iam-service-local`

**Kubernetes:**
- Deployment name: `auth-service` → `iam-service`
- Service name: `auth-service` → `iam-service`
- ConfigMap: `auth-service-config` → `iam-service-config`
- Secrets: `auth-service-secrets` → `iam-service-secrets`

## Migration Steps

### Step 1: Backup (Quan Trọng!)

```bash
# Backup database
pg_dump $DATABASE_URL > auth-service-backup.sql

# Backup code (nếu cần rollback)
cp -r services/auth-service services/auth-service.backup
```

### Step 2: Update Codebase

1. **Update package references:**
 ```bash
 # Tìm và thay thế trong code
 find . -type f -name "*.ts" -o -name "*.js" -o -name "*.json" | xargs sed -i '' 's/@goodgo\/auth-service/@goodgo\/iam-service/g'
 ```

2. **Update environment variables:**
 - Update `SERVICE_NAME=iam-service` trong tất cả env files
 - Update Docker Compose và Kubernetes configs

3. **Run Prisma migration:**
 ```bash
 cd services/iam-service
 pnpm prisma generate
 pnpm prisma migrate dev --name add_iam_models
 ```

### Step 3: Deployment

#### Deployment Strategy Comparison

```mermaid
graph LR
 subgraph BlueGreen[" Blue-Green Deployment (Khuyến nghị)"]
 BG1[Ưu điểm:<br/> Zero downtime<br/> Easy rollback<br/> Safe testing]
 BG2[Nhược điểm:<br/> Cần thêm resources<br/> Phức tạp hơn]
 end

 subgraph InPlace[" In-Place Migration"]
 IP1[Ưu điểm:<br/> Simple setup<br/> Less resources<br/> Gradual migration]
 IP2[Nhược điểm:<br/> Potential downtime<br/> Harder rollback<br/> Higher risk]
 end

 Decision{Chọn Strategy} -->|Production| BlueGreen
 Decision -->|Staging/Dev| InPlace

 style BlueGreen fill:#1a472a,stroke:#2d8659,color:#fff
 style InPlace fill:#5f4a1e,stroke:#8b7030,color:#fff
 style BG1 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style BG2 fill:#4a1a1a,stroke:#8b2e2e,color:#fff
 style IP1 fill:#2d5016,stroke:#4a7c2c,color:#fff
 style IP2 fill:#4a1a1a,stroke:#8b2e2e,color:#fff
 style Decision fill:#4a2c5f,stroke:#6b4391,color:#fff
```

#### Option A: Blue-Green Deployment (Khuyến Nghị)

1. **Deploy iam-service mới:**
 ```bash
 kubectl apply -f deployments/staging/kubernetes/iam-service.yaml
 ```

2. **Verify iam-service hoạt động tốt**

3. **Switch traffic:**
 - Update Ingress để point đến `iam-service`
 - Hoặc dùng weighted routing để gradually migrate

4. **Monitor và verify**

5. **Decommission auth-service cũ sau khi verify**

#### Option B: In-Place Migration

1. **Deploy cả `auth-service` và `iam-service` cùng lúc**

2. **Gradually route traffic từ auth-service sang iam-service**

3. **Monitor performance và errors**

4. **Sau khi verify mọi thứ hoạt động tốt, có thể deprecate `auth-service`**

### Step 4: Rollback (Nếu Cần)

```bash
# Restore database
psql $DATABASE_URL < auth-service-backup.sql

# Switch back to auth-service in docker-compose
# hoặc
kubectl rollout undo deployment/auth-service
```

## Verification Checklist

- [ ] All existing endpoints still work
- [ ] Database migration successful
- [ ] New IAM endpoints working
- [ ] No breaking changes in responses
- [ ] Performance metrics acceptable
- [ ] Error rates normal
- [ ] All clients can connect successfully

## Troubleshooting

### Database Migration Issues

```bash
# Check migration status
pnpm prisma migrate status

# Reset migration (DEV ONLY!)
pnpm prisma migrate reset
```

### Service Connection Issues

```bash
# Check service health
curl http://localhost:5001/health

# Check logs
docker logs iam-service-local
# hoặc
kubectl logs deployment/iam-service
```

## Support

Nếu gặp vấn đề trong quá trình migration, vui lòng:
1. Check logs và error messages
2. Review migration guide này
3. Contact team lead hoặc DevOps team

## Quick Tips

### Migration Best Practices

 **DO:**
- Backup database trước khi migrate
- Test migration trên staging trước
- Monitor metrics trong quá trình migration
- Sử dụng Blue-Green deployment cho production
- Prepare rollback plan trước khi deploy
- Document tất cả các thay đổi

 **DON'T:**
- Skip backup step
- Migrate trực tiếp trên production
- Ignore error logs
- Deploy vào giờ peak traffic
- Quên update environment variables
- Rush migration process

### Common Issues & Solutions

| Vấn đề | Nguyên nhân | Giải pháp |
|--------|-------------|-----------|
| Migration failed | Database connection | Check `DATABASE_URL` trong `.env` |
| Service won't start | Missing env vars | Verify tất cả env vars được set |
| Slow performance | Database indexes | Run Prisma migrations đầy đủ |
| Connection timeout | Network issues | Check firewall & security groups |
| New endpoints 404 | Routing config | Update Traefik/Ingress config |

### Troubleshooting Quick Reference

```bash
# Check migration status
pnpm prisma migrate status

# View service logs
docker logs iam-service-local -f
kubectl logs deployment/iam-service -f --tail=100

# Test health endpoint
curl http://localhost:5001/health
curl http://localhost:5001/health/ready

# Database connection test
psql $DATABASE_URL -c "SELECT 1"

# Rollback migration (CAREFUL!)
pnpm prisma migrate reset # DEV ONLY
kubectl rollout undo deployment/iam-service
```

### Color Palette Reference

**Diagram Colors:**
- **Success/Recommended**: `#1a472a` (Dark green)
- **Process/Info**: `#1e3a5f` (Dark blue)
- **Decision/Important**: `#4a2c5f` (Dark purple)
- **Warning/Alternative**: `#5f4a1e` (Dark yellow)
- **Error/Rollback**: `#4a1a1a` (Dark red)

### Important Reminders

- **Always backup** trước khi migrate
- **Test thoroughly** trên staging
- **Monitor closely** sau khi deploy
- **Prepare rollback** plan
- **Document changes** cho team
- ⏰ **Schedule wisely** - tránh giờ peak
- **Communicate** với team và stakeholders

---

**Last Updated**: 2024-12-30