docs: 批量更新历史文档中的 backend-single 引用为 server

2026-06-27 17:27:27 +08:00
parent 5586dc5eac
commit 591f70a2f6
39 changed files with 1209 additions and 673 deletions
@@ -0,0 +1,462 @@
+# backend-single 重命名为 server 实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 将 `backend-single` 目录重命名为 `server`，同步更新 Maven artifactId、部署脚本、配置文件、项目文档和历史文档中的所有引用。
+
+**Architecture:** 分 10 个任务按依赖顺序执行。先移动目录（Task 1），再更新构建配置（Task 2-3），然后更新根级脚本（Task 4-5），接着更新文档（Task 6-8），最后批量替换历史文档（Task 9）并全面验证（Task 10）。
+
+**Tech Stack:** Git, Maven, Python (deploy scripts), Bash, sed (batch replace)
+
+---
+
+### Task 1: 目录重命名
+
+**Files:**
+- Move: `backend-single/` → `server/`
+
+- [ ] **Step 1: 使用 git mv 重命名目录**
+
+```bash
+cd /g/IdeaProjects/emotion-museun
+git mv backend-single server
+```
+
+Expected: 目录从 `backend-single/` 重命名为 `server/`，Git 历史完整保留。
+
+- [ ] **Step 2: 确认目录已移动**
+
+```bash
+ls -d server/
+ls server/pom.xml
+```
+
+Expected: 两个命令都成功，无报错。
+
+- [ ] **Step 3: 提交目录移动**
+
+```bash
+git commit -m "refactor: 重命名 backend-single 目录为 server"
+```
+
+---
+
+### Task 2: 更新 Maven pom.xml
+
+**Files:**
+- Modify: `server/pom.xml:8,12`
+
+- [ ] **Step 1: 修改 artifactId 和 name**
+
+在 `server/pom.xml` 中，将第 8 行和第 12 行的 `backend-single` 替换为 `server`：
+
+```xml
+    <!-- 第 8 行 -->
+    <artifactId>server</artifactId>
+
+    <!-- 第 12 行 -->
+    <name>server</name>
+```
+
+- [ ] **Step 2: 验证 pom.xml 修改**
+
+```bash
+grep -n "backend-single" server/pom.xml
+```
+
+Expected: 无任何输出（无残留引用）。
+
+- [ ] **Step 3: 提交 pom.xml 修改**
+
+```bash
+git add server/pom.xml
+git commit -m "refactor: 更新 Maven artifactId 为 server"
+```
+
+---
+
+### Task 3: 更新后端部署脚本 JAR 名称
+
+**Files:**
+- Modify: `server/deploy.py:22`
+- Modify: `server/deploy.sh:10`
+
+- [ ] **Step 1: 修改 server/deploy.py 中的 JAR_NAME**
+
+将 `server/deploy.py` 第 22 行：
+
+```python
+JAR_NAME = "backend-single-1.0.0.jar"
+```
+
+改为：
+
+```python
+JAR_NAME = "server-1.0.0.jar"
+```
+
+- [ ] **Step 2: 修改 server/deploy.sh 中的 JAR_NAME**
+
+将 `server/deploy.sh` 第 10 行：
+
+```bash
+JAR_NAME="backend-single-1.0.0.jar"
+```
+
+改为：
+
+```bash
+JAR_NAME="server-1.0.0.jar"
+```
+
+- [ ] **Step 3: 验证后端部署脚本无残留**
+
+```bash
+grep -n "backend-single" server/deploy.py server/deploy.sh
+```
+
+Expected: 无任何输出。
+
+- [ ] **Step 4: 提交后端部署脚本修改**
+
+```bash
+git add server/deploy.py server/deploy.sh
+git commit -m "refactor: 更新后端部署脚本 JAR 名称为 server-1.0.0.jar"
+```
+
+---
+
+### Task 4: 更新根目录部署脚本
+
+**Files:**
+- Modify: `deploy.py:398,405,413`
+- Modify: `deploy.sh:77,81,82,86`
+
+- [ ] **Step 1: 修改根目录 deploy.py**
+
+将 `deploy.py` 中 3 处 `backend-single` 替换为 `server`：
+
+第 398 行注释：
+```python
+# 后端 - 调用 server/deploy.sh remote
+```
+
+第 405 行路径拼接：
+```python
+    deploy_script = PROJECT_DIR / "server" / "deploy.py"
+```
+
+第 413 行 cwd：
+```python
+        cwd=str(PROJECT_DIR / "server"),
+```
+
+- [ ] **Step 2: 修改根目录 deploy.sh**
+
+将 `deploy.sh` 中 4 处 `backend-single` 替换为 `server`：
+
+第 77 行注释：
+```bash
+# 后端 - 调用 server/deploy.sh
+```
+
+第 81 行存在性检查：
+```bash
+    if [ ! -f "server/deploy.sh" ]; then
+```
+
+第 82 行错误信息：
+```bash
+        log_error "后端部署脚本不存在: server/deploy.sh"
+```
+
+第 86 行 cd 命令：
+```bash
+    cd server
+```
+
+- [ ] **Step 3: 验证根部署脚本无残留**
+
+```bash
+grep -n "backend-single" deploy.py deploy.sh
+```
+
+Expected: 无任何输出。
+
+- [ ] **Step 4: 提交根部署脚本修改**
+
+```bash
+git add deploy.py deploy.sh
+git commit -m "refactor: 更新根部署脚本中的后端目录引用为 server"
+```
+
+---
+
+### Task 5: 更新 .gitignore
+
+**Files:**
+- Modify: `.gitignore:386`
+
+- [ ] **Step 1: 修改 .gitignore**
+
+将 `.gitignore` 第 386 行：
+
+```
+backend-single/backend.err
+```
+
+改为：
+
+```
+server/backend.err
+```
+
+- [ ] **Step 2: 验证并提交**
+
+```bash
+grep -n "backend-single" .gitignore
+git add .gitignore
+git commit -m "refactor: 更新 .gitignore 中的后端日志路径"
+```
+
+Expected: grep 无输出，提交成功。
+
+---
+
+### Task 6: 更新核心项目文档
+
+**Files:**
+- Modify: `CLAUDE.md` (4 处)
+- Modify: `AGENTS.md` (4 处)
+- Modify: `README.md` (1 处)
+
+- [ ] **Step 1: 修改 CLAUDE.md**
+
+将 `CLAUDE.md` 中所有 `backend-single` 替换为 `server`：
+
+第 23 行项目结构树：
+```
+├── server/                  # Spring Boot 单体后端服务
+```
+
+第 37 行标题：
+```
+### 后端 (server)
+```
+
+第 41 行命令：
+```
+cd server
+```
+
+第 50 行 JAR 名称：
+```
+java -jar target/server-1.0.0.jar
+```
+
+- [ ] **Step 2: 修改 AGENTS.md**
+
+将 `AGENTS.md` 中所有 `backend-single` 替换为 `server`（与 CLAUDE.md 相同的 4 处位置和内容）。
+
+- [ ] **Step 3: 修改 README.md**
+
+将 `README.md` 第 73 行：
+
+```
+├── backend-single/         # SpringBoot单体后端服务
+```
+
+改为：
+
+```
+├── server/                 # SpringBoot单体后端服务
+```
+
+- [ ] **Step 4: 验证并提交**
+
+```bash
+grep -n "backend-single" CLAUDE.md AGENTS.md README.md
+git add CLAUDE.md AGENTS.md README.md
+git commit -m "docs: 更新核心文档中的后端目录引用为 server"
+```
+
+Expected: grep 无输出，提交成功。
+
+---
+
+### Task 7: 更新部署相关文档
+
+**Files:**
+- Modify: `server/部署说明.md` (1 处)
+- Modify: `快速部署参考.md` (4 处)
+- Modify: `一键部署说明.md` (5 处)
+
+- [ ] **Step 1: 修改 server/部署说明.md**
+
+将 `server/部署说明.md` 第 14 行：
+
+```
+# 在 backend-single 目录下执行
+```
+
+改为：
+
+```
+# 在 server 目录下执行
+```
+
+- [ ] **Step 2: 修改 快速部署参考.md**
+
+将 `快速部署参考.md` 中所有 `backend-single` 替换为 `server`（4 处：第 71、83、134、136 行）。
+
+- [ ] **Step 3: 修改 一键部署说明.md**
+
+将 `一键部署说明.md` 中所有 `backend-single` 替换为 `server`（5 处：第 78、152、156、301、304 行）。注意第 156 行 `backend-single-1.0.0.jar` 变为 `server-1.0.0.jar`。
+
+- [ ] **Step 4: 验证并提交**
+
+```bash
+grep -n "backend-single" "server/部署说明.md" "快速部署参考.md" "一键部署说明.md"
+git add "server/部署说明.md" "快速部署参考.md" "一键部署说明.md"
+git commit -m "docs: 更新部署文档中的后端目录引用为 server"
+```
+
+Expected: grep 无输出，提交成功。
+
+---
+
+### Task 8: 更新前端代码和其他文档
+
+**Files:**
+- Modify: `web/src/types/auth.ts:5`
+- Modify: `web-admin/AI_CONFIG_TEST_SAVE_FEATURE.md:284-287`
+
+- [ ] **Step 1: 修改 web/src/types/auth.ts 注释**
+
+将第 5 行：
+
+```ts
+// 登录请求（对齐 backend-single：手机号 + 短信验证码）
+```
+
+改为：
+
+```ts
+// 登录请求（对齐 server：手机号 + 短信验证码）
+```
+
+- [ ] **Step 2: 修改 web-admin/AI_CONFIG_TEST_SAVE_FEATURE.md**
+
+将文件中 4 处 `backend-single/src/main/java/` 替换为 `server/src/main/java/`（第 284-287 行）。
+
+- [ ] **Step 3: 验证并提交**
+
+```bash
+grep -rn "backend-single" web/ web-admin/
+git add "web/src/types/auth.ts" "web-admin/AI_CONFIG_TEST_SAVE_FEATURE.md"
+git commit -m "docs: 更新前端代码和文档中的后端目录引用为 server"
+```
+
+Expected: grep 无输出（在这两个目录中），提交成功。
+
+---
+
+### Task 9: 批量替换历史文档
+
+**Files:**
+- Modify: `docs/superpowers/` 下约 37 个 `.md` 文件（排除本次新建的设计文档）
+
+- [ ] **Step 1: 使用 sed 批量替换**
+
+在 Windows Git Bash 中执行：
+
+```bash
+cd /g/IdeaProjects/emotion-museun
+find docs/superpowers -name "*.md" \
+  ! -name "2026-06-27-backend-single-rename-to-server-design.md" \
+  -exec sed -i 's/backend-single/server/g' {} +
+```
+
+说明：
+- `sed -i` 原地替换
+- `! -name` 排除本次设计文档自身（避免修改自己的文件名引用）
+- `s/backend-single/server/g` 全局替换
+
+- [ ] **Step 2: 验证 docs/superpowers/ 中无残留**
+
+```bash
+grep -rn "backend-single" docs/superpowers/ \
+  --include="*.md" \
+  ! --include="2026-06-27-backend-single-rename-to-server-design.md"
+```
+
+Expected: 无任何输出。
+
+- [ ] **Step 3: 提交历史文档更新**
+
+```bash
+git add docs/superpowers/
+git commit -m "docs: 批量更新历史文档中的 backend-single 引用为 server"
+```
+
+---
+
+### Task 10: 全面验证
+
+**Files:** 无新增修改
+
+- [ ] **Step 1: 全项目 grep 验证无残留**
+
+```bash
+grep -rn "backend-single" --include="*.md" --include="*.py" --include="*.sh" \
+  --include="*.xml" --include="*.ts" --include="*.java" --include="*.yml" \
+  --include="*.yaml" --include="*.json" --include="*.properties" .
+```
+
+Expected: **无任何输出**。如果有残留，逐一修复。
+
+**注意**：以下文件中出现 `backend-single` 是允许的（不需要修改）：
+- `docs/superpowers/specs/2026-06-27-backend-single-rename-to-server-design.md`（本次设计文档自身）
+- `docs/superpowers/plans/2026-06-27-backend-single-rename-to-server.md`（本次计划文档自身）
+
+- [ ] **Step 2: Maven 编译验证**
+
+```bash
+cd /g/IdeaProjects/emotion-museun/server
+mvn clean install -DskipTests
+```
+
+Expected: BUILD SUCCESS，生成 `target/server-1.0.0.jar`。
+
+- [ ] **Step 3: 验证 JAR 文件名称**
+
+```bash
+ls -lh server/target/server-1.0.0.jar
+```
+
+Expected: 文件存在，名称正确。
+
+- [ ] **Step 4: 验证 Git 历史保留**
+
+```bash
+git log --follow --oneline server/pom.xml | head -5
+```
+
+Expected: 能看到旧的重命名之前的提交历史。
+
+- [ ] **Step 5: 验证 .gitignore 生效**
+
+```bash
+git status
+```
+
+Expected: 工作区干净（无意外未跟踪文件）。
+
+- [ ] **Step 6: 最终提交（如有修复）**
+
+如果 Step 1 中发现了残留并修复了，执行：
+
+```bash
+git add -A
+git commit -m "fix: 修复遗漏的 backend-single 引用"
+```