docs(05): create CloudKit CRUD phase plans
Phase 5: CloudKit CRUD - 2 plans created - 4 total tasks defined - Ready for execution Plan 05-01: Smart sync with change detection - Change detection with diff reporting - Differential sync (upload only changed records) Plan 05-02: Verification and record management - Sync verification (CloudKit vs local comparison) - Individual record CRUD operations Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Trey t
165
.planning/phases/05-cloudkit-crud/05-02-PLAN.md
Normal file
165
.planning/phases/05-cloudkit-crud/05-02-PLAN.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
phase: 05-cloudkit-crud
|
||||
plan: 02
|
||||
type: execute
|
||||
domain: data-pipeline
|
||||
---
|
||||
|
||||
<objective>
|
||||
Add sync verification and individual record management to cloudkit_import.py.
|
||||
|
||||
Purpose: Enable verification that CloudKit matches local data, plus ability to manage individual records.
|
||||
Output: Enhanced cloudkit_import.py with --verify, --get, --update-record, and --delete-record flags.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
~/.claude/get-shit-done/workflows/execute-phase.md
|
||||
~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/05-cloudkit-crud/05-01-PLAN.md
|
||||
|
||||
**Relevant source files:**
|
||||
@Scripts/cloudkit_import.py
|
||||
|
||||
**Tech stack available:** Python 3, requests, cryptography, CloudKit server-to-server API
|
||||
**Established patterns:** query_all() for full record retrieval, compute_diff() for change detection, sync_diff() for smart sync
|
||||
|
||||
**Prior plan context:**
|
||||
- Plan 05-01 adds change detection and smart sync
|
||||
- query_all() returns dict of recordName -> record data
|
||||
- compute_diff() identifies new/updated/unchanged/deleted
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Add sync verification with --verify flag</name>
|
||||
<files>Scripts/cloudkit_import.py</files>
|
||||
<action>
|
||||
Add sync verification to confirm CloudKit matches local canonical data.
|
||||
|
||||
1. Add `--verify` flag to argparse:
|
||||
- Query CloudKit for all record types
|
||||
- Compare counts with local data
|
||||
- Report discrepancies
|
||||
|
||||
2. Add `verify_sync(ck, data_dir, verbose)` function:
|
||||
- For each record type (Stadium, Team, Game, LeagueStructure, TeamAlias, StadiumAlias):
|
||||
- Query CloudKit count
|
||||
- Get local count from JSON files
|
||||
- Compare and report
|
||||
- Output format per type:
|
||||
```
|
||||
Stadium: CloudKit=32, Local=32 [OK]
|
||||
Game: CloudKit=5758, Local=5760 [MISMATCH: 2 missing in CloudKit]
|
||||
```
|
||||
|
||||
3. Add spot-check verification:
|
||||
- Random sample 5 records per type (if count matches)
|
||||
- Verify field values match between CloudKit and local
|
||||
- Report any field mismatches found
|
||||
|
||||
4. Add `--verify-deep` flag:
|
||||
- Full field-by-field comparison of ALL records (not just sample)
|
||||
- Report each mismatch with recordName and field name
|
||||
- Warning: "Deep verification may take several minutes for large datasets"
|
||||
|
||||
5. Menu integration:
|
||||
- Add option 14: "Verify sync (quick)"
|
||||
- Add option 15: "Verify sync (deep)"
|
||||
|
||||
Avoid: Modifying any data during verification. This is read-only.
|
||||
</action>
|
||||
<verify>
|
||||
```bash
|
||||
cd Scripts && python cloudkit_import.py --verify --verbose
|
||||
```
|
||||
Should output verification report showing CloudKit vs local counts with OK/MISMATCH status.
|
||||
</verify>
|
||||
<done>--verify flag reports accurate comparison between CloudKit and local data for all record types</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Add individual record management commands</name>
|
||||
<files>Scripts/cloudkit_import.py</files>
|
||||
<action>
|
||||
Add commands for managing individual records by ID.
|
||||
|
||||
1. Add `--get <type> <id>` flag:
|
||||
- Query single record by recordName
|
||||
- Print all field values in formatted output
|
||||
- Example: `--get Stadium stadium_nba_td_garden`
|
||||
|
||||
2. Add CloudKit `lookup(record_names)` method:
|
||||
- Use records/lookup endpoint for efficient single/batch lookup
|
||||
- Return list of records
|
||||
|
||||
3. Add `--update-record <type> <id> <field>=<value>` flag:
|
||||
- Lookup record to get current recordChangeTag
|
||||
- Update specified field(s)
|
||||
- Handle CONFLICT error with retry
|
||||
- Example: `--update-record Stadium stadium_nba_td_garden capacity=19156`
|
||||
|
||||
4. Add `--delete-record <type> <id>` flag:
|
||||
- Lookup record to get recordChangeTag
|
||||
- Delete single record
|
||||
- Confirm before delete (unless --force)
|
||||
- Example: `--delete-record Game game_mlb_2025_ari_phi_0401`
|
||||
|
||||
5. Add `--list <type>` flag:
|
||||
- Query all records of type
|
||||
- Print recordNames (one per line)
|
||||
- Support `--list <type> --count` for just the count
|
||||
- Example: `--list Stadium` prints all stadium IDs
|
||||
|
||||
6. Error handling:
|
||||
- Record not found: "Error: No Stadium with id 'xyz' found in CloudKit"
|
||||
- Invalid type: "Error: Unknown record type 'Foo'. Valid types: Stadium, Team, Game, ..."
|
||||
|
||||
Avoid: Deleting records without confirmation. Updating records without checking conflict.
|
||||
</action>
|
||||
<verify>
|
||||
```bash
|
||||
cd Scripts && python cloudkit_import.py --get Stadium stadium_nba_td_garden
|
||||
```
|
||||
Should print all fields for the specified stadium record.
|
||||
|
||||
```bash
|
||||
cd Scripts && python cloudkit_import.py --list Game --count
|
||||
```
|
||||
Should print the count of Game records in CloudKit.
|
||||
</verify>
|
||||
<done>Individual record management commands work: --get, --list, --update-record, --delete-record</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Before declaring plan complete:
|
||||
- [ ] `--verify` reports accurate count comparison for all record types
|
||||
- [ ] `--verify-deep` performs full field comparison with mismatch reporting
|
||||
- [ ] `--get <type> <id>` retrieves and displays single record
|
||||
- [ ] `--list <type>` lists all recordNames for type
|
||||
- [ ] `--update-record` updates field with conflict handling
|
||||
- [ ] `--delete-record` deletes with confirmation
|
||||
- [ ] Interactive menu has options 14-15
|
||||
- [ ] No regressions to existing functionality
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Verification accurately detects sync discrepancies
|
||||
- Individual record operations work for all record types
|
||||
- Conflict handling prevents data corruption
|
||||
- All CRUD operations now fully supported
|
||||
- Phase 5 complete
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/05-cloudkit-crud/05-02-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user