rui-docs/backend/业务应用模块创建规则.md

# 业务应用模块创建规则

> 在 `app/` 目录下创建业务模块，按子模块模式拆分。
> `app/` 目录整体不提交到 git。

## 模块结构

```
app/
├── pom.xml                           # 聚合所有业务模块
└── rui-{领域}/
    ├── pom.xml                       # 领域聚合 POM
    ├── rui-{领域}-api/               # [可部署] REST API 服务（有 main Class）
    ├── rui-{领域}-common/            # [库] DTO、枚举、配置、工具
    ├── rui-{领域}-core/              # [库] Mapper、Entity、Service（数据库层）
    ├── rui-{领域}-provider/          # [库] 第三方集成（可选）
    └── rui-{领域}-task/              # [库] MQ 监听器 + 定时任务（可选）
```

### 三模块（最小配置）

| 模块 | 类型 | 作用 |
|------|------|------|
| `-api` | 可部署 | REST 控制器、启动类、application.yml |
| `-common` | 库 | DTO、VO、枚举、常量、配置属性 |
| `-core` | 库 | Mapper、Entity、Service（MyBatis Plus） |

### 五模块（含第三方集成和异步任务）

| 模块 | 类型 | 作用 |
|------|------|------|
| `-provider` | 库（可选） | 第三方 SDK/API 封装（支付、短信、AI 等） |
| `-task` | 库（可选） | MQ 监听器、定时任务、异步处理 |

## 包命名

```
com.rui.{领域}.api          # api 模块
com.rui.{领域}              # common 模块
com.rui.{领域}.core         # core 模块
com.rui.{领域}.provider     # provider 模块
com.rui.{领域}.task         # task 模块
```

## POM 层级

```
app/pom.xml                 → parent: rui-parent (不加 relativePath)
  └── rui-{领域}/pom.xml    → parent: rui-app
        ├── rui-{领域}-api/ → parent: rui-{领域}
        ├── rui-{领域}-common/
        ├── rui-{领域}-core/
        ├── rui-{领域}-provider/  （可选）
        └── rui-{领域}-task/      （可选）
```

> `<relativePath>` 一律不加，Maven 自动从本地仓库查找父 POM。

## 依赖关系

```
common ——→ rui-common-core
core ———→ rui-common-mybatis, rui-common-security, common
api ———→ core, rui-common-security, rui-common-web
provider → common
task ———→ core, common
```

- **框架依赖**（`rui-common-*`）：版本由 `rui-parent` BOM 管理，不加 `<version>`
- **内部模块依赖**（`rui-{领域}-*`）：加 `<version>${project.version}</version>`

## app/pom.xml 模板

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>com.rui</groupId>
        <artifactId>rui-parent</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>rui-app</artifactId>
    <packaging>pom</packaging>

    <name>rui-app</name>
    <description>睿核科技 — 业务应用模块聚合</description>

    <modules>
        <module>rui-payment</module>
        <!-- 新增模块在此添加 -->
    </modules>
</project>
```

## api 模块 POM 模板

```xml
<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>com.rui</groupId>
        <artifactId>rui-{领域}-core</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>com.rui</groupId>
        <artifactId>rui-common-security</artifactId>
    </dependency>
    <dependency>
        <groupId>com.rui</groupId>
        <artifactId>rui-common-web</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>repackage</id>
                    <goals><goal>repackage</goal></goals>
                    <configuration><attach>true</attach></configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

## 启动类模板

```java
package com.rui.{领域}.api;

import com.rui.common.security.annotation.EnableResourceServer;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableResourceServer
public class {Domain}ApiApplication {
    public static void main(String[] args) {
        SpringApplication.run({Domain}ApiApplication.class, args);
    }
}
```

## 日志配置模板

api 模块需复制日志配置文件：

```bash
cp docs/logback-spring-template.xml \
   app/rui-{领域}/rui-{领域}-api/src/main/resources/logback-spring.xml
```

- 无需修改，自动读取 `spring.application.name` 作为日志目录名
- 按级别分文件（debug / info / warn / error）
- 控制台彩色输出，dev 环境显示 DEBUG

## 注意事项

1. **`app/` 目录加入 `.gitignore`**，业务模块不提交到框架仓库
2. api 模块需配置 `@EnableResourceServer`（资源服务器模式）
3. **各模块 Bean 通过 `AutoConfiguration.imports` 自动注入**，不在启动类上使用 `scanBasePackages`（参见下方「模块 Bean 注入规范」）
4. Mapper 扫描由 `rui-common-mybatis` 统一处理（`@MapperScan("com.rui.**.mapper")`），各模块无需重复配置
5. 白名单 URL 通过 `security.oauth2.ignore-urls` 在 Nacos 配置
6. 本地开发配置如 `config/application-dev.yml` 也需 gitignore

## Git 规则

