---
name: IAM Service Migration Plan
overview: Kế hoạch chi tiết để chuyển đổi auth-service thành IAM service với các module mở rộng cho Identity Management, Access Management và Governance
todos:
  - id: phase1-rename
    content: "Phase 1: Rename service directory and update package.json, environment variables, main.ts, and deployment configs"
    status: completed
  - id: phase1-docs
    content: "Phase 1: Update README.md, ARCHITECTURE files, and create IAM_PROPOSAL.md"
    status: completed
  - id: phase1-deploy
    content: "Phase 1: Update docker-compose.yml and Kubernetes configs for iam-service"
    status: completed
  - id: phase2-schema
    content: "Phase 2: Add Identity Management models (Organization, Group, UserProfile, IdentityVerification) to Prisma schema"
    status: completed
  - id: phase2-schema-access
    content: "Phase 2: Add Access Management models (AccessRequest, AccessReview, AccessReviewItem) to Prisma schema"
    status: completed
  - id: phase2-schema-governance
    content: "Phase 2: Add Governance models (ComplianceReport, PolicyTemplate, RiskScore) to Prisma schema"
    status: completed
  - id: phase2-migration
    content: "Phase 2: Create and run Prisma migration, update seed script, generate Prisma client"
    status: completed
  - id: phase3-repositories
    content: "Phase 3: Create repositories for Organization, Group, UserProfile, IdentityVerification, AccessRequest, AccessReview"
    status: completed
  - id: phase3-dtos
    content: "Phase 3: Create DTOs (Zod schemas) for Identity, Access, and Governance modules"
    status: completed
  - id: phase4-user-lifecycle
    content: "Phase 4: Implement User Lifecycle Management (service, controller, module) with CRUD, bulk operations, deactivation"
    status: completed
  - id: phase4-profile
    content: "Phase 4: Implement Profile Management (service, controller, module) with avatar upload support"
    status: completed
  - id: phase4-verification
    content: "Phase 4: Implement Identity Verification (service, controller, module) for email, phone, document verification"
    status: completed
  - id: phase4-org-group
    content: "Phase 4: Implement Organization & Group Management (services, controllers, modules) with hierarchy support"
    status: completed
  - id: phase5-access-request
    content: "Phase 5: Implement Access Request & Approval system (service, controller, module) with workflow support"
    status: completed
  - id: phase5-access-review
    content: "Phase 5: Implement Access Review & Certification system (service, controller, module) with periodic reviews"
    status: completed
  - id: phase5-access-analytics
    content: "Phase 5: Implement Access Analytics (service, controller, module) with usage stats and risk analysis"
    status: completed
  - id: phase6-compliance
    content: "Phase 6: Implement Compliance Reporting (service, controller, module) with GDPR, SOC2, ISO27001 support"
    status: completed
  - id: phase6-policy
    content: "Phase 6: Implement Policy Governance (service, controller, module) with versioning and templates"
    status: completed
  - id: phase6-risk
    content: "Phase 6: Implement Risk Management (service, controller, module) with risk scoring and analysis"
    status: completed
  - id: phase6-reporting
    content: "Phase 6: Implement Reporting Dashboard (service, controller, module) with access summary and security events"
    status: completed
  - id: phase7-routes
    content: "Phase 7: Update routes/index.ts to integrate all new Identity, Access, and Governance endpoints while maintaining backward compatibility"
    status: completed
  - id: phase8-unit-tests
    content: "Phase 8: Write unit tests for all repositories, services, and controllers"
    status: pending
  - id: phase8-integration-tests
    content: "Phase 8: Write E2E tests for Identity, Access, and Governance workflows"
    status: pending
  - id: phase9-swagger
    content: "Phase 9: Update Swagger/OpenAPI documentation with all new endpoints and schemas"
    status: pending
  - id: phase9-docs
    content: "Phase 9: Update README, ARCHITECTURE docs, and create MIGRATION_GUIDE.md"
    status: completed
  - id: phase10-deploy
    content: "Phase 10: Deploy to staging, run tests, then deploy to production with monitoring"
    status: pending
---

# Kế Hoạch Chuyển Đổi Auth Service → IAM Service

## Tổng Quan

Plan này mô tả chi tiết các bước để chuyển đổi `auth-service` hiện tại thành `iam-service` với các tính năng mở rộng về Identity Management, Access Management, và Governance & Compliance.

## Phạm Vi

- **Rename service**: auth-service → iam-service
- **Database schema**: Thêm các models mới cho Identity, Access Management, Governance
- **Modules mới**: Identity, Access, Governance modules
- **Backward compatibility**: Giữ nguyên các API endpoints hiện tại
- **Deployment**: Update docker-compose, Kubernetes configs

---

## Phase 1: Foundation & Renaming (Week 1)

### 1.1 Service Rename

**Tasks:**

1. Rename service directory

   - `services/auth-service` → `services/iam-service`

2. Update `package.json`

   - File: `services/iam-service/package.json`
   - Change `name`: `"@goodgo/auth-service"` → `"@goodgo/iam-service"`
   - Change `description`: Update to "Enterprise IAM (Identity and Access Management) Service"

3. Update environment variables

   - File: `services/iam-service/.env.example`
   - Change `SERVICE_NAME=auth-service` → `SERVICE_NAME=iam-service`
   - Keep all other variables unchanged for backward compatibility

