Skip to content

IFLOW.md

Latest commit

 

History

History
423 lines (311 loc) · 11.4 KB

IFLOW.md

File metadata and controls

423 lines (311 loc) · 11.4 KB

zenEnglish 项目上下文

最后更新：2026年1月17日

项目概述

项目名称： zenEnglish
产品类型： 考研复试英语口语AI智能体（微信小程序 + Web）
一句话定位： 面向西安高校考研生的「院校/专业定制型复试英语口语AI导师」

核心价值主张

  1. 更对口：西交电气/西工大航宇/西电通信/西外翻硕等专业专用题库
  2. 更像复试：模拟"你真正会遇到的导师"——本校导师风格 + 专业追问
  3. 更省时间：用15-30天，刷够10-20场高还原模拟，所有弱点一目了然

目标用户

  • 主目标人群： 西安及周边高校考研学生（含一战/二战、自考跨考）
  • 目标院校优先： 西交大、西工大、西电、西外、西北大、西财、西邮等

商业目标（首年）

  • 在西安本地实现 $20万+ 年经常性收入（ARR）
  • 累积 2,000+ 月活用户，免费转付费转化率 ≥ 5%
  • 打通 3–5 家本地考研机构的 B 端合作试点

文档结构

文件 说明 状态
PRD.md 产品需求文档（V1.0） 完成
HLD.md 高阶设计文档（V1.0） 完成
LLD.md 低层设计文档（V1.0） 完成

文档说明

  • PRD.md：包含产品定义、市场分析、功能规划、收费设计、里程碑规划等
  • HLD.md：包含系统架构设计、技术选型、核心模块设计、竞品技术分析等
  • LLD.md：包含详细数据库设计、API接口规范、消息格式、数据结构等

技术栈

后端技术栈

组件 技术选型 版本
开发语言 Python 3.12+
API框架 FastAPI 0.104+
ORM SQLAlchemy 2.0+
数据库迁移 Alembic 1.13+
数据验证 Pydantic 2.5+
ASGI服务器 uvicorn 0.24+
缓存 Redis 7.0+
消息队列 RabbitMQ 3.12+
异步任务 Celery 5.3+

AI技术栈

组件 技术选型 说明
ASR Whisper / Faster-Whisper 开源、高准确率
ASR优化 中文口音微调 针对中国考生优化
LLM Qwen2.5 / DeepSeek 开源、中文友好
LLM编排 LangChain + LangGraph Agent工作流
TTS VITS / Edge-TTS 高质量语音合成
评分算法 GOP + DNN-HMM 音素级评分
向量模型 text2vec / BGE 文本向量化

前端技术栈

组件 技术选型 版本
跨平台框架 uni-app 3.0+
前端框架 Vue 3 3.3+
类型系统 TypeScript 5.0+
UI组件库 Vant 4.0+
状态管理 Pinia 2.1+
HTTP客户端 Axios 1.6+

数据库技术栈

组件 技术选型 用途
MySQL 8.0+ 关系型数据存储
MongoDB 6.0+ 非结构化数据存储（对话记录）
Redis 7.0+ 缓存、会话、限流
Milvus 2.3+ 向量数据库（语义搜索）

DevOps技术栈

组件 技术选型 版本
容器化 Docker 24.0+
容器编排 Kubernetes 1.28+
负载均衡 Nginx 1.24+
API网关 Kong 3.4+
监控 Prometheus 2.47+
可视化 Grafana 10.0+
日志 ELK Stack 8.10+
对象存储 MinIO / 阿里云OSS 音频/文件存储

系统架构

整体架构

客户端层 → API网关层 → 业务服务层 → AI服务层 → 数据层

核心服务

服务名称 端口 职责
用户服务 8001 用户注册/登录、用户信息管理
题库服务 8002 题库管理、导师风格、题目推荐
练习服务 8003 练习会话管理、实时交互
评分服务 8004 多维度评分、发音诊断
报告服务 8005 学习报告生成、报告导出
支付服务 8006 订单管理、支付处理
通知服务 8007 消息推送、通知管理
统计服务 8008 数据统计、分析
订阅服务 8009 订阅管理、权限控制
ASR服务 9001 语音识别
TTS服务 9002 语音合成
LLM服务 9003 大语言模型调用
Agent编排 9004 Agent工作流管理
评分引擎 9005 评分算法执行
纠错引擎 9006 语法纠错

核心功能

1. 基础功能层（MVP必须，部分免费）

  • 语音交互基础能力（ASR + TTS）
  • 通用复试流程模拟（自我介绍、家庭、专业背景、研究兴趣、职业规划等）
  • 基础评分与纠错（发音、流利度、词汇多样性、语法准确性）
  • 练习记录与基础错题本

2. 进阶功能层（竞品对齐，收费为主）

  • 压力渐进式训练模式（温和/正常/高压）
  • 突发追问引擎（基于回答关键词生成追问）
  • 发音诊断与可视化（音素级发音评估）
  • 学术表达增强（输出更学术的优化回答）
  • 学习报告（每日小结、周度报告、PDF导出）

3. 本地化差异化功能层（核心护城河，付费主力）

  • 西安高校/专业定制题库（学校级-学院级-专业级）
  • 导师风格数字孪生（学术深挖型/实践导向型/友好交流型/刻板高压型）
  • 西安特化发音训练模块（/l/–/n/混淆、/θ/ /ð/发音问题）
  • 目标院校匹配度评分
  • 西安复试时间线与训练计划

核心流程

用户注册/登录流程

  1. 用户打开小程序
  2. 点击"微信一键登录"
  3. 小程序调用wx.login()获取code
  4. 前端将code发送到后端
  5. 后端调用微信API获取openid和session_key
  6. 后端查询用户是否存在并返回JWT token
  7. 前端存储token，跳转到首页

