qzl
4.2 KiB
Backend Schemas Restructure Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Hard-cut refactor backend schema modules into clear domain/shared/enums boundaries while keeping API contracts in v1/*/schemas.py.
Architecture: Introduce schemas/enums.py and move reusable schema models into schemas/domain and schemas/shared. Update all backend imports to explicit new module paths and remove old schema package wrappers and duplicate directories.
Tech Stack: Python 3.13, Pydantic v2, Ruff, Pytest, Alembic migration runner.
Task 1: Create new schema module layout
Files:
- Create:
backend/src/schemas/enums.py - Create:
backend/src/schemas/domain/automation.py - Create:
backend/src/schemas/domain/inbox.py - Create:
backend/src/schemas/domain/schedule.py - Create:
backend/src/schemas/domain/memory.py - Create:
backend/src/schemas/domain/memory_content.py - Create:
backend/src/schemas/domain/chat_message.py - Create:
backend/src/schemas/domain/chat_session.py - Create:
backend/src/schemas/domain/todo.py - Create:
backend/src/schemas/domain/invite_code.py - Create:
backend/src/schemas/shared/user.py
Step 1: Write failing import checks
def test_new_schema_paths_importable() -> None:
import schemas.domain.automation # noqa: F401
Step 2: Run test to verify it fails
Run: uv run pytest backend/tests/unit -k new_schema_paths_importable -v
Expected: FAIL with import error
Step 3: Implement new modules
Copy and normalize existing reusable models into new modules.
Step 4: Run test to verify it passes
Run: uv run pytest backend/tests/unit -k new_schema_paths_importable -v
Expected: PASS
Task 2: Update all backend imports to new schema paths
Files:
- Modify:
backend/src/**/*.py(affected import lines)
Step 1: Write failing grep assertions
Run: uv run python -c "..." with assertions for old import patterns.
Step 2: Verify failures with old paths present
Run: uv run ruff check backend/src
Step 3: Implement import rewrites
Replace old paths (schemas.model_enums, schemas.automation, schemas.memories.memory_content, etc.) with new explicit modules.
Step 4: Verify static checks pass
Run: uv run ruff check backend/src
Expected: PASS
Task 3: Remove legacy schema wrappers and duplicates
Files:
- Delete:
backend/src/schemas/model_enums.py - Delete:
backend/src/schemas/automation/__init__.py - Delete:
backend/src/schemas/inbox/messages.py - Delete:
backend/src/schemas/schedule/items.py - Delete:
backend/src/schemas/memories/__init__.py - Delete:
backend/src/schemas/memories/memory_content.py - Delete:
backend/src/schemas/messages/chat_message.py - Delete:
backend/src/schemas/messages/__init__.py - Delete:
backend/src/schemas/sessions/chat_session.py - Delete:
backend/src/schemas/sessions/__init__.py - Delete:
backend/src/schemas/todo/contracts.py - Delete:
backend/src/schemas/todo/__init__.py - Delete:
backend/src/schemas/user/context.py - Delete:
backend/src/schemas/user/__init__.py - Delete:
backend/src/schemas/inbox/__init__.py - Delete:
backend/src/schemas/invite_codes/__init__.py - Modify:
backend/src/schemas/__init__.py
Step 1: Remove old modules
Delete legacy wrappers after all imports are rewritten.
Step 2: Verify no old imports remain
Run: uv run python -c "..." or grep-based assertion commands.
Expected: zero matches
Task 4: Verification and migration
Files:
- Verify only
Step 1: Run quality gates
Run: uv run ruff check backend/src
Step 2: Run impacted tests
Run: uv run pytest backend/tests/unit/v1/automation_jobs backend/tests/unit/v1/schedule_items backend/tests/unit/v1/todo backend/tests/unit/v1/friendships backend/tests/unit/v1/inbox_messages backend/tests/unit/v1/users backend/tests/unit/v1/agent backend/tests/unit/core/agentscope
Step 3: Run migration script
Run: ./infra/scripts/dev-migrate.sh migrate
Step 4: Commit
git add backend/src/schemas backend/src/v1 backend/src/models backend/src/core docs/plans
git commit -m "refactor: restructure backend schema modules by domain boundaries"