# 商品售卖网站技术文档

## 1. 项目概述

本项目是一个多功能商品售卖平台，支持管理员后台、供货商后台和用户前端，具备完整的商品管理、订单处理、库存管理、多语言支持等功能。

## 2. 技术栈选择

### 2.1 前端技术
- **框架**：Vue 3 + Vite
- **状态管理**：Pinia
- **路由**：Vue Router
- **UI 库**：Element Plus
- **样式**：SCSS
- **国际化**：i18n
- **HTTP 客户端**：Axios

### 2.2 后端技术
- **语言**：Go 1.20+
- **Web 框架**：Gin
- **数据库**：SQLite（默认）/ MySQL / PostgreSQL
- **缓存**：Redis
- **认证**：JWT
- **ORM**：GORM
- **邮件服务**：SMTP

## 3. 系统架构

### 3.1 架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                              前端层                               │
├─────────────────────┬─────────────────────┬───────────────────────┤
│     用户前端        │   管理员后台        │    供货商后台         │
└─────────┬──────────┴─────────┬──────────┴──────────┬──────────────┘
          │                    │                    │
┌─────────▼────────────────────▼────────────────────▼──────────────┐
│                              API 层                             │
└───────────────────────────────┬──────────────────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────────┐
│                           服务层                                │
└───────────────────────────────┬──────────────────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────────┐
│                          数据层                                 │
└───────────────────────────────────────────────────────────────────┘
```

## 4. 功能模块设计

### 4.1 核心模块

#### 4.1.1 用户管理
- **用户注册**：支持邮箱注册，需验证邮箱，可通过邀请码注册获得额外购买资格
- **用户登录**：支持邮箱密码登录，可记住密码，登录失败次数限制
- **忘记密码**：通过邮箱验证码重置密码
- **邮箱验证**：注册和修改邮箱时需验证，确保邮箱有效性
- **个人中心**：展示用户基本信息、购买资格、订单历史、收藏夹等
- **收货地址管理**：支持添加、编辑、删除收货地址，设置默认地址
- **密码修改**：定期提醒用户修改密码，支持密码强度检测
- **邀请系统**：生成个人邀请码，邀请新用户注册可获得购买资格奖励

#### 4.1.2 商品管理
- **商品分类管理**：支持多级分类，可设置分类图标、排序，支持分类购买限制
- **品牌管理**：支持品牌创建、编辑、删除，可设置品牌Logo、描述、排序
- **商品信息管理**：支持商品名称、描述、价格、库存、图片等基本信息管理
- **自定义字段**：支持为商品添加自定义字段，如颜色、尺寸、材质等属性
- **商品价格设置**：支持设置基础价格、促销价格、会员价格等
- **购买资格设置**：设置商品是否需要购买资格才能购买
- **购买限制设置**：
  - 商品级限制：最低/最高购买数量、重量、金额
  - 分类级限制：最低/最高购买数量、重量、金额
- **商品多分类归属**：支持一个商品属于多个分类
- **商品品牌关联**：支持为商品关联品牌
- **库存管理**：实时库存监控，库存预警，支持供货商独立管理库存

#### 4.1.3 订单管理
- **购物车功能**：支持添加/删除商品，调整数量，查看总价，保存购物车状态
- **订单创建与支付**：支持多种支付方式，订单创建后自动扣除购买资格
- **订单状态跟踪**：订单状态实时更新，包括待支付、待确认、待发货、已发货、已完成、已退款等
- **订单导出**：支持导出订单为Excel、CSV等格式
- **订单确认与发货**：供货商可确认订单，上传发货照片、快递单照片和报关清单
- **物流信息管理**：支持添加快递单号，实时跟踪物流状态
- **订单退款**：
  - 未发货订单可申请退款
  - 已发货订单不允许退款
  - 退款时扣除管理员设置的通道费率
  - 退款状态跟踪与管理

#### 4.1.4 供货商管理
- **供货商注册与授权**：管理员添加和授权供货商，设置供货商权限
- **商品授权管理**：管理员授权特定分类或商品给供货商管理
- **库存管理**：供货商可独立管理授权商品的库存数量，实时更新
- **订单处理**：供货商可查看分配给自己的订单，确认订单状态
- **发货管理**：供货商可上传发货照片、快递单照片和报关清单，添加快递单号
- **销售统计**：供货商可查看自己的销售数据和库存状态

#### 4.1.5 管理员功能
- **仪表盘统计**：显示用户数、商品数、订单数、营收等统计数据
- **系统设置**：
  - 网站基本信息设置
  - 验证码开关设置
  - 通道费率设置
- **SMTP 配置**：配置邮件发送服务器，用于验证码、订单通知等
- **支付通道配置**：配置多种支付方式，如支付宝、微信支付等
- **运费设置**：设置首重、续重费用，支持不同地区运费设置
- **服务费设置**：设置服务费费率，支持按订单金额比例计算
- **邀请奖励设置**：设置邀请X人赠送X个购买资格
- **抽奖系统**：创建和管理抽奖活动，设置奖品和规则
- **工单管理**：查看、分配、处理用户提交的工单

#### 4.1.6 资讯模块
- **资讯发布**：管理员可创建、编辑、删除资讯文章
- **资讯置顶**：支持设置资讯为置顶状态，置顶资讯优先显示
- **资讯排序**：支持自定义排序，置顶资讯按排序字段显示
- **资讯封面**：支持设置资讯封面图片
- **资讯摘要**：支持设置资讯摘要信息
- **发布控制**：支持设置资讯为草稿或已发布状态
- **用户端浏览**：用户可浏览已发布的资讯列表和详情

#### 4.1.7 多语言支持
- **语言切换**：支持中文、日语、英语三种语言切换
- **语言配置**：管理员可配置各语言的翻译内容
- **语言偏好**：保存用户语言偏好，下次访问自动使用

### 4.2 特色功能

#### 4.2.1 购买资格系统
- **商品购买资格设置**：设置商品是否需要购买资格，需要多少资格
- **邀请赠送资格**：邀请新用户注册可获得购买资格奖励
- **抽奖获得资格**：通过参与抽奖活动获得购买资格
- **资格管理**：用户可查看自己的购买资格数量和使用记录

#### 4.2.2 抽奖系统
- **自定义抽奖物品**：支持设置实物奖品、虚拟奖品和购买资格
- **购买权重抽奖**：根据用户购买金额计算权重，权重越高中奖概率越大
- **随机抽奖**：完全随机抽取中奖用户
- **周期抽奖**：支持设置每日、每周、每月等周期抽奖
- **报名有效期设置**：设置用户报名一次，可参与多期抽奖的有效期
- **抽奖结果公示**：自动公示抽奖结果，保证公平透明

#### 4.2.3 工单系统
- **用户提交工单**：用户可提交问题、建议、投诉等工单
- **工单分类**：支持多种工单类型，如订单问题、账户问题、商品问题等
- **管理员处理工单**：管理员可分配、处理、回复工单
- **工单状态跟踪**：实时更新工单状态，如待处理、处理中、已解决、已关闭等
- **工单历史**：用户可查看自己的工单历史和处理记录

## 5. 数据库设计

### 5.0 数据库配置

系统支持三种数据库，通过环境变量 `DB_DRIVER` 配置：

| DB_DRIVER 值 | 数据库 | 说明 |
| :--- | :--- | :--- |
| `sqlite` | SQLite | 默认，无需额外安装，文件存储在 `DB_FILEPATH` 指定路径 |
| `mysql` | MySQL | 需配置 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME` |
| `postgres` | PostgreSQL | 需配置 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME`、`DB_SSLMODE` |

**环境变量配置示例**：
```
# SQLite（默认）
DB_DRIVER=sqlite
DB_FILEPATH=sale.db

