# 岁月时书 - 服务端需求文档 V1

> **产品定位**：为「岁月时书」客户端提供 AI 对话、回忆录生成、用户管理等核心后端服务。

---

## 1. 系统概述

### 1.1 核心职责

- 管理用户对话与消息
- 提供 AI 引导式对话能力
- 自动整理对话生成回忆录
- 用户账户与套餐管理

### 1.2 技术架构概览

```
┌─────────────────────────────────────────────────────────┐
│                      客户端 (App)                        │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      API Gateway                         │
│                    (认证/限流/路由)                       │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  对话服务      │   │  回忆录服务    │   │  用户服务      │
│  Chat Service │   │ Memoir Service│   │  User Service │
└───────────────┘   └───────────────┘   └───────────────┘
        │                   │                   │
        ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────┐
│                      数据存储层                          │
│              (PostgreSQL / Redis / OSS)                 │
└─────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│                      AI 服务层                           │
│                (LLM API / ASR 语音转写)                  │
└─────────────────────────────────────────────────────────┘
```

---

## 2. API 设计

### 2.1 基础约定

- **协议**：HTTPS
- **格式**：JSON
- **认证**：Bearer Token (JWT)
- **版本**：`/api/v1/`

### 2.2 响应格式

**成功响应**
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

**错误响应**
```json
{
  "code": 10001,
  "message": "错误描述",
  "data": null
}
```

**错误码规范**
| 错误码范围 | 类型 |
|-----------|------|
| 10000-19999 | 通用错误 |
| 20000-29999 | 用户模块错误 |
| 30000-39999 | 对话模块错误 |
| 40000-49999 | 回忆录模块错误 |

---

## 3. 功能模块 API

### 3.1 用户模块

#### 3.1.1 用户注册（V1 占位）

```
POST /api/v1/auth/register
```

**请求参数**
```json
{
  "phone": "13800138000",
  "code": "123456",
  "nickname": "李明华"
}
```

**响应数据**
```json
{
  "user_id": "u_xxxxx",
  "token": "jwt_token_xxxxx",
  "expires_at": "2024-12-31T23:59:59Z"
}
```

#### 3.1.2 用户登录（V1 占位）

```
POST /api/v1/auth/login
```

**请求参数**
```json
{
  "phone": "13800138000",
  "code": "123456"
}
```

#### 3.1.3 获取用户信息

```
GET /api/v1/user/profile
```

**响应数据**
```json
{
  "user_id": "u_xxxxx",
  "nickname": "李明华",
  "avatar_url": null,
  "plan_type": "free",
  "plan_label": "免费体验版",
  "created_at": "2024-01-01T00:00:00Z"
}
```

#### 3.1.4 更新用户信息

```
PUT /api/v1/user/profile
```

**请求参数**
```json
{
  "nickname": "新昵称",
  "avatar_url": "https://..."
}
```

---

### 3.2 对话模块

#### 3.2.1 获取对话列表

```
GET /api/v1/conversations
```

**说明**
- V1 版本每个用户仅有一个默认对话「回忆录助手」
- 用户首次访问时自动创建
- 不支持用户手动创建新对话（后续版本支持多 Agent）

**响应数据**
```json
{
  "conversations": [
    {
      "id": "conv_xxxxx",
      "title": "回忆录助手",
      "avatar_emoji": "📖",
      "last_message": "您想从哪里开始呢？可以聊聊童年...",
      "last_message_at": "2024-01-15T14:30:00Z",
      "unread_count": 0,
      "type": "system"
    }
  ],
  "total": 1,
  "has_more": false
}
```

#### 3.2.2 创建新对话（后续版本）

```
POST /api/v1/conversations
```

**说明**：V1 暂不开放，后续版本支持多 Agent 时启用

**请求参数**
```json
{
  "type": "custom",
  "title": "关于童年的回忆",
  "agent_type": "memoir_assistant"
}
```

**响应数据**
```json
{
  "id": "conv_xxxxx",
  "title": "关于童年的回忆",
  "created_at": "2024-01-15T15:00:00Z"
}
```

#### 3.2.3 获取对话消息列表

```
GET /api/v1/conversations/:id/messages
```

**查询参数**
| 参数 | 类型 | 说明 |
|-----|------|------|
| before | string | 游标，获取此消息之前的内容 |
| limit | int | 每页数量，默认 50 |

