完善课程小结工作区与后台统计

app/MAINTENANCE.md

@@ -49,6 +49,33 @@
 - `make logs`：查看最近服务日志。
 - `make install-gitea-backup`：安装提交后自动推送到 Gitea 的 Git hook。
 
+## 收尾验证注意事项
+
+收尾阶段要验证“当前运行服务”，不要只验证工作区文件。应用镜像在构建时把源码复制进容器；修改 Python、HTML、JS、CSS 后，如果没有重新执行 `make build` 和 `make up`，`curl` 到的接口和浏览器加载的页面仍可能是旧镜像内容。
+
+- 部署类验证按依赖顺序执行，不要并行运行 `make up`、`make ps`、`curl`。先等 `make up` 完成，再看 `make ps`，最后访问接口或页面。
+- 如果接口返回旧字段或旧页面，先确认是否已重建并重启容器；不要直接把旧响应判断成代码逻辑错误。
+- 前端脚本或样式变更后，记得同步更新 HTML 中对应静态资源的 `?v=` 参数，再构建镜像，避免浏览器继续使用缓存。
+- 用 `curl` 做收尾验证时优先使用简单命令。需要检查 HTML 内容时，先直接获取页面；如果要配合 `grep`，先在本地确认引号转义正确，避免把 shell 引号错误误判成服务问题。
+- 如果 `curl http://127.0.0.1:<端口>` 连接失败，但 `make ps` 显示容器和端口正常，先区分执行环境网络限制和服务异常；必要时再看 `make logs`。
+
+推荐收尾顺序：
+
+```bash
+make check
+make build
+make up
+make ps
+```
+
+随后再访问具体接口或页面，例如：
+
+```bash
+set -a; . ./app/.env
+curl -sS -u "admin:${ACCOUNTS_AUTH_PASSWORD}" "http://127.0.0.1:${APP_PORT:-18080}/api/account-health"
+curl -sS -u "admin:${ACCOUNTS_AUTH_PASSWORD}" "http://127.0.0.1:${APP_PORT:-18080}/admin"
+```
+
 ## Gitea 自动备份
 
 新时空教务管理系统推荐把 Gitea SSH 仓库配置为 `origin`，并用 `post-commit` hook 在每次提交后自动推送当前分支。