qzl
124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# 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**
|
|
|
|
```python
|
|
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**
|
|
|
|
```bash
|
|
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"
|
|
```
|