4. Update `main.ts`

   - File: `services/iam-service/src/main.ts`
   - Update service name in tracing initialization: `'auth-service'` → `'iam-service'`

5. Update Dockerfile (if exists)

   - File: `services/iam-service/Dockerfile`
   - Update any hardcoded service names

### 1.2 Update Documentation Files

**Tasks:**

1. Update README.md

   - File: `services/iam-service/README.md`
   - Change title: "Auth Service" → "IAM Service"
   - Update description to include IAM scope
   - Add migration notes section

2. Update ARCHITECTURE files

   - Files: `services/iam-service/ARCHITECTURE.vi.md`, `ARCHITECTURE.en.md`
   - Update service name references
   - Add new IAM architecture sections (placeholder for now)

3. Create IAM_PROPOSAL.md

   - File: `services/iam-service/IAM_PROPOSAL.md`
   - Document IAM architecture proposal
   - Include module structure and database schema changes

### 1.3 Update Deployment Configurations

**Tasks:**

1. Update docker-compose.yml

   - File: `deployments/local/docker-compose.yml`
   - Rename service: `auth-service` → `iam-service`
   - Update container_name: `auth-service-local` → `iam-service-local`
   - Update SERVICE_NAME env var
   - Update Traefik labels:
     - Router rule: Add `/api/v1/identity/*`, `/api/v1/access/*`, `/api/v1/governance/*`
     - Keep existing `/api/v1/auth/*` routes for backward compatibility

2. Update Kubernetes configs

   - Files:
     - `deployments/staging/kubernetes/auth-service.yaml` → `iam-service.yaml`
     - `deployments/production/kubernetes/auth-service.yaml` → `iam-service.yaml`
   - Update all metadata names
   - Update image name: `goodgo/auth-service` → `goodgo/iam-service`
   - Update service names in ingress configs

3. Update environment example files

   - Files:
     - `deployments/local/env.local.example`
     - `deployments/staging/env.staging.example`
     - `deployments/production/env.production.example`
   - Add new IAM-specific environment variables (with defaults)

---

## Phase 2: Database Schema Extension (Week 2)

### 2.1 Prisma Schema Extension

**File**: `services/iam-service/prisma/schema.prisma`

**Tasks:**

1. **Add Identity Management Models**
```prisma
// Organization model
model Organization {
  id          String   @id @default(cuid())
  name        String
  domain      String?  @unique
  parentId    String?
  settings    Json?
  isActive    Boolean  @default(true)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  users       User[]
  groups      Group[]
  policies    Policy[]
  parent      Organization? @relation("OrganizationHierarchy", fields: [parentId], references: [id])
  children    Organization[] @relation("OrganizationHierarchy")
  
  @@index([domain])
  @@map("organizations")
}

// Group model
model Group {
  id             String   @id @default(cuid())
  name           String
  organizationId String?
  description    String?
  isActive       Boolean  @default(true)
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt
  
  organization   Organization? @relation(fields: [organizationId], references: [id])
  members        GroupMember[]
  permissions    GroupPermission[]
  
  @@unique([organizationId, name])
  @@index([organizationId])
  @@map("groups")
}

// GroupMember model
model GroupMember {
  id        String   @id @default(cuid())
  userId    String
  groupId   String
  role      String   @default("member") // member, admin
  joinedAt  DateTime @default(now())
  expiresAt DateTime?
  
  user      User   @relation(fields: [userId], references: [id], onDelete: Cascade)
  group     Group  @relation(fields: [groupId], references: [id], onDelete: Cascade)
  
  @@unique([userId, groupId])
  @@index([userId])
  @@index([groupId])
  @@map("group_members")
}

// GroupPermission model
model GroupPermission {
  id           String   @id @default(cuid())
  groupId      String
  permissionId String
  createdAt    DateTime @default(now())
  
  group       Group      @relation(fields: [groupId], references: [id], onDelete: Cascade)
  permission  Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
  
  @@unique([groupId, permissionId])
  @@index([groupId])
  @@map("group_permissions")
}

// UserProfile model
model UserProfile {
  id            String   @id @default(cuid())
  userId        String   @unique
  firstName     String?
  lastName      String?
  phone         String?
  phoneVerified Boolean  @default(false)
  avatarUrl     String?
  customFields  Json?    // Extended attributes
  preferences   Json?    // User preferences
  metadata      Json?    // Additional metadata
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
  
  user          User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  @@index([phone])
  @@map("user_profiles")
}

// IdentityVerification model
model IdentityVerification {
  id          String   @id @default(cuid())
  userId      String
  type        VerificationType
  status      VerificationStatus @default(PENDING)
  method      String?
  token       String?  @unique // OTP token, verification code
  verifiedAt  DateTime?
  expiresAt   DateTime?
  metadata    Json?    // Verification details
  createdAt   DateTime @default(now())
  
  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  @@index([userId, type])
  @@index([token])
  @@index([status])
  @@map("identity_verifications")
}

enum VerificationType {
  EMAIL
  PHONE
  DOCUMENT
  BIOMETRIC
}

enum VerificationStatus {
  PENDING
  VERIFIED
  REJECTED
  EXPIRED
}
```

