# CLAUDE.md

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

## 项目概述

羽毛球活动管理系统 - 基于若依（RuoYi）框架的前后端分离项目，用于管理羽毛球俱乐部的签到、活动记录、采购管理和账单结算。

## 项目结构

```
claude-badminton/
├── backend/              # 后端 (Spring Boot + MyBatis + PostgreSQL)
│   ├── ruoyi-admin/     # 主应用模块 (端口: 8081)
│   ├── ruoyi-common/    # 通用工具模块
│   ├── ruoyi-framework/ # 框架核心模块
│   ├── ruoyi-system/    # 系统管理模块
│   ├── ruoyi-service/   # 业务服务模块 (羽毛球管理)
│   ├── ruoyi-generator/ # 代码生成模块
│   ├── ruoyi-quartz/    # 定时任务模块
│   ├── ruoyi-ui/        # 旧版前端 (Vue 2)
│   └── sql/             # 数据库脚本
└── frontend/            # 新版前端 (Vue 3 + Vite + Element Plus)
```

## 命令速查

### 后端命令

```bash
# 进入后端目录
cd backend

# Maven 构建
mvn clean package -DskipTests          # 打包（跳过测试）
mvn clean install                      # 安装到本地仓库

# 运行（开发环境）
cd ruoyi-admin
mvn spring-boot:run

# 运行（生产环境）
java -jar ruoyi-admin/target/ruoyi-admin.jar --spring.profiles.active=prod

# Windows 快捷脚本
bin\run.bat        # 启动服务
bin\clean.bat      # 清理编译
bin\package.bat    # 打包
```

### 前端命令

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install
# 或使用国内镜像
npm install --registry=https://registry.npmmirror.com

# 开发环境 (端口: 80, 代理到 http://localhost:8081)
npm run dev

# 构建
npm run build:prod    # 生产环境
npm run build:stage   # 预发布环境

# 预览构建产物
npm run preview
```

### 数据库初始化

```bash
# 使用 PostgreSQL，按顺序执行：
# 1. backend/sql/postgresql.sql       - 基础表结构
# 2. backend/sql/postgresql_view.sql  - 视图和代码生成支持
# 注意：quartz.sql 和 ry_20250522.sql 是 MySQL 语法，仅用于参考
```

## 技术栈

### 后端
- **框架**: Spring Boot 2.5.15 + Spring Security 5.7.12
- **数据库**: PostgreSQL (原项目为 MySQL，已适配 PostgreSQL)
- **ORM**: MyBatis (配置支持 MyBatis-Plus)
- **认证**: JWT (io.jsonwebtoken:jjwt 0.9.1)
- **缓存**: Redis (可选)
- **API 文档**: Swagger 3.0.0
- **工具库**: Druid 1.2.23, PageHelper 1.4.7, Fastjson2 2.0.57

### 前端
- **框架**: Vue 3.5.16 + Vite 6.3.5
- **UI 库**: Element Plus 2.10.7
- **状态管理**: Pinia 3.0.2
- **路由**: Vue Router 4.5.1
- **HTTP**: Axios 1.9.0
- **图表**: ECharts 5.6.0
- **富文本**: @vueup/vue-quill 1.2.0
- **自动导入**: unplugin-auto-import (Vue/Pinia API 无需手动导入)

## 架构要点

### 后端架构

#### 模块依赖关系
```
ruoyi-admin (主应用)
  ├─> ruoyi-framework (框架核心: 安全、缓存、配置)
  ├─> ruoyi-system (系统管理: 用户、角色、菜单、字典)
  ├─> ruoyi-service (业务服务: 羽毛球管理模块)
  ├─> ruoyi-generator (代码生成器)
  └─> ruoyi-quartz (定时任务)

ruoyi-framework
  └─> ruoyi-common (通用工具: 注解、常量、异常、工具类)

ruoyi-system, ruoyi-service, ruoyi-generator, ruoyi-quartz
  └─> ruoyi-common
