refactor: 重构 schemas 结构，统一枚举定义

2026-03-25 12:36:31 +08:00
parent 389f5248fc
commit d22ded21f8
122 changed files with 774 additions and 1456 deletions
@@ -0,0 +1,123 @@
+# 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"
+```