# 5. Functional Requirements

### User Management

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-001 | List users with voice configuration including license status, phone number, and voice-enabled status | Must Have | Given authenticated CLI, when `users list` executed, then returns users with all specified fields |
| REQ-002 | Filter users by licensed/unlicensed, assigned/unassigned, and account type | Must Have | Given `users list --licensed --unassigned`, then only licensed users without phone numbers returned |
| REQ-003 | Show detailed user configuration including all voice policies and assignment sources | Must Have | Given valid user identifier, when `users show <user>` executed, then returns all voice policies with source |
| REQ-004 | Search users by name, UPN, or phone number with partial matching | Must Have | Given search query "john", when `users search john` executed, then returns all matching users |
| REQ-005 | Resolve users by UPN, display name, or object ID with disambiguation for multiple matches | Must Have | Given ambiguous display name, when used in command, then error lists matching candidates |

### Number Management

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-006 | List all phone numbers with status, type, assignment, and location | Must Have | Given authenticated CLI, when `numbers list` executed, then returns all numbers with specified fields |
| REQ-007 | Filter numbers by status (assigned/unassigned), type, and city | Must Have | Given filters applied, when `numbers list --status unassigned --type calling-plan`, then only matching numbers returned |
| REQ-008 | Show detailed number information including activation state, port status, and capabilities | Must Have | Given valid phone number, when `numbers show <number>` executed, then returns all detail fields |
| REQ-009 | Search numbers by pattern with wildcard support (last 4 digits, area code) | Must Have | Given pattern "206*", when `numbers search "206*"` executed, then returns all 206 area code numbers |
| REQ-010 | Assign phone number to user with emergency location, supporting async polling | Must Have | Given valid user/number/location, when `numbers assign` executed, then number assigned and status confirmed |
| REQ-011 | Enforce emergency location requirement for Calling Plan numbers (E911 compliance) | Must Have | Given Calling Plan number without location, when assign attempted, then error with location requirement message |
| REQ-012 | Unassign phone number with confirmation prompt and async polling | Must Have | Given assigned number, when `numbers unassign` executed with confirmation, then number unassigned |
| REQ-013 | Update phone number location or network site without reassignment | Should Have | Given assigned number, when `numbers update --location` executed, then location updated synchronously |
| REQ-014 | Bulk assign numbers from CSV with progress reporting and error handling | Must Have | Given valid CSV file, when `numbers bulk-assign` executed, then all rows processed with progress shown |
| REQ-015 | Support dry-run mode for assign/unassign/bulk operations | Must Have | Given --dry-run flag, when operation executed, then preview shown without changes made |

### Policy Management

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-016 | List available policies by type from CSV cache | Must Have | Given valid CSV cache, when `policies list calling` executed, then all calling policies listed |
| REQ-017 | Show user's effective policy assignments with assignment source | Must Have | Given valid user, when `policies show <user>` executed, then all policies shown with direct/group/global source |
| REQ-018 | Assign policy to user with validation against known policies | Must Have | Given valid policy name, when `policies assign` executed, then policy assigned successfully |
| REQ-019 | Support all voice policy types: calling, voicemail, emergency, caller-id, dial-plan, voice-routing | Must Have | Given any supported policy type, when policy commands executed, then operation succeeds |
| REQ-020 | Bulk assign policies from CSV | Should Have | Given valid CSV file, when `policies bulk-assign` executed, then all rows processed |

### Location Management

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-021 | List emergency locations from CSV cache with address details | Must Have | Given valid CSV cache, when `locations list` executed, then all locations listed with addresses |
| REQ-022 | Search locations by name, city, or address | Must Have | Given search query, when `locations search` executed, then matching locations returned |
| REQ-023 | Show detailed location information | Must Have | Given valid location identifier, when `locations show` executed, then full details displayed |
| REQ-024 | Display staleness warning when CSV cache > 30 days old | Must Have | Given stale CSV, when location commands executed, then warning displayed with refresh guidance |
| REQ-025 | Operate in degraded mode when CSV files missing | Should Have | Given missing CSV, when commands executed, then warning shown and operation proceeds where possible |

### Tenant Management

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-026 | List all configured tenant profiles | Must Have | Given configured tenants, when `tenants list` executed, then all profiles listed with status |
| REQ-027 | Switch active tenant preserving cached tokens | Must Have | Given valid tenant name, when `tenants switch` executed, then context switched in < 5 seconds |
| REQ-028 | Add new tenant profile via interactive wizard or flags | Must Have | Given valid credentials, when `tenants add` executed, then profile saved to config |
| REQ-029 | Test tenant connection and permissions | Must Have | Given tenant profile, when `tenants test` executed, then connectivity and permissions validated |
| REQ-030 | Remove tenant profile with confirmation | Must Have | Given existing tenant, when `tenants remove` executed with confirmation, then profile deleted |

### Authentication

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-031 | Support certificate-based authentication (recommended) | Must Have | Given valid certificate, when `auth login --method certificate` executed, then authenticated successfully |
| REQ-032 | Support client-secret authentication with env var | Must Have | Given secret in env var, when `auth login --method client-secret` executed, then authenticated successfully |
| REQ-033 | Auto-authenticate when token missing or expired | Must Have | Given expired token, when any command executed, then auto-login initiated |
| REQ-034 | Show current authentication status | Must Have | Given authenticated session, when `auth status` executed, then shows tenant, expiry, method |
| REQ-035 | Clear cached tokens (single tenant or all) | Must Have | Given cached tokens, when `auth logout` executed, then tokens cleared |
| REQ-036 | Refresh authentication tokens | Should Have | Given valid session, when `auth refresh` executed, then token refreshed |

### Output & UX

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-037 | Support JSON output for all commands via --json flag | Must Have | Given any list/show command, when --json flag used, then valid JSON output returned |
| REQ-038 | Display rich table output with color-coded status by default | Must Have | Given terminal with color support, when command executed, then colored tables displayed |
| REQ-039 | Show progress bars for bulk operations | Must Have | Given bulk operation, when executing, then progress bar shows completion percentage |
| REQ-040 | Provide verbose mode with API call logging | Must Have | Given --verbose flag, when command executed, then API calls and timing shown |
| REQ-041 | Include remediation guidance in all error messages | Must Have | Given any error, when displayed, then includes suggestions for resolution |

### API Contract Validation

| ID | Requirement | Priority | Testable Criteria |
|----|-------------|----------|-------------------|
| REQ-042 | Validate API responses against strict schemas, failing fast on unexpected changes | Must Have | Given schema mismatch, when API response received, then operation fails with ContractError |
| REQ-043 | Provide `api-check` command to validate API contracts before operations | Must Have | Given test tenant, when `api-check` executed, then all endpoint schemas validated and report generated |

---

