# AppData Retirement Runbook

Use this when retiring an AppData key after its domain writes have moved to relation-table APIs. The order is fixed: backup, measure, freeze writes, compare, remove fallback, archive.

## Scope Gate

Retire one AppData key family at a time. Good candidates have domain CRUD writes, read APIs, pagination boundaries, audit events, and a rollback path.

## Preparation

```bash
pnpm backup:postgres -- --env-file .env.production
pnpm backup:server-data -- --env-file .env.production
pnpm deploy:smoke -- --base-url http://localhost
```

Record the key family being retired, the owning domain API, and the relation tables that replace it.

## Count And Consistency Checks

Run counts before disabling writes.

```bash
docker compose --env-file .env.production -f docker-compose.prod.yml exec postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select key, jsonb_array_length(value) as appdata_rows from app_data where key in ('products-overview','requirements','version-plans','dev-tasks','test-cases','bugs','members','task-categories','task-worklogs','overtime') order by key;"
docker compose --env-file .env.production -f docker-compose.prod.yml exec postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select 'requirements' as table_name, count(*) from requirements union all select 'version_plans', count(*) from version_plans union all select 'dev_tasks', count(*) from dev_tasks union all select 'test_cases', count(*) from test_cases union all select 'bugs', count(*) from bugs;"
```

For partitioned entities, also check missing partition keys.

```bash
docker compose --env-file .env.production -f docker-compose.prod.yml exec postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select 'requirements_missing_product' as check_name, count(*) from requirements where product_id is null union all select 'dev_tasks_missing_version', count(*) from dev_tasks where version_id is null union all select 'test_cases_missing_version', count(*) from test_cases where version_id is null union all select 'bugs_missing_version', count(*) from bugs where version_id is null;"
```

## Disable AppData Writes

1. Merge the domain-specific frontend store change that stops calling `saveServerData` for the retired key.
2. Keep AppData read fallback for one release while relation reads are verified.
3. Deploy and run smoke tests.

```bash
pnpm deploy:smoke -- --base-url http://localhost --expected-version "$APP_VERSION"
```

## Remove Fallback

Remove AppData read fallback only after one successful release where:

- Domain writes went through relation APIs.
- AppData row counts did not grow for the retired key.
- V2.2 read paths and page workflows returned expected data.
- No `AppData relation sync failed` logs appeared during the observation window.

## Archive

Export retired keys before any later table cleanup.

```bash
docker compose --env-file .env.production -f docker-compose.prod.yml exec postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "copy (select key, value, updated_at from app_data where key in ('dev-tasks','test-cases','bugs')) to stdout with csv header" > backups/postgres/appdata-retired-executions-20260708.csv
```

## Rollback

- If relation writes fail but AppData still has fresh data, roll back to the previous app image that still writes AppData.
- If AppData writes were already disabled and relation writes are bad, restore PostgreSQL from the backup made at the start of this runbook.
- If only read fallback removal caused the issue, roll back app images first and leave the database unchanged.

## Data Risks

- Removing fallback too early can hide valid historical JSON rows that were never mapped into relation tables.
- Re-enabling old AppData writes after relation writes have accepted new edits can overwrite newer relation state through compatibility sync.
- AppData exports can contain business-sensitive text; store backup CSV files in the same restricted location as database dumps.