2. **Add Access Management Models**
```prisma
// AccessRequest model
model AccessRequest {
  id          String   @id @default(cuid())
  userId      String
  resource    String
  action      String
  reason      String?
  status      RequestStatus @default(PENDING)
  requestedAt DateTime @default(now())
  reviewedAt  DateTime?
  reviewedBy  String?
  expiresAt   DateTime?
  metadata    Json?
  
  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  approvers   AccessRequestApprover[]
  
  @@index([userId])
  @@index([status])
  @@index([resource])
  @@map("access_requests")
}

enum RequestStatus {
  PENDING
  APPROVED
  REJECTED
  EXPIRED
  CANCELLED
}

// AccessRequestApprover model
model AccessRequestApprover {
  id          String   @id @default(cuid())
  requestId   String
  approverId  String
  status      ApprovalStatus @default(PENDING)
  comments    String?
  reviewedAt  DateTime?
  
  request     AccessRequest @relation(fields: [requestId], references: [id], onDelete: Cascade)
  
  @@unique([requestId, approverId])
  @@index([approverId])
  @@map("access_request_approvers")
}

enum ApprovalStatus {
  PENDING
  APPROVED
  REJECTED
}

// AccessReview model
model AccessReview {
  id          String   @id @default(cuid())
  name        String
  description String?
  type        ReviewType
  status      ReviewStatus @default(DRAFT)
  startDate   DateTime
  endDate     DateTime
  createdBy   String
  createdAt   DateTime @default(now())
  completedAt DateTime?
  
  items       AccessReviewItem[]
  
  @@index([status])
  @@index([type])
  @@map("access_reviews")
}

enum ReviewType {
  PERIODIC
  ADHOC
  CERTIFICATION
}

enum ReviewStatus {
  DRAFT
  ACTIVE
  COMPLETED
  CANCELLED
}

// AccessReviewItem model
model AccessReviewItem {
  id          String   @id @default(cuid())
  reviewId    String
  userId      String
  resource    String
  access      Json     // Current access details
  status      ReviewItemStatus @default(PENDING)
  reviewedBy  String?
  reviewedAt  DateTime?
  comments    String?
  
  review      AccessReview @relation(fields: [reviewId], references: [id], onDelete: Cascade)
  
  @@index([reviewId])
  @@index([userId])
  @@index([status])
  @@map("access_review_items")
}

enum ReviewItemStatus {
  PENDING
  APPROVED
  REVOKED
  NO_CHANGE
}
```

3. **Add Governance Models**
```prisma
// ComplianceReport model
model ComplianceReport {
  id          String   @id @default(cuid())
  type        ComplianceType
  name        String
  periodStart DateTime
  periodEnd   DateTime
  status      ReportStatus @default(DRAFT)
  data        Json?
  generatedAt DateTime?
  generatedBy String?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  @@index([type])
  @@index([status])
  @@map("compliance_reports")
}

enum ComplianceType {
  GDPR
  SOC2
  ISO27001
  HIPAA
  CUSTOM
}

enum ReportStatus {
  DRAFT
  GENERATED
  PUBLISHED
  ARCHIVED
}

// PolicyTemplate model
model PolicyTemplate {
  id          String   @id @default(cuid())
  name        String
  category    PolicyCategory
  description String?
  content     Json     // Policy template structure
  version     String   @default("1.0.0")
  isActive    Boolean  @default(true)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  @@index([category])
  @@index([isActive])
  @@map("policy_templates")
}

enum PolicyCategory {
  SECURITY
  ACCESS
  COMPLIANCE
  DATA
  PRIVACY
}

// RiskScore model
model RiskScore {
  id          String   @id @default(cuid())
  userId      String
  score       Int      // 0-100
  level       RiskLevel
  factors     Json     // Risk factors
  calculatedAt DateTime @default(now())
  
  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  @@index([userId])
  @@index([score])
  @@index([level])
  @@map("risk_scores")
}

enum RiskLevel {
  LOW
  MEDIUM
  HIGH
  CRITICAL
}
```

4. **Update Existing User Model**
```prisma
// Add to existing User model
model User {
  // ... existing fields ...
  
  // New relations
  organizationId String?
  organization   Organization? @relation(fields: [organizationId], references: [id])
  profile        UserProfile?
  verifications  IdentityVerification[]
  accessRequests AccessRequest[]
  riskScores     RiskScore[]
  groupMembers   GroupMember[]
}
```


### 2.2 Create Migration

**Tasks:**

1. Generate Prisma migration

   - Command: `cd services/iam-service && pnpm prisma migrate dev --name add_iam_models`
   - This will create migration file in `prisma/migrations/`

2. Update seed script

   - File: `services/iam-service/prisma/seed.ts`
   - Add seed data for new models (organizations, groups, etc.)

3. Update Prisma Client

   - Command: `pnpm prisma:generate`
   - Verify types are generated correctly

---

## Phase 3: Core Infrastructure Extensions (Week 3)

### 3.1 Repository Layer Extensions

**Tasks:**

1. **Create Organization Repository**

   - File: `services/iam-service/src/repositories/organization.repository.ts`
   - Extend `BaseRepository` from `modules/common/repository.ts`
   - Methods:
     - `findById(id: string)`
     - `findByDomain(domain: string)`
     - `findChildren(parentId: string)`
     - `create(data: CreateOrganizationInput)`
     - `update(id: string, data: UpdateOrganizationInput)`
     - `delete(id: string)`

