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

# Migration Guide: 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`
- Traefik labels: Thêm routes mới cho `/api/v1/identity/*`, `/api/v1/access/*`, `/api/v1/governance/*`

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

### Bước 1: Backup

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

# Backup code
cp -r services/auth-service services/auth-service.backup
```

### Bước 2: Database Migration

```bash
cd services/iam-service

# Generate Prisma client với schema mới
pnpm prisma generate

# Tạo migration
pnpm prisma migrate dev --name add_iam_models

# Verify migration
pnpm prisma studio  # Check database structure
```

### Bước 3: Update Dependencies

```bash
# Install dependencies (nếu có package mới)
pnpm install

# Verify types compile
pnpm typecheck
```

### Bước 4: Update Deployment

**Local Development:**
```bash
cd deployments/local
# Update docker-compose.yml (đã được cập nhật)
docker-compose up -d iam-service
```

**Staging/Production:**
- Update Kubernetes manifests
- Update ingress routes
- Update ConfigMaps và Secrets

### Bước 5: Verify Backward Compatibility

Test tất cả các endpoints cũ vẫn hoạt động:

```bash
# Test auth endpoints
curl http://localhost/api/v1/auth/me

# Test RBAC endpoints  
curl http://localhost/api/v1/rbac/permissions

# Test MFA endpoints
curl http://localhost/api/v1/mfa/devices
```

### Bước 6: Gradual Rollout

1. **Dual Deployment** (Optional):
   - Deploy cả `auth-service` và `iam-service` cùng lúc
   - Route traffic dần dần sang `iam-service`
   - Monitor errors và performance

2. **Update Clients**:
   - Update clients để sử dụng các endpoints mới nếu cần
   - Clients không cần update nếu chỉ dùng endpoints cũ

3. **Deprecate Old Service**:
   - Sau khi verify mọi thứ hoạt động tốt, có thể deprecate `auth-service`
   - Đảm bảo tất cả clients đã migrate sang `iam-service`

## Rollback Plan

Nếu cần rollback:

1. **Database Rollback**:
   ```bash
   # Revert Prisma migration
   cd services/iam-service
   pnpm prisma migrate resolve --rolled-back <migration_name>
   
   # Hoặc restore từ backup
   psql $DATABASE_URL < auth-service-backup.sql
   ```

2. **Service Rollback**:
   ```bash
   # Switch back to auth-service in docker-compose
   # Hoặc revert Kubernetes deployment
   kubectl rollout undo deployment/auth-service
   ```

## Breaking Changes

**Không có breaking changes** trong migration này. Tất cả các API endpoints và database models hiện có đều được giữ nguyên.

## Notes

- Migration này là **additive** - chỉ thêm các tính năng mới, không xóa hoặc thay đổi tính năng cũ
- Database migrations là **non-destructive** - không xóa hoặc modify dữ liệu hiện có
- Clients có thể tiếp tục sử dụng các endpoints cũ mà không cần thay đổi

## Support

Nếu gặp vấn đề trong quá trình migration, vui lòng:
1. Check logs: `docker-compose logs iam-service`
2. Verify database connection
3. Check environment variables
4. Review error messages và stack traces