```

#### 核心业务模块 (ruoyi-service)
羽毛球管理系统的业务逻辑位于 `ruoyi-service` 模块，包含：
- **签到管理** (`badminton_signin`): 用户每日签到，自动创建活动记录
- **活动记录** (`badminton_activity`): 活动信息、参与人员、费用计算
- **采购管理** (`badminton_procurement`): 羽毛球及耗材采购、批次管理
- **批次库存** (`badminton_shuttlecock_batch`): 按批次核算成本，FIFO 消耗
- **消耗明细** (`badminton_shuttlecock_usage`): 活动消耗与批次关联
- **账单管理** (`badminton_bill`): 月度账单生成、费用分摊、付款记录

#### 关键业务流程

**多批次羽毛球消耗**:
1. 活动记录可从多个采购批次消耗羽毛球
2. 前端选择批次（多选）并输入各批次消耗数量
3. 系统按 FIFO 原则优先消耗早期批次
4. 自动计算费用：各批次费用 = 数量 × 该批次单价
5. 扣减库存并更新批次状态（有库存/预警/已用完）

**账单生成**:
1. 每月 1 日自动生成上月账单（定时任务）
2. 汇总用户参与的活动记录，计算分摊金额
3. 支持平均分摊、阶梯分摊、混合分摊模式
4. 生成账单主表和明细表，关联具体活动

#### 配置文件
- `application.yml`: 主配置（端口 8081，context-path: /）
- `application-dev.yml`: 开发环境（数据库、Redis 连接）
- `application-prod.yml`: 生产环境
- 数据库使用 PostgreSQL，PageHelper 方言配置为 `postgresql`

### 前端架构

#### 路由系统
- **静态路由** (`src/router/index.js`): 登录、注册、404、401、首页
- **动态路由**: 从后端 API `GET /getRouters` 获取，根据用户权限动态加载
- 组件解析: `import.meta.glob('./../../views/**/*.vue')` 映射后端路由字符串到 Vue 组件
- 特殊组件: `Layout` (主外壳), `ParentView` (嵌套路由), `InnerLink` (iframe)

#### 认证流程
1. JWT 令牌存储在 cookie (`Admin-Token`)
2. `src/permission.js` 全局路由守卫检查令牌
3. 首次认证: 获取用户信息 (`/getInfo`)，生成动态路由
4. Axios 拦截器注入 `Authorization: Bearer {token}` 头部
5. 权限格式: `模块:实体:操作` (如 `system:user:edit`)，`*:*:*` = 全部权限

#### API 层 (`src/utils/request.js`)
- 基础 URL: `VITE_APP_BASE_API` (开发环境 `/dev-api`, 生产环境 `/prod-api`)
- 超时: 10 秒
- 防重复提交: 1 秒内阻止相同 POST/PUT 请求
- 响应码: 200=成功, 401=会话过期, 500=错误, 601=警告
- 文件下载: `download()` 方法处理 blob 验证

#### 目录结构
```
src/
├── api/                    # API 接口定义（按后端模块组织）
│   ├── badminton/         # 羽毛球管理 API
│   │   ├── activity.js    # 活动记录
│   │   ├── billing.js     # 账单管理
│   │   ├── procurement.js # 采购管理
│   │   └── signin.js      # 签到管理
│   ├── system/            # 系统管理 API
│   ├── monitor/           # 监控 API
│   └── tool/              # 工具 API
├── views/                  # 页面组件
│   ├── badminton/         # 羽毛球管理页面
│   │   ├── signin/        # 签到页面
│   │   ├── activity/      # 活动记录页面
│   │   ├── procurement/   # 采购管理页面
│   │   ├── billing/       # 账单管理页面
│   │   └── statistics/    # 统计分析页面
│   ├── system/            # 系统管理页面
│   ├── monitor/           # 监控页面
│   └── tool/              # 工具页面
├── store/modules/          # Pinia 状态管理
│   ├── user.js            # 用户状态
│   ├── permission.js      # 权限路由
│   ├── app.js             # 应用配置
│   ├── settings.js        # 界面设置
│   ├── tagsView.js        # 标签视图
│   └── dict.js            # 字典缓存
├── layout/                 # 布局组件
│   ├── components/        # 侧边栏、导航栏、标签视图
│   └── index.vue          # 主布局
├── components/             # 全局组件
│   ├── Pagination/        # 分页组件
│   ├── DictTag/           # 字典标签
│   ├── Editor/            # 富文本编辑器
│   ├── FileUpload/        # 文件上传
│   └── RightToolbar/      # 右侧工具栏
├── plugins/                # 插件系统
│   ├── auth.js            # 权限指令
│   ├── cache.js           # 缓存操作
│   ├── modal.js           # 弹窗封装
│   ├── tab.js             # 标签页操作
│   └── download.js        # 文件下载
├── directive/              # 自定义指令
│   └── permission/        # 权限指令 (v-permission)
├── utils/                  # 工具函数
│   ├── request.js         # Axios 封装
│   ├── auth.js            # Token 操作
│   ├── ruoyi.js           # 若依工具函数
│   ├── validate.js        # 表单验证
│   └── dict.js            # 字典工具
└── assets/                 # 静态资源
    ├── icons/svg/         # SVG 图标 (vite-plugin-svg-icons)
    └── styles/            # 全局样式