2. **Create Group Repository**

   - File: `services/iam-service/src/repositories/group.repository.ts`
   - Methods:
     - `findById(id: string)`
     - `findByOrganization(organizationId: string)`
     - `findUserGroups(userId: string)`
     - `addMember(groupId: string, userId: string, role: string)`
     - `removeMember(groupId: string, userId: string)`
     - `getMembers(groupId: string)`

3. **Create User Profile Repository**

   - File: `services/iam-service/src/repositories/user-profile.repository.ts`
   - Methods:
     - `findByUserId(userId: string)`
     - `create(userId: string, data: CreateProfileInput)`
     - `update(userId: string, data: UpdateProfileInput)`
     - `updateAvatar(userId: string, avatarUrl: string)`

4. **Create Identity Verification Repository**

   - File: `services/iam-service/src/repositories/identity-verification.repository.ts`
   - Methods:
     - `findByToken(token: string)`
     - `findByUserAndType(userId: string, type: VerificationType)`
     - `create(data: CreateVerificationInput)`
     - `updateStatus(id: string, status: VerificationStatus)`

5. **Create Access Request Repository**

   - File: `services/iam-service/src/repositories/access-request.repository.ts`
   - Methods:
     - `findById(id: string)`
     - `findByUser(userId: string)`
     - `findPendingByUser(userId: string)`
     - `create(data: CreateAccessRequestInput)`
     - `updateStatus(id: string, status: RequestStatus)`

6. **Create Access Review Repository**

   - File: `services/iam-service/src/repositories/access-review.repository.ts`
   - Methods:
     - `findById(id: string)`
     - `findActive()`
     - `findByStatus(status: ReviewStatus)`
     - `create(data: CreateAccessReviewInput)`
     - `getItems(reviewId: string)`

7. **Update Repository Index**

   - File: `services/iam-service/src/repositories/index.ts`
   - Export all new repositories

### 3.2 DTO Definitions

**Tasks:**

1. **Identity DTOs**

   - File: `services/iam-service/src/modules/identity/identity.dto.ts`
   - Zod schemas:
     - `CreateOrganizationDto`
     - `UpdateOrganizationDto`
     - `CreateGroupDto`
     - `UpdateGroupDto`
     - `CreateUserProfileDto`
     - `UpdateUserProfileDto`
     - `VerificationRequestDto`
     - `VerifyCodeDto`

2. **Access DTOs**

   - File: `services/iam-service/src/modules/access/access.dto.ts`
   - Zod schemas:
     - `CreateAccessRequestDto`
     - `ApproveAccessRequestDto`
     - `RejectAccessRequestDto`
     - `CreateAccessReviewDto`
     - `ReviewAccessItemDto`

3. **Governance DTOs**

   - File: `services/iam-service/src/modules/governance/governance.dto.ts`
   - Zod schemas:
     - `GenerateComplianceReportDto`
     - `CreatePolicyTemplateDto`
     - `CalculateRiskScoreDto`

---

## Phase 4: Identity Management Module (Week 4-5)

### 4.1 User Lifecycle Management

**Tasks:**

1. **Create User Management Service**

   - File: `services/iam-service/src/modules/identity/user/user.service.ts`
   - Extend existing `AuthService` functionality
   - Add methods:
     - `getUser(userId: string)`
     - `updateUser(userId: string, data: UpdateUserInput)`
     - `deleteUser(userId: string)` (soft delete)
     - `deactivateUser(userId: string)`
     - `reactivateUser(userId: string)`
     - `bulkImportUsers(file: Buffer, organizationId?: string)`
     - `bulkExportUsers(filters: UserFilters)`
     - `searchUsers(query: string, filters: UserFilters)`

2. **Create User Management Controller**

   - File: `services/iam-service/src/modules/identity/user/user.controller.ts`
   - Endpoints:
     - `GET /api/v1/identity/users`
     - `GET /api/v1/identity/users/:id`
     - `PUT /api/v1/identity/users/:id`
     - `DELETE /api/v1/identity/users/:id`
     - `POST /api/v1/identity/users/:id/deactivate`
     - `POST /api/v1/identity/users/:id/reactivate`
     - `POST /api/v1/identity/users/bulk-import`
     - `GET /api/v1/identity/users/bulk-export`

3. **Create User Module**

   - File: `services/iam-service/src/modules/identity/user/user.module.ts`
   - Wire up dependencies

4. **Create Index File**

   - File: `services/iam-service/src/modules/identity/user/index.ts`

### 4.2 Profile Management

**Tasks:**

1. **Create Profile Service**

   - File: `services/iam-service/src/modules/identity/profile/profile.service.ts`
   - Methods:
     - `getProfile(userId: string)`
     - `updateProfile(userId: string, data: UpdateProfileInput)`
     - `uploadAvatar(userId: string, file: Buffer, mimetype: string)`
     - `deleteAvatar(userId: string)`
     - `updatePreferences(userId: string, preferences: Json)`

2. **Create Profile Controller**

   - File: `services/iam-service/src/modules/identity/profile/profile.controller.ts`
   - Endpoints:
     - `GET /api/v1/identity/users/:id/profile`
     - `PUT /api/v1/identity/users/:id/profile`
     - `POST /api/v1/identity/users/:id/profile/avatar`
     - `DELETE /api/v1/identity/users/:id/profile/avatar`

