# CLAUDE.md

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

## Development Commands

**Build and Run:**
- `pnpm run dev` - Start development server on port 8080
- `pnpm run build` - Build both client and server
- `pnpm run build:client` - Build client only
- `pnpm run build:server` - Build server only
- `pnpm start` - Start production server

**Database:**
- MySQL database runs on localhost:3306 (default credentials: root/empty)
- Redis runs on localhost:6379
- MinIO runs on localhost:9000/9001 (credentials: minioadmin/minioadmin)
- Use `docker-compose up` to start all services

## Architecture Overview

**Frontend (src/client/):**
- React 19 + TypeScript + Vite
- Two main sections: `admin/` and `home/`
- Uses Radix UI components and Tailwind CSS
- React Router for navigation
- React Hook Form for forms
- TanStack Query for API calls

**Backend (src/server/):**
- Hono.js framework with OpenAPI support
- TypeORM with MySQL database
- Modular structure under `src/server/modules/`
- JWT authentication
- File storage with MinIO integration

**Key Modules:**
- `users/` - User management and authentication
- `files/` - File upload/download functionality
- `payments/` - Payment processing
- `membership/` - Membership plans
- `templates/` - Document templates
- `documents/` - Document processing (Word merge feature)

**API Structure:**
- OpenAPI documentation available at `/doc`
- API routes defined in `src/server/api/`
- Client API calls in `src/client/api.ts`

## Development Patterns

**Form Validation:**
- Frontend uses React Hook Form with Zod validation
- Backend uses Zod with `z.coerce` for type conversion
- Always use `dayjs` objects instead of native Date objects

**Database:**
- TypeORM entities with decorators
- Migrations in `src/server/migrations/`
- Environment variables for database configuration

**File Handling:**
- MinIO integration for file storage
- File upload/download utilities
- Document processing with docxtemplater and mammoth

## Common Issues & Solutions

1. **Date validation errors**: Use `dayjs()` instead of `new Date()`
2. **OpenAPI path parameters**: Use `{id}` format instead of `:id`
3. **Type coercion**: Use `z.coerce.number()` and `z.coerce.boolean()` for URL params
4. **Form validation mismatches**: Ensure frontend and backend validation rules match

## Environment Setup

Required environment variables:
- `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASE`
- Database defaults to localhost:3306 with root/empty credentials
- MinIO defaults to localhost:9000 with minioadmin/minioadmin

## Roo Framework

The project uses Roo framework for code generation and validation:
- Commands in `.roo/commands/`
- API-client validation rules
- Entity-field mapping checks

## Project Standards & Rules
- @.roo/rules/01-general.md - 通用开发规范
- @.roo/rules/02-typescript.md - TypeScript规范
- @.roo/rules/03-modules.md - 模块化规范
- @.roo/rules/04-api.md - API开发规范
- @.roo/rules/05-database.md - 数据库规范
- @.roo/rules/06-service-di.md - 服务与依赖注入规范
- @.roo/rules/07-openapi.md - OpenAPI规范
- @.roo/rules/08-rpc.md - RPC调用规范
- @.roo/rules/09-logging.md - 日志规范
- @.roo/rules/10-entity.md - 实体定义规范
- @.roo/rules/11-admin-frontend.md - 管理前端规范
- @.roo/rules/11-custom-crud.md - 自定义CRUD规范
- @.roo/rules/11-entity-creation.md - 实体创建规范
- @.roo/rules/11-home-frontend.md - 首页前端规范
- @.roo/rules/11-standard-crud.md - 标准CRUD规范
- @.roo/rules/12-generic-crud.md - 通用CRUD规范
- @.roo/rules/14-crud-filtering.md - CRUD筛选规范
- @.roo/rules/15-user-tracking.md - 用户追踪规范

## Development Notes
- Uses pnpm as package manager
- Vite for both dev server and production builds
- SSR (Server-Side Rendering) setup with Hono.js
- Environment variables via `.env` file
- Port 8080 for development and production

## Claude Code
- Always response in Chinese