chore(repo): consolidate local env and clean root files

docs/agents/handoff.md

@@ -0,0 +1,36 @@
+# 项目交接补充
+
+更新时间：2026-04-06
+
+这份文档只记录补充性的交接和运维提示；一切当前状态仍优先以 `memory.md`、`docs/architecture.md`、`docs/api-reference.md` 为准。
+
+## 当前主线
+
+- 产品方向已经从旧教务切到“网盘 + 快传 + 管理台 + Android 壳”
+- 前端静态站发布走 `node scripts/deploy-front-oss.mjs`
+- Android APK 发包走 `node scripts/deploy-android-apk.mjs`
+- 后端交付仍是 `cd backend && mvn package` 后手动上传 jar 并重启服务
+
+## 本地配置整理
+
+- 根目录 `.env` 已收口多吉云 API 凭据、服务器 SSH 信息和常用部署元信息
+- `.env.example` 作为模板保留在仓库中
+- 旧的 `.env.oss.local` 仅作为兼容回退读取，不再是主入口
+
+## 线上运维关键信息
+
+- 后端服务名：`my-site-api.service`
+- 后端 jar 路径：`/opt/yoyuzh/yoyuzh-portal-backend.jar`
+- 后端环境变量文件：`/opt/yoyuzh/app.env`
+- 后端额外配置文件：`/opt/yoyuzh/application-prod.yml`
+- API 域名：`https://api.yoyuzh.xyz`
+- 主站域名：`https://yoyuzh.xyz`
+
+## 遇到线上登录/网络异常时先看什么
+
+1. 前端当前生产包是否是最新资源
+2. `api.yoyuzh.xyz` 的 DNS / TLS / 反向代理是否正常
+3. `my-site-api.service` 是否正常运行
+4. 服务端和 Nginx 日志里是否已有真实请求
+
+不要在没有确认链路问题前先改前端业务逻辑。

docs/api-reference.md

@@ -410,5 +410,12 @@
 1. `memory.md`
 2. `docs/architecture.md`
 3. `docs/api-reference.md`
-4. `backend/src/main/java/com/yoyuzh/config/SecurityConfig.java`
-5. 对应业务模块的 `Controller + Service`
+4. `AGENTS.md`
+5. `CLAUDE.md`
+6. `backend/src/main/java/com/yoyuzh/config/SecurityConfig.java`
+7. 对应业务模块的 `Controller + Service`
+
+补充说明：
+
+- 根目录 `.env` 现在是本地密钥和部署参数的统一入口
+- 额外的交接背景可查看 `docs/agents/handoff.md`

docs/architecture.md

@@ -87,6 +87,7 @@
 ### 2.3 文档与脚本
 
 - `docs/`: 实现计划与补充文档
+- `docs/agents/`: 补充性的 agent / handoff 文档；根目录 `CLAUDE.md` 与 `AGENTS.md` 仍是入口
 - `scripts/`: 前端静态站发布、对象存储迁移和本地辅助脚本
 
 ## 3. 模块划分
@@ -402,6 +403,7 @@ Android 壳补充说明：
 - 仓库根目录没有 `package.json`，不要在根目录执行 `npm`
 - 前端命令只从 `front/package.json` 读取
 - 后端命令只从 `backend/pom.xml` 读取
+- 根目录 `.env` 是当前统一的本地密钥与部署配置入口；`.env.example` 是模板，旧 `.env.oss.local` 仅保留兼容回退
 - 前端 `npm run lint` 实际是 `tsc --noEmit`
 - 后端没有单独 lint 命令
 - 本仓库大量使用 Lombok，VS Code 若出现“final 字段未初始化”之类误报，优先检查 Lombok 扩展、Java Language Server 和 annotation processor
@@ -414,9 +416,14 @@ Android 壳补充说明：
 2. `docs/architecture.md`
 3. `docs/api-reference.md`
 4. `AGENTS.md`
+5. `CLAUDE.md`
 
 如果要继续某个具体功能，再进入对应模块的：
 
 - 前端页面文件
 - 后端 Controller / Service
 - 紧邻测试文件
+
+如果需要额外的交接背景，再补读：
+
+- `docs/agents/handoff.md`