# yaoai-video 升级到 Mac v2 + 团队协同编码流程

> 版本：2026-06-02
> 适用：把 `d:\git-6\yaoai-video`（Mac 端运营管理端 v2 升级版）合并到当前 `d:\git-6` 主线，并规范后续团队 git 协同。
> 目标：在 Windows 本地把升级版跑通 → 拆 commit 推到 main → 其他成员可平滑同步。

---

## 0. 升级带来的核心变化（动手前必看）

| 维度 | 变化 |
|---|---|
| 数据库 | 新增 V21~V39 共 19 个 Flyway 迁移（admin_menus / admin_page_data / admin_report_definitions / permission_policies / tenant_member_permissions 等） |
| 后端 yaoai-admin 模块 | 由 2 个 controller 扩展到 9 个（adminuser / audit / billing / dashboard / menu / page / plan / tenant / user） |
| 接口路径 | `/admin/...` 改造为 `/admin-api/...`，Vite 不再需要 rewrite |
| 运营端前端 | 由 1 个 LoginView 扩展到 14 个 view，加入 ECharts 大盘、Element Plus 全量菜单 |
| 依赖 | 新增 `echarts` 与 `read-excel-file` |
| 基础设施 | 新版含 k8s 编排、`.local-tools`（Mac JDK/Maven）、Dockerfile 更新 |

> 升级影响：V1~V20 兼容，但 **V13 admin_backend.sql 在 Mac 端被改写**，若团队有人在生产 V13 上手工补丁过，需要先 `mysqldump` 备份再 reset。

---

## 1. 升级前准备（5 分钟）

### 1.1 停掉所有正在跑的服务

```powershell
# 停前端
taskkill /F /IM node.exe /T

# 停后端（找 PID）
netstat -ano | findstr :8081
taskkill /F /PID <上面查到的PID>
```

### 1.2 检查 git 状态

```powershell
cd d:\git-6
git status
```

预期看到三类文件：

| 类型 | 处理方式 |
|---|---|
| 之前为了让 heke 登录改的 `DevDataInitializer.java` | `git checkout -- <path>` 丢弃 |
| `.env`、本地配置文件 | 保留 |
| `node_modules/`、`target/`、`.local-data/` | 已经被 .gitignore 忽略，OK |

### 1.3 备份当前目录（一键回退用）

```powershell
# 在 D 盘根目录建一份完整备份
mkdir d:\git-6-backup-$((Get-Date).ToString('yyyyMMdd-HHmm'))
Copy-Item -Path d:\git6 -Destination d:\git-6-backup-<时间戳>\ -Recurse -Force
```

---

## 2. 覆盖升级版代码（10 分钟）

Mac 升级版路径：`d:\git-6\yaoai-video\yaoai-video`

```powershell
$src = "d:\git-6\yaoai-video\yaoai-video"
$dst = "d:\git-6"

# 2.1 运营端前端
Copy-Item -Path "$src\yaoai-admin-web\*" -Destination "$dst\yaoai-admin-web\" -Recurse -Force

# 2.2 后端工程各模块（不会覆盖 target/ 因为是源码目录）
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-admin"        -Destination "$dst\yaoai-comic-studio\yaoai-admin"        -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-api"          -Destination "$dst\yaoai-comic-studio\yaoai-api"          -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-agent"        -Destination "$dst\yaoai-comic-studio\yaoai-agent"        -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-pipeline"     -Destination "$dst\yaoai-comic-studio\yaoai-pipeline"     -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-billing"      -Destination "$dst\yaoai-comic-studio\yaoai-billing"      -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-bootstrap"    -Destination "$dst\yaoai-comic-studio\yaoai-bootstrap"    -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-domain"       -Destination "$dst\yaoai-comic-studio\yaoai-domain"       -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-security"     -Destination "$dst\yaoai-comic-studio\yaoai-security"     -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-storage"      -Destination "$dst\yaoai-comic-studio\yaoai-storage"      -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-common"       -Destination "$dst\yaoai-comic-studio\yaoai-common"       -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-ai-core"      -Destination "$dst\yaoai-comic-studio\yaoai-ai-core"      -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-ai-providers" -Destination "$dst\yaoai-comic-studio\yaoai-ai-providers" -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-media"        -Destination "$dst\yaoai-comic-studio\yaoai-media"        -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\yaoai-task"         -Destination "$dst\yaoai-comic-studio\yaoai-task"         -Recurse -Force
Copy-Item -Path "$src\yaoai-comic-studio\pom.xml"            -Destination "$dst\yaoai-comic-studio\pom.xml"            -Force
Copy-Item -Path "$src\yaoai-comic-studio\Dockerfile"         -Destination "$dst\yaoai-comic-studio\Dockerfile"         -Force
Copy-Item -Path "$src\yaoai-comic-studio\docker-compose.yml" -Destination "$dst\yaoai-comic-studio\docker-compose.yml" -Force

# 2.3 根目录
Copy-Item -Path "$src\README.md"          -Destination "$dst\README.md"          -Force
Copy-Item -Path "$src\docker-compose.yml" -Destination "$dst\docker-compose.yml" -Force
Copy-Item -Path "$src\.env.example"       -Destination "$dst\.env.example"       -Force
```

