|
|
@@ -0,0 +1,335 @@
|
|
|
+# 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` (前端详细架构)
|