```

#### 全局属性 (通过 `getCurrentInstance()` 访问)
- `useDict`: 字典加载
- `download`: 文件下载
- `parseTime`: 时间格式化
- `resetForm`: 表单重置
- `handleTree`: 树形数据处理
- `addDateRange`: 日期范围查询
- `getConfigKey`: 获取系统配置
- `selectDictLabel`: 字典标签转换

#### SVG 图标
将 SVG 文件放在 `src/assets/icons/svg/`，自动注册，使用 `<svg-icon icon-class="名称" />`

## 开发约定

### 后端约定
- **包结构**: `com.ruoyi.{module}.{layer}` (如 `com.ruoyi.badminton.controller`)
- **Controller**: 继承 `BaseController`，使用 `AjaxResult` 统一响应
- **Service**: 接口 + 实现类，事务注解 `@Transactional`
- **Mapper**: MyBatis XML 映射文件位于 `resources/mapper/`
- **权限注解**: `@PreAuthorize("@ss.hasPermi('system:user:list')")`
- **日志注解**: `@Log(title = "用户管理", businessType = BusinessType.INSERT)`
- **数据权限**: `@DataScope` 注解自动过滤数据

### 前端约定
- **语言**: 全项目使用中文（Element Plus zh-cn、界面文本、注释）
- **API 模块**: 每个端点导出独立函数 (如 `listUser`, `getUser`, `addUser`)
- **视图模式**: CRUD 列表页 + 搜索表单 + 表格 + 添加/编辑对话框
- **字典使用**: `useDict()` 加载，`<dict-tag>` 显示
- **组件尺寸**: 存储在 cookie (`size`)，默认 `'default'`
- **路径别名**: `@` → `./src`, `~` → 项目根目录

## 常见任务

### 添加新的业务模块

**后端**:
1. 在 `ruoyi-service` 创建包: `com.ruoyi.{module}`
2. 创建 `domain` (实体类，继承 `BaseEntity`)
3. 创建 `mapper` (接口 + XML)
4. 创建 `service` (接口 + 实现类)
5. 创建 `controller` (继承 `BaseController`)
6. 在 `resources/mapper/{module}/` 创建 Mapper XML
7. 配置权限标识和菜单（通过系统管理界面）

**前端**:
1. 在 `src/api/` 创建 API 模块文件
2. 在 `src/views/` 创建页面组件
3. 后端配置菜单后，前端自动加载路由（无需手动配置）

### 使用代码生成器

1. 访问系统管理 → 代码生成
2. 导入数据表，配置生成信息
3. 生成代码（Java + Vue + SQL）
4. 将生成的代码复制到对应目录
5. 执行菜单 SQL，刷新页面即可看到新菜单

### 调试技巧

**后端**:
- 日志级别: `application.yml` 中设置 `logging.level.com.ruoyi: debug`
- Swagger 文档: `http://localhost:8081/swagger-ui/index.html`
- Druid 监控: `http://localhost:8081/druid/index.html`

**前端**:
- 开发环境自动代理 `/dev-api` 到 `http://localhost:8081`
- 修改代理目标: `vite.config.js` 中的 `baseUrl` 变量
- 查看路由: Vue DevTools → Router
- 查看状态: Vue DevTools → Pinia

## 重要文件

### 后端
- `backend/pom.xml`: Maven 父 POM，依赖版本管理
- `backend/ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java`: 启动类
- `backend/ruoyi-admin/src/main/resources/application.yml`: 主配置
- `backend/ruoyi-common/src/main/java/com/ruoyi/common/core/domain/AjaxResult.java`: 统一响应
- `backend/ruoyi-framework/src/main/java/com/ruoyi/framework/security/`: Spring Security 配置

### 前端
- `frontend/vite.config.js`: Vite 配置（代理、插件、构建）
- `frontend/src/main.js`: 应用入口
- `frontend/src/permission.js`: 路由守卫
- `frontend/src/settings.js`: 界面配置
- `frontend/src/utils/request.js`: Axios 封装
- `frontend/src/store/modules/permission.js`: 动态路由生成

## 注意事项

1. **数据库**: 项目已从 MySQL 适配到 PostgreSQL，SQL 语法需注意差异
2. **端口冲突**: 后端 8081，前端 80，确保端口未被占用
3. **跨域**: 开发环境通过 Vite 代理解决，生产环境需配置 Nginx
4. **权限**: 新增功能需在系统管理中配置菜单和权限标识
5. **字典**: 使用字典管理固定数据（如状态码），避免硬编码
6. **文件上传**: 上传路径配置在 `application.yml` 的 `ruoyi.profile`
7. **定时任务**: 使用 Quartz，在系统监控 → 定时任务中管理
8. **批次消耗**: 羽毛球消耗支持多批次，前端需传递批次数组

## 参考文档

- 若依官方文档: http://doc.ruoyi.vip
- 技术实现文档: `frontend/docs/技术实现文档.md` (详细的业务逻辑和数据库设计)
- 前端 CLAUDE.md: `frontend/CLAUDE.md` (前端详细架构)