# backend2

**Repository Path**: Sakura_236/backend2

## Basic Information

- **Project Name**: backend2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flask-Shop 后端重构版（backend2）

## 概述
本目录是在不改动原 backend 的前提下，对现有后端代码进行结构化重构的版本。功能与原逻辑保持一致，按常见工程分层拆分为 routes、models、services、utils 等。

## 技术栈
- Flask
- Flask-SQLAlchemy
- Flask-JWT-Extended
- Flask-Cors
- python-alipay-sdk
- pandas / scikit-surprise

## 目录结构
```
backend2/
  app.py
  config.py
  alipay_config.py
  extensions/
    __init__.py
  models/
    __init__.py
  routes/
    __init__.py
    auth.py
    seller.py
    products.py
    categories.py
    orders.py
    users.py
    favorites.py
    likes.py
    comments.py
    upload.py
    pay.py
    recommend.py
  services/
    recommend_service.py
  utils/
    auth.py
    order.py
    upload.py
```

## 环境变量
- DATABASE_URL
- JWT_SECRET_KEY

## 启动方式
在 backend2 目录执行：
```
python app.py
```

## Swagger (Flasgger)
安装依赖：
```
pip install flasgger
```
启动服务后访问：
- http://localhost:5000/apidocs/

## API 文档（常见写法）

### 1) 基础信息
- Base URL: `http://localhost:5000`
- Content-Type: `application/json`（上传接口除外）
- 鉴权：需要登录的接口请在请求头添加 `Authorization: Bearer <token>`

### 2) 通用响应约定
本项目没有统一包装响应结构，以下为实际返回情况：
- 成功：一般返回业务 JSON 或列表
- 失败：返回 `{ "message": "..." }` 或 `{ "error": "..." }`

### 3) 状态码说明
- 200/201：成功
- 400：参数错误或业务校验不通过
- 401：未登录或身份无效
- 403：权限不足
- 404：资源不存在
- 500：服务器异常

### 4) 分页约定
- 收藏列表：`page`、`per_page`
- 点赞列表：`page`、`per_page`
- 地址列表：`page`、`page_size`

## 接口目录（总览）

### 认证与登录
- POST /api/auth/register
- POST /api/auth/login
- POST /api/seller/login

### 商品
- GET /api/products
- GET /api/products/{product_id}
- POST /api/seller/products
- GET /api/seller/products
- PUT /api/seller/products/{product_id}
- DELETE /api/seller/products/{product_id}

### 商品分类
- GET /api/categories
- POST /api/categories
- PUT /api/categories/{category_id}
- DELETE /api/categories/{category_id}

### 订单
- GET /api/orders
- POST /api/orders
- GET /api/orders/{order_id}
- DELETE /api/orders/{order_id}
- PUT /api/orders/{order_id}/ship
- POST /api/orders/{order_id}/confirm
- POST /api/orders/{order_id}/refund
- POST /api/orders/{order_id}/refund/approve
- POST /api/orders/{order_id}/refund/reject

### 用户与地址
- GET /api/users
- PUT /api/users/{user_id}
- DELETE /api/users/{user_id}
- GET /api/user/profile
- GET /api/user/addresses
- POST /api/user/addresses
- PUT /api/user/addresses/{address_id}
- DELETE /api/user/addresses/{address_id}

### 收藏
- POST /api/favorites
- GET /api/favorites
- DELETE /api/favorites/{product_id}
- GET /api/favorites/check

### 点赞
- POST /api/products/{product_id}/like
- DELETE /api/products/{product_id}/like
- GET /api/products/{product_id}/like/status
- GET /api/user/likes

### 评论
- GET /api/products/{product_id}/comments
- POST /api/products/{product_id}/comments

### 支付（支付宝）
- POST /api/pay/recharge
- POST /api/pay/check_recharge

### 上传
- POST /api/upload/image

### 推荐
- GET /api/recommend/{user_id}

### 静态资源
- GET /static/uploads/{path}

## 接口细节

### 认证与登录

#### POST /api/auth/register
请求体：
```json
{
  "username": "string",
  "email": "string",
  "password": "string",
  "gender": "string",
  "phone": "string",
  "avatar": "string"
}
```
成功响应：
```json
{
  "message": "用户注册成功"
}
```

#### POST /api/auth/login
请求体：
```json
{
  "username": "string",
  "password": "string"
}
```
成功响应：
```json
{
  "access_token": "jwt",
  "username": "string",
  "role": "user",
  "avatar": "string",
  "id": 1
}
```

#### POST /api/seller/login
请求体：
```json
{
  "username": "string",
  "password": "string"
}
```
成功响应同登录。

