# 青核后端（qinghe-backend）

青核是一个校园社交与服务平台，提供用户、动态、话题讨论、组局活动、好友与群聊、通知、认证和内容审核等能力。本仓库是青核项目的后端与工程协作仓库，不包含 App / Web 前端源码。

首次独立部署请阅读 [本地部署说明](方案分析与实现（md）文件/部署说明-本地部署.md)，使用脱敏模板与专用启动器。下文普通 IDEA/JAR 启动用于已有安全配置的开发环境。

## 当前交付基线

| 项目 | 当前状态 |
| --- | --- |
| 后端模块 | `campus-server`，包根 `com.campus` |
| 默认端口 | `8009` |
| 业务接口前缀 | `/api` |
| 构建产物 | `campus-server/target/campus-server-1.0.0.jar` |
| 数据库迁移 | `campus-server/src/main/resources/db/migration/`；当前 Flyway 关闭，脚本不会自动执行 |
| 接口契约 | 运行时 Swagger / OpenAPI；内部专题接口资料由维护者单独提供 |
| 自动化测试 | 以当前源码执行 `mvn test` 或 `mvn clean verify` 的结果为准 |
| 部署与验收边界 | 见本仓库的本地部署说明；内部工作记录和开发规范不随源码公开 |

2026-10-21 部署材料验证：`mvn -Pportable clean verify` 通过，496 用例 / 0 失败 / 0 错误 / 0 跳过；启动器离线检查及 Compose 静态校验通过。尚未执行 Docker 实机启动、全新空库或第三方服务验收，详细边界见本地部署说明。

## 仓库结构

```text
qinghe-backend/
├─ campus-server/                  Spring Boot 后端模块
│  ├─ pom.xml                      Maven 构建配置
│  ├─ .env.example                 环境变量占位示例
│  ├─ compose.local.yml            独立本地基础设施及可选后端容器
│  ├─ Start-Local.ps1              独立配置启动器
│  └─ src/
│     ├─ main/java/com/campus/      Controller、Service、实体、持久层与配置
│     ├─ main/resources/           应用配置与 db/migration/ 迁移脚本
│     └─ test/java/com/campus/      后端测试
├─ 方案分析与实现（md）文件/
│  └─ 部署说明-本地部署.md         随源码提供的部署与验收说明
└─ README.md                       项目入口与启动、联调说明
```

目录位置沿用现有工作区。其他内部方案、工作记录、`AGENTS.md`、真实应用配置和 `gitea-upload/` 保留在维护者本地，不随本次源码发布。

## 技术栈

- Java 8 编译目标，本地可使用 JDK 17 / 21 构建运行。
- Spring Boot **2.7.18**。
- Spring MVC、Spring Security、Spring Data JPA / Hibernate，使用 `javax.*`。
- MySQL、Redis、RabbitMQ；Flyway 依赖已引入，当前配置关闭自动迁移。
- 环信 IM，阿里云 OSS、VOD、推送、OCR 和短信。
- Maven、JUnit 5、Mockito。
- SpringDoc OpenAPI UI 1.7.0。

## 环境准备

开发机需要安装 JDK 和 Maven，并可在 PowerShell 中执行：

```powershell
java -version
mvn -version
```

后端启动需要数据库、Redis、RabbitMQ、JWT 等配置，以及对应业务使用的第三方服务配置。使用团队通过安全渠道提供的配置或在运行环境中注入对应 Spring 配置项。不要将真实密码、JWT secret、Token 或云服务密钥写入 README、脚本、日志或 Git。

仓库存在两份应用配置：

- `campus-server/src/main/resources/application.yml`：模块内的应用配置，IDEA 启动时加载，构建时打入 JAR。
- 根目录 `application.yml`：外部应用配置；按下文从仓库根目录运行 JAR 时默认加载，同名配置项优先于 JAR 内配置。

两份配置涉及共同配置项时必须同步维护。启动前确认工作目录和实际连接环境；配置文件被 Git 忽略，拉取源码后需单独准备。