**响应数据**
```json
{
  "messages": [
    {
      "id": "msg_xxxxx",
      "sender_type": "ai",
      "content_type": "text",
      "content": "您好！我是您的回忆录助手...",
      "created_at": "2024-01-15T14:30:00Z"
    },
    {
      "id": "msg_yyyyy",
      "sender_type": "user",
      "content_type": "text",
      "content": "我想聊聊我的童年",
      "created_at": "2024-01-15T14:31:00Z"
    }
  ],
  "has_more": false
}
```

#### 3.2.4 发送消息

```
POST /api/v1/conversations/:id/messages
```

**请求参数（文字消息）**
```json
{
  "content_type": "text",
  "content": "我出生在一个小村庄..."
}
```

**请求参数（语音消息）**
```json
{
  "content_type": "audio",
  "content": "https://oss.example.com/audio/xxxxx.m4a",
  "metadata": {
    "duration": 15
  }
}
```

**请求参数（图片消息，后续版本）**
```json
{
  "content_type": "image",
  "content": "https://oss.example.com/images/xxxxx.jpg",
  "metadata": {
    "width": 1080,
    "height": 720
  }
}
```

**响应数据**
```json
{
  "user_message": {
    "id": "msg_xxxxx",
    "sender_type": "user",
    "content_type": "text",
    "content": "我出生在一个小村庄...",
    "created_at": "2024-01-15T14:35:00Z"
  },
  "ai_response": {
    "id": "msg_yyyyy",
    "sender_type": "ai",
    "content_type": "text",
    "content": "这个开头真让人期待！能再详细说说那个村庄是什么样的吗？",
    "created_at": "2024-01-15T14:35:02Z"
  }
}
```

#### 3.2.5 上传音频文件

```
POST /api/v1/upload/audio
Content-Type: multipart/form-data
```

**请求参数**
| 参数 | 类型 | 说明 |
|-----|------|------|
| file | File | 音频文件（M4A/AAC）|
| duration | int | 音频时长（秒）|

**响应数据**
```json
{
  "url": "https://oss.example.com/audio/xxxxx.m4a",
  "duration": 15,
  "transcription": "我出生在一个小村庄，那时候家里很穷..."
}
```

**处理流程**
1. 接收音频文件
2. 上传至 OSS 存储
3. 调用语音识别服务（ASR）转写
4. 返回音频 URL 和转写文本

#### 3.2.6 流式消息接口（可选增强）

```
POST /api/v1/conversations/:id/messages/stream
```

**说明**：使用 Server-Sent Events (SSE) 实现 AI 回复的流式输出

**事件类型**
```
event: message_start
data: {"message_id": "msg_xxxxx"}

event: content_delta
data: {"delta": "这个"}

event: content_delta
data: {"delta": "开头"}

event: message_end
data: {"message_id": "msg_xxxxx"}
```

---

### 3.3 回忆录模块

#### 3.3.1 获取用户回忆录

```
GET /api/v1/memoir
```

**响应数据**
```json
{
  "id": "memoir_xxxxx",
  "title": "这一生",
  "subtitle": "我的回忆录",
  "updated_at": "2024-01-15T14:35:00Z",
  "word_count": 3500,
  "chapter_count": 4
}
```

#### 3.3.2 获取章节列表

```
GET /api/v1/memoir/chapters
```

**响应数据**
```json
{
  "chapters": [
    {
      "id": "chapter_001",
      "number": 1,
      "title": "童年与家庭",
      "status": "complete",
      "page_count": 3,
      "word_count": 1200,
      "updated_at": "2024-01-15T14:00:00Z"
    },
    {
      "id": "chapter_002",
      "number": 2,
      "title": "上学的日子",
      "status": "partial",
      "page_count": 2,
      "word_count": 600,
      "updated_at": "2024-01-15T14:30:00Z"
    },
    {
      "id": "chapter_003",
      "number": 3,
      "title": "工作与事业",
      "status": "pending",
      "page_count": 0,
      "word_count": 0,
      "updated_at": null
    }
  ]
}
```

#### 3.3.3 获取章节内容

```
GET /api/v1/memoir/chapters/:id
```

**响应数据**
```json
{
  "id": "chapter_001",
  "number": 1,
  "title": "童年与家庭",
  "status": "complete",
  "content": "我出生在一个普通的农村家庭...\n\n\"日子虽然清苦，但那时候的快乐是最纯粹的。\"\n\n父亲是村里的木匠...",
  "images": [
    {
      "id": "img_001",
      "url": "https://...",
      "caption": "老家的院子",
      "position": 3
    }
  ],
  "updated_at": "2024-01-15T14:00:00Z"
}
```

#### 3.3.4 获取完整回忆录

```
GET /api/v1/memoir/full
```

