fundplatform/开发规则清单.md

# 资金服务平台 - 开发规则清单

> **创建时间**: 2026-02-17  
> **用途**: 重新生成代码前的规范和约束  
> **版本**: v1.0

---

## 1. 技术栈规范

### 1.1 核心框架
- **Java**: 21
- **Spring Boot**: 3.2.0
- **Spring Cloud**: 2023.0.0
- **认证框架**: Apache Shiro 2.0.0（必须，不使用 Spring Security）
- **数据库连接池**: HikariCP
- **ORM框架**: MyBatis-Plus 3.5.6

### 1.2 依赖版本锁定
```xml
<lombok.version>1.18.30</lombok.version>
<shiro.version>2.0.0</shiro.version>
<jwt.version>4.4.0</jwt.version>
<hutool.version>5.8.23</hutool.version>
<mybatis-plus.version>3.5.6</mybatis-plus.version>
```

### 1.3 禁用的依赖
- ❌ `spring-boot-starter-security`
- ❌ Shiro 1.x（不兼容 Spring Boot 3）

---

## 2. Maven 多模块配置规范

### 2.1 父 POM 配置
```xml
<pluginManagement>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version>
            <configuration>
                <source>21</source>
                <target>21</target>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</pluginManagement>
```

### 2.2 子模块 POM 配置
**每个子模块都必须显式激活 maven-compiler-plugin**：
```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version>
            <configuration>
                <source>21</source>
                <target>21</target>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
```

### 2.3 依赖冲突检查
- ⚠️ 避免在 pom.xml 中重复声明同一依赖
- ⚠️ 使用 `mvn dependency:tree` 检查依赖冲突

---

## 3. Lombok 使用规范

### 3.1 禁止在继承 ServiceImpl 的类上使用 @Slf4j

**❌ 错误示例**：
```java
@Slf4j
@Service
public class DeptService extends ServiceImpl<DeptMapper, Dept> {
    public void saveDept(Dept dept) {
        log.info("保存部门"); // 编译错误！
    }
}
```

**✅ 正确示例**：
```java
@Service
public class DeptService extends ServiceImpl<DeptMapper, Dept> {
    private static final Logger logger = LoggerFactory.getLogger(DeptService.class);
    
    public void saveDept(Dept dept) {
        logger.info("保存部门");
    }
}
```

**原因**: MyBatis-Plus 的 ServiceImpl 基类已定义 `protected Log log`（org.apache.ibatis.logging.Log），与 Lombok @Slf4j 生成的字段冲突。

### 3.2 实体类 Lombok 注解规范
```java
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_dept")
public class Dept extends BaseEntity {
    // 必须确保 import lombok.Data 和 import lombok.EqualsAndHashCode 存在
}
```

### 3.3 Controller/Component Lombok 注解
```java
@RestController
@RequestMapping("/api/v1/dept")
@RequiredArgsConstructor  // 推荐用于依赖注入
public class DeptController {
    private final DeptService deptService;
}
```

---

## 4. Shiro 认证框架规范

### 4.1 核心组件清单
1. **JwtToken.java** - 自定义 Token 类
2. **JwtRealm.java** - 认证授权域
3. **JwtFilter.java** - JWT 过滤器
4. **ShiroConfig.java** - Shiro 配置类
5. **PasswordEncoderConfig.java** - 密码编码器（使用 BCrypt）

### 4.2 权限注解规范
- ✅ 使用 `@RequiresRoles("ADMIN")`
- ✅ 使用 `@RequiresPermissions("system:user:view")`
- ❌ 不使用 Spring Security 注解（@PreAuthorize）

### 4.3 认证流程
1. 用户登录 → 查询数据库
2. BCrypt 验证密码
3. 生成 JWT Token（包含 userId, username, tenantId）
4. 每次请求通过 JwtFilter 验证 Token
5. JwtRealm 加载用户权限

---

## 5. 代码编写规范

### 5.1 分层架构
```
Controller → Service → Mapper → Database
    ↓          ↓
   DTO        Entity
```

### 5.2 包结构规范
```
com.fundplatform.sys
├── controller      # 控制器层
├── service         # 业务逻辑层
├── mapper          # 数据访问层
├── entity          # 实体类
├── dto             # 数据传输对象
├── vo              # 视图对象
├── security        # 安全相关（Shiro配置）
├── config          # 配置类
└── util            # 工具类
```

### 5.3 命名规范
- **Entity**: 单数名词，如 `User.java`、`Dept.java`
- **Mapper**: 实体名 + Mapper，如 `UserMapper.java`
- **Service**: 实体名 + Service，如 `UserService.java`
- **Controller**: 实体名 + Controller，如 `UserController.java`

### 5.4 日志规范
```java
// 业务操作日志
logger.info("[ServiceName] 业务操作描述: {}, 参数: {}", entity.getName(), param);

// 错误日志
logger.error("[ServiceName] 操作失败: {}", errorMessage, exception);
```

---

## 6. 数据库规范

### 6.1 表命名规范
- 系统表前缀: `sys_`（如 `sys_user`, `sys_role`）
- 业务表前缀: `biz_`（如 `biz_project`, `biz_fund`）

### 6.2 字段规范
- 主键: `主表名_id`（如 `user_id`, `dept_id`）
- 租户ID: `tenant_id`（必须字段，默认值 1）
- 软删除: `deleted`（0-未删除，1-已删除）
- 状态: `status`（1-启用，0-禁用）
- 时间: `created_time`, `updated_time`

