# chees_song

**Repository Path**: chees_cn/chees_song

## Basic Information

- **Project Name**: chees_song
- **Description**: 基于suno的AI音乐工作台
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# chees_song

An AI music generation platform based on Suno V5 API, supporting card redemption, task management, and admin dashboard.

## Project Overview

Chees Song is a complete AI music generation service platform consisting of:
- **PC Client (chees-client)**: Vue 3 frontend for desktop users to generate AI music (Port 5173)
- **Mobile Client (chees-mobile)**: Vue 3 mobile frontend, optimized for mobile devices (Port 5175)
- **Admin Dashboard (chees-admin)**: Vue 3 admin panel for user management, card management, and audit logs (Port 5174)
- **Backend (chees-backend)**: Node.js/Express API handling authentication, tasks, and card redemption
- **Shared Package (shared)**: Common type definitions and contracts

## Tech Stack

- **Frontend**: Vue 3 + TypeScript + Vite + Pinia
- **Backend**: Node.js + Express + TypeScript
- **Testing**: Vitest (Unit Tests) + Playwright (E2E Tests)
- **Storage**: JSON file storage (atomic writes, backup/restore support)
- **Authentication**: JWT + scrypt password hashing

## Requirements

- **Node.js**: >= 20.0.0
- **npm**: >= 10.0.0
- **OS**: Windows 10/11, macOS, Linux

## Project Configuration Guide

### 1. Clone the Project

```bash
git clone https://gitee.com/chees_cn/chees_song.git
cd chees_song
```

### 2. Install Dependencies

```bash
# Install all workspace dependencies
npm run bootstrap

# Or use npm install
npm install
```

### 3. Environment Variables Configuration

#### Backend Configuration (chees-backend/.env)

Create `chees-backend/.env` file:

```env
# Server port
PORT=3000

# Data storage path
DATA_DIR=./data

# JWT configuration
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=7d

# Admin account
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123

# Suno API configuration
SUNO_API_KEY=your-suno-api-key
SUNO_API_URL=https://api.suno.ai
```

#### PC Client Configuration (chees-client/.env)

Create `chees-client/.env` file:

```env
# API base URL
VITE_API_BASE_URL=http://localhost:3000

# Development server port
PORT=5173
```

#### Mobile Client Configuration (chees-mobile/.env)

Create `chees-mobile/.env` file:

```env
# API base URL
VITE_API_BASE_URL=http://localhost:3000

# Development server port
PORT=5175
```

#### Admin Dashboard Configuration (chees-admin/.env)

Create `chees-admin/.env` file:

```env
# API base URL
VITE_API_BASE_URL=http://localhost:3000

# Development server port
PORT=5174
```

### 4. Data Directory Initialization

```bash
# Create data directory
mkdir -p chees-backend/data

# Directory structure
chees-backend/data/
├── users.json      # User data
├── cards.json      # Card data
├── tasks.json      # Task data
├── audit.json      # Audit logs
└── config.json     # System configuration
```

## Project Operation Guide

### Development Mode Startup

#### Option 1: Start Services Separately

```bash
# 1. Start backend service (Port 3000)
cd chees-backend
npm run dev

# 2. Start PC client (Port 5173)
cd chees-client
npm run dev

# 3. Start mobile client (Port 5175)
cd chees-mobile
npm run dev

# 4. Start admin dashboard (Port 5174)
cd chees-admin
npm run dev
```

#### Option 2: Use npm Workspace Commands

```bash
# Start backend
npm run dev --workspace=chees-backend

# Start PC client
npm run dev --workspace=chees-client

# Start mobile client
npm run dev --workspace=@chees/mobile

# Start admin dashboard
npm run dev --workspace=chees-admin
```

#### Option 3: Use PowerShell (Windows)

```powershell
# Execute in project root directory
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd chees-backend; npm run dev"
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd chees-client; npm run dev"
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd chees-mobile; npm run dev"
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd chees-admin; npm run dev"
```

#### Option 4: Use Bash Background (Linux/macOS)

```bash
# Start all services in background
cd chees-backend && npm run dev &
cd chees-client && npm run dev &
cd chees-mobile && npm run dev &
cd chees-admin && npm run dev &
```

### Access URLs

Once services are started, access via:

