Initial commit: 商品售卖网站

商品售卖网站技术文档.md

@@ -0,0 +1,752 @@
+# 商品售卖网站技术文档
+
+## 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 接口、前端设计等方面。通过采用现代化的技术栈和合理的架构设计，系统能够满足用户的各种需求，提供良好的用户体验。
+
+项目将按照开发计划分阶段实施，确保系统的质量和稳定性。同时，系统设计考虑了未来的扩展性，为后续功能的添加和优化预留了空间。