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,74 @@
+---
+author: peanu
+created_at: 2026-06-27
+purpose: 将 backend-single 目录重命名为 server 的设计方案
+---
+
+# 设计：backend-single 重命名为 server
+
+## 背景
+
+项目中的后端服务目录当前名为 `backend-single`，该名称是早期"单体服务"阶段的遗留命名。随着项目演进，这个名称已不再准确反映实际情况，且在日常开发中较长不便。将其重命名为更简洁的 `server` 可提升可读性和一致性。
+
+## 决策
+
+- **目录重命名**：`backend-single/` → `server/`，使用 `git mv` 保留 Git 历史
+- **Maven artifactId**：`backend-single` → `server`，JAR 文件随之变为 `server-1.0.0.jar`
+- **历史文档**：`docs/superpowers/` 下的历史设计和计划文档也全部更新，保持一致性
+
+## 变更范围
+
+### 第一层：目录和构建
+
+| 操作 | 目标 |
+|------|------|
+| `git mv backend-single server` | 目录重命名 |
+| `server/pom.xml` artifactId | `backend-single` → `server` |
+| `server/pom.xml` name | `backend-single` → `server` |
+| `server/deploy.py` JAR_NAME | `backend-single-1.0.0.jar` → `server-1.0.0.jar` |
+| `server/deploy.sh` JAR_NAME | 同上 |
+
+### 第二层：部署脚本
+
+| 文件 | 变更内容 |
+|------|---------|
+| 根目录 `deploy.py` | 3 处 `backend-single` → `server`（注释、路径拼接、cwd） |
+| 根目录 `deploy.sh` | 4 处 `backend-single` → `server`（注释、存在性检查、cd） |
+| `.gitignore` | `backend-single/backend.err` → `server/backend.err` |
+
+### 第三层：项目文档
+
+| 文件 | 说明 |
+|------|------|
+| `CLAUDE.md` | 项目结构树（1 处）+ 后端命令段落（3 处） |
+| `AGENTS.md` | 同 CLAUDE.md 的结构和命令段落 |
+| `README.md` | 项目结构树（1 处） |
+| `server/部署说明.md` | 自引用路径 |
+| `快速部署参考.md` | 4 处部署路径引用 |
+| `一键部署说明.md` | 5 处部署路径引用 |
+
+### 第四层：前端和其他代码
+
+| 文件 | 说明 |
+|------|------|
+| `web/src/types/auth.ts` | 第 5 行注释引用 |
+| `web-admin/AI_CONFIG_TEST_SAVE_FEATURE.md` | 4 处后端文件路径引用 |
+
+### 第五层：历史文档批量替换
+
+约 20 个 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 下的 `.md` 文件，将其中所有 `backend-single` 替换为 `server`。
+
+## 不在范围内
+
+- **Java 包名**：`com.emotion` 保持不变，不在本次重命名范围内
+- **数据库名/表名**：不涉及数据库变更
+- **`dev-services.py`**：该脚本自动发现 Spring Boot 服务，不直接引用 `backend-single` 字符串，无需修改
+- **`deploy-server.sh`**：已存在的文件，不包含 `backend-single` 引用
+
+## 验证标准
+
+1. `mvn clean install -DskipTests` 在 `server/` 目录下编译成功
+2. `server/deploy.py backend` 能正确找到 JAR 并部署
+3. 根目录 `deploy.py` 能正确调用 `server/deploy.py`
+4. 项目中不再有任何 `backend-single` 字符串残留（grep 验证）
+5. Git 历史完整保留（`git log --follow server/pom.xml` 能看到旧历史）