455a20c1df
新增内容： 1. 添加 AGENTS.md 和 CLAUDE.md AI 助手配置文件 2. 添加安全修复说明文档 (doc/security-fixes.md) 3. 新增单元测试用例： - fund-common: TenantContextHolderTest, UserContextHolderTest, PageResultTest, ResultTest - fund-sys: AuthServiceImplTest, RoleServiceImplTest, TenantServiceImplTest 修改内容： 1. 数据库初始化脚本更新 (fund_sys_init.sql) 2. 前端依赖更新 (package.json) 3. 登录和密码管理功能优化： - 管理后台和移动端登录页面 - 密码修改功能 4. 租户上下文处理优化 (TenantLineHandlerImpl) 5. 网关过滤器增强： - TenantGatewayFilter 租户过滤 - TokenAuthFilter 认证过滤 6. Controller 层代码优化 7. DTO 和 Service 层代码改进 技术改进： - 密码加密方式从 BCrypt 改为 MD5（前后端一致） - 登录验证流程优化，支持多租户 - 增加日志输出便于调试 - 代码规范性和可维护性提升
166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# 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 收集
|