refactor: 重构 schemas 结构，统一枚举定义
This commit is contained in:
qzl
@@ -0,0 +1,99 @@
|
||||
# Protocols 文档修复计划
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** 修复 protocols 文档中与后端实现不一致的错误
|
||||
|
||||
**Architecture:** 直接修改 docs/protocols/ 下的 markdown 文件，确保文档与 backend/src/models/ 中的实际模型定义保持一致
|
||||
|
||||
**Tech Stack:** Markdown 编辑
|
||||
|
||||
---
|
||||
|
||||
## 修复任务清单
|
||||
|
||||
### Task 1: 修复 Memories Protocol - 移除不存在的 `agent_id` 字段
|
||||
|
||||
**文件:**
|
||||
- 修改: `docs/protocols/models/memory.md`
|
||||
|
||||
**修改内容:**
|
||||
- 从 "数据库存储" 章节的表格中移除 `agent_id` 字段
|
||||
- 该字段在实现中不存在
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 修复 InboxMessages Protocol - 添加缺失的 `group_id` 字段
|
||||
|
||||
**文件:**
|
||||
- 修改: `docs/protocols/models/inbox-messages.md`
|
||||
|
||||
**修改内容:**
|
||||
- 在 `InboxMessageResponse` 数据结构中添加 `group_id: uuid | null` 字段
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 修复 ScheduleItems Protocol - 补充 `permission` 位掩码说明
|
||||
|
||||
**文件:**
|
||||
- 修改: `docs/protocols/calendar/schedule-items.md`
|
||||
|
||||
**修改内容:**
|
||||
- 在 `ScheduleItemResponse` 的说明中，添加 `permission` 字段的位掩码语义：
|
||||
- `1` = view
|
||||
- `2` = invite
|
||||
- `4` = edit
|
||||
- 在 `ScheduleItemShareRequest` 中补充说明
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 修复 Friendships Protocol - 补充内部状态说明
|
||||
|
||||
**文件:**
|
||||
- 修改: `docs/protocols/models/friendships.md`
|
||||
|
||||
**修改内容:**
|
||||
- 在 `FriendRequestResponse` 的 `status` 字段说明中，添加注释：
|
||||
- `blocked` 和 `declined` 为内部实现状态
|
||||
- 对外返回时映射为 `rejected`
|
||||
- 说明这是实现细节，客户端应处理所有枚举值
|
||||
|
||||
---
|
||||
|
||||
### Task 5: 修复 Memories Protocol - 改进 `source` 列移除说明
|
||||
|
||||
**文件:**
|
||||
- 修改: `docs/protocols/models/memory.md`
|
||||
|
||||
**修改内容:**
|
||||
- 在 "数据库存储" 章节的表格中，明确标注 `source` 列已移除
|
||||
- 或者在表格下方添加更醒目的 "已移除字段" 说明
|
||||
|
||||
---
|
||||
|
||||
### Task 6: 修复 Automation Jobs Protocol - 添加 `bootstrap_key` 字段
|
||||
|
||||
**文件:**
|
||||
- 修改: `docs/protocols/models/automation-jobs.md`
|
||||
|
||||
**修改内容:**
|
||||
- 在 "Canonical Fields" 表格中添加 `bootstrap_key: string | null` 字段说明
|
||||
- 简短说明其用途（引导配置键）
|
||||
|
||||
---
|
||||
|
||||
## 执行顺序
|
||||
|
||||
1. Task 1 - Memories: 移除 agent_id
|
||||
2. Task 2 - InboxMessages: 添加 group_id
|
||||
3. Task 3 - ScheduleItems: 补充 permission 说明
|
||||
4. Task 4 - Friendships: 补充状态说明
|
||||
5. Task 5 - Memories: 改进 source 说明
|
||||
6. Task 6 - AutomationJobs: 添加 bootstrap_key
|
||||
|
||||
---
|
||||
|
||||
## 验证方式
|
||||
|
||||
- 人工检查：对比修改后的文档与 backend/src/models/ 中的实际模型定义
|
||||
- 确保文档中描述的每个字段都能在对应 model 文件中找到
|
||||
@@ -0,0 +1,29 @@
|
||||
# Backend Schemas Restructure Design
|
||||
|
||||
**Goal:** Restructure `backend/src/schemas` into clear domain/shared/enums modules while keeping API contracts in `backend/src/v1/*/schemas.py`.
|
||||
|
||||
**Architecture:** Move reusable validation models and enums into `schemas/domain`, `schemas/shared`, and `schemas/enums.py`. Keep versioned request/response contracts in `v1/*/schemas.py` and update imports to explicit module paths. Remove legacy aggregate exports and duplicate/empty schema directories.
|
||||
|
||||
**Tech Stack:** Python 3.13, Pydantic v2, Ruff, Pytest.
|
||||
|
||||
---
|
||||
|
||||
## Approved decisions
|
||||
|
||||
- Use one-shot hard cut.
|
||||
- Keep API contracts in `backend/src/v1/*/schemas.py`.
|
||||
- Keep `schemas` as reusable constraints only.
|
||||
- Remove implicit root re-export usage.
|
||||
|
||||
## Target structure
|
||||
|
||||
- `backend/src/schemas/enums.py`
|
||||
- `backend/src/schemas/domain/*.py`
|
||||
- `backend/src/schemas/shared/*.py`
|
||||
- `backend/src/v1/*/schemas.py` (unchanged naming and ownership)
|
||||
|
||||
## Validation gates
|
||||
|
||||
- `uv run ruff check ...`
|
||||
- `uv run pytest ...` for impacted suites
|
||||
- `./infra/scripts/dev-migrate.sh migrate`
|
||||
@@ -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"
|
||||
```
|
||||
Reference in New Issue
Block a user