- **PC Client**: http://localhost:5173
- **Mobile Client**: http://localhost:5175
- **Admin Dashboard**: http://localhost:5174
- **Backend API**: http://localhost:3000

### Production Build

#### Build All Workspaces

```bash
# Build all frontend and backend
npm run build --workspaces --if-present
```

#### Build Separately

```bash
# Build backend
cd chees-backend && npm run build

# Build PC client
cd chees-client && npm run build

# Build mobile client
cd chees-mobile && npm run build

# Build admin dashboard
cd chees-admin && npm run build
```

#### Preview Production Build

```bash
# PC client preview
cd chees-client && npm run preview

# Mobile client preview
cd chees-mobile && npm run preview

# Admin dashboard preview
cd chees-admin && npm run preview
```

### Testing

#### Unit Tests

```bash
# Run all unit tests
npm run test

# Run specific workspace tests
npm run test --workspace=chees-client
npm run test --workspace=chees-admin
npm run test --workspace=@chees/mobile
npm run test --workspace=chees-backend
```

#### Type Checking

```bash
# Check all workspaces
npm run typecheck

# Check specific workspace
npm run typecheck --workspace=chees-client
npm run typecheck --workspace=@chees/mobile
```

#### E2E Tests

```bash
# Run E2E tests (requires built files)
npm run test:e2e

# List E2E tests
npm run test:e2e:check
```

#### Smoke Tests

```bash
# Run full smoke test (test + type check + E2E list check)
npm run smoke
```

### Data Backup and Restore

#### Backup Data

```bash
# Backup data directory
cp -r chees-backend/data chees-backend/data-backup-$(date +%Y%m%d)

# Or use compression
tar -czvf backup-$(date +%Y%m%d).tar.gz chees-backend/data
```

#### Restore Data

```bash
# Restore data directory
cp -r chees-backend/data-backup-20240101 chees-backend/data

# Or extract restore
tar -xzvf backup-20240101.tar.gz
```

### Card Generation (Admin Operation)

1. Login to admin dashboard: http://localhost:5174
2. Go to "Card Management" page
3. Click "Generate Cards"
4. Set:
   - Batch ID (optional)
   - Credit denomination
   - Quantity to generate
   - Channel tag (optional)
   - Notes (optional)
5. Click generate, export CSV file

### User Workflow

#### PC Client Usage

1. Visit http://localhost:5173
2. Register/Login account
3. Create song generation task in Dashboard:
   - Enter song title
   - Add tags (e.g.: pop, electronic, happy)
   - Enter style prompt
   - Click submit (consumes 1 credit)
4. View task status in Dashboard
5. After completion, view and play songs in Library

#### Mobile Client Usage

1. Visit http://localhost:5175 on mobile browser
   - Or use LAN IP: http://192.168.x.x:5175
2. Register/Login account
3. Use bottom navigation bar:
   - **Home**: Create song tasks
   - **Library**: View history songs
   - **Profile**: View credits, redeem cards, logout
4. Redeem card code:
   - Go to "Profile" page
   - Click "Redeem Card"
   - Enter 16-digit card code
   - Click redeem

### Troubleshooting

#### Port Conflicts

```bash
# Check port usage (Windows)
netstat -ano | findstr :5173

# Check port usage (Linux/macOS)
lsof -i :5173

# Change port: modify .env in corresponding workspace
PORT=5176
```

#### Dependency Installation Failed

```bash
# Clear cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm run bootstrap
```

#### Build Failed

```bash
# Clear build cache
rm -rf dist
rm -rf node_modules/.vite

# Rebuild
npm run build
```

#### Data File Corruption

```bash
# Stop backend service
# Backup and delete corrupted data file
mv chees-backend/data/users.json chees-backend/data/users.json.bak
# Restart service, system will create empty file
```

## Project Structure