**响应数据**
```json
{
  "id": "memoir_xxxxx",
  "title": "这一生",
  "subtitle": "我的回忆录",
  "chapters": [
    {
      "id": "chapter_001",
      "number": 1,
      "title": "童年与家庭",
      "content": "...",
      "images": []
    },
    {
      "id": "chapter_002",
      "number": 2,
      "title": "上学的日子",
      "content": "...",
      "images": []
    }
  ],
  "updated_at": "2024-01-15T14:35:00Z"
}
```

#### 3.3.5 导出回忆录（V1 占位）

```
POST /api/v1/memoir/export
```

**请求参数**
```json
{
  "format": "pdf",
  "chapters": ["chapter_001", "chapter_002"]
}
```

**响应数据**
```json
{
  "task_id": "export_xxxxx",
  "status": "processing",
  "estimated_time": 30
}
```

```
GET /api/v1/memoir/export/:task_id
```

**响应数据**
```json
{
  "task_id": "export_xxxxx",
  "status": "completed",
  "download_url": "https://...",
  "expires_at": "2024-01-16T14:35:00Z"
}
```

---

## 4. 数据模型

### 4.1 数据库 Schema

#### 用户表 (users)

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | VARCHAR(32) | 主键，如 u_xxxxx |
| phone | VARCHAR(20) | 手机号，唯一 |
| nickname | VARCHAR(50) | 昵称 |
| avatar_url | VARCHAR(500) | 头像 URL |
| plan_type | ENUM | 套餐类型：free/premium |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

#### 对话表 (conversations)

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | VARCHAR(32) | 主键，如 conv_xxxxx |
| user_id | VARCHAR(32) | 用户 ID，外键 |
| title | VARCHAR(100) | 对话标题 |
| type | ENUM | 类型：system/custom |
| avatar_emoji | VARCHAR(10) | 头像 emoji |
| last_message | TEXT | 最后一条消息内容 |
| last_message_at | TIMESTAMP | 最后消息时间 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

#### 消息表 (messages)

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | VARCHAR(32) | 主键，如 msg_xxxxx |
| conversation_id | VARCHAR(32) | 对话 ID，外键 |
| sender_type | ENUM | 发送者：user/ai |
| content_type | ENUM | 内容类型：text/image/audio |
| content | TEXT | 消息内容或资源 URL |
| metadata | JSON | 扩展数据（图片尺寸、音频时长等）|
| created_at | TIMESTAMP | 创建时间 |

#### 回忆录表 (memoirs)

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | VARCHAR(32) | 主键，如 memoir_xxxxx |
| user_id | VARCHAR(32) | 用户 ID，外键，唯一 |
| title | VARCHAR(100) | 书名 |
| subtitle | VARCHAR(200) | 副标题 |
| word_count | INT | 总字数 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

#### 章节表 (memoir_chapters)

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | VARCHAR(32) | 主键，如 chapter_xxxxx |
| memoir_id | VARCHAR(32) | 回忆录 ID，外键 |
| number | INT | 章节序号 |
| title | VARCHAR(100) | 章节标题 |
| content | TEXT | 章节内容（Markdown） |
| status | ENUM | 状态：pending/partial/complete |
| word_count | INT | 字数 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

#### 章节资源表 (chapter_assets)

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | VARCHAR(32) | 主键 |
| chapter_id | VARCHAR(32) | 章节 ID，外键 |
| type | ENUM | 类型：image/audio |
| url | VARCHAR(500) | 资源 URL |
| caption | VARCHAR(200) | 说明文字 |
| position | INT | 在内容中的位置 |
| created_at | TIMESTAMP | 创建时间 |

---

## 5. AI 服务设计

### 5.1 语音识别服务（ASR）

#### 5.1.1 功能说明

将用户上传的语音消息转写为文字，供 AI 对话使用。

#### 5.1.2 技术选型

| 服务商 | 优势 | 说明 |
|-------|------|------|
| 阿里云 ASR | 中文识别准确率高 | 推荐 |
| 腾讯云 ASR | 价格较低 | 备选 |
| Whisper API | 多语言支持好 | 可选 |

#### 5.1.3 处理流程

```
1. 接收音频文件（M4A/AAC 格式）
2. 调用 ASR 服务进行转写
3. 返回转写文本
4. 文本用于 AI 对话上下文
```

#### 5.1.4 性能要求

- 转写延迟：< 3秒（60秒内音频）
- 识别准确率：> 95%（普通话）
- 支持方言识别（可选增强）

---

### 5.2 对话 AI

#### 5.2.1 系统提示词设计

