# Multi-Profile Module Roadmap

## Scope in `sms_admin_es`

This repository now owns:

- Tenant-scoped Multi Profile country policy administration for `app_id = 1023`
- Admin-side profile visibility and management backed by isolated ClickHouse tables
- Read-only subscriber profile visibility inside Subscriber 360 when the logged-in admin has Multi Profile access
- Admin session profile-context switching that does not overload `session('app_id')`

This repository still does **not** alter existing billing, subscription ownership, device ownership, or current customer login flows.

## New Data Storage

All Multi Profile data is isolated in new ClickHouse tables:

- `multi_profile_policies`
- `multi_profile_profiles`
- `multi_profile_activity_logs`

Design notes:

- `ReplacingMergeTree(version)` is used for mutable policy/profile state snapshots
- `MergeTree` is used for append-only activity logs
- Partitioning is monthly on `event_time`
- Bloom/set indexes are added for country, profile type, status, and lookup-heavy fields
- Retention defaults are 5 years for policy/profile state and 3 years for activity logs

## Backend Surface

Implemented APIs:

- `GET /admin/api/core/multi-profile/countries`
- `GET /admin/api/core/multi-profile/policies`
- `POST /admin/api/core/multi-profile/policies`
- `GET /admin/api/core/multi-profile/policies/{id}`
- `PUT|PATCH /admin/api/core/multi-profile/policies/{id}`
- `POST /admin/api/core/multi-profile/policies/{id}/publish`
- `DELETE /admin/api/core/multi-profile/policies/{id}`
- `GET /admin/api/core/multi-profile/customers/lookup`
- `GET /admin/api/core/multi-profile/customers/{customer}/workspace`
- `GET /admin/api/core/multi-profile/customers/{customer}/summary`
- `GET /admin/api/core/multi-profile/customers/{customer}/profiles`
- `POST /admin/api/core/multi-profile/customers/{customer}/profiles`
- `PUT|PATCH /admin/api/core/multi-profile/customers/{customer}/profiles/{profile}`
- `POST /admin/api/core/multi-profile/customers/{customer}/profiles/{profile}/activate`
- `POST /admin/api/core/multi-profile/customers/{customer}/profiles/{profile}/deactivate`
- `DELETE /admin/api/core/multi-profile/customers/{customer}/profiles/{profile}`
- `POST /admin/api/core/multi-profile/customers/{customer}/profiles/{profile}/switch`
- `POST /admin/api/core/multi-profile/customers/{customer}/context/clear`

## Policy Resolution

Resolution order:

1. Active country override
2. Active global policy
3. Draft country override
4. Draft global policy
5. Safe default: `max_profiles = 1`, `kids_enabled = false`

## Profile Rules

- Every customer gets one auto-backfilled Owner profile
- Owner is immutable for deletion/deactivation
- Profile count and Kids count are validated against the resolved country policy
- PIN flags are capability flags only; no PIN values are stored
- Subscription/package ownership stays account-level and is only surfaced as read-only context

## Frontend Changes

- New Filament page: `Core > Multi Profile`
- New country policy table, KPI cards, and edit/create modal
- Customer profile workspace with lookup, profile list, switch actions, and activity log
- Subscriber 360 read-only Profiles tab gated to the same module permission and `app_id = 1023`

## Permissions and RBAC

- New module row is seeded in `modules`
- Module access is granted only to active `SUPERADMIN` and `ADMIN` users for `app_id = 1023`
- All endpoints enforce both tenant gating and module access
- Existing module assignment flows remain unchanged; tenant admins can delegate access through current permissions UI

## Migration and Backfill

- ClickHouse table creation is additive through Laravel migration
- Owner profile backfill is lazy and idempotent on first read/mutation for a customer
- No existing PostgreSQL tables or columns are modified

## Testing Strategy

- Feature coverage should validate tenant gating, module authorization, policy CRUD, and profile summary responses
- Unit coverage should validate policy resolution, owner backfill, and profile limit enforcement
- Use PostgreSQL-backed app tests and mock ClickHouse service boundaries where full infrastructure is unavailable

## Deployment Plan

1. Run the new migration explicitly before traffic shift
2. Run `MultiProfileModuleSeeder`
3. Verify `modules` row and `user_access` updates only for `app_id = 1023`
4. Smoke test the new module page and subscriber read-only tab with a tenant 1023 admin
5. Monitor ClickHouse insert/query failures and module visibility

## Follow-On Integration

If customer-facing profile selection needs to travel into consumer sessions/tokens, the next step is to connect the admin session context to the external customer auth/profile service contract. This is intentionally separate from current SMS admin tenant scoping.