Monorepo 多项目管理策略
版本：3.0（简化版）
更新时间：2026-03-16
重要变更：废弃 Git Worktree，酒店智能体采用单分支开发模式
概述
本文档描述 stooland Monorepo 项目的代码管理策略。
核心变更（2026-03-16）：
- ❌ 废弃 Git Worktree：复杂度高，维护成本大
- ❌ 废弃多分支策略：酒店智能体直接在 master 开发
- ✅ 采用标准 Monorepo：目录隔离，简单高效
- ✅ 单分支开发：快速迭代，减少合并冲突
背景与目标
业务背景
战略决策（2026-03-16）：
- 原有系统 (stooland)：智能媒体平台，包含分镜创作、AIGC 能力等
- ** storyboard-web**：通用分镜创作工具（专业创作者使用）
- hotel-web：酒店垂类 AI 内容智能体（酒店运营人员使用）⭐ 新建
产品定位差异：
storyboard-web= 专业创作工具（给制作人用）hotel-web= 行业解决方案（给酒店运营人员用）- 两者用户画像、使用场景、价值主张完全不同
技术架构调整（2026-03-16）：
- ❌ 废弃 Git Worktree：复杂度高，维护成本大，不适合当前场景
- ✅ 采用标准 Monorepo：统一仓库，目录隔离，简单高效
- ✅ 单分支开发：hotel-web 在 master 分支直接开发，无需复杂分支
- ✅ 独立部署：每个前端项目独立构建和部署
- ✅ 共享后端：共用 api/、pybridge/、social-publisher/ 等后端服务
核心目标
- 简化流程：降低开发复杂度，提升效率
- 项目隔离：通过目录结构自然隔离，互不干扰
- 按需共享：后端服务复用，前端代码独立
- 快速迭代：支持快速开发和部署
目录结构
/Users/mzy/docker/dnmp/www/stooland/ ← Monorepo 根目录
├── api/ ← 主后端（ThinkPHP 8）
│ ├── app/
│ │ ├── Aigc/ ← AIGC 模块（复用）
│ │ ├── Hotel/ ← 酒店模块（新建）⭐
│ │ └── ...
│ └── ...
├── web/ ← 管理后台（原有系统）
├── storyboard-web/ ← 分镜工具（原有系统）
├── hotel-web/ ← 酒店智能体（新建）⭐
│ ├── src/
│ │ ├── views/
│ │ ├── components/
│ │ ├── services/
│ │ └── ...
│ └── ...
├── pybridge/ ← Python 视频处理服务
├── social-publisher/ ← 社交媒体发布工具
└── muse-engine/ ← AI 引擎说明：
- 所有项目在同一仓库，通过目录自然隔离
- 每个前端项目有独立的
package.json和构建配置 - 后端服务共享，通过路由前缀区分（
/api/aigc/*、/api/hotel/*）
分支策略
简化分支结构
核心原则：简单优先，避免过度设计
| 项目 | 开发分支 | 生产分支 | 说明 |
|---|---|---|---|
| 原有系统 | develop | master | 保持现有流程 |
| 分镜工具 | develop | master | 保持现有流程 |
| 酒店智能体 ⭐ | master（直接开发） | master | 简化流程，无需 develop 分支 |
为什么酒店智能体采用单分支？
- 新建项目：没有历史包袱，不需要复杂的分支管理
- 快速迭代：减少分支合并的复杂度，提升开发效率
- 团队精简：初期团队规模小，单分支足够
- 部署简单：构建脚本直接指向
hotel-web/目录
分支结构图
┌─────────────────────────────────────────────────────────────────┐
│ Monorepo 简化分支策略 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 原有系统 / 分镜工具： │
│ master ◄─── develop（日常开发） │
│ │
│ 酒店智能体（新建）： │
│ master（直接在 master 开发，简化流程）⭐ │
│ │
│ 所有项目共享后端服务： │
│ api/、pybridge/、social-publisher/ │
│ │
└─────────────────────────────────────────────────────────────────┘Git 工作流对比
❌ 之前的复杂方案（已废弃）
bash
# Git Worktree + 多分支
cd /Users/mzy/docker/dnmp/www/stooland-hotel
git checkout -b feature/hotel-mvp hotel-develop
# 问题：需要维护 worktree，容易混淆✅ 现在的简单方案
bash
# 标准 Monorepo + 单分支
cd /Users/mzy/docker/dnmp/www/stooland/hotel-web
# 直接在 master 开发，无需复杂分支
git add src/views/hotel-selector/
git commit -m "feat: 酒店选择器"
git push origin master日常工作流
酒店智能体开发流程（简化版）
bash
# 1. 进入酒店智能体目录
cd /Users/mzy/docker/dnmp/www/stooland/hotel-web
# 2. 拉取最新代码
git pull origin master
# 3. 开发功能（直接在 master 开发）
# 编辑代码...
# 4. 提交代码
git add .
git commit -m "feat: 酒店选择器 - 酒店搜索功能"
# 5. 推送代码
git push origin master
# 6. 触发自动部署（CI/CD）
# 自动部署到 hotel-test.example.com说明：
- 直接在
master分支开发，无需创建功能分支 - 每次提交自动触发测试和部署
- 通过 commit message 区分功能模块
原有系统开发流程（保持不变）
bash
# 1. 进入原有系统目录
cd /Users/mzy/docker/dnmp/www/stooland
# 2. 创建功能分支
git checkout -b feature/some-feature develop
# 3. 开发并提交
git add .
git commit -m "feat: 新增某某功能"
# 4. 合并到 develop
git checkout develop
git merge feature/some-feature分镜工具开发流程（保持不变）
bash
# 1. 进入分镜工具目录
cd /Users/mzy/docker/dnmp/www/stooland/storyboard-web
# 2. 创建功能分支
git checkout -b feature/premium-template develop
# 3. 开发并提交
git add src/views/aigc/
git commit -m "feat: 高级模板市场功能"
# 4. 合并到 develop
git checkout develop
git merge feature/premium-template代码复用策略
后端服务复用
所有前端项目共享后端服务：
api/
├── app/
│ ├── Aigc/ ← AIGC 能力（所有项目复用）
│ ├── Hotel/ ← 酒店模块（hotel-web 专用）
│ └── ...
└── ...
路由前缀区分：
- /api/aigc/* ← 通用 AIGC 能力
- /api/hotel/* ← 酒店特定 API前端代码复用
可以复用的部分：
- 通用组件：
VideoPlayer.vue、VoiceSelector.vue等 - 工具函数：
utils/目录下的通用工具 - 服务层：API 调用封装
复用方式：
javascript
// 方式 1：直接引用（不推荐，耦合度高）
import VideoPlayer from '@/components/VideoPlayer.vue'
// 方式 2：复制到各自项目（推荐，解耦）
// hotel-web/src/components/shared/VideoPlayer.vue
// 基于原有组件优化，适配酒店场景不建议复用的部分：
- 业务逻辑层（差异太大）
- UI 布局（风格不同）
- 状态管理（数据结构不同）
Git Worktree 常用命令
| 命令 | 说明 |
|---|---|
git worktree list | 查看所有 worktree |
git worktree add <path> <branch> | 创建新的 worktree |
git worktree remove <path> | 删除 worktree |
git worktree prune | 清理已删除的 worktree |
发布流程
酒店智能体发布（简化）
bash
# 1. 确保代码已提交
cd /Users/mzy/docker/dnmp/www/stooland/hotel-web
git add .
git commit -m "release: 准备发布 v1.0"
git push origin master
# 2. 打标签
git tag -a v1.0 -m "酒店智能体 v1.0 发布"
git push origin v1.0
# 3. 触发自动部署（CI/CD）
# 自动部署到 hotel.example.com说明：
- 直接在
master发布，无需创建 release 分支 - 通过 Git Tag 标记版本
- CI/CD 自动构建和部署
分镜工具发布（保持不变）
bash
cd /Users/mzy/docker/dnmp/www/stooland/storyboard-web
git checkout master
git merge develop
git tag -a v2.0 -m "分镜工具 v2.0"
git push origin master --tags原有系统发布（保持不变）
bash
cd /Users/mzy/docker/dnmp/www/stooland
git checkout master
git merge develop
git tag -a v3.0 -m "原有系统 v3.0"
git push origin master --tags关键原则
| 原则 | 说明 |
|---|---|
| 简单优先 | 能简单就不要复杂，避免过度设计 |
| 项目隔离 | 通过目录结构自然隔离，互不干扰 |
| 按需共享 | 后端服务复用，前端代码按需复制 |
| 快速迭代 | 酒店智能体直接在 master 开发，快速发布 |
| CI/CD 自动化 | 提交自动测试，打标签自动部署 |
目录与分支对照表
| 目录 | 当前分支 | 说明 |
|---|---|---|
stooland/ | develop → master | 原有系统 |
storyboard-web/ | develop → master | 分镜工具 |
hotel-web/ | master（直接开发） | 酒店智能体 ⭐ |
FAQ
Q: 为什么酒店智能体不采用 develop 分支？
A:
- 新建项目，没有历史包袱
- 团队规模小，单分支足够
- 减少合并冲突，提升开发效率
- 通过 CI/CD 保证代码质量
Q: 可以在多个目录同时开发吗？
A: 可以，通过目录自然隔离，互不干扰。
Q: 需要重复安装依赖吗？
A: 需要，每个前端项目独立运行 npm install，后端共享 composer install。
Q: Monorepo 会占用额外磁盘空间吗？
A: 相比多个独立仓库，Monorepo 更节省空间（共享 .git 目录）。
Q: 如何管理多个前端项目的端口？
A:
web/: 5173storyboard-web/: 5173（独立目录，不冲突）hotel-web/: 5174（错开端口）
Q: 后端 API 如何支持多个前端项目？
A: 后端统一提供 API，通过路由前缀区分：
/api/aigc/*: 通用 AIGC 能力/api/hotel/*: 酒店特定 API
Q: 如何保证代码质量？
A:
- ESLint + Prettier 代码规范
- 提交前自动运行测试
- CI/CD 自动构建和部署
- Code Review 机制
Q: 如果酒店智能体做大了，需要改回 develop 分支吗？
A: 可以根据团队规模调整：
- 团队 < 5 人：保持单分支
- 团队 > 5 人：考虑引入 develop 分支
- 灵活调整，不要过度设计