# CLAUDE.md

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

## Project Overview

gen2d — AI 驱动的 2D 游戏素材生成工具。用户通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧。目标是无缝融入 Unity / Godot 等主流 2D 游戏引擎的工作流。

## Directory Structure

```
gen2d/
├── backend/          # Go + Gin API 服务
│   ├── cmd/          # 入口 (main.go)
│   ├── internal/     # 业务逻辑（不对外暴露）
│   │   ├── handler/  # HTTP handlers
│   │   ├── service/  # 业务 service 层
│   │   ├── model/    # 数据模型 / DTO
│   │   ├── middleware/
│   │   └── config/
│   ├── pkg/          # 可复用的公共库
│   ├── go.mod
│   └── go.sum
├── frontend/         # Vite + React 前端
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/ # API 调用层
│   │   ├── stores/   # 状态管理
│   │   ├── types/
│   │   └── utils/
│   ├── public/
│   ├── index.html
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── package.json
└── CLAUDE.md
```

## Common Commands

### Backend (Go + Gin)

```bash
cd backend

# 安装依赖
go mod tidy

# 运行开发服务器
go run cmd/main.go

# 构建
go build -o bin/gen2d cmd/main.go

# 运行全部测试
go test ./...

# 运行单个包的测试
go test ./internal/service/...

# 运行单个测试函数
go test -run TestFunctionName ./internal/service/

# 代码检查
golangci-lint run
```

### Frontend (Vite + React)

```bash
cd frontend

# 安装依赖
npm install

# 开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 类型检查
npm run typecheck

# Lint
npm run lint

# 运行测试
npm run test

# 运行单个测试文件
npm run test -- src/components/AssetCard.test.tsx
```

## Architecture

### 后端分层

- **Handler** — 解析 HTTP 请求，调用 service，返回响应。不包含业务逻辑。
- **Service** — 核心业务逻辑：提示词处理、AI 模型调用、素材后处理。
- **Model** — 请求/响应 DTO、数据库实体（如有）。
- **Pkg** — 通用工具：图片处理、颜色分析、sprite 切片等。

### 前端架构

- 使用 React + TypeScript，状态管理使用 zustand 或 React Context。
- API 调用集中在 `services/` 目录，组件不直接发请求。
- 素材预览和参数调整是核心交互，需要关注 Canvas/WebGL 渲染性能。

### 前后端通信

- RESTful API，JSON 格式。
- 前端开发时通过 Vite proxy 转发到后端 `localhost:PORT`。
- 图片素材通过 base64 或对象存储 URL 传输，大文件走 OSS/COS。

## 2D 游戏素材生成约束

### 素材类型

项目需要覆盖以下常见 2D 游戏素材类型：

- **Sprite / 角色** — 像素风、卡通、手绘风等，需支持多帧动画序列
- **Tilemap / 地形瓦片** — 可无缝拼接的地形纹理（草地、水域、道路等）
- **UI 元素** — 按钮、血条、对话框、图标等
- **背景 / 场景** — 横版卷轴背景、俯视视角场景
- **特效** — 火焰、烟雾、魔法等粒子效果帧

### 风格一致性

- 提供**风格种子 (Style Seed)** 机制：用户选定一套风格后，后续生成继承相同的色板、线条风格、分辨率。
- 支持**参考图上传**：以已有素材作为风格参考。
- 生成时返回**风格向量 / 特征参数**，可用于后续生成的风格锁定。

### 管线兼容性

生成的素材需满足主流游戏引擎的导入要求：

- **Sprite Sheet** — 输出标准的 spritesheet 拆分格式，附带 JSON/CSV 元数据（frame 位置、锚点、碰撞框）。
- **透明通道** — PNG 格式，带 alpha 通道，背景透明。
- **尺寸规范** — 支持常见尺寸（16×16, 32×32, 48×48, 64×64, 128×128, 256×256），可自定义。
- **命名规范** — 输出文件遵循 `{category}_{name}_{index}.png` 格式，便于引擎批量导入。
- **Unity / Godot 导出** — 可选生成 `.aseprite` 元数据或 Unity Sprite Editor 兼容的 `.meta` 信息。

### 生成效率与成本

- 支持**批量生成**：一次请求生成多个变体（如角色的行走 8 方向 × 4 帧）。
- 提供**低分辨率预览 → 高分辨率出图**的两阶段流程，减少无效生成。
- 后端应做**请求去重与缓存**：相同提示词 + 参数的结果缓存复用。
- AI 模型调用支持**异步队列**，前端轮询或 WebSocket 获取结果。

## Conventions

- 后端 Go 代码遵循 [Effective Go](https://go.dev/doc/effective_go) 和 Go 官方 style。
- 前端使用 ESLint + Prettier，提交前自动格式化。
- API 路径统一使用 `/api/v1/` 前缀。
- 错误响应统一格式：`{"code": int, "message": string, "data": any}`。
- Git commit message 使用中文或英文均可，但需要清晰描述变更内容。