# python_demo

**Repository Path**: lijunlin23/python_demo

## Basic Information

- **Project Name**: python_demo
- **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-08-21
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python Demo - FastAPI 分层架构项目

基于 **FastAPI + SQLAlchemy 2.0 + MySQL** 的完整分层示例：
- 用户管理 CRUD（新增/详情/修改/删除/分页/登录/统计）
- 订单管理 CRUD（下单/详情/修改/取消/支付/发货/收货/分页/统计）
- 管理后台仪表盘（带简易 Token 鉴权）

## 目录结构

```
python_demo/
├── app/
│   ├── __init__.py
│   ├── database.py              # 数据库连接配置（Engine/Session/Base/get_db/init_db）
│   ├── models/                  # ORM 模型层
│   │   ├── __init__.py
│   │   ├── base.py             # 基础模型 BaseModel（公共字段 + 软删）
│   │   ├── user.py             # 用户模型 → t_user
│   │   ├── order.py            # 订单模型 → biz_order
│   │   └── order_item.py       # 订单项模型 → biz_order_item
│   ├── schemas/                 # Pydantic 数据模型（请求/响应结构）
│   │   ├── __init__.py
│   │   ├── common.py           # 统一响应/分页/批量ID
│   │   ├── user.py             # 用户 Schema
│   │   └── order.py            # 订单 Schema
│   ├── repositories/            # 数据访问层 DAO
│   │   ├── __init__.py
│   │   ├── user_repository.py
│   │   └── order_repository.py
│   ├── services/                # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── user_service.py     # 密码哈希、唯一性判断、状态流转
│   │   └── order_service.py    # 订单号生成、金额计算、状态机
│   └── routers/                 # 路由层 / API
│       ├── __init__.py
│       ├── users.py            # /api/users
│       ├── orders.py           # /api/orders
│       ├── admin.py            # /api/admin （X-Admin-Token 鉴权）
│       └── redis_examples.py   # /api/redis（14 个业务场景实例）
│   ├── core/                    # Redis + 基础设施层
│   │   ├── config.py           # 全局配置（Redis/MySQL 参数）
│   │   ├── database.py         # 数据库连接（已移至此）
│   │   └── redis_ops.py        # Redis 操作工具类
├── main.py                      # FastAPI 入口
├── requirements.txt             # 依赖
├── README.md
```

## 分层调用关系

```
HTTP 请求
  ↓
routers (FastAPI APIRouter) — 参数解析、Depends(get_db)、调用Service
  ↓
services (业务逻辑层) — 业务规则判断、组合多个Repository
  ↓
repositories (DAO层) — 纯SQLAlchemy查询，无业务
  ↓
models (ORM层) — BaseModel/Base.metadata
  ↓
database (Engine/Session) → MySQL
```

## 启动步骤

### 1. 准备 MySQL

用户指定配置：
```
host:     localhost:3306
user:     root
password: root1234
database: ys-faery-lake
```

请先手动创建数据库：
```sql
CREATE DATABASE IF NOT EXISTS `ys-faery-lake` DEFAULT CHARSET utf8mb4;
```

### 2. 配置环境变量（可选，不配置用默认值即可连通）

复制 .env.example 为 .env 即可（数据库信息默认 root/root1234@ys-faery-lake）

### 3. 安装依赖

```bash
cd /Users/lynn/PycharmProjects/python_demo
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 4. 启动服务

```bash
python main.py
# 或
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### 5. 访问

- 首页:         http://localhost:8000/
- Swagger UI:   http://localhost:8000/docs   ← 直接在浏览器调接口
- Redoc:        http://localhost:8000/redoc
- 健康检查:     http://localhost:8000/health

启动时 `init_db()` 会自动执行 `CREATE TABLE IF NOT EXISTS`：
- t_user          (用户表)
- biz_order       (订单表)
- biz_order_item  (订单项表)

## 接口速查

### 用户模块 /api/users
| Method | Path                      | 说明 |
| :----- | :------------------------ | :--- |
| POST   | /api/users                | 新增用户 |
| GET    | /api/users/{id}           | 详情 |
| PUT    | /api/users/{id}           | 修改 |
| DELETE | /api/users/{id}           | 软删除 |
| POST   | /api/users/batch-delete   | 批量删除 |
| GET    | /api/users                | 分页列表（支持 user_name/status/sex...） |
| POST   | /api/users/login          | 登录：{user_name, password} |
| GET    | /api/users/statistics/summary | 用户统计（总/启用/停用） |

### 订单模块 /api/orders
| Method | Path                              | 说明 |
| :----- | :-------------------------------- | :--- |
| POST   | /api/orders                       | 下单 |
| GET    | /api/orders/{id}                  | 详情（含订单项） |
| PUT    | /api/orders/{id}                  | 修改收货信息/备注 |
| POST   | /api/orders/{id}/cancel           | 取消订单（待付款/待发货） |
| POST   | /api/orders/{id}/pay              | 模拟支付成功 |
| POST   | /api/orders/{id}/ship             | 发货 |
| POST   | /api/orders/{id}/complete         | 确认收货 |
| DELETE | /api/orders/{id}                  | 软删除 |
| GET    | /api/orders                       | 分页列表 |
| GET    | /api/orders/statistics/summary    | 订单统计 |
| GET    | /api/orders/statistics/user/{uid}/status-count | 用户各状态订单数（徽标） |

### 管理后台 /api/admin
请求 Header 带 `X-Admin-Token: admin-token-123`

| Method | Path                          | 说明 |
| :----- | :---------------------------- | :--- |
| GET    | /api/admin/dashboard          | 仪表盘：用户统计 + 订单统计 |
| GET    | /api/admin/users/statistics   | 用户统计 |
| GET    | /api/admin/orders/statistics  | 订单统计 |

## 订单状态流转

```
0待付款 ──(支付)──→ 1已付款待发货 ──(发货)──→ 2已发货 ──(收货)──→ 3已完成
  │                   │
  └──(取消)──→ 4已取消 ┘
```