nginx-ui/CLAUDE.md

# NGINX UI - Claude Code Guidelines

This project is a web-based NGINX management interface built with Go backend and Vue.js frontend.

## Package Manager
- **Use pnpm exclusively** for all frontend package management operations
- Commands: `pnpm install`, `pnpm run dev`, `pnpm typecheck`

## Backend (Go) Development

### Technologies & Frameworks
- **Go** with Gin web framework
- **GORM** for database operations  
- **Gen** for query simplification
- **Cosy** framework (https://cosy.uozi.org/)

### Code Organization
- **API Controllers**: Implement in `api/$module_name/` directory
- **Database Models**: Define in `model/` folder
- **Business Logic**: Place complex logic and error handling in `internal/$module_name/`
- **Routing**: Register routes in `router/` directory
- **Configuration**: Manage settings in `settings/` directory

### Development Guidelines
- Write concise, maintainable Go code with clear examples
- Run `gofmt`/`goimports` before committing backend changes
- Use Gen to streamline database queries and reduce boilerplate
- Follow Cosy Error Handler best practices for error management
- Implement standardized CRUD operations using Cosy framework
- Apply efficient database pagination for large datasets
- Validate changes with `go test ./... -race -cover` before pushing
- Keep files modular and well-organized by functionality
- **All comments and documentation must be in English**

## Frontend (Vue.js) Development

### Technology Stack
- **TypeScript** for all code
- **Vue 3** with Composition API
- **Vite** build tool
- **Vue Router** for routing
- **Pinia** for state management
- **VueUse** for utilities
- **Ant Design Vue** for UI components
- **UnoCSS** for styling

### Code Standards
- Use functional and declarative programming patterns (avoid classes)
- Prefer interfaces over types for better extendability
- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)
- Always use Vue Composition API with `<script setup>` syntax
- Leverage Vue 3.4+ features: `defineModel()`, `useTemplateRef()`, v-bind shorthand

### File Organization
- **Components**: Use CamelCase naming in `src/components/` (e.g., `ChatGPT/ChatGPT.vue`)
- **Views**: Use lowercase with underscores for folders, CamelCase for components (e.g., `src/views/system/About.vue`)
- **API & Types**: Define in `app/src/api/`
- **Exports**: Favor named exports for functions

### UI & Styling
- Use Ant Design Vue components and UnoCSS for styling
- Implement responsive design with mobile-first approach
- Use Antdv Flex layout for responsive layouts

### Performance Optimization
- Leverage VueUse functions for enhanced reactivity
- Wrap async components in Suspense with fallback UI
- Use dynamic loading for non-critical components
- Optimize images: WebP format, size data, lazy loading
- Implement code splitting and chunking strategy in Vite build
- Optimize Web Vitals (LCP, CLS, FID)

### Code Quality
- **Always use ESLint MCP after generating frontend code** to ensure code quality and consistency
- Run `pnpm lint`, `pnpm lint:fix`, and `pnpm typecheck` to keep style and typings aligned

## Development Commands
- **Frontend**: `pnpm run dev`, `pnpm lint`, `pnpm typecheck`, `pnpm run build`
- **Backend**: `go generate ./...`, `go build ./...`, run `go test ./... -race -cover`; for release artifacts reuse the README command with `-tags=jsoniter -ldflags "$LD_FLAGS ..."`.
- **Demo stack**: `docker-compose -f docker-compose-demo.yml up` to bootstrap the sample environment


## Release Workflow
- Start releases from the `dev` branch with a clean working tree.
- Run `./version.sh` outside the sandbox to update the version, rebuild the frontend, and refresh generated artifacts that require network access.
- Prepare release notes in a temporary local markdown file such as `release-notes-vX.Y.Z.md`.
- Follow the existing three-section release note style: `Features`, `Bug Fixes`, and `Contributors`.
- Write contributor names using GitHub handles when they are known from the merged PR, not raw git author names.
- Do not commit the release note markdown file. Keep it untracked and use it directly for the tag annotation and GitHub Release body.
- Commit only the version-preparation artifacts with `chore: prepare vX.Y.Z`.
- Create an annotated tag from the release note file. If local GPG signing blocks tag creation in the sandbox, create the tag outside the sandbox with `git -c tag.gpgSign=false tag -a vX.Y.Z -F release-notes-vX.Y.Z.md`.
- Push both `dev` and the release tag with `git push origin dev vX.Y.Z`.
- Publish the release with `gh release create vX.Y.Z --verify-tag --title vX.Y.Z -F release-notes-vX.Y.Z.md --discussion-category Announcements`.
- The release flow is expected to create the GitHub Release and the linked Discussion post, then GitHub Actions handles binary, Docker, Homebrew, WinGet, and branch-sync automation.

## Language Requirements
- **All code comments, documentation, and communication must be in English**
- Maintain consistency and accessibility across the codebase
- 优先使用 context7 mcp 搜索文档
- 生成 find 命令的时候应该排除掉 ./.go/ 这个文件夹，因为那里面是 devcontainer 的依赖