练习流程

  1. 创建会话 → 选择模式（通用/院校定制）→ 选择压力等级
  2. 开始练习 → AI提问 → 用户录音 → ASR转写 → LLM评分 → TTS反馈
  3. 循环提问 → 根据回答生成追问
  4. 结束练习 → 生成报告

评分流程

  1. 接收用户音频
  2. ASR转写为文本
  3. 发音评分（GOP算法）
  4. 流利度评分（语速、停顿、语流长度）
  5. 词汇评分（LLM分析，词汇多样性）
  6. 语法评分（LLM分析，语法错误、句式多样性）
  7. 院校匹配度评分（仅院校定制模式）
  8. 综合评分（加权计算）

数据库设计

MySQL核心表

表名 说明
users 用户表
questions 题目表
tutor_styles 导师风格表
practice_sessions 练习会话表
practice_turns 练习轮次表
scoring_records 评分记录表
phoneme_errors 发音错误表
reports 报告表
orders 订单表
institutions 机构表
institution_students 机构学生表

MongoDB集合

集合名 说明
conversations 对话记录集合
university_knowledge 院校知识库集合

API接口规范

基础路径

https://api.zenenglish.com/api/v1

统一响应格式

{
  "code": 0,
  "message": "success",
  "data": {},
  "timestamp": "2026-01-17T10:30:00Z",
  "request_id": "uuid"
}

核心接口

接口 方法 说明
/auth/wechat/login POST 微信登录
/user/profile GET 获取用户信息
/user/profile PUT 更新用户信息
/questions GET 获取题目列表
/questions/recommend GET 获取推荐题目
/practice/sessions POST 创建练习会话
/practice/sessions/{id}/ws WS WebSocket实时交互
/practice/sessions/{id} GET 获取会话详情
/practice/records GET 获取练习记录

收费模式

C端收费结构

  1. 免费版（长期）

    • 每日1场通用模拟
    • 基础评分 + 最近3天记录
    • 部分话题样例答案预览

  2. 冲刺包（主打产品）

    • 15天冲刺：¥88
    • 30天冲刺：¥168

  3. 年度会员：¥258–¥298

    • 所有已支持院校通用题库
    • 所有进阶功能 + 报告导出

B端合作模式

  • 机构按学员数季付费：约¥50/生/季
  • 或按项目整体报价（提供专属Branding + 内嵌机构Logo）

里程碑规划

阶段 时间 主要目标 关键交付
MVP 1–2个月 跑通通用模拟 + 评分闭环 小程序上线，通用题库，基础评分与记录
迭代一 3–4个月 上线西安高校定制 + 冲刺包付费 3所重点院校题库，高压模式，学习报告，支付
迭代二 5–6个月 拓展院校与专业 + B端试点 西安主流院校覆盖，机构后台，首批合作机构
后续 6个月+ 复制到其他城市/场景 全国更多院校通用版，四六级/职场场景

核心指标（KPI）

用户指标

  • MAU ≥ 2,000
  • 免费→付费转化率 ≥ 5%
  • 7日留存 ≥ 40%，30日留存 ≥ 25%

收入指标

  • 年收入（ARR）≥ ¥200,000
  • 单用户平均客单价：¥150–¥200

体验与口碑

  • 用户主观满意度（NPS）≥ 60
  • 重大服务中断 < 0.1%

竞品对比

功能模块 可栗口语 咕噜口语 星空外语 zenEnglish
ASR Whisper/Faster-Whisper 自研深度学习引擎 自研深度学习引擎 Whisper + 中文口音优化
LLM OpenAI GPT系列 DeepSeek-R1 DeepSeek-R1 Qwen/DeepSeek + 院校知识库
评分维度 4维度 4维度 + 音素级 4维度 + 音素级 4维度 + 院校匹配度
场景覆盖 通用场景 15000+场景 15000+场景 西安高校定制场景
压力模式 基础压力模式 3级压力模式 3级压力模式 3级压力模式 + 导师风格
定价 ¥98-398 ¥98-398 ¥98-398 ¥88-298

项目约定

代码规范

  • 后端：遵循PEP 8规范
  • 前端：遵循ESLint + Prettier规范
  • 数据库：使用下划线命名法（snake_case）
  • API：使用RESTful风格

提交规范

  • feat: 新功能
  • fix: 修复bug
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 重构
  • test: 测试相关
  • chore: 构建/工具相关

分支策略

  • main: 主分支，保持稳定
  • develop: 开发分支
  • feature/*: 功能分支
  • hotfix/*: 紧急修复分支

重要提醒

  1. 本地化优先：所有功能设计优先考虑西安高校的本地化需求
  2. 院校/专业深度定制：这是项目的核心差异化优势，需要重点投入
  3. 成本控制：使用开源模型（Qwen、Whisper）降低成本
  4. 快速迭代：基于LangChain/LangGraph快速构建Agent系统
  5. 用户体验：确保AI响应速度 <200ms，提供流畅的交互体验

常用命令

后端开发

# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8001

# 运行数据库迁移
alembic upgrade head

# 创建新的迁移
alembic revision --autogenerate -m "description"

# 运行测试
pytest tests/

# 代码格式化
black .
isort .

前端开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev:h5

# 构建生产版本
npm run build:h5

# 代码检查
npm run lint
npm run lint:fix

Docker

# 构建镜像
docker build -t zenenglish/api:latest .

# 运行容器
docker run -p 8001:8001 zenenglish/api:latest

# 查看日志
docker logs -f zenenglish-api

联系信息

如有问题或需要帮助，请参考：

  • PRD.md：产品相关问题
  • HLD.md：架构设计相关问题
  • LLD.md：技术实现相关问题