# 记忆系统开发指南 (Development Guide)

本文档详细说明了 PRD 中定义的记忆系统的技术实现细节。

## 1. 数据库架构变更 (Schema Changes)

目前的 `MemoryItem` 表结构尚可，但需要增强字段以支持丰富的情感和元数据。

### 1.1 `MemoryItem` 表优化
建议使用 Alembic 进行迁移，增加以下字段或在 `value` JSON 中规范化以下结构：

```python
# 建议在 models.py 中明确这些字段，或者严格定义 value 字段的 Schema
class MemoryItem(Base):
    # ... 现有字段 ...
    
    # 新增/规范化字段建议
    # value 字段的 JSON 结构规范：
    # {
    #   "content": "小兔子战胜了大灰狼",      # 记忆的核心文本
    #   "keywords": ["勇敢", "森林"],         # 用于检索的关键词
    #   "emotion": "positive",               # 情感倾向: positive/negative/neutral
    #   "source_story_id": 123,              # 来源故事 ID
    #   "confidence": 0.85                   # 记忆置信度 (如果是 AI 自动提取)
    # }
```

### 1.2 `StoryUniverse` 表优化 (成就系统)
目前的成就存储在 `achievements` JSON 字段中。为了支持更复杂的查询（如"获得勇气勋章的所有用户"），建议将其重构为独立关联表，或保持 JSON 但规范化结构。

**当前 JSON 结构规范**:
```json
[
  {
    "id": "badge_courage_01",
    "type": "勇气",
    "name": "小小勇士",
    "description": "第一次在故事中独自面对困难",
    "icon_url": "badges/courage.png",
    "obtained_at": "2023-10-27T10:00:00Z",
    "source_story_id": 45
  }
]
```

---

## 2. 核心逻辑实现

### 2.1 记忆注入逻辑 (Prompt Engineering)

修改 `backend/app/api/stories.py` 中的 `_build_memory_context` 函数。

**目标**: 生成一段自然的、不仅是罗列数据的 Prompt。

**伪代码逻辑**:
```python
def format_memory_for_prompt(memories: list[MemoryItem]) -> str:
    """
    将记忆项转换为自然语言 Prompt 片段。
    """
    context_parts = []
    
    # 1. 角色记忆
    chars = [m for m in memories if m.type == 'favorite_character']
    if chars:
        names = ", ".join([c.value['name'] for c in chars])
        context_parts.append(f"孩子特别喜欢的角色有：{names}。请尝试让他们客串出场。")
        
    # 2. 近期情节
    recent_stories = [m for m in memories if m.type == 'recent_story'][:2]
    if recent_stories:
        for story in recent_stories:
            context_parts.append(f"最近发生过：{story.value['summary']}。可以在对话中不经意地提及此事。")
            
    # 3. 避雷区 (负面记忆)
    scary = [m for m in memories if m.type == 'scary_element']
    if scary:
        items = ", ".join([s.value['keyword'] for s in scary])
        context_parts.append(f"【绝对禁止】不要出现以下让孩子害怕的元素：{items}。")

    return "\n".join(context_parts)
```

### 2.2 成就提取与通知流程

当前流程在 `app/tasks/achievements.py`。需要完善闭环。

**改进后的流程**:
1.  **Story Generation**: 故事生成成功，存入数据库。
2.  **Async Task**: 触发 Celery 任务 `extract_story_achievements`。
3.  **LLM Analysis**: 调用 Gemini 分析故事，提取成就。
4.  **Update DB**: 更新 `StoryUniverse.achievements`。
5.  **Notification (新增)**:
    *   创建一个 `Notification` 或 `UserMessage` 记录（需要新建表或使用 Redis Pub/Sub）。
    *   前端轮询或通过 SSE (Server-Sent Events) 接收通知："🎉 恭喜！在这个故事里，小明获得了[诚实勋章]！"

### 2.3 记忆清理与衰减 (Maintenance)

需要一个后台定时任务（Cron Job），清理无效记忆，避免 Prompt 过长。

*   **频率**: 每天一次。
*   **逻辑**:
    *   删除 `ttl_days` 已过期的记录。
    *   对 `recent_story` 类型的 `base_weight` 进行每日衰减 update（或者只在读取时计算，数据库存静态值，推荐读取时动态计算以减少写操作）。
    *   当 `MemoryItem` 总数超过 100 条时，触发"记忆总结"任务，将多条旧记忆合并为一条"长期印象" (Long-term Impression)。

---

## 3. API 接口规划

### 3.1 获取成长时间轴
`GET /api/profiles/{id}/timeline`

**Response**:
```json
{
  "events": [
    {
      "date": "2023-10-01",
      "type": "milestone",
      "title": "初次相遇",
      "description": "创建了角色 [小明]"
    },
    {
      "date": "2023-10-05",
      "type": "story",
      "title": "小明与魔法树",
      "image_url": "..."
    },
    {
      "date": "2023-10-05",
      "type": "achievement",
      "badge": {
        "name": "好奇宝宝",
        "icon": "..."
      }
    }
  ]
}
```

### 3.2 记忆反馈 (人工干预)
`POST /api/memories/{id}/feedback`

允许家长手动删除或修正错误的记忆。
*   **Action**: `delete` | `reinforce` (强化，增加权重)