# AI 智能单词本 - 开发实施方案 ## 项目概述 本项目是一个前后端分离的英语学习应用，通过 AI 生成单词释义和例句，帮助用户构建个人单词本。 --- ## 一、技术架构设计 ### 1.1 整体架构图 ```mermaid graph TB subgraph "客户端层" User[用户] end subgraph "应用层" FE[Nginx / Vite] BE[Go + Gin] end subgraph "数据层" DB[(MySQL 8.0)] end subgraph "外部服务" AI[AI大模型
DeepSeek / 通义千问] end User --> FE FE --> BE BE --> AI BE --> DB style FE fill:#e1f5ff style BE fill:#ffe1e1 style DB fill:#e1ffe1 style AI fill:#ffe1ff ``` ### 1.2 核心技术栈 | 层级 | 技术选型 | 说明 | |------|----------|------| | 前端 | Vite + Vue3/React/Vanilla | 现代化构建工具，快速开发 | | 前端服务器 | Nginx | 生产环境静态资源服务与反向代理 | | 后端 | Go 1.21+ + Gin | 高性能 Web 框架 | | 数据库 | MySQL 8.0 | 关系型数据库 | | ORM | GORM | Go 语言 ORM 框架 | | 身份认证 | JWT | 无状态 token 认证 | | 配置管理 | Viper | 配置文件管理 | | 容器化 | Docker + Docker Compose | 统一部署环境 | ### 1.3 跨域处理策略 ```mermaid graph LR subgraph "开发环境" FE[Vite
proxy配置] -->|代理| BE[后端:8080] end subgraph "生产环境" U[用户请求] --> FE2[Nginx:80] FE2 -->|/api/* 代理转发| BE2[后端:8080] FE2 -->|静态资源| SR[dist/] end ``` **原则：后端代码严禁配置 CORS，统一通过代理解决跨域。** --- ## 二、目录结构规划 ``` week05/homework/docker-gin ├── backend/ # 后端 Go 项目 │ ├── Dockerfile # Go 多阶段构建镜像 │ ├── main.go # 应用入口 │ ├── .env.example # 环境变量示例文件 │ ├── config/ # 配置管理 │ │ └── config.go # Viper 配置加载 │ ├── model/ # 数据模型层 │ │ ├── user.go # 用户模型 │ │ └── word.go # 单词模型 │ ├── api/ # 路由与控制器层 │ │ └── handler.go # 请求处理器 │ ├── service/ # 业务逻辑层 │ │ ├── auth.go # 认证服务 │ │ ├── ai.go # AI 调用服务 │ │ └── word.go # 单词业务 │ ├── middleware/ # 中间件 │ │ └── jwt.go # JWT 鉴权中间件 │ ├── utils/ # 工具函数 │ │ └── hash.go # 密码加密工具 │ └── go.mod # Go 依赖管理 │ ├── frontend/ # 前端项目 │ ├── Dockerfile # Nginx 镜像构建 │ ├── nginx.conf # 生产环境 Nginx 配置 │ ├── package.json # 依赖管理 │ ├── vite.config.js/ts # Vite 配置(开发代理) │ ├── index.html # HTML 入口 │ └── src/ │ ├── main.js/tsx # 应用入口 │ ├── api/ # API 请求封装 │ ├── components/ # 页面组件 │ │ ├── common/ # 公共组件 │ │ ├── auth/ # 登录/注册 │ │ └── word/ # 单词相关 │ ├── router/ # 路由配置 │ ├── store/ # 状态管理 │ └── utils/ # 工具函数 │ ├── docs/ # 项目文档 │ ├── api.md # API 接口文档 │ ├── db.md # 数据库设计文档 │ └── init.sql # 数据库初始化脚本 │ ├── docker-compose.yml # 容器编排配置 └── README.md # 项目说明与运行指南 ``` --- ## 三、数据库设计 ### 3.1 ER 图 ```mermaid erDiagram USER ||--|{ WORD : has USER { uuid id PK "用户ID" string username UK "用户名" string password "密码(hash)" datetime created_at "创建时间" datetime updated_at "更新时间" tinyint is_deleted "软删除标记" } WORD { uuid id PK "单词记录ID" uuid user_id FK "所属用户ID" string word "单词" text definition "释义" json examples "例句列表" string ai_provider "AI模型来源" datetime created_at "创建时间" datetime updated_at "更新时间" tinyint is_deleted "软删除标记" } ``` ### 3.2 表结构设计思路 1. **用户表 (users)** - 使用 UUID 作为主键，安全性更高 - 用户名设置唯一索引，防止重复注册 - 密码字段存储 bcrypt 哈希值，严禁明文 - 包含标准时间戳字段 - 支持软删除（is_deleted） 2. **单词表 (words)** - 使用 UUID 作为主键 - 通过 user_id 外键关联用户 - 单词字段设为索引，配合 user_id 提高查询效率 - 例句使用 JSON 类型存储 3 条数据 - 记录 AI 来源以支持多模型切换 - 支持软删除和分页查询 --- ## 四、API 接口设计 ### 4.1 接口总览 ```mermaid graph LR subgraph "无需鉴权" A[POST /api/auth/register] B[POST /api/auth/login] end subgraph "需要鉴权" C[GET /api/words/query] D[POST /api/words/save] E[GET /api/words/list] F[DELETE /api/words/:id] end ``` ### 4.2 接口设计要点 | 接口 | 方法 | 说明 | 关键参数 | |------|------|------|----------| | 注册 | POST | 用户名密码注册 | username, password | | 登录 | POST | 返回 JWT Token | username, password | | 查询单词 | GET | AI 生成释义和例句 | word, ai_provider | | 保存单词 | POST | 持久化到数据库 | word, definition, examples, ai_provider | | 单词列表 | GET | 分页获取用户单词 | page, page_size | | 删除单词 | DELETE | 软删除单词记录 | 路径参数 id | --- ## 五、核心功能实现步骤 ### 5.1 数据库初始化流程 ```mermaid sequenceDiagram participant DC as docker-compose participant M as MySQL容器 participant SQL as init.sql DC->>M: 启动容器 DC->>M: 挂载 init.sql M->>M: 初始化数据库 M->>SQL: 执行建表语句 SQL-->>M: 完成建表 M-->>DC: 准备就绪 ``` **关键点：** - 通过 docker-compose.yml 将 `docs/init.sql` 挂载到容器的 `/docker-entrypoint-initdb.d/` 目录 - MySQL 容器首次启动时自动执行该目录下的 SQL 脚本 - 严禁在代码中调用 GORM 的 AutoMigrate ### 5.2 用户认证流程 ```mermaid sequenceDiagram participant U as 用户 participant FE as 前端 participant BE as 后端 Note over U,BE: 注册流程 U->>FE: 提交用户名密码 FE->>BE: POST /api/auth/register BE->>BE: 验证用户名重复 BE->>BE: bcrypt 哈希密码 BE->>BE: 存入数据库 BE-->>FE: 注册成功 Note over U,BE: 登录流程 U->>FE: 提交用户名密码 FE->>BE: POST /api/auth/login BE->>BE: 验证用户存在 BE->>BE: bcrypt 验证密码 BE->>BE: 生成 JWT Token BE-->>FE: 返回 Token FE->>FE: 存入 localStorage ``` ### 5.3 智能查询单词流程 ```mermaid flowchart TD A[接收查询请求
word + ai_provider] --> B{鉴权检查} B -->|失败| C[返回 401 错误] B -->|通过| D{检查数据库} D -->|已保存| E[直接返回数据库记录] D -->|未保存| F[调用 AI 接口] F --> G[解析 AI 响应] G --> H[返回 AI 结果至前端
不保存到数据库] H --> I[前端展示查询结果] I --> J{用户点击保存?} J -->|是| K[前端调用保存接口] J -->|否| L[结束] K --> M[后端写入数据库] ``` ### 5.4 AI 调用服务设计 ```mermaid graph TB subgraph "AI 调用层" Service[AI Service] end subgraph "AI 提供商" DS[DeepSeek] QW[通义千问] end Service -->|根据 ai_provider| DS Service -->|根据 ai_provider| QW DS -->|返回结构化 JSON| Service QW -->|返回结构化 JSON| Service ``` --- ## 六、开发环境配置 ### 6.1 前端开发配置（Vite Proxy） 在 `vite.config.js/ts` 中配置代理，解决开发环境跨域问题： ```javascript export default { server: { proxy: { '/api': { target: 'http://localhost:8080', // 后端服务地址 changeOrigin: true, // 改变请求源 } } } } ``` ### 6.2 后端配置管理 使用 Viper 管理配置，支持从 `.env` 文件加载： | 配置项 | 说明 | 示例 | |--------|------|------| | DB_HOST | 数据库地址 | db | | DB_PORT | 数据库端口 | 3306 | | DB_USER | 数据库用户 | root | | DB_PASSWORD | 数据库密码 | password | | DB_NAME | 数据库名 | wordbook | | JWT_SECRET | JWT 签名密钥 | secret_key | | DEEPSEEK_API_KEY | DeepSeek 密钥 | sk-xxx | | QIANWEN_API_KEY | 通义千问密钥 | xxx | --- ## 七、容器化部署设计 ### 7.1 网络架构图 ```mermaid graph TB subgraph "宿主机" Host[宿主机] Port80[端口 80] end subgraph "Docker 网络" Net[wordbook-network] end subgraph "frontend 容器" Nginx[Nginx:80] end subgraph "backend 容器" Gin[Gin:8080] end subgraph "db 容器" MySQL[MySQL:3306] end Host --> Port80 Port80 -->|外部访问| Nginx Nginx --> Net Gin --> Net MySQL --> Net Nginx -.->|/api/* 代理| Gin Gin -.->|数据库连接| MySQL style Host fill:#f0f0f0 style Net fill:#e6f3ff ``` ### 7.2 服务设计要点 | 服务 | 暴露端口 | 依赖 | 说明 | |------|----------|------|------| | frontend | 80:80 | backend | 对外唯一入口 | | backend | 无 | db | 内部网络访问 | | db | 无 | - | 内部网络访问 | **安全考虑：** - 只有 frontend 暴露端口到宿主机 - backend 和 db 仅在容器网络内通信 - 通过容器名相互访问（`http://backend:8080`） ### 7.3 Dockerfile 设计 **后端多阶段构建：** ```mermaid graph LR A[构建阶段
golang:alpine] -->|编译| B[二进制文件] B -->|复制| C[运行阶段
alpine:latest] C --> D[精简镜像] ``` **前端 Nginx 构建：** ```mermaid graph LR A[node:18-alpine
Vite Build] -->|dist 产物| B[nginx:alpine
复制 dist 并替换 nginx.conf] ``` --- ## 八、开发实施顺序 ### 阶段一：项目初始化 1. 创建项目目录结构 2. 初始化后端项目（go mod init） 3. 初始化前端项目（npm create vite@latest） 4. 配置 docker-compose.yml 基础框架 ### 阶段二：数据库设计 1. 编写 `docs/init.sql` 建表语句 2. 编写 `docs/db.md` 数据库设计文档 3. 在 docker-compose 中配置 MySQL 初始化挂载 ### 阶段三：后端开发 1. **配置层**：Viper 环境变量加载 2. **模型层**：定义 User 和 Word 结构体 3. **认证模块**： - 用户注册逻辑 - 用户登录逻辑 - JWT 生成与验证中间件 4. **AI 调用模块**： - DeepSeek 接口封装 - 通义千问接口封装 - Prompt 模板设计 5. **单词业务模块**： - 查询逻辑（数据库检查 + AI 调用） - 保存逻辑 - 列表查询（分页） - 删除逻辑（软删除） 6. **API 路由**：注册所有接口 7. **API 文档**：编写 `docs/api.md` ### 阶段四：前端开发 1. **基础配置**： - Vite proxy 配置 - API 请求封装（axios） 2. **认证页面**： - 登录表单 - 注册表单 - Token 存储与管理 3. **单词学习页面**： - 查询单词表单 - AI 结果展示 - 保存按钮 4. **单词本页面**： - 单词列表展示 - 分页器 - 删除功能 5. **状态管理**：管理用户登录状态 ### 阶段五：容器化部署 1. **后端 Dockerfile**：多阶段构建优化 2. **前端 Dockerfile**：Nginx 配置 3. **Nginx 反向代理**：配置 `/api/*` 路由 4. **Docker Compose 编排**：网络、依赖、环境变量 5. **本地测试**：完整流程验证 ### 阶段六：文档编写 1. 编写 `README.md`：项目说明与运行指南 2. 完善 `docs/api.md` 3. 完善 `docs/db.md` 4. 整理代码注释 --- ## 九、注意事项与最佳实践 ### 9.1 安全注意事项 - ⚠️ **严禁明文存储密码**：必须使用 bcrypt 等加密算法 - ⚠️ **严禁后端配置 CORS**：统一通过代理解决跨域 - ⚠️ **严禁使用 AutoMigrate**：数据库初始化必须通过 SQL 脚本 - ⚠️ **敏感信息管理**：API Key 不应提交到代码仓库 ### 9.2 开发规范 1. 代码风格遵循 Go 和各语言社区规范 2. 所有接口必须有明确的参数说明和返回示例 3. 数据库字段必须有清晰的注释 4. 容器镜像应尽可能精简 ### 9.3 调试建议 - 开发时可以先单独启动后端和前端测试 - 使用 Docker Compose 日志查看：`docker-compose logs -f` - 数据库连接问题检查网络配置和用户权限 --- ## 十、验收标准 1. ✅ 项目目录结构符合要求 2. ✅ 用户可正常注册和登录 3. ✅ 可查询单词并获取 AI 生成的释义和例句 4. ✅ 可保存单词到个人单词本 5. ✅ 单词列表支持分页 6. ✅ 可删除已保存的单词 7. ✅ 使用 Docker Compose 一键启动 8. ✅ 生产环境通过 Nginx 反向代理访问 9. ✅ 三份文档完整且清晰 ---