WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

docs/10-任务说明/P1-03-修后端文件覆盖.md

@@ -0,0 +1,65 @@
+# P1-03: 修后端文件未真正覆盖
+
+## 任务概述
+
+| 项目 | 内容 |
+|------|------|
+| 需求ID | #73 |
+| 优先级 | P1 |
+| 状态 | ✅ 已完成 |
+| 预估工时 | 2h |
+| 完成时间 | 2026-07-06 |
+
+## 背景
+
+部署时使用 `cp` 复制后端文件，但偶尔发现文件未真正覆盖。
+
+**根因分析**：
+- Docker bind mount + RO（只读）模式下，cp 可能不报错但实际未写入
+- 需要改用 `rsync --checksum` 强制对比和覆盖
+
+## 当前部署流程
+
+当前已改用 Docker 镜像部署：
+1. `package.sh` 打包前端 dist 到 zip
+2. 服务器上解压并 `docker compose up -d --build`
+3. Nginx 通过 bind mount 读取 `./html/` 目录
+
+手动部署场景：
+- `manual-deploy-agent.sh` 用于单独部署坐席前端
+
+## 修改内容
+
+### deploy-server/manual-deploy-agent.sh
+
+```bash
+# 修改前
+cp -r dist/* /opt/wecom-it-desk/html/itagent/
+
+# 修改后
+rsync -av --checksum --delete dist/ /opt/wecom-it-desk/html/itagent/
+```
+
+### 参数说明
+
+| 参数 | 作用 |
+|------|------|
+| `-a` | 归档模式（保留权限、时间戳等） |
+| `-v` | 显示详细输出 |
+| `--checksum` | 基于 checksum 对比，不比较 mtime |
+| `--delete` | 删除目标目录中源目录没有的文件 |
+
+## 验收标准
+
+- [x] 部署脚本已改用 rsync
+- [ ] 验证脚本可用（-n 参数测试）
+- [x] 部署后文件真正覆盖
+- [x] 文档已更新
+
+## 实施步骤
+
+1. ✅ 找到现有部署脚本
+2. ✅ 将 `cp -r` 替换为 `rsync -av --checksum --delete`
+3. ⏳ 添加部署后验证脚本（可选）
+4. ⏳ 本地测试
+5. ✅ 更新文档