smart-project/docs/superpowers/specs/2026-04-27-main-readme-and-branch-cleanup-design.md

主分支 README 补齐与分支清理设计

1. 问题定义

当前仓库已经包含 admin-web/、h5-app/、server/ 三个可独立运行的子项目，也有 SPEC.md 与 docs/ 作为目标架构说明，但根目录缺少一个能够让维护者快速上手的 README.md。此外，仓库当前存在多个历史功能分支，主分支虽然已同步远端，但分支整理尚未完成。

本轮工作的目标是：在 最新的 main 分支 上补齐一个中文根 README，详细说明当前仓库的启动、构建、部署与生产建议，并在确认边界后清理 已合并到 main 的本地和远程分支，最后把主分支推送到远端。

2. 当前项目状态

2.1 已确认事实

• 当前仓库默认维护分支为 main
• origin/main 已同步，当前 main 无落后
• 本地存在多个历史功能分支，远端也存在部分对应分支
• 用户已明确：
  • 先将当前未提交改动 stash
  • README 以当前可运行的 admin-web / h5-app / server 为主
  • 同时补充目标生产架构建议
  • 清理范围为“已合并到 main 的本地和远程分支”

2.2 仓库结构判断

• admin-web/：React 19 + Vite + Ant Design 的后台前端
• h5-app/：React 18 + Vite + Ant Design Mobile 的移动端前端
• server/：Node.js + Express + TypeScript 服务端
• SPEC.md 与 docs/：说明目标产品、数据库、API 和生产架构

3. 方案比较

方案 A：根目录单 README 总览式文档（选定）

在仓库根目录新增一个完整 README.md，统一承载：

• 仓库定位
• 目录结构
• 环境要求
• 本地开发方式
• 各子项目构建与部署方式
• Nginx 反向代理示例
• 生产部署建议

优点：

• 新接手的人只看一个入口就能跑起来
• 适合主分支长期维护
• 与当前单仓多应用结构最匹配

代价：

• README 会偏长，需要控制层级和可读性

方案 B：根 README 只做导航，细节拆到 docs/

优点：

• 根文档更短
• 结构更轻

问题：

• 部署信息分散，首次上手成本更高
• 与用户希望“详细描述部署方法”的目标不完全一致

方案 C：只按目标生产架构写 README

优点：

• 更贴近最终形态

问题：

• 会弱化当前仓库真实可运行方式
• 对现阶段开发与交付帮助不够直接

综合当前仓库状态与用户目标，本轮采用 方案 A。

4. 设计范围

4.1 README 结构

根 README 将包含以下章节：

1. 项目简介
2. 仓库结构说明
3. 技术栈概览
4. 环境准备（Node.js、npm、MySQL 建议版本）
5. 本地开发步骤
6. 各子项目构建方式
7. 生产部署建议
8. Nginx 反向代理与静态资源部署示例
9. 数据库与环境变量说明
10. 常见问题与注意事项

4.2 部署口径

README 以“当前仓库如何运行与部署”为主：

• admin-web：后台站点构建产物部署
• h5-app：移动端站点构建产物部署
• server：Node.js API 服务部署

同时补充“目标生产架构建议”：

• Node.js / Express + TypeScript
• MySQL 8.0
• Nginx 反向代理
• Aliyun OSS 文件存储

4.3 分支清理规则

仅清理满足以下条件的分支：

• 已经合并进入 main
• 不删除 main
• 不删除未合并分支
• 远程分支只删除已合并到 origin/main 的分支

5. 执行顺序

1. 在 main 上新增并完善根 README.md
2. 运行仓库中已有的构建/测试命令，确认 README 描述与实际工程一致
3. 识别并删除已合并到 main 的本地分支
4. 删除对应已合并的远程分支
5. 提交主分支变更并推送到 origin/main

6. 风险与约束

• 当前工作区原有未提交改动已通过 stash 暂存，不能丢失
• 分支清理必须基于“已合并”判断，避免误删仍在开发中的分支
• README 不能把文档中的目标架构误写成当前仓库已经全部落地的事实
• 部署说明要明确区分“当前可运行方案”和“生产建议方案”