3. **Create Profile Module**

   - File: `services/iam-service/src/modules/identity/profile/profile.module.ts`

### 4.3 Identity Verification

**Tasks:**

1. **Create Verification Service**

   - File: `services/iam-service/src/modules/identity/verification/verification.service.ts`
   - Methods:
     - `requestEmailVerification(userId: string)`
     - `verifyEmail(token: string)`
     - `requestPhoneVerification(userId: string, phone: string)`
     - `verifyPhone(token: string)`
     - `requestDocumentVerification(userId: string, document: Buffer)`
     - `getVerificationStatus(userId: string, type: VerificationType)`

2. **Create Verification Controller**

   - File: `services/iam-service/src/modules/identity/verification/verification.controller.ts`
   - Endpoints:
     - `POST /api/v1/identity/verification/email/request`
     - `POST /api/v1/identity/verification/email/verify`
     - `POST /api/v1/identity/verification/phone/request`
     - `POST /api/v1/identity/verification/phone/verify`
     - `POST /api/v1/identity/verification/document/upload`
     - `GET /api/v1/identity/verification/:id/status`

3. **Create Verification Module**

   - File: `services/iam-service/src/modules/identity/verification/verification.module.ts`

4. **Add Email/SMS Service Integration**

   - Create config: `services/iam-service/src/config/notification.config.ts`
   - Integrate with email service (SMTP) and SMS service

### 4.4 Organization & Group Management

**Tasks:**

1. **Create Organization Service**

   - File: `services/iam-service/src/modules/identity/organization/organization.service.ts`
   - Methods:
     - `create(data: CreateOrganizationInput)`
     - `getById(id: string)`
     - `getByDomain(domain: string)`
     - `update(id: string, data: UpdateOrganizationInput)`
     - `delete(id: string)`
     - `getChildren(parentId: string)`
     - `getUsers(organizationId: string)`
     - `addUser(organizationId: string, userId: string)`
     - `removeUser(organizationId: string, userId: string)`

2. **Create Organization Controller**

   - File: `services/iam-service/src/modules/identity/organization/organization.controller.ts`
   - Endpoints:
     - `GET /api/v1/identity/organizations`
     - `POST /api/v1/identity/organizations`
     - `GET /api/v1/identity/organizations/:id`
     - `PUT /api/v1/identity/organizations/:id`
     - `DELETE /api/v1/identity/organizations/:id`
     - `GET /api/v1/identity/organizations/:id/users`

3. **Create Group Service**

   - File: `services/iam-service/src/modules/identity/group/group.service.ts`
   - Methods:
     - `create(organizationId: string, data: CreateGroupInput)`
     - `getById(id: string)`
     - `getByOrganization(organizationId: string)`
     - `update(id: string, data: UpdateGroupInput)`
     - `delete(id: string)`
     - `addMember(groupId: string, userId: string, role: string)`
     - `removeMember(groupId: string, userId: string)`
     - `getMembers(groupId: string)`
     - `assignPermission(groupId: string, permissionId: string)`
     - `revokePermission(groupId: string, permissionId: string)`

4. **Create Group Controller**

   - File: `services/iam-service/src/modules/identity/group/group.controller.ts`
   - Endpoints:
     - `GET /api/v1/identity/organizations/:id/groups`
     - `POST /api/v1/identity/organizations/:id/groups`
     - `GET /api/v1/identity/groups/:id`
     - `PUT /api/v1/identity/groups/:id`
     - `DELETE /api/v1/identity/groups/:id`
     - `GET /api/v1/identity/groups/:id/members`
     - `POST /api/v1/identity/groups/:id/members`
     - `DELETE /api/v1/identity/groups/:id/members/:userId`

5. **Create Modules**

   - Files:
     - `services/iam-service/src/modules/identity/organization/organization.module.ts`
     - `services/iam-service/src/modules/identity/group/group.module.ts`

6. **Create Identity Module Index**

   - File: `services/iam-service/src/modules/identity/index.ts`
   - Export all identity modules

---

## Phase 5: Access Management Module (Week 6-7)

### 5.1 Access Request & Approval

**Tasks:**

1. **Create Access Request Service**

   - File: `services/iam-service/src/modules/access/request/request.service.ts`
   - Methods:
     - `createRequest(userId: string, data: CreateAccessRequestInput)`
     - `getRequest(id: string)`
     - `getUserRequests(userId: string)`
     - `approveRequest(requestId: string, approverId: string, comments?: string)`
     - `rejectRequest(requestId: string, approverId: string, comments?: string)`
     - `cancelRequest(requestId: string, userId: string)`
     - `getPendingApprovals(approverId: string)`

2. **Create Access Request Controller**

   - File: `services/iam-service/src/modules/access/request/request.controller.ts`
   - Endpoints:
     - `GET /api/v1/access/requests`
     - `POST /api/v1/access/requests`
     - `GET /api/v1/access/requests/:id`
     - `PUT /api/v1/access/requests/:id/approve`
     - `PUT /api/v1/access/requests/:id/reject`
     - `DELETE /api/v1/access/requests/:id`

3. **Create Access Request Module**

   - File: `services/iam-service/src/modules/access/request/request.module.ts`

### 5.2 Access Review & Certification

**Tasks:**