### 商品

#### GET /api/products
响应：商品列表数组。

#### GET /api/products/{product_id}
响应字段：
```json
{
  "id": 1,
  "name": "string",
  "price": 9.9,
  "stock": 10,
  "category_id": 1,
  "description": "string",
  "image_url": "string",
  "target": "string",
  "flower_language": null,
  "scene": null,
  "like_count": 0
}
```

#### POST /api/seller/products
请求体：
```json
{
  "name": "string",
  "price": 9.9,
  "stock": 10,
  "category_id": 1,
  "description": "string",
  "image_url": "string",
  "target": "string"
}
```
成功响应：
```json
{
  "message": "商品添加成功",
  "product_id": 1
}
```

#### PUT /api/seller/products/{product_id}
请求体：与新增相同，字段可选。

#### DELETE /api/seller/products/{product_id}
有订单关联时返回 400。

### 商品分类

#### GET /api/categories
响应数组：`id`、`name`、`parent_id`。

#### POST /api/categories
请求体：
```json
{ "name": "string" }
```
同名分类存在时直接返回已存在分类。

#### PUT /api/categories/{category_id}
请求体：`name`。
如果分类下有商品，无法编辑。

#### DELETE /api/categories/{category_id}
如果分类下有商品，无法删除。

### 订单

#### 订单状态
可能状态值：`已支付`、`已发货`、`已完成`、`已退款`、`退款审核中`、`退款被拒绝`、`待支付`。

#### POST /api/orders
请求体：
```json
{
  "items": [
    { "product_id": 1, "quantity": 2 }
  ],
  "receiver": "string",
  "receiver_phone": "string",
  "receiver_address": "string",
  "remark": "string"
}
```
成功响应：
```json
{ "success": true, "message": "Order created", "order_id": 1 }
```

#### GET /api/orders
返回订单数组，包含 `items` 明细。

#### GET /api/orders/{order_id}
返回单个订单详情。

#### PUT /api/orders/{order_id}/ship
仅 `已支付` 可发货。

#### POST /api/orders/{order_id}/confirm
仅 `已发货` 或 `退款被拒绝` 可确认。

#### POST /api/orders/{order_id}/refund
- `已支付`：直接退款并退余额
- `已发货`/`退款被拒绝`/`已完成`：进入退款审核

#### POST /api/orders/{order_id}/refund/approve
需要卖家或管理员。

#### POST /api/orders/{order_id}/refund/reject
需要卖家或管理员。

### 用户与地址

#### GET /api/users
可选查询参数：`search`（用户名或邮箱模糊匹配）。

#### PUT /api/users/{user_id}
请求体字段可选：`username`、`email`、`gender`、`phone`、`avatar`、`balance`、`password`。

#### GET /api/user/profile
返回当前登录用户基本信息。

#### GET /api/user/addresses
查询参数：`page`、`page_size`。

#### POST /api/user/addresses
请求体：
```json
{ "realname": "string", "phone": "string", "address": "string" }
```

#### PUT /api/user/addresses/{address_id}
请求体字段可选：`realname`、`phone`、`address`。

### 收藏

#### POST /api/favorites
请求体：
```json
{ "product_id": 1 }
```

#### GET /api/favorites
查询参数：`page`、`per_page`。

#### GET /api/favorites/check
查询参数：`product_id`。

### 点赞

#### POST /api/products/{product_id}/like
成功响应含 `like_count`。

#### GET /api/products/{product_id}/like/status
未登录返回 `liked=false`。

#### GET /api/user/likes
查询参数：`page`、`per_page`。

### 评论

#### GET /api/products/{product_id}/comments
返回评论数组：`id`、`username`、`avatar`、`content`、`created_at`。

#### POST /api/products/{product_id}/comments
请求体：
```json
{ "content": "string" }
```

### 支付（支付宝）

#### POST /api/pay/recharge
请求体：
```json
{ "amount": 100 }
```
响应：
```json
{ "pay_url": "string" }
```

#### POST /api/pay/check_recharge
请求体：
```json
{ "out_trade_no": "string" }
```
成功响应：
```json
{ "message": "充值成功", "new_balance": 100 }
```

### 上传

#### POST /api/upload/image
`multipart/form-data`：
- file: 文件
- type: 可选，`avatar` 或 `product`，默认 `common`
响应：
```json
{ "url": "/static/uploads/products/xxx.png" }
```

### 推荐

#### GET /api/recommend/{user_id}
响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "product_id": 1,
      "name": "string",
      "price": 9.9,
      "image_url": "string",
      "reason": "string",
      "type": "cf"
    }
  ]
}
```