# 项目架构设计文档

## 系统架构图

```
┌─────────────────────────────────────────────────────────┐
│              移动端 (React Native)                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 登录     │  │ 角色管理 │  │ 对话界面 │              │
│  └──────────┘  └──────────┘  └──────────┘              │
│         │             │             │                    │
│         └─────────────┴─────────────┘                    │
│                  │ HTTPS                                 │
└──────────────────┼──────────────────────────────────────┘
                   │
┌──────────────────┼──────────────────────────────────────┐
│           FastAPI 后端服务                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 认证API  │  │ 角色API  │  │ 对话API  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
│  ┌──────────────────────────────────────┐              │
│  │        AI适配层（多平台统一）         │              │
│  └──────────────────────────────────────┘              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │好感度服务│  │主动消息  │  │ Celery   │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└──────────────────┼──────────────────────────────────────┘
                   │
        ┌──────────┼──────────┐
        │          │          │
┌───────▼──┐ ┌─────▼────┐ ┌──▼─────────┐
│PostgreSQL│ │  Redis   │ │ AI平台API  │
│          │ │          │ │(用户密钥)  │
└──────────┘ └──────────┘ └────────────┘
```

## 数据流

### 对话流程
1. 用户发送消息 → Mobile App
2. App调用 POST /api/conversations/{id}/messages
3. 后端保存用户消息
4. 获取对话历史（最近10条）
5. 调用用户配置的AI平台（使用解密的API Key）
6. AI返回回复（包含情感分析）
7. 解析回复，提取好感度变化
8. 更新好感度表
9. 保存AI回复
10. 返回给App

### 主动消息流程
1. Celery Beat每分钟触发检查任务
2. 查询满足条件的对话（好感度≥40，空闲≥3分钟）
3. 计算是否应该发送（概率判断）
4. 调用AI生成主动消息
5. 保存到数据库
6. 发送推送通知到移动端
7. 更新next_proactive_at时间

## 好感度计算

```python
def update_affection(user_message, ai_response):
    # 1. AI在回复中附带情感分析
    # <sentiment>{"affection_change": 3, "reason": "..."}</sentiment>

    # 2. 提取affection_change
    change = extract_sentiment(ai_response)

    # 3. 更新好感度（限制在-100~100）
    new_score = clamp(current_score + change, -100, 100)

    # 4. 计算新等级
    new_level = get_level(new_score)

    # 5. 保存变化记录
    save_log(change, reason)
```

## 技术要点

### 安全性
- API Key使用Fernet对称加密存储
- 密码使用bcrypt哈希
- 所有API需要JWT认证
- 生产环境强制HTTPS

### 性能优化
- Redis缓存对话上下文
- PostgreSQL分区表（消息表）
- 数据库连接池
- 异步I/O（FastAPI + AsyncPG）

### 可扩展性
- 水平扩展：多个FastAPI实例
- 任务队列：Celery分布式
- 数据库：读写分离（主从）
- 缓存：Redis集群

## 部署架构

```
          Nginx
            │
    ┌───────┼───────┐
    │       │       │
 FastAPI FastAPI FastAPI
    │       │       │
    └───────┼───────┘
            │
    ┌───────┼───────┐
    │               │
PostgreSQL        Redis
(Primary)      (Cluster)
    │
PostgreSQL
(Replica)
```

## 监控指标

- API响应时间
- AI调用延迟
- 好感度分布
- 主动消息发送成功率
- Token使用量
- 数据库查询性能