# PythonMusic

**Repository Path**: qijinliangcom_admin/PythonMusic

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PythonMusic - 音乐管理系统

全栈音乐管理平台，包含 **Python 后端**、**Web 管理后台** 和 **iOS 客户端**。

---

## 项目结构

```
PythonMusic/
├── Server/                    # Python FastAPI 后端
│   ├── app/
│   │   ├── api/v1/endpoints/  # API 端点 (auth, users, singers, albums, musics, categories, tags, common, sys_logs)
│   │   ├── core/              # 核心模块 (config, security, cache, exceptions, limiter, middleware)
│   │   ├── crud/              # 数据库 CRUD 操作
│   │   ├── db/                # 数据库模型与会话
│   │   ├── models/            # SQLAlchemy ORM 模型
│   │   └── schemas/           # Pydantic 请求/响应模型
│   ├── frontend/              # React + TypeScript Web 管理后台
│   ├── main.py                # FastAPI 入口
│   ├── requirements.txt       # Python 依赖
│   └── seed_data.py           # 测试数据填充脚本
└── Client/                    # SwiftUI iOS 客户端
    └── SwiftUI-music/         # 音乐播放 App
```

---

## 技术栈

| 层级 | 技术 |
|------|------|
| **后端** | Python 3.9+, FastAPI, SQLAlchemy 2.0, Pydantic v2, SQLite/PostgreSQL, Redis (可选) |
| **Web 前端** | React 19, TypeScript, Vite 7, Ant Design 6, Axios, Zustand |
| **iOS 客户端** | Swift 6, SwiftUI, AVPlayer, URLSession, UserDefaults |

---

## 快速开始

### 1. 后端服务

```bash
cd Server

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量 (创建 .env 文件)
cat > .env << EOF
DATABASE_URL=sqlite+aiosqlite:///./music.db
SECRET_KEY=dev-secret-key-change-in-production
DEBUG=true
APP_ENV=development
UPLOAD_DIR=./uploads
EOF

# 创建上传目录
mkdir -p uploads

# 启动服务
python3 main.py
```

服务启动后访问：
- **API 文档**: http://localhost:8000/docs
- **健康检查**: http://localhost:8000/health

### 2. 填充测试数据

```bash
cd Server
source venv/bin/activate
python3 seed_data.py
```

默认管理员账户：`admin` / `123456`

### 3. Web 管理后台

```bash
cd Server/frontend
npm install
npm run dev
```

访问 http://localhost:5173

### 4. iOS 客户端

用 Xcode 打开 `Client/SwiftUI-music/SwiftUI-music.xcodeproj`，选择模拟器运行。

App 会自动连接 `localhost:8000` 后端 API。

---

## API 接口概览

| 模块 | 说明 | 主要接口 |
|------|------|----------|
| **auth** | 认证 | 登录、注册、忘记/重置密码 |
| **users** | 用户管理 | CRUD (管理员) |
| **singers** | 歌手管理 | CRUD + 状态管理 |
| **albums** | 专辑管理 | CRUD + 按歌手/名称筛选 |
| **musics** | 音乐管理 | CRUD + 批量删除 + 审核 |
| **categories** | 分类管理 | 树形结构 |
| **tags** | 标签管理 | CRUD + 关联音乐 |
| **common** | 通用功能 | 仪表盘统计、文件上传 |
| **sys_logs** | 系统日志 | 查看/删除 (管理员) |

完整接口文档见 [API_DOCUMENTATION.md](Server/API_DOCUMENTATION.md)

---

## 统一响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

分页响应：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [ ... ],
    "total": 100,
    "page": 1,
    "size": 10
  }
}
```

---

## 权限角色

| 角色 | 说明 |
|------|------|
| `user` | 普通用户，可浏览已审核的音乐、歌手 |
| `admin` | 管理员，可管理所有资源 |
| `super_admin` | 超级管理员 |
| `auditor` | 审核员，审核音乐 |

认证方式：JWT Bearer Token，默认有效期 30 分钟。

```
Authorization: Bearer <access_token>
```

---

## iOS 客户端功能

- 🔐 用户登录/注册
- 🏠 首页推荐（热门音乐、歌手精选）
- 🔍 音乐/歌手/专辑搜索
- ▶️ 在线音乐播放 (AVPlayer)
- 📱 响应式布局 (iPhone + iPad)

---

## License

MIT