c45a2c040b
- usePlayer：paused 且 tts_auto 时清空队列并重置，再播当前片段 - 用 statusRef 与暂停同步，避免 WS 紧连 enqueue 时状态滞后 - 补充 use-player 单测 - api: 调整 copyright_source_pdf 脚本 - docs: 新增软著《岁月时书》软件设计说明书 Co-authored-by: Cursor <cursoragent@cursor.com>
520 lines
28 KiB
Markdown
520 lines
28 KiB
Markdown
# 软件设计说明书（兼操作手册）
|
||
|
||
---
|
||
|
||
## 文档封面信息
|
||
|
||
|
||
| 项目 | 内容 |
|
||
| ------ | ------------- |
|
||
| 软件全称 | 岁月留书 |
|
||
| 英文名称 | Life Echo |
|
||
| 文档名称 | 《岁月留书》软件设计说明书 |
|
||
| 文档版本 | 1.0 |
|
||
| 对应软件版本 | 1.0 |
|
||
| 著作权人 | 上海华嘎科技有限公司 |
|
||
| 编写单位 | 上海华嘎科技有限公司 |
|
||
| 编写日期 | 2026年5月12日 |
|
||
|
||
|
||
---
|
||
|
||
## 第 1 章 引言
|
||
|
||
### 1.1 编写目的
|
||
|
||
本说明书描述「岁月留书（Life Echo）」一体化软件系统在代码仓库层面的组成结构、总体架构、主要功能规格、核心业务流程、开发与测试状况以及典型环境下的安装与运维使用方法。
|
||
|
||
### 1.2 适用范围
|
||
|
||
本说明书适用于以下组成部分的整体说明：
|
||
|
||
1. **后端 API 服务**：路径 `api/`，基于 FastAPI，对外提供 REST API、WebSocket 实时对话能力及静态资源挂载。
|
||
2. **客户端应用**：路径 `app-expo/`，基于 Expo Router 与 React Native，面向终端用户提供登录、对话、回忆录浏览与导出相关交互界面。
|
||
3. **内部评测前端**：路径 `app-eval-web/`，基于 Vite，用于开发与回归评测场景（一般不纳入终端用户交付镜像，与内部评测 API 配合使用）。
|
||
4. **工程与运维文档**：路径 `docs/`，存放与本项目相关的运维、设计备忘等资料；本说明书为其中面向著作权登记的汇总文档。
|
||
|
||
### 1.3 术语与缩写
|
||
|
||
|
||
| 术语 | 含义 |
|
||
| ------------------ | ----------------------------------------------------- |
|
||
| JWT | JSON Web Token，访问令牌与刷新令牌组合的认证机制 |
|
||
| WebSocket | 全双工通信协议，本项目中用于实时语音与文本对话管线 |
|
||
| ASR | Automatic Speech Recognition，语音转文字 |
|
||
| TTS | Text-To-Speech，文字转语音 |
|
||
| LLM | Large Language Model，大语言模型；后端通过适配层调用兼容 OpenAI API 的服务 |
|
||
| Agent | 基于 LangChain 组织的对话与回忆录编排逻辑单元 |
|
||
| ChatOrchestrator | 实时对话编排入口，负责将用户输入路由至画像采集或访谈对话等分支 |
|
||
| MemoirOrchestrator | 回忆录正文流水线编排入口，负责分段调度抽取、分类与各 Specialist Agent |
|
||
| Celery | Python 异步分布式任务队列，用于回忆录 Phase 处理、记忆压实、嵌入调度等后台作业 |
|
||
| Phase1 / Phase2 | 回忆录批量处理阶段的工程称谓：Phase1 侧重批次准备与派发，Phase2 按类别执行故事管线 |
|
||
| Redis | 内存数据结构存储，用作会话缓存与队列协调等 |
|
||
| PostgreSQL | 关系型数据库；会话消息等持久化真源存放于此 |
|
||
| pgvector | PostgreSQL 扩展，用于向量检索相关的记忆块存储与检索 |
|
||
| Alembic | 数据库 Schema 迁移工具；本项目禁止手写 DDL 绕过迁移脚本 |
|
||
|
||
|
||
---
|
||
|
||
## 第 2 章 系统概述
|
||
|
||
### 2.1 建设目标与业务边界
|
||
|
||
本软件面向「口述回忆录」类产品形态，建设目标包括：
|
||
|
||
1. **实时智能访谈**：通过 WebSocket 维持长连接，在移动端采集用户语音或文本输入，经 ASR（若语音）形成可处理文本，再由 LLM 驱动的 Agent 结合传记结构与历史记忆检索结果生成引导性回复。
|
||
2. **结构化回忆录生成**：将多轮对话中的有效叙事内容抽取、归类，按章节与阅读片段组织为可阅读的「回忆录」文稿，并支持章节级素材与图像任务（工程上区分为正文配图与章节封面等管线）。
|
||
3. **可导出成品**：服务端将回忆录内容排版并生成 PDF 等可供用户留存与分享的文档形式（具体能力以当前 `features/memoir` 与相关服务实现为准）。
|
||
4. **账户、套餐与商业化支撑**：提供用户注册登录、套餐（Plan）、配额（Quota）、订单与支付（含微信、支付宝等适配）等能力，保证多租户下的资源可控与可审计。
|
||
|
||
### 2.2 非功能需求概要
|
||
|
||
|
||
| 类别 | 要求说明 |
|
||
| ----- | ----------------------------------------------------------------- |
|
||
| 实时性 | WebSocket 连接内消息顺序稳定；首轮「边播 TTS 边出字」模式下，服务端按协议先推送音频再推送对应文本分段 |
|
||
| 安全 | REST 接口使用 JWT；WebSocket 连接通过 Query 携带 `access_token` 校验身份 |
|
||
| 可运维 | 健康检查路由 `/health`；请求追踪依赖中间件注入 request id；日志采用统一结构化封装 |
|
||
| 可扩展 | 外部厂商能力集中在 `adapters`，业务仅依赖 `ports` 协议，便于替换 ASR/TTS/LLM/短信/对象存储等实现 |
|
||
| 数据一致性 | 会话消息以数据库表 `conversation_messages` 为权威存储，Redis 承担缓存与加速读取职责 |
|
||
|
||
|
||
### 2.3 系统边界图（逻辑）
|
||
|
||
客户端（Expo 应用或评测前端）仅与本后端 HTTP/WebSocket 交互；后端再访问 PostgreSQL、Redis，并向 Celery Worker 投递异步任务；外部云服务包括 LLM、ASR、TTS、短信、对象存储及支付网关等，经由适配层调用。
|
||
|
||
---
|
||
|
||
## 第 3 章 总体设计与运行环境
|
||
|
||
### 3.1 Monorepo 目录组成
|
||
|
||
仓库根目录主要包含：
|
||
|
||
```
|
||
life-echo/
|
||
├── api/ # 后端（FastAPI，Python，uv + Alembic + Celery）
|
||
├── app-expo/ # 移动端（Expo Router + React Native）
|
||
├── app-eval-web/ # 内部评测 Web（Vite）
|
||
├── docs/ # 设计与运维文档（含本说明书）
|
||
├── package.json # 根级脚本聚合（如 husky、子项目脚本转发）
|
||
└── README.md # 项目总览
|
||
```
|
||
|
||
### 3.2 后端进程形态
|
||
|
||
1. **主 API 进程**：模块入口 `api/app/main.py` 创建 FastAPI 应用 `app`，挂载各业务 Router，注册 WebSocket 路径 `/ws/conversation/{conversation_id}`，并在启动阶段执行 Alembic 迁移、Redis 连接、ASR 就绪检查、微信支付客户端预初始化等。
|
||
2. **内部评测 API 进程**（可选隔离部署）：模块入口 `api/app/internal_main.py` 创建 `internal_app`，挂载 `evaluation` 相关路由，用于回归评测与会话对比，默认与主 API 进程分离以降低评测对线上入口的影响。
|
||
3. **Celery Worker**：消费 memoir 处理、记忆压实、嵌入调度、记忆富化等任务队列；具体队列名与路由以 `tasks` 包及环境变量为准。
|
||
|
||
### 3.3 客户端组成
|
||
|
||
`app-expo` 采用文件式路由，源码主目录为 `src/app/`，典型路由分组包括：
|
||
|
||
|
||
| 路由分组 | 相对路径示例 | 用途说明 |
|
||
| ------- | --------------------------------------------------------------------------------------------------- | ------------------------- |
|
||
| 认证 | `(auth)/login.tsx`、`register.tsx`、`reset-password.tsx` | 登录、注册、重置密码 |
|
||
| 主导航 Tab | `(tabs)/index.tsx`、`memoir.tsx`、`profile.tsx` | 首页、回忆录、个人中心 |
|
||
| 对话与内容 | `(main)/conversation/[id].tsx`、`chapter/[id].tsx` | 单会话对话页、章节阅读 |
|
||
| 设置与合规 | `(main)/personal-info.tsx`、`export-data.tsx`、`delete-data.tsx`、`faq.tsx`、`feedback.tsx`、`about.tsx` | 个人信息、导入导出与删除数据、常见问题、反馈、关于 |
|
||
| 法律文档 | `legal/[type].tsx` | 法律类展示页 |
|
||
|
||
|
||
### 3.4 开发与运行依赖（摘要）
|
||
|
||
后端建议环境：Python 3.10 及以上；依赖与锁文件由 `uv` 管理（`api/pyproject.toml` 与 `api/uv.lock`）。数据库使用 PostgreSQL；缓存与消息代理使用 Redis。容器编排可使用 `docker-compose` 系列文件（以 `api/` 目录下实际文件名为准）。
|
||
|
||
移动端使用 Node.js 生态执行 `npm install` 与 `npx expo start` 等命令。内部评测前端在 `app-eval-web/` 目录使用 Vite 开发服务器。
|
||
|
||
### 3.5 内部评测前端（app-eval-web）
|
||
|
||
`app-eval-web` 为研发与质量保障使用的单页应用工程，默认仅监听本机开发端口（常见为 `5174`，以 Vite 控制台输出为准）。其通过 HTTP 调用 `internal_app` 暴露的评测 REST API，前缀固定为 `/internal/api/evaluation`（见 `api/app/internal_main.py` 中的 `include_router` 配置）。该前端**不作为**终端用户应用商店交付物的一部分描述，仅在说明「Monorepo 完整组成」时列出。
|
||
|
||
---
|
||
|
||
## 第 4 章 软件结构说明
|
||
|
||
### 4.1 后端分层架构
|
||
|
||
后端严格按功能域拆分，并遵守「路由不写业务 SQL、服务不直连三方 SDK」的边界约定：
|
||
|
||
|
||
| 层次 | 目录 | 职责 |
|
||
| ---- | --------------------------- | -------------------------------------------------------------- |
|
||
| 接口层 | `app/features/*/router.py` | 定义 REST 或协议入口，注入服务依赖，返回 Pydantic 模型 |
|
||
| 业务层 | `app/features/*/service.py` | 业务规则、事务边界、编排对多个 repo 与端口的调用 |
|
||
| 持久层 | `app/features/*/repo.py` | 数据库增删查改，不在此层随意 `commit`（由上层统一事务策略） |
|
||
| 领域模型 | `app/features/*/models.py` | SQLAlchemy ORM 模型 |
|
||
| 端口 | `app/ports/` | 协议（Protocol），描述 ASR、TTS、LLM、短信等能力 |
|
||
| 适配器 | `app/adapters/` | 具体厂商实现，如 DeepSeek、腾讯、OpenAI Whisper 等 |
|
||
| 智能体 | `app/agents/` | LangChain Agent 及 `ChatOrchestrator`、`MemoirOrchestrator` 等编排类 |
|
||
| 核心设施 | `app/core/` | 配置、数据库引擎、Redis、安全、日志、中间件、异常处理等 |
|
||
| 任务 | `api/tasks/` | Celery 应用与任务定义入口 |
|
||
|
||
|
||
### 4.2 功能域与源码对应关系
|
||
|
||
以下功能域均位于 `api/app/features/` 下，各自通常包含 `router`、`service`、`repo`（按需）、`schemas`、`deps` 等文件：
|
||
|
||
|
||
| 域 | 目录 | 主要职责 |
|
||
| --- | --------------- | ---------------------------------------------------- |
|
||
| 认证 | `auth/` | 注册、登录、短信验证码、JWT 签发与校验、头像预设等 |
|
||
| 用户 | `user/` | 用户资料、反馈等对外接口 |
|
||
| 对话 | `conversation/` | REST 会话管理、WebSocket 管线、`ChatOrchestrator` 调用、历史与额度守护 |
|
||
| 记忆 | `memory/` | 记忆块写入、向量检索、富化管道、压实服务、嵌入调度与对外查询接口 |
|
||
| 回忆录 | `memoir/` | 章节与阅读素材、PDF 服务、叙事安全、口述规范化、章节封面与正文图像任务、状态服务等 |
|
||
| 故事 | `story/` | 与篇章素材、同步写入、配图意图等相关的服务与仓储（与回忆录流水线协同） |
|
||
| 套餐 | `plan/` | 套餐目录与订购相关能力 |
|
||
| 配额 | `quota/` | 配额检查与扣减策略，供对话、回忆录、支付等场景注入使用 |
|
||
| 支付 | `payment/` | 订单、微信与支付宝等支付通道封装 |
|
||
| 任务 | `tasks/` | 任务状态查询等对前端的任务进度暴露 |
|
||
| 内容 | `content/` | TTS 等内容相关接口 |
|
||
| 资源 | `asset/` | 资源存取相关仓储与模型 |
|
||
| 评测 | `evaluation/` | 内部评测数据模型、打分、会话目录、回放、对比摘要等（由 `internal_main` 挂载） |
|
||
|
||
|
||
### 4.3 WebSocket 协议文件
|
||
|
||
工程在 `api/app/features/conversation/ws/protocol.md` 中维护 WebSocket 文本协议说明，包括连接 URL 形态、客户端到服务端与服务端到客户端的消息类型枚举、心跳与重连语义等，与实现代码共同构成可审查的契约说明。
|
||
|
||
---
|
||
|
||
## 第 5 章 功能规格说明
|
||
|
||
本章按业务域给出可测试的规格化描述：目标、典型输入、处理要点、输出与约束。
|
||
|
||
### 5.1 认证与用户（auth / user）
|
||
|
||
**目标**：为全站提供可信身份，支撑受保护 REST 与 WebSocket。
|
||
|
||
**典型输入**：手机号与密码注册、登录；短信验证码发送与校验；刷新令牌请求。
|
||
|
||
**处理要点**：密码经安全哈希存储；签发短期访问令牌与长期刷新令牌；对外 schema 校验在 Pydantic 层完成。
|
||
|
||
**输出**：令牌对、用户基础资料、错误码与错误信息遵循 `app/core/errors.py` 约定的统一错误响应结构（含 `error_code`、`message`、`request_id`）。
|
||
|
||
**约束**：成功业务响应可为直接模型或字典，不必统一包装信封；敏感环境变量不得写入代码库。
|
||
|
||
### 5.2 对话与实时管线（conversation）
|
||
|
||
**目标**：维持长连接会话，完成「语音或文本 →（可选 ASR）→ Agent 推理 →（可选 TTS）→ 客户端展示」闭环。
|
||
|
||
**典型输入**：`TEXT`、`AUDIO_SEGMENT`、`AUDIO_MESSAGE`、`TRANSCRIBE_ONLY`、`TTS_REQUEST`、`TTS_CANCEL`、`END_CONVERSATION`、心跳等，详见 `protocol.md`。
|
||
|
||
**处理要点**：连接 URL 为 `/ws/conversation/{conversation_id}?token={jwt_access_token}`；编排由 `ChatOrchestrator` 将用户消息路由到画像分支或访谈分支；会话真源写入 `conversation_messages`，Redis 用于加速与缓存；额度由 `quota` 相关守护在管线中发挥作用。
|
||
|
||
**输出**：`TRANSCRIPT`、`AGENT_RESPONSE` 分段、`TTS_AUDIO`、`MEMOIR_UPDATE`、`ERROR` 等下行消息。
|
||
|
||
**约束**：同一连接内消息顺序稳定；若本轮开启服务端 TTS，则每一助手分段先 `TTS_AUDIO` 再对应 `AGENT_RESPONSE`。
|
||
|
||
### 5.3 记忆与检索（memory）
|
||
|
||
**目标**：将对话中可复用的事实与摘要以向量块形式持久化，支持后续会话与回忆录生成时的语义检索。
|
||
|
||
**典型输入**：会话轮次文本、用户标识、检索 query、富化开关相关配置。
|
||
|
||
**处理要点**：写入与切块、嵌入、可选 LLM 富化、定时压实（compaction）等由服务与 Celery 任务协同；异步与同步路径行为可能不同，工程文档中建议以 `docs/memory-retrieval.md`（若存在）等行为矩阵为准。
|
||
|
||
**输出**：检索到的记忆证据、供提示词注入的结构化片段、必要的追踪信息（若开启）。
|
||
|
||
**约束**：配置项如 `CHAT_MEMORY_RETRIEVAL_ENABLED`、`MEMORY_COMPACTION_ENABLED` 等由 `app/core/config.py` 集中管理，调参需结合运行环境与负载。
|
||
|
||
### 5.4 回忆录与 PDF（memoir）
|
||
|
||
**目标**：将多轮叙事整理为结构化章节与阅读体验，并生成可导出的文档与配图。
|
||
|
||
**典型输入**：会话 id、回忆录 id、章节 id、导出请求、图像生成相关任务参数。
|
||
|
||
**处理要点**：`MemoirOrchestrator` 负责分段编排；Phase1 批次准备后 `process_memoir_phase1` 等 Celery 任务派发 Phase2，按类别进入 `run_story_pipeline_for_category_batch`；图像方面区分正文图 `generate_story_image` 与章节封面 `generate_chapter_cover` enqueue 逻辑；PDF 由 `pdf_service` 等模块调用排版引擎完成。
|
||
|
||
**输出**：章节文本、阅读片段、PDF 文件流或 URL、任务状态更新、经由 WebSocket 的 `MEMOIR_UPDATE` 通知。
|
||
|
||
**约束**：涉及对象存储 URI 时需经预签名或受控网关访问；长篇生成依赖队列与超时配置。
|
||
|
||
### 5.5 故事与素材（story）
|
||
|
||
**目标**：承接回忆录流水线中篇章级写入与配图意图抽取等职责，与 `memoir` 域协同。
|
||
|
||
**典型输入**：批量单元规划结果、叙事路由 Agent 输出、图像意图字段。
|
||
|
||
**处理要点**：仓储与服务分层保持与全局架构一致；同步写入路径需考虑与数据库事务的一致性。
|
||
|
||
**输出**：持久化的故事单元记录、下游图像任务触发条件。
|
||
|
||
### 5.6 套餐与配额（plan / quota）
|
||
|
||
**目标**：定义可售卖套餐与用户使用限额，避免超卖与滥用。
|
||
|
||
**典型输入**：套餐 id、用户当前订阅状态、对话轮次或回忆录导出等资源计量事件。
|
||
|
||
**处理要点**：`QuotaService` 供会话与回忆录等模块注入调用；不得在功能模块内硬编码配额 SQL。
|
||
|
||
**输出**：允许或拒绝决策、剩余额度字段（若接口暴露）。
|
||
|
||
### 5.7 支付与订单（payment）
|
||
|
||
**目标**：完成下单、渠道拉起、回调处理与订单状态推进。
|
||
|
||
**典型输入**：支付方式枚举、订单金额、回调报文。
|
||
|
||
**处理要点**：微信与支付宝客户端由适配层封装；支付失败与幂等处理在服务层体现。
|
||
|
||
**输出**：支付参数包、订单状态、错误码。
|
||
|
||
### 5.8 任务进度（tasks）
|
||
|
||
**目标**：向前端暴露长时间运行任务的状态，改善用户对回忆录生成等操作的感知。
|
||
|
||
**典型输入**：任务 id 或业务关联键。
|
||
|
||
**处理要点**：与 `task_tracker` 等核心组件协作（若启用）。
|
||
|
||
**输出**：状态枚举、进度百分比或步骤文案。
|
||
|
||
### 5.9 内容与朗读（content）
|
||
|
||
**目标**：提供与朗读相关的服务端能力配合对话气泡交互。
|
||
|
||
**典型输入**：文本分段、音色参数（若支持）。
|
||
|
||
**处理要点**：与 TTS 适配层衔接；必要时写入缓存或以 URL 形式下发。
|
||
|
||
### 5.10 内部评测（evaluation）
|
||
|
||
**目标**：支持离线或半离线环境下的会话回放、评分与对比报告生成，服务于研发质量保障。
|
||
|
||
**典型输入**：评测会话导入数据、评测脚本、评分 Rubric 版本。
|
||
|
||
**处理要点**：评测 HTTP API 运行在 `internal_app`；浏览器界面由 `app-eval-web` 调用上述 API。
|
||
|
||
**输出**：评测轨迹、对比摘要、门禁报告（gate report）等结构化结果。
|
||
|
||
---
|
||
|
||
## 第 6 章 核心业务流程与设计说明
|
||
|
||
### 6.1 逻辑分层与依赖关系
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph clients [Clients]
|
||
ExpoApp[app-expo]
|
||
EvalWeb[app-eval-web]
|
||
end
|
||
subgraph backend [api FastAPI]
|
||
Router[features routers]
|
||
Service[services]
|
||
Repo[repos]
|
||
Agents[agents]
|
||
Ports[ports]
|
||
Adapters[adapters]
|
||
end
|
||
subgraph infra [Infrastructure]
|
||
PG[(PostgreSQL)]
|
||
Redis[(Redis)]
|
||
Celery[Celery workers]
|
||
end
|
||
ExpoApp --> Router
|
||
EvalWeb --> Router
|
||
Router --> Service
|
||
Service --> Repo
|
||
Service --> Agents
|
||
Service --> Ports
|
||
Ports --> Adapters
|
||
Repo --> PG
|
||
Service --> Redis
|
||
Service --> Celery
|
||
```
|
||
|
||
|
||
|
||
### 6.2 访问令牌认证与刷新（REST 概要）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant A as auth_router
|
||
participant S as AuthService
|
||
participant DB as PostgreSQL
|
||
C->>A: POST login credentials
|
||
A->>S: validate_and_issue_tokens
|
||
S->>DB: verify user password hash
|
||
DB-->>S: user row
|
||
S-->>A: access_token refresh_token
|
||
A-->>C: 200 JSON tokens
|
||
C->>A: GET protected with Authorization Bearer
|
||
A->>S: verify access_token
|
||
S-->>A: user context
|
||
A-->>C: 200 protected resource
|
||
C->>A: POST refresh with refresh_token
|
||
A->>S: rotate if valid
|
||
S-->>A: new token pair
|
||
A-->>C: 200 new tokens
|
||
```
|
||
|
||
|
||
|
||
### 6.3 WebSocket 对话主路径（概要）
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Connected: JWT valid connect
|
||
Connected --> Transcribing: AUDIO or AUDIO_SEGMENT
|
||
Transcribing --> AgentThink: TRANSCRIPT ready
|
||
Connected --> AgentThink: TEXT input
|
||
AgentThink --> StreamingReply: ChatOrchestrator yields
|
||
StreamingReply --> Connected: segments sent optional TTS
|
||
Connected --> Ending: END_CONVERSATION
|
||
Ending --> [*]
|
||
Connected --> Connected: PING PONG heartbeat
|
||
```
|
||
|
||
|
||
|
||
### 6.4 回忆录异步流水线（概要）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph realtime [Realtime path]
|
||
WS[WebSocket pipeline]
|
||
CO[ChatOrchestrator]
|
||
DB1[(conversation_messages)]
|
||
end
|
||
subgraph batch [Batch path]
|
||
MO[MemoirOrchestrator]
|
||
P1[Phase1 Celery]
|
||
P2[Phase2 by category]
|
||
PDF[PDF service]
|
||
IMG[Image tasks]
|
||
end
|
||
WS --> CO
|
||
CO --> DB1
|
||
DB1 --> MO
|
||
MO --> P1
|
||
P1 --> P2
|
||
P2 --> PDF
|
||
P2 --> IMG
|
||
```
|
||
|
||
|
||
|
||
### 6.5 记忆写入、富化与压实（概念）
|
||
|
||
用户经对话产生的新素材经 `memory` 域服务切块与嵌入后进入 PostgreSQL/pgvector；可选富化任务进入独立 Celery 队列（如 `memory_idle`）；压实任务按配置周期合并或清理旧块，以降低检索噪声与存储膨胀。详细行为以环境变量开关与代码内服务实现为准。
|
||
|
||
---
|
||
|
||
## 第 7 章 接口与数据概要
|
||
|
||
### 7.1 REST 与 WebSocket 入口形态
|
||
|
||
主应用 `app` 注册的路由前缀以各 `router` 定义为准；OpenAPI 文档在 `settings.enable_docs` 为真时可通过 `/docs` 与 `/redoc` 访问。WebSocket 固定路径模板为 `/ws/conversation/{conversation_id}`，鉴权参数为 Query 中的 `token`。
|
||
|
||
内部评测应用 `internal_app` 的评测相关接口前缀参见 `internal_main` 中的说明（例如 `/internal/api/evaluation/` 一类路径，以实际路由定义为准）。
|
||
|
||
### 7.2 统一错误响应
|
||
|
||
业务错误返回 JSON 结构包含字段：`error_code`、`message`、`request_id`，由全局异常处理器注册，保证客户端可程序化解析。
|
||
|
||
### 7.3 数据库与迁移
|
||
|
||
业务表模型分散于各 `features/*/models.py`，并在 `app/main.py` 中间接 import 以聚合到 `Base.metadata`。一切结构变更必须通过 `api/alembic` 版本脚本完成。应用启动时可在 `run_alembic_upgrade_at_startup` 中自动执行 `upgrade head`，生产可配置失败即退出。
|
||
|
||
### 7.4 核心实体（语义级）
|
||
|
||
|
||
| 实体 | 语义 |
|
||
| ---------------------- | ---------------------------- |
|
||
| User | 注册用户、凭据哈希、画像字段 |
|
||
| Conversation / Session | 对话容器，关联多条消息 |
|
||
| ConversationMessage | 单条用户或助手消息，WebSocket 与历史查询的真源 |
|
||
| Memoir / Chapter | 回忆录与章节树；阅读片段与导出依赖其内容 |
|
||
| MemoryChunk | 向量检索用的记忆块 |
|
||
| Order / Payment | 订单与支付流水 |
|
||
| Plan / Quota | 套餐定义与用户使用额度 |
|
||
|
||
|
||
---
|
||
|
||
## 第 8 章 开发状况与测试结果说明
|
||
|
||
### 8.1 当前实现状态（与仓库说明对齐）
|
||
|
||
下列能力在根目录 `README.md` 中标记为已实现或持续演进，著作权文档在此做技术化转述：
|
||
|
||
1. 用户注册与登录（手机号与密码）。
|
||
2. 基于 JWT 的访问令牌与刷新令牌机制。
|
||
3. 基于 WebSocket 的实时语音与文本对话。
|
||
4. AI 引导访谈与画像采集分支（由 `ChatOrchestrator` 路由）。
|
||
5. 语音识别与语音合成适配（具体厂商由配置与适配器决定）。
|
||
6. 对话内容向章节与回忆录结构的整理与异步处理。
|
||
7. 回忆录章节管理与 PDF 导出能力。
|
||
8. Android 端本地数据能力（Room 等，详见客户端工程）。
|
||
9. 离线数据同步相关能力（详见客户端工程）。
|
||
10. 用户套餐与订单支付相关能力。
|
||
11. 常见问题与反馈入口（用户域接口与客户端页面）。
|
||
|
||
标记为规划或进行中的能力（如更多传记模板、章节编辑深化、多语言等）以仓库 `README.md` 最新描述为准，本说明书不将其表述为已完成交付。
|
||
|
||
### 8.2 测试策略与自动化范围
|
||
|
||
后端测试以 `pytest` 为主，辅以 `httpx.AsyncClient` 与 `ASGITransport` 进行异步 HTTP 场景测试。项目规则强调：
|
||
|
||
1. 测试应服务真实业务场景，避免仅为覆盖率堆砌无断言价值的用例。
|
||
2. 优先覆盖核心用户路径、鉴权与配额、幂等性与关键持久化状态。
|
||
3. 不优先测试第三方库自身行为或脆弱实现细节。
|
||
4. 测试应用 `dependency_overrides` 替换数据库与外部依赖，避免直接 import 生产入口带来的环境副作用。
|
||
|
||
典型可自动化部分包括：注册登录与刷新链路、受保护资源访问、主要 CRUD 与失败分支。依赖真实 ASR、TTS、LLM、短信、支付沙箱的全链路测试多在手工或独立 E2E 环境执行。
|
||
|
||
### 8.3 测试结果表述方式建议
|
||
|
||
在向登记机关提交「测试结果」材料时，可将以下内容整理为附录表格或截图说明：
|
||
|
||
1. 本地或 CI 执行 `uv run pytest` 的命令、通过用例数量与跳过用例原因。
|
||
2. 关键模块的覆盖率报告（若政策允许附带 `pytest-cov` 摘要）。
|
||
3. 手工测试用例清单：WebSocket 多轮对话、回忆录生成端到端、支付回调联调（若适用）。
|
||
|
||
本说明书不嵌入具体 CI 截图，以免与仓库演进不同步；导出 PDF 前由实施者替换为当期报告。
|
||
|
||
---
|
||
|
||
## 第 9 章 安装、配置与使用方法
|
||
|
||
### 9.1 获取源代码
|
||
|
||
通过版本控制系统克隆 `life-echo` 仓库，检查 out 的分支与标签与本次登记版本一致。
|
||
|
||
### 9.2 后端本地开发（推荐路径）
|
||
|
||
在 `api/` 目录：
|
||
|
||
1. 安装 `uv` 并执行 `uv sync --dev` 安装运行与开发依赖。
|
||
2. 复制环境变量模板为 `.env`，按 `api/README.md` 填入数据库 URL、Redis URL、JWT 密钥、LLM 与 ASR 相关 Key 等。
|
||
3. 使用 `docker compose -f docker-compose.dev.yml up -d` 或项目提供的一键脚本启动 PostgreSQL 与 Redis。
|
||
4. 执行 `uv run alembic upgrade head`（若未依赖启动时自动迁移）。
|
||
5. 执行 `uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000` 或通过 `./dev-up.sh` 拉起 API 与 Celery。
|
||
|
||
环境变量优先级与 LLM 提供商选择逻辑以 `api/README.md` 与 `app/core/config.py` 为准。
|
||
|
||
### 9.3 内部评测入口
|
||
|
||
在 `api/` 目录执行 `uv run uvicorn app.internal_main:internal_app --host 0.0.0.0 --port 7999`（端口以实际环境变量为准）。在另一终端于 `app-eval-web/` 执行 `npm install` 与 `npm run dev`，通过浏览器访问 Vite 提示的本地地址操作评测台。
|
||
|
||
### 9.4 移动端使用
|
||
|
||
在 `app-expo/` 目录执行 `npm install` 与 `npx expo start`，按 Expo CLI 提示在模拟器或真机打开应用。将 API 基础地址指向已启动的后端（含合法 TLS 或开发环境豁免配置），完成登录后即可使用对话与回忆录功能。具体网络权限与麦克风权限以各平台 `app.json` / 插件配置为准。
|
||
|
||
### 9.5 生产部署注意
|
||
|
||
1. `SECRET_KEY` 与所有第三方密钥必须来自安全存储。
|
||
2. CORS `allow_origins` 在生产应收敛为前端真实域名，而非通配。
|
||
3. 建议将 `ALEMBIC_STARTUP_FAIL_FAST` 设为严格模式以避免实例在错误 Schema 下带病运行。
|
||
4. Celery Worker 与 Beat 应与 API 分离进程或容器，并为 `memory_idle` 等专用队列配置合理并发。
|
||
|
||
### 9.6 日志与排错
|
||
|
||
业务代码使用 `app.core.logging.get_logger(__name__)` 取得 logger，便于按 request id 关联。出现 4xx/5xx 时优先检查错误体中的 `request_id` 与服务端日志同一时间窗口。 |