# CLAUDE.md

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

## 项目概述

这是一个基于若依框架（RuoYi v3.8.8）的全栈银行客户关系管理系统，扩展了自定义业务逻辑，用于客户关系管理、基于网格的片区管理和移动端办公支持。

**技术栈：**
- **后端**：Spring Boot 2.5.14、Java 1.8、Maven 多模块项目
- **前端**：Vue 2.6 + Vant UI（移动端 H5 应用）
- **数据库**：MySQL + MyBatis Plus ORM
- **缓存**：Redis + JWT 认证
- **API 文档**：Swagger 3.0

## 构建与运行命令

### 后端（Maven）
```bash
# 构建整个项目（跳过测试）
mvn clean package -Dmaven.test.skip=true

# 或使用便捷脚本：
bin/package.bat    # 构建
bin/run.bat        # 运行（启动 RuoYiApplication）
bin/clean.bat      # 清理构建产物
```

构建后的可执行 JAR 位于 `ruoyi-admin/target/ruoyi-admin.jar`。

### 前端（Vue H5）
```bash
cd szzh-h5
npm install        # 安装依赖
npm run serve      # 开发服务器（dev 模式）
npm run build      # 生产环境构建
npm run build:dev  # 开发环境构建
```

## 架构

### Maven 模块结构
```
ruoyi/                    # 父 POM
├── ruoyi-admin/          # 主应用入口（RuoYiApplication）
├── ruoyi-framework/      # 框架核心（安全、配置、拦截器）
├── ruoyi-system/         # 系统管理（用户、角色、部门、菜单）
├── ruoyi-common/         # 通用工具类和基类
├── ruoyi-quartz/         # 定时任务支持
├── ruoyi-generator/      # 代码生成工具
└── ibs/                  # 自定义业务逻辑模块
```

### IBS 业务模块（`ibs/src/main/java/com/ruoyi/ibs`）
核心业务域包含以下子模块：

| 模块 | 功能说明 |
|------|---------|
| `app` | 企业微信（QYWeiXin）集成、认证 |
| `audio` | 音频录制和处理 |
| `cmpm` | 客户经理关系管理（移交、认领、调整） |
| `custmap` | 客户地图可视化和收藏位置 |
| `customerselect` | 客户筛选和基于 CSV 标签的选择 |
| `dashboard` | 仪表盘数据、营销活动、通知 |
| `datavisual` | 拜访轨迹和区域数据可视化 |
| `draw` | 地图绘制图层及审核工作流 |
| `grid` | 地理网格管理、虚拟网格、地址解析 |
| `list` | 客户列表（零售、商户）、家庭成员、营销活动 |
| `qxhy` | 第三方集成（清香和一） |
| `rules` | 业务关系规则引擎 |
| `tabs` | 客户详情标签页和列表信息 |
| `task` | 拜访任务、预约、工作记录、反馈 |

### 前端结构（`szzh-h5/src`）
```
views/
├── cart/           # 购物车功能
├── category/       # 分类管理
├── customer/       # 客户视图
├── dashboard/      # 仪表盘视图
├── grid/           # 网格管理视图
├── login/          # 认证登录
├── map/            # 地图功能
├── visitingTask/   # 拜访任务管理
└── workBench/      # 工作台视图
```

## 关键配置

### 环境配置文件
- `application.yml` - 基础配置
- `application-dev.yml` - 开发环境
- `application-pre.yml` - 预生产环境
- `application-uat.yml` - UAT 环境
- `application-pro.yml` - 生产环境

### 重要路径
- MyBatis Mapper 文件：`ibs/src/main/resources/mapper/**/*.xml`
- 类型处理器：`com.ruoyi.ibs.handler`
- 上传路径（Windows）：`D:/ruoyi/files/`
- 上传路径（Linux）：`/home/webapp/ruoyi/files/`

## 代码规范

### 后端包结构（每个模块）
```
com.ruoyi.ibs.{module}/
├── controller/      # REST 接口
├── domain/
│   ├── entity/      # 数据库实体（@TableName）
│   ├── dto/         # 请求 DTO
│   └── vo/          # 响应 VO
├── mapper/          # MyBatis Mapper
└── service/
    ├── I{Xxx}Service       # 接口
    └── impl/
        └── {Xxx}ServiceImpl # 实现
```

### 命名规范
- Controller 以 `Controller` 结尾
- Service 接口以 `I` 开头（如 `IGridService`）
- Service 实现以 `ServiceImpl` 结尾
- DTO 以 `DTO` 结尾（数据传输对象）
- VO 以 `VO` 结尾（视图对象）
- 实体类使用 `@TableName` 注解映射表名

## 认证与安全

- 基于 JWT 的认证，可配置令牌过期时间（默认 3000 分钟）
- Token 请求头：`Authorization`
- Spring Security 实现基于角色的访问控制
- 在 `/system/*`、`/monitor/*`、`/tool/*` 路径启用 XSS 过滤

## 开发注意事项

- 热部署默认禁用（`spring.devtools.restart.enabled: false`）
- `com.ruoyi` 包的日志级别为 `debug`
- 使用 Druid 连接池
- PageHelper 配置为 MySQL 分页方言
- 主应用入口：`ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java`