### 6.3 BaseEntity 基类
```java
@Data
public class BaseEntity implements Serializable {
    private Long tenantId;      // 租户ID
    private Integer deleted;     // 删除标记
    private LocalDateTime createdTime;   // 创建时间
    private Long createdBy;      // 创建人
    private LocalDateTime updatedTime;   // 更新时间
    private Long updatedBy;      // 更新人
}
```

---

## 7. API 规范

### 7.1 RESTful 路径规范
```
GET    /api/v1/dept          # 查询列表
GET    /api/v1/dept/{id}     # 查询单个
POST   /api/v1/dept          # 创建
PUT    /api/v1/dept/{id}     # 更新
DELETE /api/v1/dept/{id}     # 删除
```

### 7.2 统一响应格式
```java
public class Result<T> {
    private Integer code;    // 200-成功，其他-失败
    private String message;
    private T data;
}
```

### 7.3 认证路径规范
```
POST /api/v1/auth/login      # 登录（不需要认证）
POST /api/v1/auth/logout     # 登出
POST /api/v1/auth/refresh    # 刷新Token
```

---

## 8. 多租户规范

### 8.1 租户隔离
- 所有业务表必须包含 `tenant_id` 字段
- Service 层插入数据时自动设置 `tenant_id`
- 查询时自动过滤 `tenant_id`

### 8.2 默认租户
- 系统租户: `tenant_id = 0`
- 业务租户: `tenant_id >= 1`

---

## 9. 编译和测试规范

### 9.1 编译命令
```bash
# 清理编译
cd /home/along/MyCode/wanjiabuluo/fundplatform/fundplatform
mvn clean compile -DskipTests

# 安装到本地仓库
mvn clean install -DskipTests

# 编译单个模块
mvn clean compile -pl fund-sys -am -DskipTests
```

### 9.2 禁止的操作
- ❌ 不要在 run_in_terminal 中重复 `cd` 到同一目录
- ❌ 不要使用 `mvn clean` 后立即执行其他命令（应分开执行）

---

## 10. Git 规范

### 10.1 分支策略
- `main` - 生产分支
- `develop` - 开发分支
- `feature/*` - 功能分支
- `bugfix/*` - 修复分支

### 10.2 提交规范
```
feat: 新功能
fix: 修复bug
refactor: 重构
docs: 文档更新
style: 代码格式调整
test: 测试相关
chore: 构建/工具链相关
```

---

## 11. 常见陷阱清单

### 11.1 Lombok 相关
- ✓ 每个子模块必须显式配置 maven-compiler-plugin
- ✓ 继承 ServiceImpl 的类不能使用 @Slf4j
- ✓ 确保所有 import lombok.* 语句存在

### 11.2 Shiro 相关
- ✓ 使用 Shiro 2.0.0（支持 jakarta.servlet）
- ✓ 保留 spring-security-crypto（用于 BCrypt）
- ✓ 登录接口路径配置为匿名访问

### 11.3 Maven 相关
- ✓ 避免在 pom.xml 中重复声明依赖
- ✓ 父 pom 中未创建的子模块需注释掉
- ✓ 使用 `-U` 参数强制更新依赖

### 11.4 数据库相关
- ✓ 初始化 SQL 主键必须与字段定义一致
- ✓ tenant_id 必须有默认值保障机制
- ✓ 软删除字段 deleted 默认为 0

---

## 12. 重新生成代码的策略

### 12.1 代码生成工具选择
**选项 A**: MyBatis-Plus 代码生成器
- 优点: 自动生成 Entity、Mapper、Service、Controller
- 缺点: 需要手动调整生成的代码

**选项 B**: 手动编写
- 优点: 完全可控，符合规范
- 缺点: 工作量大

**选项 C**: 模板化生成
- 优点: 可重复使用，质量稳定
- 缺点: 需要先建立模板

### 12.2 推荐策略
1. **第一步**: 手动编写核心基础类（BaseEntity、Result、自定义异常）
2. **第二步**: 使用 MyBatis-Plus 生成器生成基础 CRUD
3. **第三步**: 手动完善业务逻辑和复杂查询
4. **第四步**: 编写单元测试验证

### 12.3 生成顺序
```
1. fund-common (基础类)
   ├── BaseEntity
   ├── Result
   └── 工具类

2. fund-sys (系统模块)
   ├── 实体类 (Entity)
   ├── Mapper 接口
   ├── Service 实现
   ├── Controller
   └── Shiro 配置

3. fund-gateway (网关)
   └── 路由配置

4. fund-cust (客户模块)
5. fund-proj (项目模块)
```

---

## 13. 架构约束

### 13.1 必须遵守的架构要求
1. ✅ 使用 Shiro 作为认证框架（架构文档要求）
2. ✅ 实现多租户数据隔离
3. ✅ Header 透传（X-Uid, X-Uname）
4. ✅ 全链路日志追踪

### 13.2 性能要求
- 接口响应时间 < 500ms
- 数据库查询使用索引
- 使用 Redis 缓存热点数据

---

## 14. 下一步行动

### 14.1 准备工作
- [ ] 备份当前代码
- [ ] 清理所有 target 目录
- [ ] 确认数据库表结构
- [ ] 准备初始化 SQL 脚本

### 14.2 代码生成
- [ ] 生成 fund-common 基础类
- [ ] 生成 fund-sys 实体类和 Mapper
- [ ] 实现 Shiro 认证框架
- [ ] 编写核心业务逻辑

### 14.3 验证
- [ ] 编译通过（mvn clean compile）
- [ ] 启动成功
- [ ] 登录功能正常
- [ ] 基础 CRUD 接口正常

---

**注意**: 本规则清单将持续更新，每次遇到问题都会添加到"常见陷阱清单"中。