aiotagro/aijianhua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新项目文档，完善需求和技术细节

Browse Source
This commit is contained in:
ylweng
2025-09-01 03:40:59 +08:00
parent 40460f78d2
commit 08a2e0c037
14 changed files with 1432 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
docs/API接口文档.md
View File

@@ -9,6 +9,46 @@
- **Base URL**: `http://localhost:3200/api/v1`
- **认证方式**: Bearer Token (JWT)
- **响应格式**: JSON
- **字符编码**: UTF-8
## 通用响应格式
### 成功响应
```json
{
"code": 200,
"message": "操作成功",
"data": {}
}
```
### 错误响应
```json
{
"code": 400,
"message": "参数错误",
"error": "详细错误信息"
}
```
## 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 500 | 服务器内部错误 |
| 1001 | 识别失败 |
| 1002 | 图片格式不支持 |
| 2001 | 推广奖励不足 |
| 2002 | 提现频率限制 |
| 3001 | 库存不足 |
| 3002 | 订单状态异常 |
## 认证接口
@@ -189,9 +229,337 @@ Authorization: Bearer <token>
]
```
## 购物车接口
### 1. 获取购物车
**GET** `/cart`
**请求头**:
```
Authorization: Bearer <token>
```
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 1,
"product_id": 1,
"product_name": "玫瑰花束",
"product_image": "/uploads/products/rose_bouquet.jpg",
"price": 29.9,
"quantity": 2,
"subtotal": 59.8,
"stock": 100
}
],
"total_amount": 59.8,
"total_quantity": 2
}
}
```
### 2. 添加商品到购物车
**POST** `/cart/items`
**请求头**:
```
Authorization: Bearer <token>
```
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| product_id | integer | 是 | 商品ID | 1 |
| quantity | integer | 是 | 数量 | 2 |
**响应示例**:
```json
{
"code": 200,
"message": "添加成功",
"data": {
"cart_item_id": 1
}
}
```
### 3. 更新购物车商品数量
**PUT** `/cart/items/{id}`
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| id | integer | 购物车项ID | 1 |
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| quantity | integer | 是 | 数量 | 3 |
**响应示例**:
```json
{
"code": 200,
"message": "更新成功"
}
```
### 4. 删除购物车商品
**DELETE** `/cart/items/{id}`
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| id | integer | 购物车项ID | 1 |
**响应示例**:
```json
{
"code": 200,
"message": "删除成功"
}
```
## 收货地址接口
### 1. 获取收货地址列表
**GET** `/addresses`
**请求头**:
```
Authorization: Bearer <token>
```
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": [
{
"id": 1,
"recipient": "张三",
"phone": "13800138000",
"province": "北京市",
"city": "北京市",
"district": "海淀区",
"detail": "中关村大街1号",
"is_default": true,
"created_at": "2023-01-01T00:00:00Z"
}
]
}
```
### 2. 添加收货地址
**POST** `/addresses`
**请求头**:
```
Authorization: Bearer <token>
```
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| recipient | string | 是 | 收货人 | "张三" |
| phone | string | 是 | 手机号 | "13800138000" |
| province | string | 是 | 省份 | "北京市" |
| city | string | 是 | 城市 | "北京市" |
| district | string | 是 | 区县 | "海淀区" |
| detail | string | 是 | 详细地址 | "中关村大街1号" |
| is_default | boolean | 否 | 是否默认 | true |
**响应示例**:
```json
{
"code": 201,
"message": "添加成功",
"data": {
"address_id": 1
}
}
```
### 3. 更新收货地址
**PUT** `/addresses/{id}`
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| id | integer | 地址ID | 1 |
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| recipient | string | 否 | 收货人 | "张三" |
| phone | string | 否 | 手机号 | "13800138000" |
| province | string | 否 | 省份 | "北京市" |
| city | string | 否 | 城市 | "北京市" |
| district | string | 否 | 区县 | "海淀区" |
| detail | string | 否 | 详细地址 | "中关村大街1号" |
| is_default | boolean | 否 | 是否默认 | true |
**响应示例**:
```json
{
"code": 200,
"message": "更新成功"
}
```
### 4. 删除收货地址
**DELETE** `/addresses/{id}`
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| id | integer | 地址ID | 1 |
**响应示例**:
```json
{
"code": 200,
"message": "删除成功"
}
```
## 支付接口
### 1. 发起支付
**POST** `/pay/orders/{order_no}`
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| order_no | string | 订单编号 | "ORDER202301010001" |
**响应示例**:
```json
{
"code": 200,
"message": "支付参数生成成功",
"data": {
"payment_params": {
"timeStamp": "1672531200",
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
"package": "prepay_id=wx201410272009395522fsd8f8f8f8f8f8",
"signType": "MD5",
"paySign": "C380BEC2BFD727A4B6845133519F3AD6"
}
}
}
```
### 2. 查询支付结果
**GET** `/pay/orders/{order_no}/status`
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| order_no | string | 订单编号 | "ORDER202301010001" |
**响应示例**:
```json
{
"code": 200,
"message": "查询成功",
"data": {
"order_no": "ORDER202301010001",
"payment_status": "paid",
"paid_amount": 59.8,
"paid_at": "2023-01-01T10:05:00Z"
}
}
```
## 文件上传接口
### 1. 上传文件
**POST** `/upload`
**请求格式**: `multipart/form-data`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| file | file | 是 | 上传文件 | - |
| type | string | 否 | 文件类型 | "avatar" |
**响应示例**:
```json
{
"code": 200,
"message": "上传成功",
"data": {
"url": "/uploads/avatars/avatar_123.jpg",
"filename": "avatar_123.jpg",
"size": 102400,
"mime_type": "image/jpeg"
}
}
```
## 花卉识别接口
### 花卉识别
### 1. 花卉识别
**POST** `/identifications/identify`
@@ -228,7 +596,7 @@ Authorization: Bearer <token>
}
```
### 获取识别历史
### 2. 获取识别历史
**GET** `/identifications/history`

