# CLAUDE.md

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

## 项目概述

3D 家具安装展示系统 — 面向电商企业的家具产品管理平台，核心能力是 3D 交互式装配动画展示。主代码在 `furniture-3d-system/` 目录。

## 常用命令

所有命令在 `furniture-3d-system/` 目录下执行：

```bash
npm run dev              # 启动开发服务器
npm run build            # 构建（prisma generate + next build）
npm run lint             # ESLint 检查
npm run type-check       # TypeScript 类型检查（next typegen + tsc --noEmit）
npm test                 # 运行 Jest 测试
npm test -- --testPathPattern="文件名" # 运行单个测试
npm run test:coverage    # 带覆盖率测试（阈值 70%）
npm run prisma:generate  # 生成 Prisma Client
npm run prisma:push      # 推送数据库 schema
npm run prisma:studio    # 打开 Prisma Studio
npm run demo:setup       # 初始化演示数据（push + seed）
```

## 技术栈

- **前端**：Next.js 16 (App Router) + React 19 + TypeScript 5 + Tailwind CSS 4
- **3D**：Three.js + React Three Fiber + Drei + GSAP
- **状态**：Zustand
- **后端**：Next.js API Routes + Prisma 7 (PostgreSQL) + Redis (ioredis) + MinIO (S3)
- **认证**：JWT + bcryptjs
- **测试**：Jest 30 + React Testing Library
- **路径别名**：`@/*` → `src/*`

## 架构（硬约束）

### 后端分层（禁止跳层）

```
API Route → Service → Repository → Database (Prisma)
```

- **API Route**（`src/app/api/`）：只做参数接收、鉴权、调用 Service、统一响应
- **Service**（`src/server/services/`）：权限校验、业务规则、缓存、事务编排
- **Repository**（`src/server/repositories/`）：纯数据访问
- **统一错误**：`AppError + ErrorCode`（`src/server/core/`）
- **统一响应**：`handleRequest`、`jsonSuccess`、`jsonError`（`src/server/core/`）
- **DTO**：`src/server/dto/`，**Validator**：`src/server/validators/`

### 前端约束

- **元组件优先**：必须复用 `src/components/ui/`（29 个基础组件），禁止手搓替代品
- **苹果风格视觉标准**：设计令牌在 `src/lib/design-tokens/`
- **品牌色**：`#008D74`（浅色）/ `#00B896`（深色）
- **禁止**：`text-gray-*` / `bg-gray-*` / 原生 `<button>` `<input>` `<select>`
- **状态管理**：`src/stores/`（auth/product/ui）
- **业务组件**：按领域分组在 `src/components/`（3d/assembly/auth/products/panels/packaging/users 等）

### 数据库

Prisma schema 在 `furniture-3d-system/prisma/schema.prisma`，22 个模型。核心实体：Product → ProductSKU → AssemblyStep/AssemblyVersion → Panel → Hole → Hardware。

## 交付规范审查（必做）

任何开发改动，交付前必须做一次规范审查，固定只查三件事：

1. **架构**：是否遵循分层、统一错误/响应格式
2. **视觉**：是否复用元组件、遵循设计令牌
3. **根因修复**：是不是真正解决问题，而不是补丁式绕过

结论只能是：`passed` / `passed with warnings` / `rejected`。
违规即 `rejected`。详细清单见 `docs/workflow/规范审查清单.md`。

## 规则优先级

用户当前明确指令 > 子目录规则（`.cursor/rules/*.mdc`）> `AGENTS.md` > 本文件

## 默认行为

- 用户未指定目录时，默认在 `furniture-3d-system/` 执行
- 未经用户明确要求，不主动 commit / push
- 中文沟通，面向非程序员，简短直白
- 优先复用现有实现，不顺手改无关问题
- 不以"最小改动"为默认目标，优先完成主需求闭环并收口同链路已发现问题