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

Date validation errors: Use dayjs() instead of new Date()
OpenAPI path parameters: Use {id} format instead of :id
Type coercion: Use z.coerce.number() and z.coerce.boolean() for URL params
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