From 00099aa945021dc9261afe8d4d04c70ab95d9616 Mon Sep 17 00:00:00 2001
From: Zhang Shun <zhangshun@users.noreply.local>
Date: Fri, 28 Aug 2026 10:23:03 +0800
Subject: [PATCH] docs: professionalize project README

---
 README.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 152 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 0b27e19..0707cd5 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,172 @@
 # 职来（mydreamjob）
 
-本目录只包含职来项目，不包含青核校园项目。
+职来是一个面向求职者、企业和平台运营方的 AI 求职招聘平台。本仓库是职来项目的后端与工程协作仓库，不包含“青核校园”React Native 项目。
 
-## 目录结构
+## 当前交付基线
 
-- `mydreamjob-server/`：Spring Boot 后端源码、测试和 Flyway 迁移
-- `backend-infra/`：Docker Compose 基础设施（MySQL、Redis、RabbitMQ）
-- `docs/`：OpenAPI、接口文档、验收脚本和数据模型文档
-- `product-docs/`：产品方案、功能设计表、UI 规范和架构图
-- `scripts/`：黑盒验收、调试、文档处理和环境脚本
-- `xlsx-analysis/`：产品功能表分析工具
-- `docx_qa/`：文档质量检查输出目录
+| 项目 | 当前状态 |
+| --- | --- |
+| Git 检查点 | V34 已冻结，最新检查点为 `bf75fc` |
+| 数据库迁移 | Flyway V1–V33；V34 为纯接口聚合模块，无新增迁移 |
+| API 契约 | 126 paths / 160 operations |
+| 自动化测试 | 1275 个通过，0 失败，0 错误 |
+| 已验收范围 | V27–V34；V33 已完成真实 MySQL/Docker 黑盒验收 |
+| 账号注销冷静期 | 30 天 |
+| 本地服务端口 | `8080` |
 
-## 后端开发
+V35 霍兰德职业兴趣测评目前仅完成设计，尚未进入编码和数据库迁移阶段。
+
+## 仓库结构
+
+```text
+zhilai/
+├─ mydreamjob-server/   Spring Boot 后端源码、测试、Flyway 迁移
+├─ backend-infra/       Docker Compose 基础设施（MySQL、Redis、RabbitMQ）
+├─ docs/                正式接口、OpenAPI、路线图和验收文档
+├─ product-docs/        产品方案、功能设计、UI 规范和架构资料
+├─ scripts/             通用验收、调试和文档处理脚本
+├─ xlsx-analysis/       产品功能表分析工具及其输出
+└─ docx_qa/             文档质量检查输出目录
+```
+
+`docs/` 是项目唯一正式的接口与验收文档目录。`mydreamjob-server/docs/` 仅保留后端内部说明或迁移说明，不作为对外接口文档入口。
+
+## 技术栈
+
+- Java 17
+- Spring Boot 3.5.16
+- Spring MVC、Spring Security、Spring Data JPA/Hibernate
+- MySQL 8.4、Flyway 11、Redis 7.4、RabbitMQ 3.13
+- Maven
+- JUnit、Mockito、MockMvc、H2（`MODE=MySQL` 集成测试）
+- SpringDoc OpenAPI 3
+
+## 环境准备
+
+开发机需要安装并可在终端使用：
 
 ```powershell
-cd C:\Users\15642\Desktop\zhilai\mydreamjob-server
-mvn test
+java -version
+mvn -version
+docker --version
+docker compose version
+python --version
 ```
 
-## 基础设施
+后端启动需要数据库、Redis、RabbitMQ 和 JWT 等配置。请使用团队已有的安全配置或 IntelliJ IDEA Run Configuration 注入环境变量，例如 `DB_PASSWORD`、`RABBITMQ_USERNAME`、`RABBITMQ_PASSWORD`、`JWT_SECRET`。不要把真实凭据写入 README、脚本、日志或 Git。
+
+## 启动基础设施
+
+在 PowerShell 中执行：
 
 ```powershell
 cd C:\Users\15642\Desktop\zhilai\backend-infra
 docker compose --env-file .env up -d
+docker compose ps
+```
+
+确认 `mydreamjob-mysql`、`mydreamjob-redis` 和 `mydreamjob-rabbitmq` 均处于 `healthy` 或可用状态后，再启动后端。`.env` 只用于本机，不应提交到仓库。
+
+## 启动后端
+
+### 构建并验证
+
+```powershell
+cd C:\Users\15642\Desktop\zhilai\mydreamjob-server
+mvn clean verify
+```
+
+### 使用最新 JAR 启动
+
+请先在 IntelliJ IDEA 或当前 PowerShell 会话中注入安全环境变量，然后执行：
+
+```powershell
+cd C:\Users\15642\Desktop\zhilai\mydreamjob-server
+java -jar .\target\mydreamjob-server-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev
+```
+
+成功启动后，使用另一个终端检查健康状态：
+
+```powershell
+Invoke-RestMethod "http://127.0.0.1:8080/api/v1/health" | ConvertTo-Json -Depth 5
 ```
 