> **不要复制** `__MACOSX/`、`.local-tools/`、`.local-data/`、`logs/`，是 Mac 端垃圾或环境相关文件。

---

## 3. 本地跑通（15 分钟）

### 3.1 重置并启动后端

```powershell
cd d:\git-6\yaoai-comic-studio
docker compose down -v
docker compose up -d
# 等待 MySQL/Redis/RabbitMQ 启动完成（约 10 秒）

# 编译
java -classpath ".mvn\wrapper\maven-wrapper.jar" "-Dmaven.multiModuleProjectDirectory=$PWD" `
     org.apache.maven.wrapper.MavenWrapperMain clean package -pl yaoai-bootstrap -am -DskipTests

# 启动
java -jar yaoai-bootstrap\target\yaoai-bootstrap-0.1.0-SNAPSHOT.jar
```

等待日志出现 `Started YaoAiApplication in xx seconds` 即可。

### 3.2 处理 heke 账号（升级版没有自动初始化）

启动后，在 MySQL 容器里**手工插入**：

```powershell
docker exec -it yaoai-mysql mysql -u root -pyaoai123 yaoai_comic
```

```sql
-- 密码 'heke123456' 的 BCrypt 哈希（可用 Python 生成: bcrypt.hashpw(b'heke123456', bcrypt.gensalt())）
INSERT INTO admin_users
    (id, username, password_hash, display_name, email, role, status, must_change_password, created_at, updated_at)
VALUES
    (1001, 'heke', '$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy',
     '何科', 'heke@yaoai.com', 'SUPER_ADMIN', 1, 0, NOW(3), NOW(3))
ON DUPLICATE KEY UPDATE
    password_hash = VALUES(password_hash),
    status = 1;
```

> 如果哈希对不上您本机生成的，登录会提示"用户名或密码错误"。**推荐用 Python 现生成**：
> ```python
> import bcrypt; print(bcrypt.hashpw(b'heke123456', bcrypt.gensalt()).decode())
> ```
> 然后用最新哈希替换上面 SQL 里的值。

### 3.3 启动前端

```powershell
# 另开一个终端
cd d:\git-6\yaoai-admin-web
npm install
npm run dev
# 浏览器打开 http://localhost:5174 ，用 heke / heke123456 登录
```

### 3.4 验证清单

- [ ] 后端日志出现 `Migrating schema yaoai_comic to version "39 - enterprise_permission_configuration"`
- [ ] 5174 看到新登录页（"Dramix Operations Console"）
- [ ] heke 登录成功，进入 Dashboard
- [ ] 左侧菜单树显示完整 7 大模块（仪表盘 / 租户 / 计费 / 数据 / 客户 / 内容 / 系统）
- [ ] ECharts 图表正常渲染

---

## 4. Git 提交与推送（10 分钟）

### 4.1 强化 .gitignore

```powershell
cd d:\git-6

# 在现有 .gitignore 末尾追加（用 Add-Content 不会破坏原内容）
Add-Content .gitignore @"

# Mac 升级文件
__MACOSX/
.local-tools/
.local-data/

# Java/Maven
target/
.mvn/wrapper/maven-wrapper.jar

# Node
node_modules/
dist/

# IDE
.idea/
*.iml
.vscode/
"@
```

### 4.2 拆 commit 提交（按"数据库 / 后端 / 前端 / 文档"4 段）

```powershell
# commit 1: 数据库迁移
git add yaoai-comic-studio/yaoai-bootstrap/src/main/resources/db/migration/
git commit -m "feat(db): 升级 V13~V39 共 19 个 Flyway 迁移

- admin_menus / admin_page_data 数据库驱动菜单
- 报告目录与算法口径
- 套餐与企业端权限配置
- 合并 V13 admin_backend 字段升级

Refs: design-docs/20-运营管理端升级PRD.md"