1. **Create Access Review Service**

   - File: `services/iam-service/src/modules/access/review/review.service.ts`
   - Methods:
     - `createReview(data: CreateAccessReviewInput)`
     - `getReview(id: string)`
     - `startReview(id: string)`
     - `completeReview(id: string)`
     - `getReviewItems(reviewId: string)`
     - `reviewItem(itemId: string, reviewerId: string, status: ReviewItemStatus, comments?: string)`
     - `getUserReviewItems(userId: string, reviewId: string)`
     - `generateReviewItems(reviewId: string)` // Auto-generate based on current access

2. **Create Access Review Controller**

   - File: `services/iam-service/src/modules/access/review/review.controller.ts`
   - Endpoints:
     - `GET /api/v1/access/reviews`
     - `POST /api/v1/access/reviews`
     - `GET /api/v1/access/reviews/:id`
     - `PUT /api/v1/access/reviews/:id`
     - `POST /api/v1/access/reviews/:id/start`
     - `POST /api/v1/access/reviews/:id/complete`
     - `GET /api/v1/access/reviews/:id/items`
     - `PUT /api/v1/access/reviews/:id/items/:itemId/review`

3. **Create Access Review Module**

   - File: `services/iam-service/src/modules/access/review/review.module.ts`

### 5.3 Access Analytics

**Tasks:**

1. **Create Access Analytics Service**

   - File: `services/iam-service/src/modules/access/analytics/analytics.service.ts`
   - Methods:
     - `getUsageStats(period: DateRange)`
     - `getPermissionDistribution()`
     - `getUserAccessSummary(userId: string)`
     - `getRiskAnalysis(filters: RiskFilters)`
     - `getAccessTrends(period: DateRange)`

2. **Create Access Analytics Controller**

   - File: `services/iam-service/src/modules/access/analytics/analytics.controller.ts`
   - Endpoints:
     - `GET /api/v1/access/analytics/usage`
     - `GET /api/v1/access/analytics/permissions`
     - `GET /api/v1/access/analytics/users/:id/summary`
     - `GET /api/v1/access/analytics/risks`

3. **Create Access Analytics Module**

   - File: `services/iam-service/src/modules/access/analytics/analytics.module.ts`

4. **Create Access Module Index**

   - File: `services/iam-service/src/modules/access/index.ts`
   - Export all access modules

---

## Phase 6: Governance Module (Week 8-9)

### 6.1 Compliance Reporting

**Tasks:**

1. **Create Compliance Service**

   - File: `services/iam-service/src/modules/governance/compliance/compliance.service.ts`
   - Methods:
     - `generateReport(type: ComplianceType, periodStart: Date, periodEnd: Date)`
     - `getReport(id: string)`
     - `getReports(filters: ReportFilters)`
     - `exportReport(id: string, format: 'pdf' | 'csv' | 'json')`
     - `publishReport(id: string)`
     - `getGDPRReport(userId: string)`
     - `getSOC2Report(periodStart: Date, periodEnd: Date)`

2. **Create Compliance Controller**

   - File: `services/iam-service/src/modules/governance/compliance/compliance.controller.ts`
   - Endpoints:
     - `GET /api/v1/governance/compliance/reports`
     - `POST /api/v1/governance/compliance/reports/generate`
     - `GET /api/v1/governance/compliance/reports/:id`
     - `GET /api/v1/governance/compliance/reports/:id/export`
     - `POST /api/v1/governance/compliance/reports/:id/publish`

3. **Create Compliance Module**

   - File: `services/iam-service/src/modules/governance/compliance/compliance.module.ts`

### 6.2 Policy Governance

**Tasks:**

1. **Create Policy Governance Service**

   - File: `services/iam-service/src/modules/governance/policy/policy-governance.service.ts`
   - Extend existing `Policy` model from RBAC
   - Methods:
     - `createTemplate(data: CreatePolicyTemplateInput)`
     - `getTemplates(category?: PolicyCategory)`
     - `createPolicyFromTemplate(templateId: string, data: CreatePolicyInput)`
     - `getPolicyVersions(policyId: string)`
     - `rollbackPolicy(policyId: string, version: string)`
     - `testPolicy(policyId: string, testData: Json)`
     - `validatePolicy(policy: Policy)`

2. **Create Policy Governance Controller**

   - File: `services/iam-service/src/modules/governance/policy/policy-governance.controller.ts`
   - Endpoints:
     - `GET /api/v1/governance/policies/templates`
     - `POST /api/v1/governance/policies/templates`
     - `GET /api/v1/governance/policies/:id/versions`
     - `POST /api/v1/governance/policies/:id/test`
     - `POST /api/v1/governance/policies/:id/rollback`

3. **Create Policy Governance Module**

   - File: `services/iam-service/src/modules/governance/policy/policy-governance.module.ts`

### 6.3 Risk Management

**Tasks:**

1. **Create Risk Service**

   - File: `services/iam-service/src/modules/governance/risk/risk.service.ts`
   - Methods:
     - `calculateRiskScore(userId: string)`
     - `getRiskScore(userId: string)`
     - `getRiskScores(filters: RiskFilters)`
     - `getRiskFactors(userId: string)`
     - `getHighRiskUsers(threshold: number)`
     - `updateRiskScore(userId: string, factors: RiskFactors)`

