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

AI 智能单词本 - 开发实施方案

项目概述

本项目是一个前后端分离的英语学习应用，通过 AI 生成单词释义和例句，帮助用户构建个人单词本。

---

一、技术架构设计

1.1 整体架构图

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 跨域处理策略

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 图

erDiagram
    USER ||--|{ WORD : has
    USER {
        uuid id PK "用户ID"
        string username UK "用户名"
        string password "密码(hash)"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
        datetime deleted_at "删除时间(软删除)"
    }
    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 "更新时间"
        datetime deleted_at "删除时间(软删除)"
    }

3.2 表结构设计思路

1. 用户表 (users)

   • 使用 UUID 作为主键，安全性更高
   • 用户名设置唯一索引，防止重复注册
   • 密码字段存储 bcrypt 哈希值，严禁明文
   • 包含标准时间戳字段
   • 支持软删除（deleted_at）

2. 单词表 (words)

   • 使用 UUID 作为主键
   • 通过 user_id 外键关联用户
   • 单词字段设为索引，配合 user_id 提高查询效率
   • 例句使用 JSON 类型存储 3 条数据
   • 记录 AI 来源以支持多模型切换
   • 支持软删除和分页查询

---

四、API 接口设计

4.1 接口总览

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 数据库初始化流程

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 用户认证流程

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 智能查询单词流程

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 调用服务设计

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 中配置代理，解决开发环境跨域问题：

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 网络架构图

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 设计

后端多阶段构建：

graph LR
    A[构建阶段<br/>golang:alpine] -->|编译| B[二进制文件]
    B -->|复制| C[运行阶段<br/>alpine:latest]
    C --> D[精简镜像]

前端 Nginx 构建：

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

---