# MySQL
DB_DRIVER=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=password
DB_NAME=sale

# PostgreSQL
DB_DRIVER=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=sale
DB_SSLMODE=disable
```

### 5.1 用户表 (users)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 用户ID |
| `username` | `VARCHAR(50)` | `UNIQUE NOT NULL` | 用户名 |
| `email` | `VARCHAR(100)` | `UNIQUE NOT NULL` | 邮箱 |
| `password_hash` | `VARCHAR(255)` | `NOT NULL` | 密码哈希 |
| `role` | `VARCHAR(20)` | `NOT NULL` | 角色(user/supplier/admin) |
| `purchase_credits` | `INTEGER` | `DEFAULT 0` | 购买资格数量 |
| `invite_code` | `VARCHAR(20)` | `UNIQUE` | 邀请码 |
| `referred_by` | `INTEGER` | `REFERENCES users(id)` | 推荐人ID |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.2 商品分类表 (categories)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 分类ID |
| `name` | `VARCHAR(100)` | `NOT NULL` | 分类名称 |
| `description` | `TEXT` | | 分类描述 |
| `parent_id` | `INTEGER` | `REFERENCES categories(id)` | 父分类ID |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.3 品牌表 (brands)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 品牌ID |
| `name` | `VARCHAR(255)` | `UNIQUE NOT NULL` | 品牌名称 |
| `description` | `TEXT` | | 品牌描述 |
| `logo` | `VARCHAR(500)` | | 品牌Logo URL |
| `sort_order` | `INTEGER` | `DEFAULT 0` | 排序 |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.4 商品表 (products)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 商品ID |
| `name` | `VARCHAR(255)` | `NOT NULL` | 商品名称 |
| `description` | `TEXT` | | 商品描述 |
| `price` | `DECIMAL(10,2)` | `NOT NULL` | 商品价格 |
| `min_purchase` | `INTEGER` | `DEFAULT 1` | 最低购买数量 |
| `max_purchase` | `INTEGER` | | 最大购买数量 |
| `min_weight` | `DECIMAL(10,2)` | | 最低购买重量 |
| `max_weight` | `DECIMAL(10,2)` | | 最大购买重量 |
| `require_credit` | `BOOLEAN` | `DEFAULT FALSE` | 是否需要购买资格 |
| `credit_cost` | `INTEGER` | `DEFAULT 0` | 购买所需资格数量 |
| `credit_reward` | `INTEGER` | `DEFAULT 0` | 购买后赠送的资格数量 |
| `images` | `TEXT` | | 商品图片(JSON数组) |
| `is_active` | `BOOLEAN` | `DEFAULT TRUE` | 是否上架 |
| `brand_id` | `INTEGER` | `REFERENCES brands(id)` | 品牌ID |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.5 商品自定义字段表 (product_custom_fields)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 字段ID |
| `product_id` | `INTEGER` | `REFERENCES products(id)` | 商品ID |
| `field_name` | `VARCHAR(100)` | `NOT NULL` | 字段名称 |
| `field_value` | `TEXT` | | 字段值 |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |

### 5.6 库存表 (inventory)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 库存ID |
| `product_id` | `INTEGER` | `REFERENCES products(id)` | 商品ID |
| `supplier_id` | `INTEGER` | `REFERENCES users(id)` | 供货商ID |
| `quantity` | `INTEGER` | `DEFAULT 0` | 库存数量 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.7 购物车表 (carts)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 购物车ID |
| `user_id` | `INTEGER` | `REFERENCES users(id)` | 用户ID |
| `product_id` | `INTEGER` | `REFERENCES products(id)` | 商品ID |
| `quantity` | `INTEGER` | `NOT NULL` | 数量 |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.8 订单表 (orders)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 订单ID |
| `user_id` | `INTEGER` | `REFERENCES users(id)` | 用户ID |
| `supplier_id` | `INTEGER` | `REFERENCES users(id)` | 供货商ID |
| `subtotal` | `DECIMAL(10,2)` | `NOT NULL` | 商品小计 |
| `shipping_fee` | `DECIMAL(10,2)` | `DEFAULT 0` | 运费 |
| `service_fee` | `DECIMAL(10,2)` | `DEFAULT 0` | 服务费 |
| `tax` | `DECIMAL(10,2)` | `DEFAULT 0` | 税费 |
| `total_amount` | `DECIMAL(10,2)` | `NOT NULL` | 订单总金额 |
| `refund_amount` | `DECIMAL(10,2)` | | 退款金额 |
| `refund_status` | `VARCHAR(20)` | | 退款状态 |
| `refund_reason` | `TEXT` | | 退款原因 |
| `status` | `VARCHAR(20)` | `NOT NULL` | 订单状态 |
| `shipping_address_id` | `INTEGER` | `REFERENCES addresses(id)` | 收货地址ID |
| `tracking_number` | `VARCHAR(100)` | | 快递单号 |
| `shipping_photo` | `TEXT` | | 发货照片 |
| `express_photo` | `TEXT` | | 快递单照片 |
| `customs_photo` | `TEXT` | | 报关清单照片 |
| `payment_method` | `VARCHAR(50)` | | 支付方式 |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.9 订单商品表 (order_items)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 订单项ID |
| `order_id` | `INTEGER` | `REFERENCES orders(id)` | 订单ID |
| `product_id` | `INTEGER` | `REFERENCES products(id)` | 商品ID |
| `quantity` | `INTEGER` | `NOT NULL` | 数量 |
| `price` | `DECIMAL(10,2)` | `NOT NULL` | 单价 |

### 5.10 收货地址表 (addresses)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 地址ID |
| `user_id` | `INTEGER` | `REFERENCES users(id)` | 用户ID |
| `name` | `VARCHAR(50)` | `NOT NULL` | 收件人姓名 |
| `phone` | `VARCHAR(20)` | `NOT NULL` | 联系电话 |
| `address` | `TEXT` | `NOT NULL` | 详细地址 |
| `is_default` | `BOOLEAN` | `DEFAULT FALSE` | 是否默认地址 |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.11 抽奖表 (lotteries)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 抽奖ID |
| `name` | `VARCHAR(100)` | `NOT NULL` | 抽奖名称 |
| `description` | `TEXT` | | 抽奖描述 |
| `start_time` | `TIMESTAMP` | `NOT NULL` | 开始时间 |
| `end_time` | `TIMESTAMP` | `NOT NULL` | 结束时间 |
| `cycle` | `VARCHAR(20)` | | 周期类型 |
| `daily_quota` | `INTEGER` | | 每日限额 |
| `total_quota` | `INTEGER` | | 总限额 |
| `registration_validity` | `INTEGER` | | 报名有效期(天) |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.12 抽奖奖品表 (lottery_prizes)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 奖品ID |
| `lottery_id` | `INTEGER` | `REFERENCES lotteries(id)` | 抽奖ID |
| `name` | `VARCHAR(100)` | `NOT NULL` | 奖品名称 |
| `type` | `VARCHAR(20)` | `NOT NULL` | 奖品类型 |
| `quantity` | `INTEGER` | `NOT NULL` | 奖品数量 |
| `weight` | `INTEGER` | `DEFAULT 1` | 权重 |
| `credit_reward` | `INTEGER` | | 赠送资格数量 |

### 5.13 抽奖参与表 (lottery_participants)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 参与ID |
| `lottery_id` | `INTEGER` | `REFERENCES lotteries(id)` | 抽奖ID |
| `user_id` | `INTEGER` | `REFERENCES users(id)` | 用户ID |
| `purchase_weight` | `INTEGER` | `DEFAULT 0` | 购买权重 |
| `registered_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 报名时间 |