2. **Create Risk Controller**

   - File: `services/iam-service/src/modules/governance/risk/risk.controller.ts`
   - Endpoints:
     - `GET /api/v1/governance/risk/scores`
     - `GET /api/v1/governance/risk/scores/:userId`
     - `POST /api/v1/governance/risk/calculate`
     - `GET /api/v1/governance/risk/dashboard`

3. **Create Risk Module**

   - File: `services/iam-service/src/modules/governance/risk/risk.module.ts`

### 6.4 Reporting Dashboard

**Tasks:**

1. **Create Reporting Service**

   - File: `services/iam-service/src/modules/governance/reporting/reporting.service.ts`
   - Methods:
     - `getAccessSummary(period: DateRange)`
     - `getUserActivity(userId: string, period: DateRange)`
     - `getSecurityEvents(period: DateRange, filters: EventFilters)`
     - `getComplianceStatus()`
     - `getRiskOverview()`

2. **Create Reporting Controller**

   - File: `services/iam-service/src/modules/governance/reporting/reporting.controller.ts`
   - Endpoints:
     - `GET /api/v1/governance/reports/access-summary`
     - `GET /api/v1/governance/reports/user-activity`
     - `GET /api/v1/governance/reports/security-events`
     - `GET /api/v1/governance/reports/compliance-status`
     - `GET /api/v1/governance/reports/risk-overview`

3. **Create Reporting Module**

   - File: `services/iam-service/src/modules/governance/reporting/reporting.module.ts`

4. **Create Governance Module Index**

   - File: `services/iam-service/src/modules/governance/index.ts`
   - Export all governance modules

---

## Phase 7: Routes Integration (Week 10)

### 7.1 Update Routes

**File**: `services/iam-service/src/routes/index.ts`

**Tasks:**

1. **Add Identity Routes**
   ```typescript
   // Import identity controllers
   import { userController } from '../modules/identity/user/user.controller';
   import { profileController } from '../modules/identity/profile/profile.controller';
   import { verificationController } from '../modules/identity/verification/verification.controller';
   import { organizationController } from '../modules/identity/organization/organization.controller';
   import { groupController } from '../modules/identity/group/group.controller';
   
   // Add routes with authentication middleware
   // User routes
   router.get(`/api/${apiVersion}/identity/users`, authenticate(), userController.list.bind(userController));
   router.post(`/api/${apiVersion}/identity/users`, authenticate(), requirePermission('identity', 'create'), userController.create.bind(userController));
   // ... more user routes
   
   // Profile routes
   router.get(`/api/${apiVersion}/identity/users/:id/profile`, authenticate(), profileController.get.bind(profileController));
   // ... more profile routes
   
   // Verification routes
   router.post(`/api/${apiVersion}/identity/verification/email/request`, authenticate(), verificationController.requestEmail.bind(verificationController));
   // ... more verification routes
   
   // Organization routes
   router.get(`/api/${apiVersion}/identity/organizations`, authenticate(), organizationController.list.bind(organizationController));
   // ... more organization routes
   
   // Group routes
   router.get(`/api/${apiVersion}/identity/organizations/:id/groups`, authenticate(), groupController.list.bind(groupController));
   // ... more group routes
   ```

2. **Add Access Routes**
   ```typescript
   // Import access controllers
   import { accessRequestController } from '../modules/access/request/request.controller';
   import { accessReviewController } from '../modules/access/review/review.controller';
   import { accessAnalyticsController } from '../modules/access/analytics/analytics.controller';
   
   // Access request routes
   router.get(`/api/${apiVersion}/access/requests`, authenticate(), accessRequestController.list.bind(accessRequestController));
   // ... more access request routes
   
   // Access review routes
   router.get(`/api/${apiVersion}/access/reviews`, authenticate(), accessReviewController.list.bind(accessReviewController));
   // ... more access review routes
   
   // Access analytics routes
   router.get(`/api/${apiVersion}/access/analytics/usage`, authenticate(), accessAnalyticsController.usage.bind(accessAnalyticsController));
   // ... more analytics routes
   ```

3. **Add Governance Routes**
   ```typescript
   // Import governance controllers
   import { complianceController } from '../modules/governance/compliance/compliance.controller';
   import { policyGovernanceController } from '../modules/governance/policy/policy-governance.controller';
   import { riskController } from '../modules/governance/risk/risk.controller';
   import { reportingController } from '../modules/governance/reporting/reporting.controller';
   
   // Compliance routes
   router.get(`/api/${apiVersion}/governance/compliance/reports`, authenticate(), complianceController.list.bind(complianceController));
   // ... more compliance routes
   
   // Policy governance routes
   router.get(`/api/${apiVersion}/governance/policies/templates`, authenticate(), policyGovernanceController.getTemplates.bind(policyGovernanceController));
   // ... more policy routes
   
   // Risk routes
   router.get(`/api/${apiVersion}/governance/risk/scores`, authenticate(), riskController.list.bind(riskController));
   // ... more risk routes
   
   // Reporting routes
   router.get(`/api/${apiVersion}/governance/reports/access-summary`, authenticate(), reportingController.accessSummary.bind(reportingController));
   // ... more reporting routes
   ```

4. **Keep Backward Compatibility**

   - Keep all existing `/api/v1/auth/*` routes unchanged
   - Keep all existing `/api/v1/rbac/*` routes unchanged
   - Keep all existing `/api/v1/mfa/*` routes unchanged
   - Keep all existing `/api/v1/sessions/*` routes unchanged

