docs: add code architecture refactoring PRD

.claude/specs/code-architecture/REFACTORING-PRD.md

@@ -0,0 +1,416 @@
+# 代码架构重构 PRD
+
+> 版本: 1.0
+> 日期: 2025-01-21
+> 状态: 待实施
+
+---
+
+## 1. 背景与目标
+
+### 1.1 现状问题
+
+经过代码审计，发现以下架构债务：
+
+| 问题 | 位置 | 影响 |
+|------|------|------|
+| 缺少 Schemas 层 | Backend API | 类型不安全，文档生成差 |
+| Fat Controller | `stories.py` 562行 | 难测试，职责混乱 |
+| 重复加载逻辑 | Frontend 5+ 组件 | 代码冗余，维护困难 |
+| 无 Repository 层 | Backend | DB 查询散落，难复用 |
+
+### 1.2 重构目标
+
+- **后端**：引入 Pydantic Schemas 层，分离请求/响应模型
+- **前端**：抽取 Vue Composables，消除重复逻辑
+- **原则**：渐进式重构，不破坏现有功能
+
+---
+
+## 2. 后端重构：Schemas 层
+
+### 2.1 目标结构
+
+```
+backend/app/
+├── api/                    # 路由层（瘦身）
+│   ├── stories.py
+│   └── ...
+├── schemas/                # 新增：Pydantic 模型
+│   ├── __init__.py
+│   ├── auth.py
+│   ├── story.py
+│   ├── profile.py
+│   ├── universe.py
+│   ├── memory.py
+│   ├── push_config.py
+│   └── common.py           # 分页、错误响应等通用结构
+├── models/                 # SQLAlchemy ORM（原 db/）
+└── services/               # 业务逻辑
+```
+
+### 2.2 Schema 设计规范
+
+#### 命名约定
+
+| 类型 | 命名模式 | 示例 |
+|------|----------|------|
+| 创建请求 | `{Entity}Create` | `StoryCreate` |
+| 更新请求 | `{Entity}Update` | `ProfileUpdate` |
+| 响应模型 | `{Entity}Response` | `StoryResponse` |
+| 列表响应 | `{Entity}ListResponse` | `StoryListResponse` |
+
+#### 示例：Story Schema
+
+```python
+# schemas/story.py
+from datetime import datetime
+from typing import Literal
+from pydantic import BaseModel, Field
+
+class StoryCreate(BaseModel):
+    """创建故事请求"""
+    type: Literal["keywords", "enhance", "storybook"]
+    data: str = Field(..., min_length=1, max_length=2000)
+    education_theme: str | None = None
+    child_profile_id: str | None = None
+    universe_id: str | None = None
+
+class StoryResponse(BaseModel):
+    """故事响应"""
+    id: int
+    title: str
+    story_text: str | None
+    pages: list[dict] | None
+    image_url: str | None
+    mode: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True  # 支持 ORM 模型转换
+
+class StoryListResponse(BaseModel):
+    """故事列表响应"""
+    stories: list[StoryResponse]
+    total: int
+    page: int
+    page_size: int
+```
+
+### 2.3 迁移步骤
+
+| 阶段 | 任务 | 文件 |
+|------|------|------|
+| P1 | 创建 `schemas/common.py` | 分页、错误响应 |
+| P2 | 创建 `schemas/story.py` | 故事相关模型 |
+| P3 | 创建 `schemas/profile.py` | 档案相关模型 |
+| P4 | 创建 `schemas/universe.py` | 宇宙相关模型 |
+| P5 | 创建 `schemas/auth.py` | 认证相关模型 |
+| P6 | 创建 `schemas/memory.py` | 记忆相关模型 |
+| P7 | 创建 `schemas/push_config.py` | 推送配置模型 |
+| P8 | 重构 `api/stories.py` | 使用新 schemas |
+| P9 | 重构其他 API 文件 | 逐个迁移 |
+
+### 2.4 验收标准
+
+- [ ] 所有 API endpoint 使用 `response_model` 参数
+- [ ] 请求体使用 Pydantic 模型而非 `Body(...)`
+- [ ] OpenAPI 文档自动生成完整类型
+- [ ] 现有测试全部通过
+- [ ] `ruff check` 无错误
+
+---
+
+## 3. 前端重构：Composables
+
+### 3.1 目标结构
+
+```
+frontend/src/
+├── composables/            # 新增：可复用逻辑
+│   ├── index.ts
+│   ├── useAsyncData.ts     # 异步数据加载
+│   ├── useFormValidation.ts # 表单验证
+│   └── useDateFormat.ts    # 日期格式化
+├── components/
+├── stores/
+└── views/
+```
+
+### 3.2 Composable 设计
+
+#### 3.2.1 useAsyncData
+
+**用途**：统一处理 API 数据加载的 loading/error 状态
+
+```typescript
+// composables/useAsyncData.ts
+import { ref, type Ref } from 'vue'
+
+interface AsyncDataOptions<T> {
+  immediate?: boolean      // 立即执行，默认 true
+  initialData?: T          // 初始数据
+  onError?: (e: Error) => void
+}
+
+interface AsyncDataReturn<T> {
+  data: Ref<T | null>
+  loading: Ref<boolean>
+  error: Ref<string>
+  execute: () => Promise<void>
+  reset: () => void
+}
+
+export function useAsyncData<T>(
+  fetcher: () => Promise<T>,
+  options: AsyncDataOptions<T> = {}
+): AsyncDataReturn<T> {
+  const { immediate = true, initialData = null, onError } = options
+
+  const data = ref<T | null>(initialData) as Ref<T | null>
+  const loading = ref(false)
+  const error = ref('')
+
+  async function execute() {
+    loading.value = true
+    error.value = ''
+    try {
+      data.value = await fetcher()
+    } catch (e) {
+      const message = e instanceof Error ? e.message : '加载失败'
+      error.value = message
+      onError?.(e instanceof Error ? e : new Error(message))
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function reset() {
+    data.value = initialData
+    loading.value = false
+    error.value = ''
+  }
+
+  if (immediate) {
+    execute()
+  }
+
+  return { data, loading, error, execute, reset }
+}
+```
+
+**使用示例**：
+
+```typescript
+// views/MyStories.vue（重构前 40 行 → 重构后 10 行）
+import { useAsyncData } from '@/composables'
+import { api } from '@/api/client'
+
+const { data: response, loading, error } = useAsyncData(
+  () => api.get<StoryListResponse>('/api/stories')
+)
+const stories = computed(() => response.value?.stories ?? [])
+```
+
+#### 3.2.2 useFormValidation
+
+**用途**：统一表单验证逻辑
+
+```typescript
+// composables/useFormValidation.ts
+import { ref, reactive } from 'vue'
+
+type ValidationRule = (value: unknown) => string | true
+
+interface FieldRules {
+  [field: string]: ValidationRule[]
+}
+
+export function useFormValidation<T extends Record<string, unknown>>(
+  initialData: T,
+  rules: FieldRules
+) {
+  const form = reactive({ ...initialData })
+  const errors = reactive<Record<string, string>>({})
+
+  function validate(): boolean {
+    let valid = true
+    for (const [field, fieldRules] of Object.entries(rules)) {
+      const value = form[field]
+      for (const rule of fieldRules) {
+        const result = rule(value)
+        if (result !== true) {
+          errors[field] = result
+          valid = false
+          break
+        } else {
+          errors[field] = ''
+        }
+      }
+    }
+    return valid
+  }
+
+  function reset() {
+    Object.assign(form, initialData)
+    Object.keys(errors).forEach(k => errors[k] = '')
+  }
+
+  return { form, errors, validate, reset }
+}
+
+// 常用验证规则
+export const required = (msg = '此字段必填') =>
+  (v: unknown) => (v !== null && v !== undefined && v !== '') || msg
+
+export const minLength = (min: number, msg?: string) =>
+  (v: unknown) => (typeof v === 'string' && v.length >= min) || msg || `至少 ${min} 个字符`
+
+export const maxLength = (max: number, msg?: string) =>
+  (v: unknown) => (typeof v === 'string' && v.length <= max) || msg || `最多 ${max} 个字符`
+```
+
+#### 3.2.3 useDateFormat
+
+**用途**：统一日期格式化
+
+```typescript
+// composables/useDateFormat.ts
+export function useDateFormat() {
+  function formatDate(dateStr: string | Date, format: 'date' | 'datetime' | 'relative' = 'date'): string {
+    const date = typeof dateStr === 'string' ? new Date(dateStr) : dateStr
+
+    if (format === 'relative') {
+      return formatRelative(date)
+    }
+
+    const year = date.getFullYear()
+    const month = String(date.getMonth() + 1).padStart(2, '0')
+    const day = String(date.getDate()).padStart(2, '0')
+
+    if (format === 'date') {
+      return `${year}-${month}-${day}`
+    }
+
+    const hours = String(date.getHours()).padStart(2, '0')
+    const minutes = String(date.getMinutes()).padStart(2, '0')
+    return `${year}-${month}-${day} ${hours}:${minutes}`
+  }
+
+  function formatRelative(date: Date): string {
+    const now = new Date()
+    const diffMs = now.getTime() - date.getTime()
+    const diffMins = Math.floor(diffMs / 60000)
+    const diffHours = Math.floor(diffMs / 3600000)
+    const diffDays = Math.floor(diffMs / 86400000)
+
+    if (diffMins < 1) return '刚刚'
+    if (diffMins < 60) return `${diffMins} 分钟前`
+    if (diffHours < 24) return `${diffHours} 小时前`
+    if (diffDays < 7) return `${diffDays} 天前`
+    return formatDate(date, 'date')
+  }
+
+  return { formatDate, formatRelative }
+}
+```
+
+### 3.3 迁移步骤
+
+| 阶段 | 任务 | 影响文件 |
+|------|------|----------|
+| P1 | 创建 `composables/useAsyncData.ts` | 新文件 |
+| P2 | 创建 `composables/useDateFormat.ts` | 新文件 |
+| P3 | 创建 `composables/useFormValidation.ts` | 新文件 |
+| P4 | 创建 `composables/index.ts` | 统一导出 |
+| P5 | 重构 `views/MyStories.vue` | 使用 useAsyncData |
+| P6 | 重构 `views/ChildProfiles.vue` | 使用 useAsyncData |
+| P7 | 重构 `views/Universes.vue` | 使用 useAsyncData |
+| P8 | 重构 `components/CreateStoryModal.vue` | 使用 useFormValidation |
+| P9 | 同步重构 `admin-frontend/` | 复制 composables |
+
+### 3.4 验收标准
+
+- [ ] `composables/` 目录包含 3 个核心 composable
+- [ ] 至少 3 个 view 组件使用 `useAsyncData`
+- [ ] `CreateStoryModal` 使用 `useFormValidation`
+- [ ] `npm run build` 无类型错误
+- [ ] 现有功能正常运行
+
+---
+
+## 4. 风险与缓解
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 重构引入 bug | 高 | 每个阶段运行测试 |
+| 类型不兼容 | 中 | 使用 `from_attributes = True` |
+| 前端构建失败 | 中 | 逐文件迁移，及时 commit |
+
+---
+
+## 5. 时间估算
+
+| 模块 | 工作量 | 预计时间 |
+|------|--------|----------|
+| Backend Schemas | 10 个新文件 + 9 个 API 重构 | 3-4 小时 |
+| Frontend Composables | 4 个新文件 + 6 个组件重构 | 2-3 小时 |
+| 测试验证 | 全量回归 | 1 小时 |
+| **总计** | | **6-8 小时** |
+
+---
+
+## 6. 后续迭代
+
+本次重构完成后，可继续：
+
+1. **Repository 层**：抽象 DB 查询逻辑
+2. **Service 层瘦身**：拆分 `provider_router.py` (433行)
+3. **前端共享包**：`frontend` 和 `admin-frontend` 共用 UI 组件
+4. **API 版本化**：引入 `/api/v1/` 前缀
+
+---
+
+## 附录：文件清单
+
+### 新增文件
+
+```
+backend/app/schemas/
+├── __init__.py
+├── common.py
+├── auth.py
+├── story.py
+├── profile.py
+├── universe.py
+├── memory.py
+└── push_config.py
+
+frontend/src/composables/
+├── index.ts
+├── useAsyncData.ts
+├── useFormValidation.ts
+└── useDateFormat.ts
+```
+
+### 修改文件
+
+```
+backend/app/api/
+├── stories.py
+├── profiles.py
+├── universes.py
+├── memories.py
+├── push_configs.py
+├── reading_events.py
+└── auth.py
+
+frontend/src/views/
+├── MyStories.vue
+├── ChildProfiles.vue
+├── Universes.vue
+└── ...
+
+frontend/src/components/
+└── CreateStoryModal.vue
+```