513 lines
14 KiB
Markdown
513 lines
14 KiB
Markdown
# 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大模型<br/>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<br/>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[接收查询请求<br/>word + ai_provider] --> B{鉴权检查}
|
||
B -->|失败| C[返回 401 错误]
|
||
B -->|通过| D{检查数据库}
|
||
D -->|已保存| E[直接返回数据库记录]
|
||
D -->|未保存| F[调用 AI 接口]
|
||
F --> G[解析 AI 响应]
|
||
G --> H[返回 AI 结果至前端<br/>不保存到数据库]
|
||
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[构建阶段<br/>golang:alpine] -->|编译| B[二进制文件]
|
||
B -->|复制| C[运行阶段<br/>alpine:latest]
|
||
C --> D[精简镜像]
|
||
```
|
||
|
||
**前端 Nginx 构建：**
|
||
```mermaid
|
||
graph LR
|
||
A[node:18-alpine<br/>Vite Build] -->|dist 产物| B[nginx:alpine<br/>复制 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. ✅ 三份文档完整且清晰
|
||
|
||
---
|
||
|