### 5.14 工单表 (tickets)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 工单ID |
| `user_id` | `INTEGER` | `REFERENCES users(id)` | 用户ID |
| `title` | `VARCHAR(200)` | `NOT NULL` | 工单标题 |
| `content` | `TEXT` | `NOT NULL` | 工单内容 |
| `status` | `VARCHAR(20)` | `NOT NULL` | 工单状态 |
| `assigned_to` | `INTEGER` | `REFERENCES users(id)` | 处理人ID |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.15 系统设置表 (system_settings)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 设置ID |
| `key` | `VARCHAR(100)` | `UNIQUE NOT NULL` | 设置键 |
| `value` | `TEXT` | | 设置值 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

### 5.16 供应商授权表 (supplier_authorizations)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 授权ID |
| `supplier_id` | `INTEGER` | `NOT NULL` | 供货商ID |
| `type` | `VARCHAR(20)` | `NOT NULL` | 授权类型(category/product) |
| `ref_id` | `INTEGER` | `NOT NULL` | 关联ID |

### 5.17 资讯表 (articles)

| 字段名 | 数据类型 | 约束 | 描述 |
| :--- | :--- | :--- | :--- |
| `id` | `SERIAL` | `PRIMARY KEY` | 资讯ID |
| `title` | `VARCHAR(255)` | `NOT NULL` | 标题 |
| `content` | `TEXT` | `NOT NULL` | 内容 |
| `summary` | `VARCHAR(500)` | | 摘要 |
| `cover_image` | `VARCHAR(500)` | | 封面图URL |
| `is_pinned` | `BOOLEAN` | `DEFAULT FALSE` | 是否置顶 |
| `is_published` | `BOOLEAN` | `DEFAULT TRUE` | 是否发布 |
| `sort_order` | `INTEGER` | `DEFAULT 0` | 排序 |
| `author_id` | `INTEGER` | `REFERENCES users(id)` | 作者ID |
| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 |
| `updated_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | 更新时间 |

## 6. API 接口设计

### 6.1 用户相关接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/auth/register` | `POST` | 认证 | 用户注册 |
| `/api/auth/login` | `POST` | 认证 | 用户登录 |
| `/api/auth/forgot-password` | `POST` | 认证 | 忘记密码 |
| `/api/auth/reset-password` | `POST` | 认证 | 重置密码 |
| `/api/auth/verify-email` | `GET` | 认证 | 邮箱验证 |
| `/api/users/profile` | `GET` | 用户 | 获取个人资料 |
| `/api/users/profile` | `PUT` | 用户 | 更新个人资料 |
| `/api/users/password` | `PUT` | 用户 | 修改密码 |
| `/api/users/addresses` | `GET` | 用户 | 获取收货地址列表 |
| `/api/users/addresses` | `POST` | 用户 | 添加收货地址 |
| `/api/users/addresses/:id` | `PUT` | 用户 | 更新收货地址 |
| `/api/users/addresses/:id` | `DELETE` | 用户 | 删除收货地址 |
| `/api/users/addresses/:id/default` | `PUT` | 用户 | 设置默认地址 |