---

## Phase 8: Testing (Week 11)

### 8.1 Unit Tests

**Tasks:**

1. **Repository Tests**

   - Files:
     - `services/iam-service/src/repositories/__tests__/organization.repository.test.ts`
     - `services/iam-service/src/repositories/__tests__/group.repository.test.ts`
     - `services/iam-service/src/repositories/__tests__/user-profile.repository.test.ts`
     - `services/iam-service/src/repositories/__tests__/identity-verification.repository.test.ts`
     - `services/iam-service/src/repositories/__tests__/access-request.repository.test.ts`
     - `services/iam-service/src/repositories/__tests__/access-review.repository.test.ts`

2. **Service Tests**

   - Files:
     - `services/iam-service/src/modules/identity/**/__tests__/*.service.test.ts`
     - `services/iam-service/src/modules/access/**/__tests__/*.service.test.ts`
     - `services/iam-service/src/modules/governance/**/__tests__/*.service.test.ts`

3. **Controller Tests**

   - Files:
     - `services/iam-service/src/modules/identity/**/__tests__/*.controller.test.ts`
     - `services/iam-service/src/modules/access/**/__tests__/*.controller.test.ts`
     - `services/iam-service/src/modules/governance/**/__tests__/*.controller.test.ts`

### 8.2 Integration Tests

**Tasks:**

1. **E2E Tests**

   - File: `services/iam-service/src/__tests__/identity.e2e.ts`
     - Test user lifecycle workflows
     - Test profile management
     - Test identity verification flows
     - Test organization & group management

   - File: `services/iam-service/src/__tests__/access.e2e.ts`
     - Test access request/approval flows
     - Test access review workflows
     - Test access analytics

   - File: `services/iam-service/src/__tests__/governance.e2e.ts`
     - Test compliance report generation
     - Test policy governance
     - Test risk scoring

### 8.3 Update Test Setup

**File**: `services/iam-service/src/__tests__/setupTests.ts`

**Tasks:**

- Update test database setup to include new models
- Update test fixtures for new entities
- Add test utilities for new modules

---

## Phase 9: Documentation & API Docs (Week 12)

### 9.1 Update OpenAPI/Swagger

**File**: `services/iam-service/src/docs/swagger.ts`

**Tasks:**

1. Add Swagger tags for new modules:

   - `Identity`
   - `Access`
   - `Governance`

2. Add API documentation for all new endpoints
3. Add request/response schemas
4. Add examples for each endpoint

### 9.2 Update README

**File**: `services/iam-service/README.md`

**Tasks:**

1. Update feature list with IAM capabilities
2. Add architecture overview
3. Add API endpoint documentation
4. Add migration guide from auth-service
5. Update setup instructions

### 9.3 Update Architecture Docs

**Files**:

- `services/iam-service/ARCHITECTURE.vi.md`
- `services/iam-service/ARCHITECTURE.en.md`

**Tasks:**

1. Update service architecture diagrams
2. Add IAM module architecture
3. Add database schema documentation
4. Add API flow diagrams
5. Add deployment architecture

### 9.4 Create Migration Guide

**File**: `services/iam-service/MIGRATION_GUIDE.md`

**Tasks:**

1. Document steps to migrate from auth-service
2. Document breaking changes (if any)
3. Document backward compatibility notes
4. Document database migration steps
5. Document environment variable changes

---

## Phase 10: Deployment & Rollout (Week 13)

### 10.1 Final Deployment Updates

**Tasks:**

1. **Update Docker Image Build**

   - Ensure Dockerfile builds correctly
   - Update image tags if needed

2. **Update Environment Variables**

   - Review all environment variables
   - Add new required variables for IAM features
   - Update example files

3. **Update Health Checks**

   - Verify health check endpoints work
   - Add health checks for new dependencies (if any)

### 10.2 Staging Deployment

**Tasks:**

1. Deploy to staging environment
2. Run smoke tests
3. Verify all endpoints work
4. Check backward compatibility
5. Run load tests

### 10.3 Production Rollout

**Tasks:**

1. Create deployment plan
2. Deploy to production
3. Monitor metrics and logs
4. Verify backward compatibility
5. Gradual rollout if needed

---

## Dependencies & Prerequisites

### External Dependencies

- Email service (SMTP) for email verification
- SMS service for phone verification
- File storage service for document/avatar uploads
- Object storage for file attachments

### Internal Dependencies

- All existing auth-service dependencies remain
- No breaking changes to existing APIs
- Database migrations are additive only

---

## Risk Mitigation

### Backward Compatibility

- All existing `/api/v1/auth/*` routes remain functional
- Existing database schema is preserved
- Existing clients continue to work without changes

### Rollback Plan

- Keep auth-service as backup during migration
- Database migrations are reversible
- Can deploy both services simultaneously during transition

### Testing Strategy

- Comprehensive unit tests for all new modules
- Integration tests for workflows
- E2E tests for critical paths
- Load testing before production

---

## Success Criteria

1. ✅ Service renamed successfully
2. ✅ All new database models created and migrated
3. ✅ All new modules implemented and tested
4. ✅ All new API endpoints functional
5. ✅ Backward compatibility maintained
6. ✅ Documentation complete
7. ✅ Deployed to staging and verified
8. ✅ Production deployment successful