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 依赖版本锁定

<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 配置

<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：

<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

❌ 错误示例：

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

✅ 正确示例：

@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 注解规范

@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_dept")
public class Dept extends BaseEntity {
    // 必须确保 import lombok.Data 和 import lombok.EqualsAndHashCode 存在
}

3.3 Controller/Component Lombok 注解

@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 日志规范

// 业务操作日志
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 基类

@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 统一响应格式

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 编译命令

# 清理编译
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 接口正常

---

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