### 6.2 商品相关接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/products` | `GET` | 商品 | 获取商品列表 |
| `/api/products/:id` | `GET` | 商品 | 获取商品详情 |
| `/api/admin/products` | `GET` | 商品 | 获取商品列表(管理员) |
| `/api/admin/products` | `POST` | 商品 | 创建商品 |
| `/api/admin/products/:id` | `PUT` | 商品 | 更新商品 |
| `/api/admin/products/:id` | `DELETE` | 商品 | 删除商品 |
| `/api/admin/products/:id/custom-fields` | `POST` | 商品 | 添加自定义字段 |
| `/api/categories` | `GET` | 分类 | 获取分类列表 |
| `/api/admin/categories` | `POST` | 分类 | 创建分类 |
| `/api/admin/categories/:id` | `PUT` | 分类 | 更新分类 |
| `/api/admin/categories/:id` | `DELETE` | 分类 | 删除分类 |
| `/api/brands` | `GET` | 品牌 | 获取品牌列表 |
| `/api/admin/brands` | `GET` | 品牌 | 获取品牌列表(管理员) |
| `/api/admin/brands` | `POST` | 品牌 | 创建品牌 |
| `/api/admin/brands/:id` | `PUT` | 品牌 | 更新品牌 |
| `/api/admin/brands/:id` | `DELETE` | 品牌 | 删除品牌 |