```markdown
你是一位温和、有耐心的回忆录采访助手。你的任务是通过对话帮助用户回忆和讲述他们的人生故事。

## 角色特点
- 像一位老朋友一样亲切
- 善于倾听和共情
- 会适时提出引导性问题
- 帮助用户回忆细节

## 对话原则
1. 每次回复要简短（1-3句话）
2. 多用鼓励和肯定的语气
3. 提问要具体，避免开放性太强
4. 关注时间、地点、人物、感受
5. 适当使用 emoji 增加亲切感

## 引导方向
- 童年与家庭
- 求学经历
- 工作与事业
- 爱情与婚姻
- 重要人生节点
- 难忘的经历

## 注意事项
- 不要一次问太多问题
- 如果用户情绪低落，给予安慰
- 尊重用户的隐私边界
- 语音消息转写可能有错别字，根据上下文理解用户意图
```

#### 5.2.2 技术选型

| 服务商 | 模型 | 说明 |
|-------|------|------|
| OpenAI | GPT-4o / GPT-4o-mini | 效果好，成本适中 |
| Claude | Claude 3.5 Sonnet | 对话质量高 |
| 智谱 AI | GLM-4 | 中文优化，国内访问快 |
| 阿里云 | 通义千问 | 国内合规，价格低 |

#### 5.2.3 上下文管理

- 保留最近 20 轮对话作为上下文
- 维护用户画像摘要（年龄、家庭背景等）
- 追踪已覆盖的话题，避免重复

### 5.3 回忆录生成 AI

#### 5.2.1 触发条件

- 用户发送消息后异步触发
- 或定时任务（每日）检查更新

#### 5.2.2 处理流程

```
1. 提取新对话内容
2. 分析内容主题
3. 匹配/创建对应章节
4. 将对话内容转化为叙述文字
5. 合并到章节内容中
6. 更新章节状态
```

#### 5.2.3 内容转化提示词

```markdown
将以下对话内容转化为回忆录章节的叙述性文字。

要求：
1. 使用第一人称
2. 保持自然流畅的叙事风格
3. 保留重要细节和情感
4. 适当引用原话作为点缀
5. 按时间或逻辑顺序组织内容

对话内容：
{对话记录}

当前章节已有内容：
{已有内容}

请输出应追加到该章节的新内容：
```

---

## 6. 服务端要求

### 6.1 性能要求

| 指标 | 要求 |
|-----|------|
| API 响应时间 (P95) | < 500ms |
| AI 回复时间 | < 3s（首字）|
| 并发用户数 | 1000 |
| 消息吞吐量 | 100 msg/s |

### 6.2 可靠性要求

| 指标 | 要求 |
|-----|------|
| 服务可用性 | 99.9% |
| 数据持久性 | 99.999999% |
| 故障恢复时间 | < 5min |

### 6.3 安全要求

- 传输加密：TLS 1.2+
- 数据加密：敏感数据 AES-256 加密存储
- 认证：JWT + 刷新令牌机制
- 授权：RBAC 权限控制
- 审计：关键操作日志记录

### 6.4 合规要求

- 用户数据隔离
- 数据导出能力
- 账号注销与数据删除
- 隐私政策声明

---

## 7. V1 实现范围

### 核心功能 ✅

- [x] 用户基础信息 API
- [x] 对话列表与详情 API
- [x] 文字消息发送与 AI 回复
- [x] 语音消息上传与转写（ASR）
- [x] 语音消息 AI 回复
- [x] 回忆录章节 API
- [x] LLM 对话能力（真实 AI）

### 简化实现（V1）

- [ ] 用户认证：允许匿名访问，通过设备 ID 识别
- [ ] 回忆录生成：使用定时任务而非实时生成

### 后续版本功能

- [ ] 手机号注册登录
- [ ] 图片消息上传与 AI 理解
- [ ] PDF 导出
- [ ] 付费套餐
- [ ] 流式 AI 回复

---

## 8. 后续迭代方向

### V1.1 功能增强

- 图片消息支持（上传 + AI 理解）
- 流式 AI 回复（SSE）
- 实时回忆录生成

### V1.2 多 Agent 支持

- 支持创建多个对话
- 不同类型的 AI 助手：
  - 回忆录助手（默认）
  - 故事整理助手
  - 照片回忆助手
- 对话管理 API（删除、归档）

### V1.3 用户体系

- 手机号注册登录
- 微信登录
- 套餐与付费

### V2.0 完整功能

- PDF/打印导出
- 家庭成员协作
- 回忆录分享
- 多语言支持
- 方言语音识别