# 平台后端服务（I1 骨架）

与 **`java/craftlabs-auth-*` SDK 分构建线**，坐标 `cn.craftlabs.platform`，**不依赖** `craftlabs-auth-bitanswer`。

- **部署与运维**：[RUNBOOK.md](RUNBOOK.md)
- **OpenAPI 契约（SSOT）**：[../contracts/README.md](../contracts/README.md)
- **误依赖门禁**：`maven-enforcer-plugin`（`validate`）+ CI `dependency:tree` 扫描 `craftlabs-auth-bitanswer`

| 模块 | 端口 | 说明 |
|------|------|------|
| `license-webhook-ingress` | 8081 | `POST /webhook/bitanswer/callback`，头 `x-bitanswer-token`（可选 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN`）；**Flyway** 建表 `webhook_callback_receipt`，**Idempotency-Key** 落库幂等 |
| `delivery-platform-api` | 8080 | **M1**：`GET|POST /api/v1/customers`、`GET|PUT|DELETE /api/v1/customers/{id}`（DELETE 软删 → `INACTIVE`）；`GET|POST /api/v1/projects`、`GET|PUT|DELETE /api/v1/projects/{id}`（DELETE 物理删）；`GET /api/v1/dictionaries/{type}`；另 `POST /api/v1/auth/login`、`GET /api/v1/ping`、JWT `Authorization: Bearer`、**OpenAPI** `/swagger-ui.html`；**Flyway** 表 `flyway_platform_api` |

生产须设置 **`PLATFORM_JWT_SECRET`**（≥32 字符）。

## I2 / M1（客户与项目）

| 路径 | 说明 |
|------|------|
| `/api/v1/customers` | 客户分页 CRUD（删除为软删 `INACTIVE`） |
| `/api/v1/projects` | 项目分页 CRUD（删除为物理删除） |
| `/api/v1/dictionaries/{type}` | 字典项，如 `PROJECT_PHASE` |

Flyway 历史表：`delivery-platform-api` → **`flyway_platform_api`**；`license-webhook-ingress` → **`flyway_webhook`**。

## 构建 Fat JAR

```bash
mvn -f services/pom.xml -pl license-webhook-ingress -am clean package
mvn -f services/pom.xml -pl delivery-platform-api -am clean package
```

产物：`*/target/*.jar`（spring-boot-maven-plugin repackage）。

## Spring Boot 版本

父 POM 当前为 **3.4.5**（易解析）；产品目标 **4.0.\*** 时升级 `services/pom.xml` 中 `spring-boot.version` 并全量回归。

## 数据层（架构约定）

| 项 | 说明 |
|----|------|
| **数据库** | **PostgreSQL 15** |
| **ORM** | **MyBatis-Plus**（`mybatis-plus-spring-boot3-starter`，版本见父 POM `mybatis-plus.version`） |

本地起库：`docker compose -f services/docker-compose.yml up -d`，默认库名 `craftlabs_platform`、用户/密码 `craftlabs`/`craftlabs`，与 `delivery-platform-api` 的 `application.yml` 默认值一致。  
Maven 单测使用 **H2（PostgreSQL 兼容模式）**，不强制本机安装 PostgreSQL。

## 环境变量（数据源，可选）

覆盖默认 JDBC 时使用：`SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD`。