### 6.3 购物车与订单接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/cart` | `GET` | 购物车 | 获取购物车内容 |
| `/api/cart` | `POST` | 购物车 | 添加商品到购物车 |
| `/api/cart/:id` | `PUT` | 购物车 | 更新购物车商品数量 |
| `/api/cart/:id` | `DELETE` | 购物车 | 删除购物车商品 |
| `/api/orders` | `GET` | 订单 | 获取用户订单列表 |
| `/api/orders/:id` | `GET` | 订单 | 获取订单详情 |
| `/api/orders` | `POST` | 订单 | 创建订单 |
| `/api/supplier/orders` | `GET` | 订单 | 获取供货商订单列表 |
| `/api/supplier/orders/:id/confirm` | `PUT` | 订单 | 确认订单 |
| `/api/supplier/orders/:id/ship` | `PUT` | 订单 | 确认发货 |
| `/api/admin/orders` | `GET` | 订单 | 获取所有订单 |
| `/api/admin/orders/export` | `GET` | 订单 | 导出订单表格 |

### 6.4 库存管理接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/supplier/inventory` | `GET` | 库存 | 获取供货商库存列表 |
| `/api/supplier/inventory/:id` | `PUT` | 库存 | 更新库存数量 |
| `/api/admin/inventory` | `GET` | 库存 | 获取所有库存 |

