Archived

This repository has been archived on 2026-05-19. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

T

wonder 7b271af6ea Update

2026-04-20 22:47:51 +08:00

7.1 KiB

Raw Blame History

全栈开发实战：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 的同源访问。

三、项目目录结构要求

整个项目需要采用前后端分离的代码组织结构，并且包含完善的文档（请严格遵循以下目录规范）：

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 数据库表结构设计。
需要列出每个表的字段名、数据类型、是否主/外键、索引设置、以及每个字段的具体业务含义。
说明你对单词本表、用户表的关联关系设计。

7.1 KiB Raw Blame History Unescape Escape