# commit 2: 后端运营模块
git add yaoai-comic-studio/yaoai-admin `
        yaoai-comic-studio/yaoai-api `
        yaoai-comic-studio/pom.xml `
        yaoai-comic-studio/Dockerfile `
        yaoai-comic-studio/docker-compose.yml
git commit -m "feat(admin-api): 升级运营后端 7 controller / 9 service

- DashboardController 数据大盘接口
- TenantAdminController 完整租户/成员/积分
- PlanAdminController 套餐管理
- AdminMenuService 数据库驱动菜单
- 路径由 /admin/ 改造为 /admin-api/"

# commit 3: 运营端前端
git add yaoai-admin-web
git commit -m "feat(admin-web): 升级运营端 UI 至 v2

- 14 个新视图 + Element Plus + ECharts
- 新增菜单树组件
- 登录页改造为 Dramix Operations Console
- 新增 echarts 与 read-excel-file 依赖"

# commit 4: 根目录同步
git add README.md docker-compose.yml .env.example .gitignore
git commit -m "docs: 同步升级版 README 与 docker-compose"
```

### 4.3 推送

```powershell
git push origin main
```

如果 main 受保护无法直推，参考 §5 用 PR 流程。

---

## 5. 团队协同编码规范（升级后的长期规则）

### 5.1 分支策略

```
main (受保护)
  ├── feature/<name>     新功能       例: feature/admin-permission
  ├── fix/<name>         Bug 修复     例: fix/login-401
  ├── upgrade/<version>  大版本升级   例: upgrade/admin-v2
  └── release/<version>  发版分支
```

### 5.2 提交规范（Conventional Commits）

```
<type>(<scope>): <subject>

<body>

<footer>
```

| type | 用途 | scope 建议 |
|---|---|---|
| feat | 新功能 | admin / api / web |
| fix | 修复 | pipeline / agent |
| refactor | 重构 | billing / storage |
| perf | 性能 | db / docker |
| docs | 文档 | deps |
| test | 测试 | |
| chore | 杂项 | |

### 5.3 提交流程

```bash
# 1. 同步主线
git checkout main && git pull origin main

# 2. 拉分支
git checkout -b feature/<name>

# 3. 开发
# ... 改代码 ...

# 4. 提交
git add <files>
git commit -m "feat(admin): 新增权限配置页"

# 5. 推送并开 PR
git push origin feature/<name>
# 在 Gitea/GitLab 上点 "Create Merge Request"
```

### 5.4 冲突预防 4 条

1. **禁止直接 push 到 main**（Gitea 后台设为 Protected）
2. **禁止修改已合并的 V*.sql**（改了 Flyway 会校验失败）。新增请建新文件 `V41__xxx.sql`
3. **依赖升级单独 PR**，标题加 `deps:` 前缀
4. **dev 账号/seed 数据放 `application-dev.yml`**，不要写死在 `DevDataInitializer.java`

### 5.5 升级后其他成员拉取流程

```bash
git pull origin main
cd yaoai-comic-studio
docker compose down -v
docker compose up -d
mvn package -pl yaoai-bootstrap -am -DskipTests
java -jar yaoai-bootstrap/target/yaoai-bootstrap-0.1.0-SNAPSHOT.jar
# 然后在 MySQL 容器里插入 heke 账号（参考 §3.2）
```

---

## 6. 回退方案

```powershell
# 6.1 放弃未提交的全部覆盖
git checkout -- .
git clean -fd

# 6.2 已经 commit 了
git log --oneline -5
git reset --hard HEAD~1   # 撤回最后一个 commit
git reset --hard HEAD~4   # 撤回最近 4 个 commit（整个升级）

# 6.3 整个目录已经乱了
Remove-Item -Recurse -Force d:\git-6
Rename-Item d:\git-6-backup-<时间戳> d:\git-6
```

---

## 7. 检查清单（勾完即完成）

### 升级阶段
- [ ] §1 服务停掉、git 干净、备份存在
- [ ] §2 升级版代码覆盖完成
- [ ] §3.1 后端启动成功
- [ ] §3.2 heke 账号已插入
- [ ] §3.3 前端启动 + 登录成功
- [ ] §3.4 验证清单 5 项全过

### Git 阶段
- [ ] §4.1 .gitignore 已强化
- [ ] §4.2 已拆 3~4 个 commit
- [ ] §4.3 已推送（PR 流程或直推 main）
- [ ] 通知团队拉取（飞书/钉钉/邮件）

### 团队规范阶段
- [ ] 在 Gitea 把 main 设为 Protected
- [ ] 把 §5 流程贴到团队 wiki 或 README
- [ ] CODEOWNERS 中指定运营端 owner
