obsidian/金山办公作业/Week05/PLAN.md

# 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. ✅ 三份文档完整且清晰

---