zhaoziyue/README.md

青核后端（qinghe-backend）

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

首次独立部署请阅读 本地部署说明，使用脱敏模板与专用启动器。下文普通 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 实机启动、全新空库或第三方服务验收，详细边界见本地部署说明。

仓库结构

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 中执行：

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 和 .env.example。不要覆盖现有真实配置；新部署者按部署说明复制私有 .env 并填写自己的配置。万能验证码在模板中默认关闭，未接入云服务时相关功能不可用。

基础设施准备

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

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

cd .\campus-server
mvn clean verify

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

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 会采用该 profile 并显式加载脱敏模板。

IDEA 启动

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

使用最新 JAR 启动

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

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

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

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

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

启动验证

在另一个 PowerShell 窗口执行：

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

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

测试与接口校验

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

# 快速回归
mvn test

# 发布前完整验证
mvn clean verify

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

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

启动后检查 Swagger UI 与 运行时 OpenAPI，并按功能对接文档核对路径、参数、鉴权、响应字段、状态码和错误文案。Markdown 接口清单是文档快照，发现与运行时不一致时需核对源码并同步更新。

接口文档与前端联调

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

文档	内容
本地部署说明	配置、基础设施、数据库初始化、升级与验收
Swagger UI	后端启动后查看接口和参数
运行时 OpenAPI	后端启动后获取接口契约

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

本地联调的 API Base URL 为：

http://127.0.0.1:8009/api

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

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

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，它不能替代迁移脚本中的数据清理、外键及约束校验。

全新独立库与已有数据库升级的步骤不同，不能把历史迁移全部重跑。具体建表、唯一约束和外键核验流程见 本地部署说明 §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/ 为对外发布用的独立快照目录，已被主仓库忽略。主工作区的修改不会自动同步到该目录，发布时需单独核对源码、配置排除规则和文档。