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.

## 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

#### 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

---

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