### 6.5 供货商管理接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/admin/suppliers` | `GET` | 供货商 | 获取供货商列表 |
| `/api/admin/suppliers` | `POST` | 供货商 | 添加供货商 |
| `/api/admin/suppliers/:id` | `PUT` | 供货商 | 更新供货商信息 |
| `/api/admin/suppliers/:id` | `DELETE` | 供货商 | 删除供货商 |
| `/api/admin/suppliers/:id/authorize` | `POST` | 供货商 | 授权商品/分类 |

### 6.6 抽奖系统接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/lotteries` | `GET` | 抽奖 | 获取抽奖列表 |
| `/api/lotteries/:id` | `GET` | 抽奖 | 获取抽奖详情 |
| `/api/lotteries/:id/register` | `POST` | 抽奖 | 报名抽奖 |
| `/api/admin/lotteries` | `POST` | 抽奖 | 创建抽奖 |
| `/api/admin/lotteries/:id` | `PUT` | 抽奖 | 更新抽奖 |
| `/api/admin/lotteries/:id` | `DELETE` | 抽奖 | 删除抽奖 |
| `/api/admin/lotteries/:id/prizes` | `POST` | 抽奖 | 添加奖品 |
| `/api/admin/lotteries/:id/draw` | `POST` | 抽奖 | 执行抽奖 |

### 6.7 工单系统接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/tickets` | `GET` | 工单 | 获取用户工单列表 |
| `/api/tickets` | `POST` | 工单 | 提交工单 |
| `/api/tickets/:id` | `GET` | 工单 | 获取工单详情 |
| `/api/admin/tickets` | `GET` | 工单 | 获取所有工单 |
| `/api/admin/tickets/:id` | `PUT` | 工单 | 更新工单状态 |
| `/api/admin/tickets/:id/assign` | `PUT` | 工单 | 分配工单 |

### 6.8 系统设置接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/settings/public` | `GET` | 设置 | 获取公共设置(费用费率等) |
| `/api/admin/stats` | `GET` | 统计 | 获取仪表盘统计数据 |
| `/api/admin/settings` | `GET` | 设置 | 获取系统设置 |
| `/api/admin/settings` | `PUT` | 设置 | 更新系统设置 |
| `/api/admin/settings/smtp` | `PUT` | 设置 | 更新SMTP设置 |
| `/api/admin/settings/payment` | `PUT` | 设置 | 更新支付通道设置 |

### 6.9 资讯模块接口

| API 路径 | 方法 | 模块 | 功能描述 |
| :--- | :--- | :--- | :--- |
| `/api/articles` | `GET` | 资讯 | 获取已发布资讯列表 |
| `/api/articles/:id` | `GET` | 资讯 | 获取资讯详情 |
| `/api/admin/articles` | `GET` | 资讯 | 获取所有资讯（含草稿） |
| `/api/admin/articles` | `POST` | 资讯 | 创建资讯 |
| `/api/admin/articles/:id` | `PUT` | 资讯 | 更新资讯 |
| `/api/admin/articles/:id` | `DELETE` | 资讯 | 删除资讯 |
| `/api/admin/articles/:id/pin` | `PUT` | 资讯 | 切换置顶状态 |

## 7. 前端设计

### 7.1 设计风格

#### 方案一：现代化科技感（推荐）
- **风格特点**：采用简洁、现代的设计风格，类似于科技企业网站
- **配色方案**：以蓝色为主色调，搭配白色和浅灰色，营造专业、科技的氛围
- **字体**：使用无衬线字体，如 Roboto、Inter 等
- **布局**：响应式设计，适配不同设备屏幕
- **动画效果**：适度的过渡动画，提升用户体验
- **特色**：简洁明了的界面，突出商品信息，操作流程顺畅