```
chees_song/
├── chees-backend/       # Backend service
│   ├── src/
│   │   ├── auth/        # Authentication (JWT, password hashing)
│   │   ├── routes/      # API routes
│   │   ├── services/    # Business logic
│   │   ├── repositories/# Data storage
│   │   └── domain/      # Domain models
│   ├── data/            # Data file storage
│   └── tests/           # Unit tests
├── chees-client/        # PC frontend
│   ├── src/
│   │   ├── components/  # Components
│   │   ├── pages/       # Pages
│   │   ├── stores/      # State management
│   │   └── api/         # API client
│   └── dist/            # Build output
├── chees-mobile/        # Mobile frontend
│   ├── src/
│   │   ├── api/         # API client
│   │   ├── layouts/     # Layout components
│   │   ├── pages/       # Pages
│   │   ├── router/      # Router
│   │   └── stores/      # State management
│   └── dist/            # Build output
├── chees-admin/         # Admin dashboard
│   ├── src/
│   │   └── views/       # Admin pages
│   └── dist/            # Build output
├── shared/              # Shared code
│   └── src/             # Common types and contracts
├── tests/e2e/           # E2E tests
└── docs/                # Documentation
```

## Core Features

### PC Client (chees-client)
- **Port**: 5173
- User registration/login
- AI music generation task creation
- Real-time task status viewing (polling)
- Personal music library management
- Card code redemption for credits
- Audio playback (dual versions)

### Mobile Client (chees-mobile)
- **Port**: 5175
- Mobile-optimized login/register interface
- Song generation form (mobile-optimized)
- Task status polling display
- Music library browsing (with filters: All/Success/Failed/Processing)
- Card code redemption (using user-visible card code)
- Audio player
- Bottom navigation bar (Dashboard / Library / Profile)
- **Features**: Touch-friendly (44px+ tap area), safe area adaptation (notch screens), responsive layout, pull-to-refresh

### Admin Dashboard (chees-admin)
- **Port**: 5174
- Admin login
- User management (view, freeze/unfreeze)
- Card generation and management (batch management, CSV export)
- Task audit logs (view, manual refund)
- Pricing and risk control configuration (credit pricing, risk control parameters)

### Backend (chees-backend)
- **Port**: 3000
- JWT authentication and session management
- Card redemption and credit system
- Task Center (submit tasks, status query, automatic refund)
- Admin audit logs
- Pricing risk engine
- Data backup/restore

## Environment Variables Reference

### Backend Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | 3000 |
| `DATA_DIR` | Data storage directory | ./data |
| `JWT_SECRET` | JWT secret key | required |
| `JWT_EXPIRES_IN` | JWT expiration time | 7d |
| `ADMIN_USERNAME` | Admin username | admin |
| `ADMIN_PASSWORD` | Admin password | required |
| `SUNO_API_KEY` | Suno API key | required |
| `SUNO_API_URL` | Suno API URL | https://api.suno.ai |

### Frontend Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `VITE_API_BASE_URL` | API base URL | http://localhost:3000 |
| `PORT` | Development server port | 5173/5174/5175 |

## API Documentation

### Authentication Endpoints

```
POST /api/auth/login          # Login
POST /api/auth/register       # Register
GET  /api/profile             # Get user info
```

### Song Task Endpoints

```
POST /api/song/submit         # Submit song generation task
GET  /api/song/status/:id     # Query task status
GET  /api/song/library        # Get song library
```

### Card Endpoints

```
POST /api/card/redeem         # Redeem card (code parameter)
```

### Admin Endpoints

```
GET  /api/admin/users         # User list
GET  /api/admin/cards         # Card list
POST /api/admin/cards/generate # Generate cards
GET  /api/admin/tasks         # Task audit logs
POST /api/admin/tasks/:id/refund # Manual refund
GET  /api/admin/config        # Get config
POST /api/admin/config        # Update config
```

## Development Guidelines

- **Code Style**: Use TypeScript strict mode
- **Components**: Use Vue 3 Composition API
- **State Management**: Use Pinia, organize by feature modules
- **Routing**: Use Vue Router, route guards by role
- **Testing**: Vitest unit tests + Playwright E2E tests
- **Commits**: Follow Conventional Commits specification
- **Workspaces**: Follow monorepo workspace conventions, avoid circular dependencies

## Contributing

1. **Fork** the repository
2. Create feature branch: `git checkout -b Feat_xxx`
3. Commit changes: `git commit -m "feat: add new feature"`
4. Push branch: `git push origin Feat_xxx`
5. Create **Pull Request**

### Commit Convention

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Formatting (changes that don't affect code execution)
- `refactor`: Refactoring
- `test`: Tests
- `chore`: Build process or auxiliary tool changes

## License

Apache License 2.0

Copyright 2024 Chees Song Team

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.