“灵语星火”第二阶段团队记录（一）

前言LingualSpark灵语星火智能外语学习平台顺利进入第二阶段系统设计与基础平台搭建4月6日 - 4月19日。如果说第一阶段是“采石挖矿”——完成12万条数据的采集、清洗和标注那么第二阶段就是“夯实地基”——我们要把项目的骨架搭好让后续的AI微调、核心功能开发能够稳稳当当地跑起来。按照任务书的规划本阶段共有5大任务系统架构设计、开发环境搭建、本地大模型部署、AI服务API对接、基础功能开发。两周时间里团队四人各司其职从架构蓝图到代码落地从模型部署到API集成完成了完整的技术底座搭建。一、系统架构设计画出项目“施工蓝图”任何一个正经的软件项目都不能上来就写代码。我们的第一件事就是搞清楚这系统到底长什么样1.1 技术选型为什么选这些团队负责人组织了技术选型讨论最终确定了如下方案层级技术选型选型理由前端Vite React 19 TypeScript Ant Design开发体验好、组件丰富、类型安全前端状态管理Zustand轻量、无冗余渲染比Redux更适合教育类项目后端框架FastAPI (Python)高性能异步、原生支持API文档自动生成数据库MySQL 8.0 RedisMySQL持久化存储Redis缓存与会话管理选型的核心原则是不追新、不守旧、求稳定。每个技术都有大量社区支持和生产实践案例不会因为技术本身的不成熟而给项目埋雷。1.2 分层架构设计参考SpringBoot思想后端负责人在搭建FastAPI项目时借鉴了企业级SpringBoot的分层架构思想将项目目录结构设计为app/ ├── controllers/# 控制器层 → 接收请求、返回响应│ ├── auth_controller.py# 登录、注册、token刷新接口│ └── user_controller.py# 用户信息管理接口├── services/# 服务层 → 核心业务逻辑实现│ ├── auth_service.py# 认证、加密、Token业务│ └── user_service.py# 用户数据操作业务├── models/# 模型层 → 数据结构与数据库映射│ ├── user_models.py# 用户请求/响应模型Pydantic│ └── database_models.py# 数据库表模型SQLAlchemy├── core/# 核心层 → 全局配置与工具│ ├── database.py# 数据库连接配置│ ├── redis_client.py# Redis客户端封装│ └── dependencies.py# 依赖注入用户认证中间件├──\__init_\_.py └── main.py# FastAPI应用入口run.py# 启动脚本分层架构的核心优势在于解耦彻底Controller只负责接收参数、调用Service、返回结果不写业务逻辑Service承载所有业务逻辑Controller、Service互不污染Model层独立维护数据结构数据库变更不影响接口定义Core层提供全局能力一次配置全项目复用。这样的设计让后续多人并行开发变得顺畅——前端开发界面后端开发登录接口调试模型部署三条线互不阻塞。1.3 数据库设计ER图与核心表结构数据库设计是整个架构的关键一环。我们梳理了项目涉及的实体及其关系绘制了数据库ER图明确了以下核心表user 表用户信息用户名、邮箱、密码哈希、年龄组、设备ID等story 表故事素材标题、正文、难度等级、年龄段、配图URL等word 表单词库单词本体、难度等级、CEFR级别等translations 表单词翻译多词性、多释义外键关联wordphrases 表词组/例句词组、翻译外键关联wordword_user 表用户学习记录用户-单词关联背诵状态复习时间等其中word表的设计经历了两轮迭代初始方案误以为“一个单词对应一条翻译一个例句”实际解析JSON数据后发现一个单词可能有多个词性、多个翻译、多个词组——translations和phrases都是数组结构。最终推翻了第一版方案重新设计为三表关联结构才真正适配了真实数据。1.4 API接口文档初版我们在架构设计阶段就定义好了API接口的初版文档包括接口路径方法功能说明/auth/registerPOST用户注册/auth/loginPOST用户登录返回JWT Token/auth/meGET获取当前用户信息/auth/mePUT更新用户信息年龄组等/storiesGET按条件获取故事列表支持年龄段筛选/stories/{id}GET获取故事详情/stories/generatePOSTAI生成故事/wordsGET获取单词列表支持难度筛选/words/reviewGET获取待复习单词错误时返回相应状态码和错误详情。二、开发环境搭建一键启动的工程化底座2.1 Docker docker-compose 容器化部署为了确保“在我机器上能跑”不会变成“在你机器上跑不了”后端负责人编写了Docker配置文件将开发环境一键容器化。docker-compose.yml 的核心结构mysql 容器MySQL 8.0挂载本地数据卷持久化存储redis 容器Redis 7.0用于Token缓存和异步任务队列app 容器FastAPI后端服务挂载本地代码目录实现热重载配置完成后团队成员只需bashgitclone https://gitee.com/guoanzou/LingualSpark.gitcdLingualSpark/FASTAPIdocker-composeup-d即可在本地启动完整开发环境无需手动安装MySQL、Redis、Python依赖等。2.2 CI/CD流水线规划我们在Gitee仓库中配置了基本的持续集成流水线代码提交触发每次提交到dev分支自动执行代码规范检查ESLint Pylint合并到main触发自动构建Docker镜像并推送到仓库人工触发部署生产环境部署通过手动触发确保发布可控。2.3 前端项目初始化前端负责人完成了React项目的初始化bashnpmcreate vitelatest frontend ----templatereact-tscdfrontendnpminstallnpminstallreact-router-dom zustand ant-design axios并规划了标准化的目录结构frontend/src/├── assets/ # 静态资源图片、字体等├── components/ # 公共组件Navbar、Footer等├── pages/ # 页面Home、About、Login等├── routes/ # 路由配置├── services/ # API请求封装├── store/ # Zustand状态管理├── types/ # TypeScript类型定义├── utils/ # 工具函数├── App.tsx└── main.tsx至此前端工程化底座搭建完成。三、基础功能开发用户系统与素材管理后台在架构和环境就绪后我们开始了最基础的CRUD功能开发。3.1 用户系统后端负责人实现了用户注册/登录功能注册接收用户名、密码、邮箱等参数SHA256随机盐值加密存储密码登录验证用户名密码生成JWT Token返回JWT设计Token中除用户名外还嵌入了后端随机生成的16位device_id用于后续实现“同一账号只能一台设备登录后登踢先登”的机制。前端负责人实现了登录/注册页面包括表单校验、错误提示、记住我功能等。四、成果小结两周时间团队完成了以下核心交付✅ 输出《系统架构设计文档》包含技术栈清单、数据库ER图、初版API文档✅ 前后端项目初始化完成Docker环境一键启动✅ 用户注册/登录功能实现管理员后台可上传/查看素材✅ 前端实现基础布局框架导航栏、底部栏、首页、关于页