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)

命令速查

后端命令

# 进入后端目录
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    # 打包

前端命令

# 进入前端目录
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

数据库初始化

# 使用 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): 月度账单生成、费用分摊、付款记录

关键业务流程

多批次羽毛球消耗:

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

账单生成:

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

配置文件

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)

认证流程

JWT 令牌存储在 cookie (Admin-Token)
src/permission.js 全局路由守卫检查令牌
首次认证: 获取用户信息 (/getInfo)，生成动态路由
Axios 拦截器注入 Authorization: Bearer {token} 头部
权限格式: 模块:实体:操作 (如 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, ~ → 项目根目录

常见任务

添加新的业务模块

后端:

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

前端:

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

使用代码生成器

访问系统管理 → 代码生成
导入数据表，配置生成信息
生成代码（Java + Vue + SQL）
将生成的代码复制到对应目录
执行菜单 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: 动态路由生成

注意事项

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

参考文档

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

CLAUDE.md 13 KB パーマリンク 履歴 Raw