# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an AI development scaffolding project with a Go backend (go-zero) and React frontend (shadcn/ui). It provides a foundation for building full-stack applications with user management, authentication, and profile functionality.

## Project Structure

```
.
├── backend/              # Go + go-zero + GORM backend
│   ├── api/              # API definition files (.api)
│   ├── internal/
│   │   ├── config/       # Configuration structures
│   │   ├── handler/      # HTTP handlers (grouped by feature)
│   │   ├── logic/        # Business logic (grouped by feature)
│   │   ├── middleware/   # CORS, Auth, Logging middleware
│   │   ├── svc/          # Service context (DB, config, middleware)
│   │   └── types/        # Request/response types (auto-generated)
│   ├── model/            # GORM entity models and data access
│   └── tests/            # Test standards documentation
└── frontend/react-shadcn/pc/   # React + Vite + shadcn/ui frontend
    ├── src/
    │   ├── components/   # UI components and layout
    │   ├── contexts/     # React contexts (AuthContext)
    │   ├── pages/        # Page components
    │   ├── services/     # API client
    │   └── types/        # TypeScript type definitions
    └── vite.config.ts    # Vite config with @/ alias
```

## Backend Development

### Build and Run

```bash
cd backend

# Run the server (requires MySQL)
go run base.go -f etc/base-api.yaml

# Run tests
go test ./...
go test ./internal/logic/user/...     # Run specific package tests
go test -v ./internal/logic/user/...  # Verbose output

# Generate code from API definitions (requires goctl)
goctl api go -api base.api -dir .
```

### Architecture

**go-zero Framework**: The backend uses go-zero with the following conventions:

- **API Definitions**: Defined in `*.api` files using goctl syntax. Main entry: `base.api`
- **Handler-Logic Pattern**: Handlers parse requests and delegate to Logic structs
- **Service Context** (`internal/svc/servicecontext.go`): Holds shared resources (DB connection, config, middleware)
- **Code Generation**: `internal/types/types.go` and `internal/handler/routes.go` are auto-generated by goctl

**Authentication Flow**:
- JWT tokens issued on login/register
- `Auth` middleware validates Bearer tokens and injects user context
- Context keys: `userId`, `username`, `email`

**Database (GORM)**:
- Models in `model/` package with entity + model files
- Auto-migration on startup in `servicecontext.go`
- Supports MySQL (primary) and SQLite (testing)

### API Structure

Base path: `/api/v1`

| Group | Middleware | Endpoints |
|-------|-----------|-----------|
| auth | Cors, Log | POST /register, /login, /refresh |
| user | Cors, Log, Auth | CRUD /user, /users |
| profile | Cors, Log, Auth | GET/PUT /profile/me, POST /profile/password |

## Frontend Development

### Build and Run

```bash
cd frontend/react-shadcn/pc

# Install dependencies
npm install

# Development server (http://localhost:5173)
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Lint
npm run lint
```

### Architecture

**Tech Stack**: React 19, TypeScript, Vite, Tailwind CSS v4, shadcn/ui components

**Key Conventions**:
- Path alias `@/` maps to `src/`
- Environment variable: `VITE_API_BASE_URL` (defaults to `http://localhost:8888/api/v1`)
- Custom UI components in `src/components/ui/` (Button, Card, Input, Modal, Table)

**Authentication**:
- `AuthContext` manages global auth state
- JWT stored in localStorage with key `token`
- `ProtectedRoute` component guards authenticated routes
- Auth header: `Authorization: Bearer <token>`

**API Client** (`src/services/api.ts`):
- Singleton `apiClient` class
- Auto-attaches auth headers from localStorage
- Methods organized by feature: auth, user management, profile

## Testing Standards

### Backend Testing

Each module follows the test flow: **Create → Query → Update → Verify Update → List → Delete → Verify Delete**

Test files use SQLite in-memory database for isolation. Example test structure:

```go
func TestCreateUserLogic(t *testing.T) {
    // Setup SQLite DB
    // Create service context with test DB
    // Execute logic
    // Verify results
}
```

### API Testing with curl

See `backend/tests/USER_MODULE_TEST_STANDARD.md` for detailed curl examples.

Quick test flow:
```bash
BASE_URL="http://localhost:8888/api/v1"

# 1. Register
POST /register

# 2. Get token, then call authenticated endpoints
GET /profile/me -H "Authorization: Bearer <token>"
```

## Configuration

### Backend (`etc/base-api.yaml`)

```yaml
Name: base-api
Host: 0.0.0.0
Port: 8888
MySQL:
  DSN: "user:pass@tcp(host:port)/dbname?charset=utf8mb4&parseTime=true&loc=Local"
```

### Frontend (`.env` or environment)

```
VITE_API_BASE_URL=http://localhost:8888/api/v1
```

## AI Development Resources

- **go-zero AI Context**: https://github.com/zeromicro/ai-context
- **shadcn/ui LLMs.txt**: https://ui.shadcn.com/llms.txt
- **zero-skills**: https://github.com/zeromicro/zero-skills