# conti-backend

Continental 门店零售 App 的后端服务。**模块化单体**：14 个 Gradle 模块，一个可部署 jar，
模块边界由 Gradle 依赖图 + ArchUnit 测试守着，将来要拆微服务时按模块切即可。

架构决策全部写在 [`conti-docs/backend/`](../conti-docs/backend/) 的 12 篇文档里，
本仓库是那些决策的落地。**文档是唯一事实来源**——代码和文档不一致时，改代码，不是改文档，
也不是把 ArchUnit 规则调松（规则调松了这套结构就白建了）。

## 版本基线

| | 版本 |
| --- | --- |
| Java | 21（toolchain） |
| Kotlin | 2.4.10 |
| Spring Boot | 4.1.0 |
| Spring Cloud | 2025.1.2 |
| Gradle | 9.5.1（wrapper） |
| MySQL | 8.4 |

版本对齐一律走 Gradle 原生 `platform()` BOM，**不引** `io.spring.dependency-management` 插件。

## 模块结构

```
bootstrap                      入口 + 全部 application*.yml；唯一产出 jar 的模块
architecture-test              ArchUnit 规则 + 原生 SQL 跨库扫描

platform/                      横切基础设施。互相之间只能依赖 platform-web
  platform-web                 ApiResult / ErrorCode / 全局异常处理 / 幂等 / AuditContext
  platform-security            JWT 签发与校验 / StoreContextHolder / SecurityConfig
  platform-persistence         BaseEntity / JPA 审计 / 多实例 Flyway / 调度 / 缓存
  platform-observability       traceId 桥接 / @Audited 审计日志 / logback-spring.xml
  platform-integration         RestClientFactory / 连接池与超时 / trace 透传

domains/                       业务域。**domain 之间不许直接依赖**
  identity-store               认证与门店（本骨架里唯一实现完整的纵切）
  identity-store-contract      给别的 domain 用的只读契约，不含 Spring Web / JPA
  workbench                    工作台聚合（并行聚合 + 按 tile 降级的示例）
  webview-ticket               WebView 票据（domain 层 + 领域事件的示例）
  bff-orchestration            预留空模块，暂无代码

integration/                   外部系统适配器
  f6-adapter                   F6（Bulkhead + CircuitBreaker + Retry + fallback）
  mini-clients                 小程序侧 O2O 等
```

### 依赖规则（由 `architecture-test` 强制）

```
api → application → domain
              ↘ infrastructure ↗

domains/A ─X─> domains/B          直接依赖：禁止
domains/A ───> domains/B-contract 只读查询：允许
domains/A ~~~> ApplicationEvent   写操作/状态联动：@TransactionalEventListener(AFTER_COMMIT)
```

具体 10 条规则见
[`architecture-test/.../ArchitectureRulesTest.kt`](architecture-test/src/test/kotlin/com/continental/retailapp/architecture/ArchitectureRulesTest.kt)，
每条规则的注释里都写了它对应文档的哪一节。几条最容易踩的：

- Entity 只能待在 `infrastructure` 包里，`api` 层碰不到 Entity；
- `domain` 层不许出现 Spring / JPA 的任何引用，它的 bean 由 `infrastructure/config/` 显式 `@Bean` 装配；
- Controller 的端点方法必须返回 `ApiResult`；
- 不许字段注入（`@Autowired` 到字段上）；
- 不许用 `java.util.Date` / `Calendar` / `SimpleDateFormat`，时间一律 `Instant`（UTC）。

## 本地怎么跑

只有 MySQL 跑在 Docker 里，应用本身用 Gradle 跑，断点和热重载都还在：

```bash
docker compose up -d mysql
SPRING_PROFILES_ACTIVE=local ./gradlew :bootstrap:bootRun
```

- 建库脚本在 `docker/mysql/init/`，表结构由 Flyway 建（本地和 dev/uat/prod 是同一套迁移脚本）。
- `local` profile 关掉了 Spring Cloud Kubernetes，不需要任何 K8s 环境。
- 种子数据由 `LocalSeedDataConfig` 在启动时写入（账号 `demo` / `demo1234`，两家门店），
  **只在 `local` profile 下存在**——种子数据绝不写进 Flyway 脚本，那些脚本在 dev/uat/prod 也会跑。