另提供不含真实凭据的 [application.example.yml](campus-server/src/main/resources/application.example.yml) 和 [.env.example](campus-server/.env.example)。不要覆盖现有真实配置；新部署者按部署说明复制私有 `.env` 并填写自己的配置。万能验证码在模板中默认关闭，未接入云服务时相关功能不可用。

## 基础设施准备

独立开发环境使用现有模块目录下的 [compose.local.yml](campus-server/compose.local.yml)，提供 MySQL、Redis、RabbitMQ，不调整其他文件位置。先准备私有 `.env` 并启动 Docker Desktop，再在 `campus-server` 目录执行：

```powershell
docker compose --env-file .env -f compose.local.yml up -d mysql redis rabbitmq
docker compose --env-file .env -f compose.local.yml ps
```

等待三个服务 healthy 后启动后端。宿主机默认端口分别为 `13306/16379/15672`，RabbitMQ 管理页端口为 `15673`。数据保留、首次初始化及可选后端容器步骤见本地部署说明。当前尚未完成 Docker 实机与全新空库验收。

## 启动后端

### 构建并验证

以下命令从仓库根目录执行，进入模块后完成编译、测试、打包与 Maven 验证：

```powershell
cd .\campus-server
mvn clean verify
```

需要快速打包且已经完成对应测试时，可在 `campus-server` 目录执行：

```powershell
mvn clean package -DskipTests
```

该命令跳过测试，不能作为测试通过的依据。构建产物为 `campus-server/target/campus-server-1.0.0.jar`。

独立部署/对外分发使用 `mvn -Pportable clean verify`，产物为 `target/portable/campus-server-1.0.0.jar`。该 profile 排除真实应用配置；普通开发产物可能包含本机配置，不应直接分发。独立启动器 [Start-Local.ps1](campus-server/Start-Local.ps1) 会采用该 profile 并显式加载脱敏模板。

### IDEA 启动

1. 打开 `campus-server/pom.xml`，等待 Maven 依赖加载完成。
2. 选择 JDK 17 或 21，运行配置的工作目录设为 `campus-server`。
3. 运行 `com.campus.CampusApplication`，等待日志出现 `Started CampusApplication`。

### 使用最新 JAR 启动

完成构建后，在 `campus-server` 目录执行：

```powershell
java -jar .\target\campus-server-1.0.0.jar
```

需要使用根目录外部配置时，另开终端并从仓库根目录执行以下命令，选择一种方式启动即可：

```powershell
java -jar .\campus-server\target\campus-server-1.0.0.jar
```

默认监听 `8009`。遇到端口占用先确认是否已有后端实例；需要另开实例时可在启动命令末尾添加 `--server.port=8010`，并相应调整联调地址。当前工作区采用上述源码或 JAR 启动方式。

### 启动验证

在另一个 PowerShell 窗口执行：

```powershell
Invoke-RestMethod 'http://127.0.0.1:8009/actuator/health'
```