+预期返回 `code=200` 且 `data.status=UP`。启动日志中的 Flyway、数据库连接或消息队列错误必须在进入联调前处理。
+
+## 测试与接口校验
+
+后端源码目录下执行：
+
+```powershell
+cd C:\Users\15642\Desktop\zhilai\mydreamjob-server
+
+# 快速回归
+mvn test
+
+# 发布前完整验证（包含 clean、编译、测试和打包）
+mvn clean verify
+```
+
+仓库根目录执行 OpenAPI 静态契约检查：
+
+```powershell
+cd C:\Users\15642\Desktop\zhilai
+python .\docs\verify_openapi.py
+```
+
+发布检查点至少应满足：测试无失败、OpenAPI 校验通过、运行时与静态契约一致、没有未经说明的数据库写入或敏感信息泄露。
+
+## 接口文档与前端联调
+
+正式接口入口：
+
+- [OpenAPI 契约](docs/openapi-rc.json)
+- [前端联调说明](docs/frontend-integration.md)
+- [后端开发路线图](docs/backend-development-roadmap.md)
+- [统一求职进度接口](docs/career-progress-api.md)
+- [同岗位竞争力排名](docs/competition-ranking-api.md)
+- [举报与屏蔽](docs/report-block-api.md)
+- [结构化面试评分](docs/interview-score-api.md)
+- [个人数据导出](docs/personal-data-export-api.md)
+- [账号注销](docs/account-deletion-api.md)
+- [隐私设置](docs/privacy-settings-api.md)
+
+本地联调的 API Base URL 为：
+
+`http://127.0.0.1:8080/api/v1`
+
+如果使用 ngrok 等内网穿透工具，前端和 Apifox 的 Base URL 统一替换为隧道地址，例如：
+
+`https://<public-tunnel-domain>/api/v1`
+
+需要认证的接口使用 `Authorization: Bearer <access-token>`。测试 Token、短信验证码和内网穿透地址不要写入提交文件或公开文档。
+
+## 开发约定
+
+每个新模块按以下顺序交付：
+
+1. 核对产品需求、现有实体、权限和接口语义。
+2. 先完成独立设计并确认边界，再开始编码。
+3. 实现 DTO、Controller、Service、Repository 和必要迁移。
+4. 补齐单元测试、MockMvc 测试和 H2 持久化测试。
+5. 执行 `mvn test`、`mvn clean verify` 和 OpenAPI 校验。
+6. 使用最新 JAR 进行 MySQL/Docker 黑盒验收。
+7. 通过验收后建立精确的 Git 检查点，再进入下一个模块。
+
+提交前应使用精确文件清单执行 `git add`，避免使用 `git add -A` 将运行产物一并提交。共享接口或迁移文件发生冲突时，先同步基线并重新验证，不直接覆盖他人改动。
+
+## 数据与安全边界
+
+- 不提交 `.env`、Token、密码、私钥、日志、数据库转储、导出文件和临时验收产物。
+- 不在审计日志、错误响应或导出文件中写入密码、JWT、验证码、手机号、邮箱等不必要的敏感信息。
+- 测试和黑盒验收不得删除真实业务数据；需要构造数据时使用独立测试账号并记录影响范围。
+- 未经明确授权，不启动或停止 Docker，不修改已验收接口语义，不修改历史 Flyway 迁移。
+- 账号注销采用 30 天冷静期；业务数据保留，仅按既定策略处理用户 PII。
+
 ## 相关项目边界
 
-青核校园 React Native 项目位于：
+“青核校园”React Native 项目位于：
 
 `C:\Users\15642\Desktop\青核\collegeCli`
 
-不要将青核项目代码提交到本仓库。
+青核项目不属于本仓库，禁止将其源代码提交到职来仓库。