#### 方案二：简约商务风
- **风格特点**：简约、专业的商务风格，注重信息的清晰展示
- **配色方案**：以灰色为主色调，搭配深蓝和白色，营造稳重、专业的氛围
- **字体**：使用无衬线字体，如 Helvetica、Arial 等
- **布局**：网格布局，信息层次分明
- **动画效果**：轻微的过渡效果，保持界面稳定感
- **特色**：信息密度高，适合商务用户，操作流程清晰

#### 方案三：时尚活力风
- **风格特点**：时尚、活力的设计风格，吸引年轻用户群体
- **配色方案**：以橙色和白色为主色调，搭配浅蓝和浅灰，营造活力、时尚的氛围
- **字体**：使用现代无衬线字体，如 Poppins、Montserrat 等
- **布局**：卡片式布局，视觉层次丰富
- **动画效果**：活泼的微动画，增强用户互动
- **特色**：视觉冲击力强，适合时尚商品，用户体验愉悦

#### 方案四：豆包飞书风（暗色毛玻璃）
- **风格特点**：暗色主题、毛玻璃效果、大字排版，类似豆包/飞书演示风格
- **配色方案**：以深蓝紫渐变为主色调（#1a1a2e → #16213e → #0f3460），搭配半透明白色毛玻璃卡片，强调色为亮紫/亮蓝
- **字体**：使用现代无衬线字体，如 Inter、SF Pro Display 等，标题大号加粗
- **布局**：全屏渐变背景 + 毛玻璃卡片悬浮布局，Hero区域大字标题居中
- **动画效果**：渐变背景微动、卡片悬浮阴影变化、淡入淡出过渡
- **特色**：
  - 深色渐变背景营造沉浸感
  - 毛玻璃（backdrop-filter: blur）卡片效果
  - 大字标题 + 简洁描述的Hero布局
  - 圆角卡片 + 微光边框
  - 适合高端产品展示，科技感与品质感并存

### 7.2 页面结构

#### 7.2.1 用户前端
- **首页**：商品展示、分类导航、抽奖活动
- **商品列表页**：筛选、排序、分页
- **商品详情页**：商品信息、自定义字段、购买选项
- **购物车页**：商品列表、数量调整、结算
- **订单确认页**：收货地址选择、支付方式选择
- **个人中心**：订单管理、收货地址、账户设置、购买资格
- **抽奖页面**：抽奖活动列表、报名入口
- **工单页面**：工单提交、工单列表
- **资讯页面**：资讯列表、资讯详情

#### 7.2.2 管理员后台
- **仪表盘**：系统概览、统计数据（用户数、商品数、订单数、营收）
- **用户管理**：用户列表、权限管理
- **商品管理**：商品列表、分类管理、品牌管理、库存管理
- **订单管理**：订单列表、订单详情、导出功能、退款管理
- **供货商管理**：供货商列表、授权管理
- **抽奖管理**：抽奖活动创建、奖品管理、抽奖执行
- **工单管理**：工单列表、工单处理
- **系统设置**：SMTP设置、支付通道设置、运费设置、服务费设置、税费设置、通道费率设置
- **资讯管理**：资讯发布、编辑、删除、置顶

#### 7.2.3 供货商后台
- **仪表盘**：订单统计、库存概览
- **订单管理**：订单列表、订单确认、发货管理
- **库存管理**：库存列表、库存更新
- **商品管理**：授权商品列表

### 7.3 多语言支持
- 使用 Vue i18n 实现多语言切换
- 支持中文、日语、英语三种语言
- 语言文件采用 JSON 格式存储
- 实现语言切换功能，保存用户语言偏好

## 8. 安全考虑

### 8.1 前端安全
- 使用 HTTPS 协议
- 实现 CSRF 保护
- 输入验证和 sanitization
- 密码强度检查
- 防止 XSS 攻击