预期返回 `{"status":"UP"}`。接口文档入口为 [Swagger UI](http://127.0.0.1:8009/swagger-ui.html)。进入联调前应处理导致启动失败或健康状态异常的问题；第三方业务能力仍需按对应功能单独验收。

## 测试与接口校验

以下命令均在 `campus-server` 目录执行：

```powershell
# 快速回归
mvn test

# 发布前完整验证
mvn clean verify

# 只运行指定测试类
mvn -Dtest=GroupAnnouncementServiceTest test
```

测试报告位于 `campus-server/target/surefire-reports/`。验证记录需注明执行时间、代码版本、使用环境及结果。

启动后检查 [Swagger UI](http://127.0.0.1:8009/swagger-ui.html) 与 [运行时 OpenAPI](http://127.0.0.1:8009/v3/api-docs)，并按功能对接文档核对路径、参数、鉴权、响应字段、状态码和错误文案。Markdown 接口清单是文档快照，发现与运行时不一致时需核对源码并同步更新。

## 接口文档与前端联调

随仓库提供的部署说明及运行时接口入口：

| 文档 | 内容 |
| --- | --- |
| [本地部署说明](方案分析与实现（md）文件/部署说明-本地部署.md) | 配置、基础设施、数据库初始化、升级与验收 |
| [Swagger UI](http://127.0.0.1:8009/swagger-ui.html) | 后端启动后查看接口和参数 |
| [运行时 OpenAPI](http://127.0.0.1:8009/v3/api-docs) | 后端启动后获取接口契约 |

其他专题接口清单与前端对接资料由维护者单独提供；需要联调某个功能时，先取得对应版本的契约说明。

本地联调的 API Base URL 为：

```text
http://127.0.0.1:8009/api
```

接口清单写出的完整路径已包含 `/api`；拼接时避免重复添加。手机联调使用手机可访问的电脑地址和端口。使用内网穿透时，将前端与 Apifox 的 Base URL 统一替换为实际隧道地址并保留 `/api` 前缀。

需要认证的接口使用请求头：

```http
access_token: <登录返回的令牌>
```

同名 Query 参数作为兜底方式，日常联调优先使用 Header。测试 Token、验证码和临时公网地址不要写入提交文件或公开文档。

接口统一返回 `{code,message,data}`；成功但没有内容时使用 `code=200, data=null`。分页参数从第 1 页开始，默认每页 20 条，上限 100 条；时间格式为 `yyyy-MM-dd HH:mm:ss`（GMT+8）。具体权限、参数、错误文案和状态码以对应功能文档为准。

## 数据库迁移与上线

当前配置为 `spring.flyway.enabled=false`，`db/migration/*.sql` **不会随启动自动执行**。上线某项功能前，阅读对应前端对接文档的迁移要求，核对目标数据库已执行的脚本，再人工执行所需迁移。

执行数据清理或包含 DDL 的脚本前先备份。MySQL DDL 可能隐式提交，不能假设整份脚本可以回滚。当前 Hibernate 使用 `ddl-auto: update`，它不能替代迁移脚本中的数据清理、外键及约束校验。

全新独立库与已有数据库升级的步骤不同，不能把历史迁移全部重跑。具体建表、唯一约束和外键核验流程见 [本地部署说明](方案分析与实现（md）文件/部署说明-本地部署.md) §6。

## 开发约定

仓库维护者另有内部开发规范。每个新功能按以下顺序交付：

1. 核对需求、现有实现、实体、权限及接口语义，确认影响范围。
2. 明确设计与兼容性要求，必要时在现有方案目录记录实现方案。
3. 实现 DTO、Controller、Service、Repository 和必要迁移，遵循统一响应、异常、事务及防重复提交规则。
4. 补齐单元测试，覆盖精确中文文案、权限、边界及失败时不落库；按风险补充集成验证。
5. 执行 `mvn test`，发布前执行 `mvn clean verify`，并完成相应运行时接口和依赖验证。
6. 在 `方案分析与实现（md）文件/` 交付 `前端对接-<功能名>.md`，说明兼容性、前端改造点、上线顺序及人工迁移要求。
7. 记录本次改动、验证结果与未完成事项；内部工作台账由维护者单独保管。

根目录的 Markdown 入口为 `AGENTS.md` 和 `README.md`；实现方案、分析及前端对接文档统一保留在 `方案分析与实现（md）文件/`。参考其他项目时按本仓库实际结构填写文档，不据此调整现有文件位置。

提交前复核差异，使用精确文件清单加入版本控制。迁移 SQL 经复核后单独纳入，共享文件发生冲突时先核对双方改动及基线，再合并验证。

## 数据与安全边界

- 不提交含真实凭据的应用配置、Token、密钥、数据库快照、JAR、压缩包、日志和 `target/` 等产物。
- 迁移 SQL 是受控例外：经复核后按文件精确加入版本控制。
- 日志、错误响应和调试输出不记录密码、JWT、验证码及不必要的个人信息。
- 测试与联调使用明确授权的环境和账号，不删除真实业务数据，不为联调放宽权限校验。

## 相关项目边界

本仓库只维护青核后端和后端文档。App / Web 前端源码位于其他仓库，所需前端改造通过对接文档交付；本文不假定前端项目在开发机上的具体路径。

`gitea-upload/` 为对外发布用的独立快照目录，已被主仓库忽略。主工作区的修改不会自动同步到该目录，发布时需单独核对源码、配置排除规则和文档。