“灵语星火”第二阶段团队记录（一）
前言
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 + Redis | MySQL持久化存储，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 表：单词翻译（多词性、多释义，外键关联word）
phrases 表：词组/例句（词组、翻译，外键关联word）
word_user 表：用户学习记录（用户-单词关联，背诵状态，复习时间等）
其中，word表的设计经历了两轮迭代：初始方案误以为“一个单词对应一条翻译+一个例句”；实际解析JSON数据后发现，一个单词可能有多个词性、多个翻译、多个词组——translations和phrases都是数组结构。最终推翻了第一版方案，重新设计为三表关联结构，才真正适配了真实数据。
1.4 API接口文档（初版）
我们在架构设计阶段就定义好了API接口的初版文档，包括：
| 接口路径 | 方法 | 功能说明 |
| /auth/register | POST | 用户注册 |
| /auth/login | POST | 用户登录，返回JWT Token |
| /auth/me | GET | 获取当前用户信息 |
| /auth/me | PUT | 更新用户信息（年龄组等） |
| /stories | GET | 按条件获取故事列表（支持年龄段筛选） |
| /stories/{id} | GET | 获取故事详情 |
| /stories/generate | POST | AI生成故事 |
| /words | GET | 获取单词列表（支持难度筛选） |
| /words/review | GET | 获取待复习单词 |
错误时返回相应状态码和错误详情。
二、开发环境搭建：一键启动的工程化底座
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 vite@latest 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环境一键启动
✅ 用户注册/登录功能实现，管理员后台可上传/查看素材
✅ 前端实现基础布局框架（导航栏、底部栏、首页、关于页）