### 8.2 后端安全
- 密码哈希存储
- JWT 认证机制
- 权限控制
- 防止 SQL 注入
- 速率限制
- 日志记录

### 8.3 数据安全
- 数据库加密
- 敏感数据保护
- 定期数据备份

## 9. 部署方案

### 9.1 开发环境
- **前端**：Vite 开发服务器
- **后端**：Go 本地开发服务器
- **数据库**：PostgreSQL 本地实例
- **缓存**：Redis 本地实例

### 9.2 生产环境
- **前端**：Nginx 静态文件服务
- **后端**：Go 应用服务器
- **数据库**：PostgreSQL 数据库集群
- **缓存**：Redis 集群
- **负载均衡**：Nginx 或云服务负载均衡
- **容器化**：Docker + Kubernetes

## 10. 项目结构

### 10.1 前端项目结构

```
frontend/
├── public/              # 静态资源
├── src/
│   ├── assets/          # 图片、样式等
│   ├── components/      # 通用组件
│   ├── views/           # 页面组件
│   │   ├── user/        # 用户前端页面
│   │   ├── admin/       # 管理员后台页面
│   │   └── supplier/    # 供货商后台页面
│   ├── router/          # 路由配置
│   ├── store/           # Pinia 状态管理
│   ├── i18n/            # 国际化文件
│   ├── api/             # API 调用
│   ├── utils/           # 工具函数
│   ├── App.vue          # 根组件
│   └── main.ts          # 入口文件
├── .env                 # 环境变量
├── vite.config.ts       # Vite 配置
└── package.json         # 依赖管理
```

### 10.2 后端项目结构

```
backend/
├── cmd/
│   └── server/          # 应用入口
├── internal/
│   ├── api/             # API 处理
│   │   ├── handlers/    # 请求处理器
│   │   ├── middlewares/ # 中间件
│   │   └── routes/      # 路由配置
│   ├── services/        # 业务逻辑
│   ├── models/          # 数据模型
│   ├── schemas/         # 数据校验
│   ├── utils/           # 工具函数
│   └── config/          # 配置管理
├── migrations/          # 数据库迁移
├── go.mod               # Go 模块文件
└── .env                 # 环境变量
```

## 11. 开发计划

### 11.1 阶段一：基础架构搭建
- 前端项目初始化
- 后端项目初始化
- 数据库设计与迁移
- 基础 API 实现

### 11.2 阶段二：核心功能实现
- 用户认证系统
- 商品管理系统
- 购物车与订单系统
- 库存管理系统

### 11.3 阶段三：特色功能实现
- 购买资格系统
- 抽奖系统
- 工单系统
- 多语言支持

### 11.4 阶段四：后台管理
- 管理员后台
- 供货商后台
- 系统设置

### 11.5 阶段五：测试与部署
- 功能测试
- 性能测试
- 安全测试
- 生产环境部署

## 12. 技术挑战与解决方案

### 12.1 多语言支持
- **挑战**：确保所有界面元素和数据都能正确翻译
- **解决方案**：使用 Vue i18n 管理翻译文件，实现语言切换功能

### 12.2 购买资格系统
- **挑战**：实现复杂的购买资格逻辑
- **解决方案**：设计专门的资格管理模块，记录和验证用户购买资格

### 12.3 抽奖系统
- **挑战**：实现公平、透明的抽奖机制
- **解决方案**：使用随机数生成器，结合购买权重计算中奖概率

### 12.4 订单处理流程
- **挑战**：协调用户、供货商和管理员的订单处理流程
- **解决方案**：设计清晰的订单状态流转，实现自动化通知

### 12.5 性能优化
- **挑战**：确保系统在高并发情况下的性能
- **解决方案**：使用 Redis 缓存热点数据，优化数据库查询

## 13. 总结

本技术文档详细描述了商品售卖网站的设计与实现方案，包括系统架构、功能模块、数据库设计、API 接口、前端设计等方面。通过采用现代化的技术栈和合理的架构设计，系统能够满足用户的各种需求，提供良好的用户体验。

项目将按照开发计划分阶段实施，确保系统的质量和稳定性。同时，系统设计考虑了未来的扩展性，为后续功能的添加和优化预留了空间。