98
docs/数据库设计文档.md
View File

@@ -84,17 +84,88 @@
| user_id | bigint | 用户ID | 非空，索引 |
| recipient | varchar(100) | 收货人 | 非空 |
| phone | varchar(20) | 手机号 | 非空 |
| address | text | 详细地址 | 非空 |
| province | varchar(50) | 省份 | 非空 |
| city | varchar(50) | 城市 | 非空 |
| district | varchar(50) | 区县 | 非空 |
| detail | varchar(255) | 详细地址 | 非空 |
| is_default | tinyint | 是否默认 | 默认0 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.8 购物车表 (cart_items)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 购物车项ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| product_id | bigint | 商品ID | 非空，索引 |
| quantity | int | 数量 | 非空，默认1 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.9 推广奖励表 (promotions)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 推广ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| promotion_code | varchar(20) | 推广码 | 非空，唯一索引 |
| total_invites | int | 总邀请人数 | 默认0 |
| successful_orders | int | 成功订单数 | 默认0 |
| total_earnings | decimal(10,2) | 总收益 | 默认0 |
| available_balance | decimal(10,2) | 可用余额 | 默认0 |
| withdrawn_amount | decimal(10,2) | 已提现金额 | 默认0 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.10 提现记录表 (withdrawals)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 提现ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| amount | decimal(10,2) | 提现金额 | 非空 |
| payment_method | varchar(20) | 支付方式 | 非空 |
| account_info | varchar(100) | 账户信息 | 非空 |
| status | varchar(20) | 状态 | 非空，默认'pending' |
| transaction_id | varchar(50) | 交易ID | 可空 |
| completed_at | timestamp | 完成时间 | 可空 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.11 支付记录表 (payments)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 支付ID | 主键，自增 |
| order_id | bigint | 订单ID | 非空，索引 |
| payment_method | varchar(20) | 支付方式 | 非空 |
| amount | decimal(10,2) | 支付金额 | 非空 |
| transaction_id | varchar(50) | 交易ID | 可空 |
| status | varchar(20) | 支付状态 | 非空 |
| paid_at | timestamp | 支付时间 | 可空 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.12 文件上传记录表 (uploads)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 上传记录ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| original_name | varchar(255) | 原始文件名 | 非空 |
| stored_name | varchar(255) | 存储文件名 | 非空 |
| file_path | varchar(500) | 文件路径 | 非空 |
| file_size | bigint | 文件大小 | 非空 |
| mime_type | varchar(100) | MIME类型 | 非空 |
| file_type | enum | 文件类型 | 默认'image' |
| upload_type | varchar(50) | 上传类型 | 非空，索引 |
| status | enum | 状态 | 默认'active' |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
## 3. 索引设计
### 3.1 唯一索引
- users.phone: 手机号唯一索引
- users.email: 邮箱唯一索引
- users.username: 用户名唯一索引
- promotions.promotion_code: 推广码唯一索引
### 3.2 普通索引
- products.category_id: 商品分类索引
@@ -103,6 +174,16 @@
- identifications.user_id: 识别记录用户索引
- identifications.created_at: 识别时间索引
- addresses.user_id: 地址用户索引
- cart_items.user_id: 购物车用户索引
- cart_items.product_id: 购物车商品索引
- promotions.user_id: 推广用户索引
- withdrawals.user_id: 提现用户索引
- withdrawals.created_at: 提现时间索引
- payments.order_id: 支付订单索引
- payments.created_at: 支付时间索引
- uploads.user_id: 上传记录用户索引
- uploads.upload_type: 上传类型索引
- uploads.created_at: 上传时间索引
## 4. 测试数据统计
@@ -114,6 +195,11 @@
- 订单商品: 4条
- 识别记录: 3条
- 收货地址: 3条
- 购物车数据: 5条
- 推广奖励: 2条
- 提现记录: 3条
- 支付记录: 3条
- 上传记录: 0条
## 5. 数据库变更记录
@@ -122,6 +208,16 @@
- 密码字段使用password，采用bcrypt加密存储
- 增加数据库初始化脚本，包含默认管理员账号（admin/admin123）
### 2024-01-15 更新
- 地址表增加省份、城市、区县字段，拆分详细地址
- 新增购物车表，支持用户购物车功能
- 新增推广奖励表，支持用户推广功能
- 新增提现记录表，支持推广收益提现
- 新增支付记录表，完善订单支付流程
### 2024-03-20 更新
- 新增文件上传记录表，支持文件上传功能
## 5. 数据库连接信息
**生产环境**: