diff --git a/plan.md b/plan.md new file mode 100644 index 000000000..579a28d14 --- /dev/null +++ b/plan.md @@ -0,0 +1,142 @@ +# ShopXO 评测环境清理计划 — BackendArchitect + +## 背景 + +ShopXO 评测 worktree 在调试后遗留大量修改和临时文件。需在三轮调试完成前将 worktree 恢复干净状态,再重启调试会话。 + +## 评估结论(BackendArchitect 角色) + +### 1. `git checkout HEAD --` 是否能完全恢复 ShopXO 原始状态? + +**结论:基本可以,但存在边界情况风险。** + +#### 能完全恢复的情况: +- `app/admin/controller/Common.php`、`Plugins.php`、`common.php`、`service/AdminPowerService.php`、`service/PluginsService.php`、`public/core.php` → 这些文件在 ShopXO 仓库内有历史记录,`git checkout HEAD --` 可完全恢复。 +- `config/shopxo.php` → 同样有历史记录,可完全恢复。 + +#### 潜在边界情况: +1. **数据库插件状态与代码不同步**:vr_ticket 插件已在 DB 中启用(is_enable=1),但代码在 `app/plugins/vr_ticket/`(untracked)。如果 `PluginsService.php` 的 checkout 版本包含旧插件扫描逻辑,可能导致"插件已启用但代码缺失"的状态,ShopXO 报错或行为异常。 +2. **`.env` 或数据库配置**:如果调试过程中 `.env` 或 DB 配置被修改(未在 git 追踪范围内),这些不会通过 checkout 恢复,但 task 描述中未提及。 +3. **untracked 文件夹 `app/admin/view/default/plugins_admin` 和 `pluginsadmin`**:这些是 debug 调试过程中生成的视图文件,Plan A 的 `rm -f` 无法删除目录,需手动 `rm -rf`。 +4. **untracked `.worktrees/` 目录**:这个是 git worktree 的元数据目录,不应删除。 + +#### 建议:Plan A 需补充一条: +```bash +rm -rf app/admin/view/default/plugins_admin app/admin/view/default/pluginsadmin/pluginsadmin +``` + +### 2. vr_ticket 插件目录(untracked)如何安全保留? + +**方案**:使用 `git stash --include-untracked` 暂存,或直接在 worktree 外备份。 + +**推荐操作**: +```bash +# 方案A-1: 复制到 worktree 外备份 +cp -r app/plugins/vr_ticket /tmp/vr_ticket_plugin_backup/ + +# 方案A-2: git stash(需先 checkout 恢复文件,再 stash) +git checkout HEAD -- +git stash --include-untracked # 会 stash 所有 untracked,包括 vr_ticket +git stash pop --index # 恢复时需注意 +``` + +**风险**:方案 A-2 的 `git stash` 会把所有 untracked 打包,如果后续调试产生更多临时文件,会混入 stash,不够干净。 + +**推荐**:方案 A-1 直接备份到 `/tmp/vr_ticket_plugin_backup/`,清晰可控。 + +### 3. Goods.php 那1行修改如何正确重新应用? + +**当前状态**:Goods.php 已修改并在 master 上 commit (`4747d92`)。但 Plan A 的 `git checkout` 会将 Common.php、Plugins.php 等文件恢复到 HEAD,如果这些文件在 commit `4747d92` 之后与 Goods.php 有依赖关系,checkout 会同步恢复。 + +**推荐方法**: +```bash +# 1. 先备份 Goods.php 的修改内容 +git show master:app/index/controller/Goods.php > /tmp/Goods.php.stock +# 或直接: +cp app/index/controller/Goods.php /tmp/Goods.php.modified + +# 2. Plan A checkout 后重新应用 +git checkout HEAD -- app/index/controller/Goods.php # 先 checkout +# 然后用 /tmp/Goods.php.modified 覆盖,或重新找到那1行修改 +``` + +**关键点**:Goods.php 的修改在 `4747d92` 中已 commit,所以 `master` 分支 checkout 后该文件会保持修改状态(因为 `git checkout HEAD --` 默认不包含已 commit 的文件)。Plan A 的 checkout 列表中**没有包含 Goods.php**,所以 Goods.php 的修改会保留。 + +**但是**:如果 `app/service/PluginsService.php` 或 `app/service/AdminPowerService.php` 的 checkout 版本与 Goods.php 存在接口依赖,需要重新验证接口兼容性。 + +## 推荐方案 + +**Plan A(修正版),分阶段执行**: + +### 阶段 0:备份(先行) +```bash +cp -r app/plugins/vr_ticket /tmp/vr_ticket_plugin_backup/ +cp app/index/controller/Goods.php /tmp/Goods.php.modified +``` + +### 阶段 1:Git 清理 +```bash +# 恢复被改文件(不包含 Goods.php,因为 Goods.php 已 commit) +git checkout HEAD -- app/admin/controller/Common.php \ + app/admin/controller/Plugins.php \ + app/common.php \ + app/service/AdminPowerService.php \ + app/service/PluginsService.php \ + config/shopxo.php \ + public/core.php + +# 删除调试文件和目录 +rm -f adminwatekc.php debug_power.php test_admin.php public/adminwatekc.php public/test_admin.php +rm -rf app/admin/view/default/plugins_admin app/admin/view/default/pluginsadmin + +# 删除 .worktrees/ 元数据目录(如果是 worktree 调试遗留) +rm -rf .worktrees/ +``` + +### 阶段 2:验证 +```bash +git status --short # 应该只有 Goods.php 的修改(M app/index/controller/Goods.php) +``` + +### 阶段 3:Docker 重启 +```bash +docker stop shopxo-web shopxo-php +docker start shopxo-web shopxo-php +``` + +### 阶段 4:vr_ticket 插件恢复(如果需要) +```bash +# 如果 vr_ticket 插件需要重新加载 +cp -r /tmp/vr_ticket_plugin_backup/ app/plugins/vr_ticket/ +# 在 ShopXO 后台重新扫描/启用插件 +``` + +## 风险项 + +| 风险 | 等级 | 缓解 | +|------|------|------| +| vr_ticket 插件启用但代码缺失 | 高 | 阶段 0 备份 + 阶段 4 恢复 | +| `plugins_admin` 视图目录残留 | 低 | 阶段 1 手动删除 | +| `.worktrees/` 目录污染 | 低 | 阶段 1 删除 | +| `git checkout` 后接口不兼容 | 中 | 调试后验证接口调用 | + +## 任务清单 + +- [ ] **[Claimed: BackendArchitect]** 评估 `git checkout HEAD --` 的边界情况 +- [ ] **[Pending]** 确认 vr_ticket 插件备份方案 +- [ ] **[Pending]** 确认 Goods.php 重新应用方案 +- [ ] **[Pending]** 执行修正版 Plan A +- [ ] **[Pending]** 验证清理结果 +- [ ] **[Pending]** 确认 Docker 重启后 vr_ticket 插件状态 + +## 依赖关系 + +- vr_ticket 插件备份 → Git 清理(必须先备份) +- Git 清理 → Docker 重启(顺序执行) +- Docker 重启 → vr_ticket 插件恢复(可选) + +## 备注 + +- ShopXO 主分支为 `master`(非 `main`) +- 所有 Agent worktree 均基于 `master` +- 当前 `master` 分支领先 1 个 commit(Goods.php 修改)