业务应用模块（`app/` 目录下的模块）使用**独立的 Git 仓库**管理，与框架主仓库完全分离。

### 仓库初始化

```bash
cd app/rui-{领域}
git init
git add .
git commit -m "feat(init): 初始化{领域}模块"
git remote add origin git@gitee.com:pigeon/rui-{领域}.git
git push -u origin master
```

### 提交规范

与框架主仓库一致：

- **格式**：`type(scope): 中文描述`
- **type**：`feat`（新功能）、`fix`（修复）、`docs`（文档）、`refactor`（重构）、`chore`（构建）
- **示例**：`feat(payment): 添加支付宝下单接口`

### 推送规则

- **本地开发**：修改后自动 `git commit`，但不自动推送
- **推送时机**：由开发者手动执行 `git push`，或在完成阶段性开发后统一推送
- **自动推送阈值**：当未推送提交数 **超过 10 个** 时，自动推送到远程
- **禁止**：将业务模块代码提交到框架主仓库（`app/` 已加入 `.gitignore`）

### 与框架主仓库的关系

```
spring-ai/                          # 框架主仓库（git）
├── backend/                        # 提交到框架仓库
├── docs/                           # 提交到框架仓库
├── app/                            # 不提交到框架仓库（.gitignore）
│   └── rui-payment/                # 独立 Git 仓库
│       ├── .git/                   # 独立的 git 历史
│       └── ...
```

## 模块 Bean 注入规范

### `@SpringBootApplication` 禁止扩大扫描范围

**API 启动类上的 `@SpringBootApplication` 不得使用 `scanBasePackages` 参数扩大包扫描范围。**

- 错误示例：`@SpringBootApplication(scanBasePackages = {"com.rui.payment"})`
- 正确示例：`@SpringBootApplication`

启动类应仅扫描自身所在包（`com.rui.{领域}.api`）及其子包。

### 跨模块 Bean 通过 AutoConfiguration 注入

其他模块需要暴露给 Spring 容器的 Bean（`@Service`、`@Component`、`@Mapper` 等），**由各模块自行通过 `AutoConfiguration.imports` 注册**。

**实现方式**：

1. 在模块中创建自动配置类（通常在 `config` 包下）：

```java
package com.rui.{领域}.core.config;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.ComponentScan;

@AutoConfiguration
@ComponentScan("com.rui.{领域}.core")
public class PaymentCoreAutoConfiguration {
}
```

2. 在模块的 `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 中注册：

```
com.rui.{领域}.core.config.PaymentCoreAutoConfiguration
```

**原则**：
- 每个可复用模块（core、provider、task）必须有自己的 `AutoConfiguration`
- 启动类只需引入依赖，无需关心其他模块的包路径
- `rui-common-mybatis` 已通过 `AutoConfiguration.imports` 自动注入并包含 `@MapperScan("com.rui.**.mapper")`，各模块无需重复配置 Mapper 扫描

## Controller 路径规范

### URL 格式

```
/{模块}/{功能}/{方法}
```

例如：`/payment/trade/create`、`/order/refund/query`

### 控制器分类

| 控制器命名 | 路径 | 认证 | 说明 |
|-----------|------|------|------|
| `XxxController` | `/{模块}/{功能}/*` | 需认证 | 常规业务接口 |
| `XxxEntryController` | `/{模块}/entry/**` | 免认证 | 对外入口（收银台、H5 等） |
| `XxxNotifyController` | `/{模块}/notify/**` | 免认证 | 第三方回调（支付、消息等） |
| `XxxInnerController` | `/{模块}/inner/**` | 通过 `@Inner` 注解控制 | 内部 Feign 调用 |

### Nacos 白名单配置

```yaml
# Spring Boot 4 使用 PathPattern，不支持 /**/ 中间通配
# 需按模块显式列出白名单路径
security:
  oauth2:
    ignore-urls:
      - /payment/entry/**
      - /payment/notify/**
      - /user/entry/**
      - /actuator/**
```

### 示例

```java
// 常规接口 — 需认证
@RestController
@RequestMapping("/payment/trade")
public class PaymentTradeController {
    @PostMapping("/create")
    public R<Trade> create(@RequestBody TradeRequest req) { ... }
}

// 对外入口 — 免认证
@RestController
@RequestMapping("/payment/entry")
public class PaymentEntryController {
    @PostMapping("/alipay")
    public R<PayResult> alipay(@RequestBody PayRequest req) { ... }
}

// 第三方回调 — 免认证
@RestController
@RequestMapping("/payment/notify")
public class PaymentNotifyController {
    @PostMapping("/alipay")
    public String alipayNotify(HttpServletRequest request) { ... }
}

// 内部调用 — @Inner 保护
@RestController
@RequestMapping("/payment/inner")
public class PaymentInnerController {
    @Inner
    @GetMapping("/trade/{id}")
    public Trade getTrade(@PathVariable Long id) { ... }
}
```