# CLAUDE.md

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

## 项目概述

**资金服务平台（FundPlatform）** — 多租户微服务架构的项目资金管理系统。

- **技术栈**: Java 21 + Spring Boot 3.2.0 + Spring Cloud Alibaba 2023.0.0.0 + MyBatis-Plus 3.5.5 + MySQL 8.0 + Redis
- **前端**: Vue 3 + TypeScript（管理后台用 Element Plus，移动端用 Vant）

## 常用命令

### 后端构建

```bash
# 构建所有模块（跳过测试）
mvn -q -DskipTests package

# 构建单个模块
mvn -q -DskipTests package -pl fund-sys -am

# 运行测试
mvn test

# 打包成 tar.gz 部署包（使用 Assembly）
mvn -q -DskipTests package -pl fund-sys -am -P assembly
```

### 前端开发

```bash
# 管理后台
cd fund-admin && npm install && npm run dev

# 移动端
cd fund-mobile && npm install && npm run dev

# 打包前端
./scripts/build-frontend.sh admin    # 或 mobile
```

### 本地环境

```bash
# 启动基础设施（MySQL、Redis、Nacos、Prometheus、Grafana）
docker-compose up -d

# 停止并清理
docker-compose down -v
```

## 模块结构

| 模块 | 端口 | 职责 |
|------|------|------|
| fund-common | — | 公共工具：Token、Redis、多租户上下文、统一响应 |
| fund-gateway | 8000 | API网关：路由、认证、限流 |
| fund-sys | 8100 | 系统服务：用户、角色、菜单、部门、租户管理 |
| fund-cust | 8200 | 客户管理 |
| fund-proj | 8300 | 项目与合同管理 |
| fund-req | 8400 | 需求工单 |
| fund-exp | 8500 | 支出管理 |
| fund-receipt | 8600 | 收款管理 |
| fund-report | 8700 | 报表统计 |
| fund-file | 8800 | 文件存储（腾讯云COS） |

## 代码架构

### 分层约定

每个业务服务模块遵循统一分层：

```
com.fundplatform.{module}/
├── controller/       REST API，返回 Result<T>
├── service/          业务逻辑
│   └── impl/
├── data/
│   ├── entity/       MyBatis-Plus 实体（对应数据库表）
│   ├── mapper/       Mapper 接口
│   └── service/      数据层服务（IService）
├── dto/              请求参数对象
├── vo/               响应视图对象
├── feign/            Feign 客户端（调用其他服务）
├── aop/              切面（操作日志等）
└── config/           模块配置
```

### 统一响应

所有接口使用 `fund-common` 中的 `Result<T>` 和 `PageResult<T>`：

```java
Result.success(data)
Result.success(data, "message")
Result.error("message")
```

### 基础实体

实体类继承 `BaseEntity`（包含 `id`、`tenantId`、`createdBy`、`createdTime`、`updatedBy`、`updatedTime`、`deleted`）。

### 认证机制

- Token 基于 UUID，存储在 Redis（Key: `auth:token:{token}`），有效期24小时
- 密码使用 MD5 加密（`Md5Util`）
- 请求头 `Authorization` 携带 Token，`X-Tenant-Id` 携带租户ID

## 多租户架构

核心设计：**一库多租户 + VIP专属实例混合模式**

1. **数据隔离**：所有业务表含 `tenant_id` 字段，MyBatis-Plus 租户插件自动注入 SQL 条件
2. **上下文传递**：`TenantContextHolder` 存储当前租户，通过 HTTP Header 传递，Feign 拦截器自动转发
3. **VIP专属实例**：Nacos 元数据 `tenant-id` 标记服务实例，`TenantAwareLoadBalancer` 将 VIP 租户路由到专属实例

```yaml
# Nacos 元数据配置（区分共享/专属实例）
spring.cloud.nacos.discovery.metadata:
  tenant-id: ${TENANT_ID:}    # 空=共享实例，有值=VIP专属
```

## 打包与部署

### 部署包结构

Maven Assembly 打包输出 tar.gz，解压后：

```
bin/    启动脚本（start.sh）
conf/   配置文件（application.yml、bootstrap.yml、logback-spring.xml、env.properties）
lib/    所有 JAR（依赖 + 应用本身）
```

> **注意**：根 pom.xml 禁用了 Spring Boot repackage，各服务的 fat jar 由 Assembly 统一管理。

### 数据库初始化

SQL 脚本位于 `doc/sql/`，执行顺序：
1. `01_create_user.sql` — 创建 MySQL 用户（fundsp / fundSP@123）
2. `02_grant_user.sql` — 授权
3. `fund_*_init.sql` — 各模块建表及初始数据

### 环境变量

关键变量在根目录 `.env` 文件中配置（MySQL、Redis、Nacos 连接信息、腾讯云COS凭证）。

## 服务间通信

使用 OpenFeign 声明式调用，`FeignChainInterceptor` 自动传递 `Authorization`、`X-Tenant-Id`、`X-Trace-Id` 等 Header。

```java
@FeignClient(name = "fund-sys")
public interface SysUserFeign {
    @GetMapping("/sys/user/{id}")
    Result<UserDto> getUserById(@PathVariable Long id);
}
```

## 注意事项

- **fund-gateway** 使用 WebFlux，不能引入 `spring-boot-starter-web`，须排除 fund-common 中的 web 自动配置
- **租户忽略**：特殊场景（如登录、租户管理）需用 `TenantIgnoreHelper` 标记绕过租户过滤
- **日志**：使用 Logback + Logstash Encoder，日志格式为 JSON，适配 ELK 收集