- Swagger UI：<http://localhost:8080/swagger-ui.html>（`local`/`dev`/`uat` 开，`prod` 关）。

数据库要重来一遍：

```bash
docker compose down -v && docker compose up -d mysql
```

## 构建与测试

```bash
./gradlew build -PexcludeIntegration   # 编译 + 单测 + ArchUnit，不需要 Docker，约 1 分钟
./gradlew build                        # 完整，含 Testcontainers / WireMock（CI 跑这个）
```

需要真实 MySQL 或 WireMock 的测试都打了 `@Tag("integration")`，`-PexcludeIntegration` 会跳过它们。
本地日常改代码用前者，提 MR 前跑一次后者。

## 部署

| 环境 | 跑在哪 | 走 CI/CD | 怎么部署 |
| --- | --- | --- | --- |
| local | 自己电脑 | 否 | 见上面 |
| dev | 内网 Ubuntu 上的 k3s | 否 | `./scripts/deploy-dev.sh <commit-sha>`（先连 VPN） |
| uat / prod | Azure Private AKS | 是 | 打 protected tag → GitLab 手动点 Promote |

- 镜像里**不编译代码**：`Dockerfile` 直接消费 CI `validate` 阶段产出的 jar，
  保证部署的字节就是被测试验证过的字节。
- **一个镜像走所有环境**，环境差异只在 ConfigMap / Secret / `SPRING_PROFILES_ACTIVE`。
- 真实密钥不在这个仓库里的任何一个文件中。`k8s/secret-uat.yaml` 里只有 `__injected_by_pipeline__`
  占位符，真值由流水线从 Azure Key Vault 现取现渲染。

k8s 清单在 `k8s/`，流水线在 `.gitlab-ci.yml`。
`lint`（ktlint/detekt）和覆盖率两个 job 目前**以注释形式留着**——插件还没接，
放开就是必红；文件里写了启用需要补什么。

## 新增一个 domain 要接线的地方

漏掉任何一处，症状都不明显（编译过、启动过，但 Flyway 不跑、ArchUnit 不检查），所以逐条对：

1. **`settings.gradle`** 加 `include 'domains:xxx'`，并写 `domains/xxx/build.gradle`
   ——只依赖 `platform-*` 和别的 domain 的 `-contract`，**不许**依赖别的 domain 本身。
2. **`bootstrap/build.gradle`** 加 `implementation project(':domains:xxx')`，
   否则这个模块根本不会被打进 jar。
3. **`DomainFlywayConfig.DOMAIN_SCHEMAS`** 加库名，并建
   `domains/xxx/src/main/resources/db/migration/<库名>/V1__init.sql`
   ——Flyway 的 location 不能是空目录；同时在 `docker/mysql/init/01-create-databases.sql` 里加建库语句。
4. **`architecture-test`**：`ArchitectureRulesTest.domains` 加包名（如 `xxx`），
   `NativeQueryScanTest.ownerByModule` 加 `"xxx" to "<库名>"`
   ——不加的话跨域依赖和跨库 SQL 这两条规则对新模块是完全失效的。

前三步是"能跑起来"，第四步是"边界还守得住"。

## 一些容易踩的坑

- **Boot 4 的包名搬过家**：`@DataJpaTest` 在 `org.springframework.boot.data.jpa.test.autoconfigure`，
  `@AutoConfigureTestDatabase` 在 `org.springframework.boot.jdbc.test.autoconfigure`，
  都要单独引 `spring-boot-starter-data-jpa-test`；`spring-boot-starter-aop` 改叫 `spring-boot-starter-aspectj`。
- **Gradle 9 不再自带 JUnit Platform launcher**，根 `build.gradle` 里那行
  `testRuntimeOnly 'org.junit.platform:junit-platform-launcher'` 删掉的话所有 test 任务会直接失败。
- **已经执行过的 Flyway 脚本不可修改**，改了 checksum 对不上，下次启动直接 `Validate failed`。
  要改就新写一个版本号更大的脚本，这条对 Dev 环境同样适用。
- **每个迁移脚本必须前向兼容**：`maxUnavailable: 0` 意味着滚动更新期间新旧两版 Pod 连同一个库，
  删列改列一律走 expand-contract 两次发布。
- **门店维度的查询一律用 `StoreContextHolder.currentStoreId()`**，绝不用请求参数里的 storeId
  ——那是越权查询的标准入口。