# 4. User Stories

### US-001: Quick User Lookup

**As an** IT administrator
**I want to** quickly look up a user's phone configuration from the command line
**So that I can** answer help desk tickets without navigating through the Teams Admin Center

**Acceptance Criteria:**
1. Can retrieve user by UPN, display name, or object ID
2. Response displays phone number, license status, and all voice policies
3. Command completes in < 3 seconds for single user lookup
4. Output clearly shows policy assignment source (direct/group/global)

**Implementation Tasks:**
- Implement `users show <user>` command
- Add user resolution logic (UPN/name/ID)
- Format policy display with assignment source

---

### US-002: Assign Phone Number

**As an** IT administrator
**I want to** assign a phone number to a user with emergency location in one command
**So that I can** complete new employee phone setup in under a minute

**Acceptance Criteria:**
1. Can specify user, phone number, and emergency location in single command
2. Validates user has Teams Phone license before attempting assignment
3. Validates location exists (from CSV cache) before API call
4. Shows real-time progress while async operation completes
5. Provides clear success/failure message with details

**Implementation Tasks:**
- Implement `numbers assign <user> <number> [location]` command
- Add async operation polling with progress display
- Implement location validation against CSV cache
- Add E911 enforcement for Calling Plan numbers

---

### US-003: Bulk Phone Assignment

**As an** MSP administrator
**I want to** assign phone numbers to multiple users from a CSV file
**So that I can** onboard entire departments or client organizations efficiently

**Acceptance Criteria:**
1. Accepts CSV with columns: user, phone_number, location
2. Validates all rows before starting assignments (--dry-run mode)
3. Shows live progress bar during execution
4. Continues processing after individual failures (--continue-on-error)
5. Generates results file with success/failure per row
6. Supports default location fallback for rows without location

**Implementation Tasks:**
- Implement `numbers bulk-assign <csv-file>` command
- Add CSV validation and parsing
- Implement progress bar with real-time status
- Generate results output file

---

### US-004: Search Phone Inventory

**As an** IT administrator
**I want to** search available phone numbers by pattern or status
**So that I can** find an appropriate number to assign to a new user

**Acceptance Criteria:**
1. Can search by last 4 digits, area code pattern, or wildcard
2. Can filter by status (unassigned, assigned, reserved)
3. Can filter by number type (Calling Plan, Direct Routing, Operator Connect)
4. Results show number, status, type, and assigned user (if any)

**Implementation Tasks:**
- Implement `numbers search <pattern>` command
- Add pattern matching (wildcards, partial numbers)
- Add status and type filters

---

### US-005: Multi-Tenant Management

**As an** MSP administrator
**I want to** quickly switch between client tenants
**So that I can** perform operations across multiple clients without re-authenticating

**Acceptance Criteria:**
1. Can list all configured tenant profiles
2. Can switch active tenant with single command (< 5 seconds)
3. Cached tokens are reused when switching back to a tenant
4. Can override tenant for single command with --tenant flag
5. Clear indication of current active tenant in prompts/output

**Implementation Tasks:**
- Implement `tenants list`, `tenants switch`, `tenants current` commands
- Implement token caching per tenant
- Add --tenant global flag override

---

### US-006: Policy Assignment

**As an** IT administrator
**I want to** view and assign voice policies to users
**So that I can** manage calling, voicemail, and emergency policies consistently

**Acceptance Criteria:**
1. Can view all policy assignments for a user with source (direct/group/global)
2. Can assign any supported voice policy type to a user
3. Can reset user to global/default policy
4. Validates policy exists before assignment attempt

**Implementation Tasks:**
- Implement `policies show <user>` command
- Implement `policies assign <user> <type> <name>` command
- Add policy validation against CSV cache

---

### US-007: Emergency Location Management

**As an** IT administrator
**I want to** view and search emergency locations
**So that I can** select the correct location when assigning phone numbers

**Acceptance Criteria:**
1. Can list all emergency locations with address details
2. Can search locations by name, city, or address
3. Can view full details of a specific location
4. Shows staleness warning if CSV data is > 30 days old

**Implementation Tasks:**
- Implement `locations list`, `locations show`, `locations search` commands
- Add CSV reading and validation
- Implement staleness detection and warnings

---

### US-008: Unassign Phone Number

**As an** IT administrator
**I want to** unassign a phone number from a user
**So that I can** reclaim numbers from departing employees

**Acceptance Criteria:**
1. Can unassign by specifying only the phone number
2. Shows confirmation prompt before unassignment (unless --force)
3. Provides dry-run preview option
4. Waits for async operation completion by default

**Implementation Tasks:**
- Implement `numbers unassign <number>` command
- Add confirmation prompt and --force flag
- Add --dry-run support

---

