kevin/life-echo

Fork 0

Files

徐在坤 514468f753 添加图片资源文件

2026-01-17 19:34:40 +08:00

18 KiB

Raw Blame History

往事拾遗 - 服务端需求文档 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 响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应

{
  "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

请求参数

{
  "phone": "13800138000",
  "code": "123456",
  "nickname": "李明华"
}

响应数据

{
  "user_id": "u_xxxxx",
  "token": "jwt_token_xxxxx",
  "expires_at": "2024-12-31T23:59:59Z"
}

3.1.2 用户登录（V1 占位）

POST /api/v1/auth/login

请求参数

{
  "phone": "13800138000",
  "code": "123456"
}

3.1.3 获取用户信息

GET /api/v1/user/profile

响应数据

{
  "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

请求参数

{
  "nickname": "新昵称",
  "avatar_url": "https://..."
}

3.2 对话模块

3.2.1 获取对话列表

GET /api/v1/conversations

说明

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

响应数据

{
  "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 时启用

请求参数

{
  "type": "custom",
  "title": "关于童年的回忆",
  "agent_type": "memoir_assistant"
}

响应数据

{
  "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

响应数据

{
  "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

请求参数（文字消息）

{
  "content_type": "text",
  "content": "我出生在一个小村庄..."
}

请求参数（语音消息）

{
  "content_type": "audio",
  "content": "https://oss.example.com/audio/xxxxx.m4a",
  "metadata": {
    "duration": 15
  }
}

请求参数（图片消息，后续版本）

{
  "content_type": "image",
  "content": "https://oss.example.com/images/xxxxx.jpg",
  "metadata": {
    "width": 1080,
    "height": 720
  }
}

响应数据

{
  "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	音频时长（秒）

响应数据

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

处理流程

接收音频文件
上传至 OSS 存储
调用语音识别服务（ASR）转写
返回音频 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

响应数据

{
  "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

响应数据

{
  "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

响应数据

{
  "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

响应数据

{
  "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

请求参数

{
  "format": "pdf",
  "chapters": ["chapter_001", "chapter_002"]
}

响应数据

{
  "task_id": "export_xxxxx",
  "status": "processing",
  "estimated_time": 30
}

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

响应数据

{
  "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 系统提示词设计

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

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

## 对话原则
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 内容转化提示词

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

要求：
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 实现范围

核心功能 ✅

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

简化实现（V1）

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

后续版本功能

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

8. 后续迭代方向

V1.1 功能增强

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

V1.2 多 Agent 支持

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

V1.3 用户体系

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

V2.0 完整功能

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

18 KiB Raw Blame History Unescape Escape

往事拾遗 - 服务端需求文档 V1

1. 系统概述

1.1 核心职责

1.2 技术架构概览

2. API 设计

2.1 基础约定

2.2 响应格式

3. 功能模块 API

3.1 用户模块

3.1.1 用户注册（V1 占位）

3.1.2 用户登录（V1 占位）

3.1.3 获取用户信息

3.1.4 更新用户信息

3.2 对话模块

3.2.1 获取对话列表

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

3.2.3 获取对话消息列表

3.2.4 发送消息

3.2.5 上传音频文件

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

3.3 回忆录模块

3.3.1 获取用户回忆录

3.3.2 获取章节列表

3.3.3 获取章节内容

3.3.4 获取完整回忆录

3.3.5 导出回忆录（V1 占位）

4. 数据模型

4.1 数据库 Schema

用户表 (users)

对话表 (conversations)

消息表 (messages)

回忆录表 (memoirs)

章节表 (memoir_chapters)

章节资源表 (chapter_assets)

5. AI 服务设计

5.1 语音识别服务（ASR）

5.1.1 功能说明

5.1.2 技术选型

5.1.3 处理流程

5.1.4 性能要求

5.2 对话 AI

5.2.1 系统提示词设计

5.2.2 技术选型

5.2.3 上下文管理

5.3 回忆录生成 AI

5.2.1 触发条件

5.2.2 处理流程

5.2.3 内容转化提示词

6. 服务端要求

6.1 性能要求

6.2 可靠性要求

6.3 安全要求

6.4 合规要求

7. V1 实现范围

核心功能 ✅

简化实现（V1）

后续版本功能

8. 后续迭代方向

V1.1 功能增强

V1.2 多 Agent 支持

V1.3 用户体系

V2.0 完整功能

18 KiB

Raw Blame History