# Phase 2 Implementation Plan - API Integration & Feature Flags

**Objective:** Wire Phase 1 core services into the Gateway Web application with proper routing, feature flags, and RBAC.

**Scope:**
1. Register API routes in Phoenix router
2. Implement feature flag service integration
3. Build RBAC matrix and auth middleware
4. Add API contract tests
5. Implement error handling & response contracts

**Estimated Effort:** 3-4 days

---

## Day 1: Route Registration & Feature Flags

### Tasks

1. **Register API routes** (router.ex)
   - Add JSON API scope for /admin/api/ai/proposals
   - Mount AiProposalController with actions
   - Add pipeline for auth & feature flag checks

2. **Feature flag service integration**
   - Check existing feature flag implementation (mw_kernel? infra_feature_store?)
   - Create FeatureFlags.enabled?/1 helper
   - Wire into controller as plug

3. **Basic tests**
   - Route existence test
   - Feature flag off → 403 response
   - Feature flag on → 200 response (or proper error)

### Success Criteria
- Routes are registered and accessible
- Feature flag gates work bidirectionally
- No compilation errors

---

## Day 2-3: RBAC & Auth Middleware

### Tasks

1. **RBAC Matrix Implementation**
   - Define role hierarchy (superadmin > admin > analyst > viewer)
   - Map roles to proposal actions:
     - generate: admin, superadmin
     - approve: admin, superadmin
     - reject: admin, superadmin, analyst
     - view: all authenticated

2. **Auth Middleware**
   - Check current auth pattern (GatewayWebWeb.AdminAuth?)
   - Extract user_id, role from conn.assigns
   - Add role check plug
   - Return 403 with reason if unauthorized

3. **Request/Response Contracts**
   - Standardize error responses
   - Add validation error formatting
   - Add request payload validation

### Success Criteria
- Unauthorized requests return 403
- Authorized requests proceed
- Error responses are consistent

---

## Day 3-4: Integration Tests

### Tasks

1. **API Contract Tests** (test/controllers/ai_proposal_controller_test.exs)
   - POST generate → 201 with proposal
   - GET show → 200 with events
   - POST approve → 200 or 422
   - POST reject → 200
   - Unauthorized → 403
   - Feature flag off → 403

2. **Regression Tests**
   - Verify no impact on existing flow builder endpoints
   - Verify no impact on router
   - Verify no impact on auth system

3. **Error Handling Tests**
   - Invalid JSON → 400
   - Missing required fields → 422
   - Non-existent proposal → 404
   - Database errors → 500

### Success Criteria
- >85% test pass rate
- Zero regressions
- All endpoints documented

---

## Implementation Files

**New Files:**
- test/controllers/ai_proposal_controller_test.exs
- lib/gateway_web_web/plugs/feature_flag_check.ex
- lib/gateway_web_web/plugs/role_check.ex

**Modified Files:**
- lib/gateway_web_web/router.ex (add routes)
- lib/gateway_web_web/controllers/ai_proposal_controller.ex (refine error handling)

---

## Acceptance Criteria

1. ✅ Routes are registered under /admin/api/ai/proposals
2. ✅ Feature flag gates work
3. ✅ RBAC enforced per action
4. ✅ Error responses standardized
5. ✅ API contract tests pass
6. ✅ Zero regressions on existing endpoints

---

## Dependencies

- Existing auth system (assumes GatewayWebWeb.AdminAuth pattern)
- Existing feature flag system (check location)
- Existing JSON response format conventions

---

## Risks & Mitigations

1. **Auth system differences** - Verify current auth pattern before implementation
2. **Feature flag location** - May need to add feature flag service if missing
3. **JSON API conventions** - Follow existing patterns from other endpoints