# iOS Deep Linking Guide

This document describes the URL deep linking system for testing and navigation in the BaoLife iOS app.

## URL Scheme

**Scheme**: `baolife://`

## Available Routes

### Main Tabs

| Route | Description |
|-------|-------------|
| `baolife://home` | Home tab (index 0) |
| `baolife://activities` | Activities tab (index 1) |
| `baolife://social` | Social tab (index 2) |
| `baolife://social/dating` | Social tab, Dating segment |
| `baolife://social/messages` | Social tab, Messages segment |
| `baolife://more` | Opens Quick Actions menu |

### Modals

| Route | Description |
|-------|-------------|
| `baolife://store` | Store modal |
| `baolife://achievements` | Achievements modal |
| `baolife://characters` | Characters/Relationships modal |
| `baolife://relationships` | Alias for characters |
| `baolife://daily-rewards` | Daily Rewards modal |
| `baolife://daily-quests` | Daily Quests modal |
| `baolife://items` | Items modal |
| `baolife://time-skip` | Time Skip modal |

### Testing Helpers

| Route | Description |
|-------|-------------|
| `baolife://skip-onboarding` | Bypasses onboarding flow |
| `baolife://set-age?age=16` | Sets character age (requires server support) |

### Debug Commands

| Route | Description |
|-------|-------------|
| `baolife://debug/dump` | Dumps full game state to Xcode console |
| `baolife://debug/preset/teen` | Load 15yo high school student preset |
| `baolife://debug/preset/youngAdult` | Load 22yo with job preset |
| `baolife://debug/preset/adult` | Load 35yo with family preset |
| `baolife://debug/preset/wealthy` | Load high money/diamonds preset |
| `baolife://debug/preset/lowEnergy` | Load low energy preset (test refills) |
| `baolife://debug/preset/relationships` | Load character with multiple relationships |

**Note:** Test presets require server-side support for the `debugSetup` message type.

## Usage

### From Terminal (Simulator)

```bash
# Navigate to a specific tab
xcrun simctl openurl booted "baolife://home"
xcrun simctl openurl booted "baolife://activities"
xcrun simctl openurl booted "baolife://social/dating"

# Open modals
xcrun simctl openurl booted "baolife://store"
xcrun simctl openurl booted "baolife://achievements"
xcrun simctl openurl booted "baolife://characters"

# Testing shortcuts
xcrun simctl openurl booted "baolife://skip-onboarding"
xcrun simctl openurl booted "baolife://set-age?age=21"

# Debug commands
xcrun simctl openurl booted "baolife://debug/dump"           # View state in Xcode console
xcrun simctl openurl booted "baolife://debug/preset/teen"    # Load teen preset
xcrun simctl openurl booted "baolife://debug/preset/wealthy" # Load wealthy preset
```

### From Safari (Device)

Type the URL directly in Safari:
```
baolife://social/dating
```

### From Another App

```swift
if let url = URL(string: "baolife://store") {
    UIApplication.shared.open(url)
}
```

## Implementation Details

### Files

- **DeepLinkManager.swift** (`Shared/Managers/DeepLinkManager.swift`) - URL parsing and route handling
- **Info.plist** - URL scheme registration (`CFBundleURLTypes`)
- **lichunWebsocketApp.swift** - `onOpenURL` handler

### Adding New Routes

1. Add case to `DeepLinkRoute` enum in `DeepLinkManager.swift`
2. Add parsing logic in `parse(url:)` method
3. Add handling logic in `handle(route:appViewModel:)` method

### Notes

- Deep links require onboarding to be complete (except `skip-onboarding`)
- Modals opened via deep link will overlay the current tab
- Dismiss modals by swiping down before testing tab navigation
- The `set-age` route logs the request but requires server-side implementation

## Common Testing Workflows

### Test Dating Age Gate
```bash
# Skip onboarding first
xcrun simctl openurl booted "baolife://skip-onboarding"

# Navigate to dating (will show age gate if under 16)
xcrun simctl openurl booted "baolife://social/dating"
```

### Test Store Flow
```bash
xcrun simctl openurl booted "baolife://store"
```

### Test Achievement System
```bash
xcrun simctl openurl booted "baolife://achievements"
```

### Quick Full App Test
```bash
# Run all navigation tests
for route in home activities social/dating store achievements characters; do
    xcrun simctl openurl booted "baolife://$route"
    sleep 2
done
```