105 lines
7.1 KiB
Markdown
105 lines
7.1 KiB
Markdown
|
||
---
|
||
|
||
# 全栈开发实战：AI 智能单词本
|
||
|
||
## 一、项目背景
|
||
|
||
开发一个辅助英语学习的前后端分离 Web 应用。用户可以通过前端页面查询单词，后端系统会调用 AI 大模型（DeepSeek 或 通义千问）生成该单词的精准释义和 3 条例句。查询结果返回前端展示后，用户可以手动点击“保存”按钮，将该单词记录持久化到个人的单词本中，方便日后复习。
|
||
|
||
**本项目重点考察**：前后端分离架构、代理与跨域处理、第三方 AI 接口对接、关系型数据库设计，以及基于 Docker 的全栈工程化容器编排部署。
|
||
|
||
## 二、技术栈与核心架构要求
|
||
|
||
* **后端语言框架**：Go (>= 1.21) + Gin (`github.com/gin-gonic/gin`)
|
||
* **前端技术栈**：必须基于 Vite 构建（可搭配 Vue3、React 或原生 Vanilla JS），且必须掌握相应的工程化配置。
|
||
* **数据库 & ORM**：MySQL 8.0 + GORM (`gorm.io/gorm`)
|
||
* **容器化部署**：Docker & Docker Compose
|
||
* **Web 服务器 (前端)**：Nginx
|
||
* **身份验证**：JWT (JSON Web Token)
|
||
* **配置管理**：Viper (或 godotenv)
|
||
|
||
【特别要求：跨域处理规范】
|
||
|
||
* **严禁跨域配置**：本项目**严禁**在后端 Go 代码中配置任何允许跨域（CORS）的中间件！
|
||
* **开发环境**：前端必须通过配置 Vite 的 `proxy` 来解决跨域问题。
|
||
* **生产环境**：必须通过 Nginx 反向代理 (`proxy_pass`) 统一路由，实现前端静态资源与后端 API 的同源访问。
|
||
|
||
## 三、项目目录结构要求
|
||
|
||
整个项目需要采用前后端分离的代码组织结构，并且包含完善的文档（请严格遵循以下目录规范）：
|
||
|
||
```text
|
||
week05/homework/docker-gin
|
||
├── backend/ # 后端 Go 代码目录
|
||
│ ├── Dockerfile # 后端镜像构建文件
|
||
│ ├── main.go
|
||
│ ├── .env # .env 文件示例
|
||
│ └── ... # 其他分层目录如 api, service, model 等
|
||
├── frontend/ # 前端项目目录（由 Vite 初始化）
|
||
│ ├── Dockerfile # 前端镜像构建文件（基于 Nginx）
|
||
│ ├── nginx.conf # Nginx 自定义配置文件（生产环境反向代理）
|
||
│ ├── vite.config.js/ts # Vite 配置文件（开发环境 Proxy）
|
||
│ └── ... # src, index.html 等
|
||
├── docs/ # 项目文档目录
|
||
│ ├── api.md # API 接口详细文档
|
||
│ ├── db.md # 数据库设计文档
|
||
│ └── init.sql # 数据库初始化脚本（包含建表语句）
|
||
├── docker-compose.yml # 统一部署文件
|
||
└── README.md # 项目总体说明与运行指南
|
||
```
|
||
|
||
## 四、核心功能需求
|
||
|
||
### 1. 用户认证模块
|
||
* **用户注册**：前端提供表单，后端接收用户名密码，后端严禁明文存储密码（需进行 Hash 加密后存入 MySQL）。
|
||
* **用户登录**：验证通过后返回 JWT Token，前端需要将 Token 存储（如 `localStorage`），并在后续请求的 Header 中携带 (`Authorization: Bearer <token>`)。
|
||
|
||
### 2. 单词学习模块 (核心业务)
|
||
* **智能查询单词**：
|
||
* **接收参数**：`word`（单词），`ai_provider`（前端让用户下拉选择模型，如 DeepSeek/通义千问）。
|
||
* **逻辑流程**：
|
||
1. 鉴权通过后，后端先在数据库中检查当前用户是否已保存过该单词。
|
||
2. 如果已保存，直接从数据库读取并返回给前端。
|
||
3. 如果未保存，根据 `ai_provider` 调用对应 AI 接口。
|
||
4. 让 AI 返回格式化的 JSON 数据（包含：释义 + 3 条例句）。
|
||
5. 直接将 AI 结果返回给前端展示，**此时不在后端进行数据库保存**。
|
||
* **手动保存单词**：
|
||
* **接收参数**：前端将上一步查询到的完整数据（单词、释义、例句列表、AI 来源）提交给后端。
|
||
* **逻辑流程**：后端接收到数据后，将其写入 MySQL 数据库，并与当前 UserID 绑定。
|
||
* **获取单词列表**：获取当前用户保存的所有单词记录（**必须支持分页**，前端提供分页器，后端接收 `page` 和 `page_size`）。
|
||
* **删除单词**：根据单词 ID，从数据库中软删除某条记录。
|
||
|
||
## 五、部署与交付要求 (Docker & Nginx & Vite)
|
||
|
||
### 1. 后端构建 (`backend/Dockerfile`)
|
||
* 使用多阶段构建编译 Go 应用，暴露出后端端口（如 8080）。镜像需尽可能精简。
|
||
|
||
### 2. 前端构建 (`frontend/Dockerfile`) 与环境配置
|
||
* **【生产环境 - Nginx 统一入口】**：基础镜像使用 `nginx:alpine`，将 Vite build 后的产物拷贝到 Nginx 发布目录。
|
||
* **必须替换自定义的 `nginx.conf`**：将 Nginx 作为整个应用的唯一外部访问入口。既要伺服前端静态页面，又要将后端接口请求（如 `/api/`）通过 `proxy_pass` 反向代理转发给内部 `backend` 容器。
|
||
|
||
### 3. 编排部署 (`docker-compose.yml`)
|
||
* 定义 3 个 Service：`db` (MySQL), `backend` (Go API), `frontend` (Nginx UI)。
|
||
* 配置共享的网络。对外只需暴露 `frontend` (Nginx) 的 80/443 等端口，`backend` 和 `db` 的端口无需直接映射到宿主机，保障安全性。`frontend` 可以通过容器名访问 `backend`，`backend` 可以访问 `db`。
|
||
* `backend` 服务需依赖于 `db` (`depends_on`)。
|
||
* **数据库初始化要求**：为了符合企业级开发规范（DBA 审计与权限控制），**严禁**在代码中使用 GORM 的 `AutoMigrate` 等工具自动建表。**必须在 `docker-compose.yml` 中将包含建表语句的 `docs/init.sql` 挂载到 MySQL 容器的 `/docker-entrypoint-initdb.d/` 目录下进行初始化。**确保一键启动即可使用，无需人工干预数据库建表。
|
||
|
||
## 六、文档编写要求 (考察重点)
|
||
|
||
本项目非常看重开发者的文档输出能力。除了提交能够正常运行的代码外，你必须编写并提交以下三份文档：
|
||
|
||
### 1. `README.md` (项目说明与运行指南)
|
||
* **项目基本信息**：至少包含你的姓名、学校、学号。
|
||
* **开发任务索引**：列出你完成的任务清单。
|
||
* **项目简介**：包含项目简介与架构图（或架构说明）。
|
||
* **运行指南（核心考点）**：必须极其清晰地写明如何从零启动该项目。包括前置依赖（Docker 等）、如何配置 AI 的 API Key（如环境变量或 `.env` 文件的创建）、一键启动命令（`docker-compose up -d`），以及启动后如何访问前端页面和后端服务。
|
||
|
||
### 2. `docs/api.md` (API 接口文档)
|
||
* 详细记录业务中的每一个接口。
|
||
* 每一项应包含：接口路径、请求方法、鉴权说明、请求参数（Query 或 Body 结构）、成功的返回示例（JSON 格式）、失败的错误码及其含义。
|
||
|
||
### 3. `docs/db.md` (数据库设计文档)
|
||
* 详细阐述你的 MySQL 数据库表结构设计。
|
||
* 需要列出每个表的字段名、数据类型、是否主/外键、索引设置、以及每个字段的具体业务含义。
|
||
* 说明你对单词本表、用户表的关联关系设计。 |