# 团队协作与版本控制

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [AGENTS.MD](file://AGENTS.MD)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [.gitignore](file://.gitignore)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)
- [.example.env](file://.example.env)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本文件面向 ThinkCMF 项目团队，系统化梳理团队协作与版本控制最佳实践，覆盖迁移管理流程（分支策略、代码审查与合并）、版本控制规范（提交信息、标签与发布）、角色分工（迁移负责人、测试、运维）、冲突解决机制（代码/数据/配置）以及沟通与问题跟踪流程。目标是帮助团队在多应用、多插件、多主题的复杂项目中保持高质量交付与可追溯性。

## 项目结构
- 仓库包含多应用（app、api）、插件（public/plugins）、主题（public/themes）、动态配置与运行时（data/）、Web 根目录（public/）等。
- 版本控制与自动化：通过 Composer 与 Think 命令行工具实现依赖安装、服务发现、资源发布与数据库迁移的自动化执行。
- CI/CD：提供基于流水线的任务触发与安全扫描能力。

```mermaid
graph TB
A["仓库根目录"] --> B["app/<应用>"]
A --> C["api/<应用>"]
A --> D["public/plugins/<插件>"]
A --> E["public/themes/<主题>"]
A --> F["data/<配置/缓存/上传>"]
A --> G["public/<Web根>"]
A --> H["composer.json/.lock"]
A --> I[".gitignore/.workflow"]
```

图表来源
- [AGENTS.MD: 78-114:78-114](file://AGENTS.MD#L78-L114)
- [composer.json: 1-77:1-77](file://composer.json#L1-L77)

章节来源
- [AGENTS.MD: 78-114:78-114](file://AGENTS.MD#L78-L114)
- [composer.json: 1-77:1-77](file://composer.json#L1-L77)

## 核心组件
- 迁移管理：基于 xia/migration（Phinx 风格），通过 Think 命令行提供创建、执行、回滚迁移的能力。
- 自动化脚本：Composer 安装后自动执行服务发现、资源发布与迁移，确保部署一致性。
- 分支与流水线：通过 .workflow 定义的流水线在特定分支上触发安全扫描等任务。
- 环境与配置：.env 优先级高于动态配置与静态配置，便于多环境隔离与快速切换。

章节来源
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)
- [AGENTS.MD: 623-630:623-630](file://AGENTS.MD#L623-L630)
- [composer.json: 67-72:67-72](file://composer.json#L67-L72)
- [.workflow/pipeline-20240224.yml: 1-24:1-24](file://.workflow/pipeline-20240224.yml#L1-L24)
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)

## 架构总览
从版本控制与协作视角，ThinkCMF 的版本生命周期由“分支策略 → 提交与评审 → 自动化 → 测试 → 标签与发布”构成；迁移作为数据库层面的“变更契约”，贯穿开发到生产的每个阶段。

```mermaid
graph TB
subgraph "分支与提交"
BR["分支策略<br/>feature/hotfix/release"] --> CM["提交规范<br/>类型:主题:描述"]
CM --> CR["代码评审<br/>PR/Review"]
end
subgraph "自动化与构建"
CR --> CI["CI 触发<br/>.workflow/pipeline-20240224.yml"]
CI --> DEP["依赖安装<br/>composer install/update"]
DEP --> AUTO["自动脚本<br/>service:discover/vendor:publish/migrate:run"]
end
subgraph "测试与验证"
AUTO --> TEST["单元/集成/迁移测试"]
TEST --> QA["质量门禁<br/>安全扫描/合规检查"]
end
subgraph "发布与追踪"
QA --> TAG["打标签<br/>vX.Y.Z(+meta)"]
TAG --> REL["发布制品<br/>版本发布"]
REL --> DOC["变更日志/发布说明"]
end
```

图表来源
- [.workflow/pipeline-20240224.yml: 1-24:1-24](file://.workflow/pipeline-20240224.yml#L1-L24)
- [composer.json: 67-72:67-72](file://composer.json#L67-L72)
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)

## 详细组件分析

### 分支策略与合并流程
- 分支模型建议采用 Git Flow 或 GitHub Flow 的变体，结合 ThinkCMF 的多应用/插件特性：
  - develop/main：稳定基线，仅接受来自 release/hotfix 的合并。
  - feature/*：功能开发，按应用或插件拆分，避免跨域耦合。
  - release/*：准备发布的稳定分支，集中修复临界问题与迁移校验。
  - hotfix/*：紧急修复，直接从稳定标签切出，快速回归测试与合并。
- 合并策略：
  - PR 必须通过 CI 与代码评审，评审通过后使用“squash 合并”保持主干整洁。
  - 合并前确保迁移已执行并通过，避免遗留 pending 状态。
- 合并后清理：
  - 删除已合并的 feature/hotfix 分支，保持分支树清晰。

章节来源
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)

### 代码审查与评审
- 评审范围：
  - 新增/修改的迁移文件必须与数据库规范一致（表/字段命名、索引、默认值）。
  - 插件与主题的新增/变更需符合命名与目录规范，避免破坏自动加载。
  - API 变更需同步 Swagger 文档或在评审中说明。
- 评审清单：
  - 是否满足最小可运行条件（依赖、迁移、资源发布）。
  - 是否存在破坏性变更（字段删除、表重命名）。
  - 是否引入新的安全风险（SQL 注入、XSS、权限绕过）。
  - 是否具备必要的测试用例与回归测试计划。

章节来源
- [AGENTS.MD: 448-508:448-508](file://AGENTS.MD#L448-L508)
- [AGENTS.MD: 564-574:564-574](file://AGENTS.MD#L564-L574)

### 迁移管理流程
- 迁移生命周期：
  - 设计：在 feature 分支中设计迁移，明确变更点与回滚策略。
  - 创建：使用迁移命令生成迁移文件，遵循命名规范与时间戳前缀。
  - 执行：在本地与测试环境执行迁移，验证数据一致性。
  - 回滚：若发现问题，及时回滚至上一个稳定迁移。
  - 归档：release/hotfix 合并后，将迁移纳入版本发布。
- 回滚策略：
  - 优先使用迁移回滚；若涉及破坏性变更，准备“反向迁移”或“数据修复脚本”。

```mermaid
flowchart TD
S["开始"] --> D["设计迁移方案"]
D --> C["创建迁移文件"]
C --> E["本地执行迁移"]
E --> V{"验证通过?"}
V --> |否| ROLL["执行回滚/修复"]
ROLL --> E
V --> |是| T["测试环境验证"]
T --> T_PASS{"测试通过?"}
T_PASS --> |否| FIX["修复并重新执行迁移"]
FIX --> T
T_PASS --> |是| M["合并到 release/hotfix"]
M --> L["上线执行迁移"]
L --> END["结束"]
```

图表来源
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)

章节来源
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)

### 版本控制最佳实践
- 提交信息规范（参考 Conventional Commits）：
  - 类型：feat/fix/docs/style/refactor/test/build/ci/chore
  - 主题：应用/插件/迁移/配置/安全
  - 描述：简洁明了，必要时附带问题编号
- 标签管理：
  - 语义化版本：vX.Y.Z（稳定版），vX.Y.Z-rc.N（候选版），vX.Y.Z-hotfix.N（热修复）
  - 标签与发布说明：每次打标签时附带变更摘要与迁移注意事项
- 版本发布策略：
  - develop → release 分支进行最终验证与迁移校验
  - release 合并至 main 并打标签，随后推送到各环境
  - hotfix 分支直接修复生产问题并回溯到 main 与 develop

章节来源
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)

### 团队角色与职责
- 迁移负责人（DBA/技术负责人）：
  - 审核迁移设计，确保数据一致性与回滚策略完备
  - 统筹迁移执行与回滚，协调跨应用/插件的影响面
- 测试人员：
  - 负责迁移回归测试、API 文档一致性检查、插件/主题兼容性验证
  - 关注安全扫描与性能回归
- 运维人员：
  - 负责生产环境迁移执行、回滚预案、监控告警与应急响应
  - 维护发布流程与环境配置（.env 优先级）

章节来源
- [AGENTS.MD: 510-547:510-547](file://AGENTS.MD#L510-L547)
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)

### 冲突解决机制
- 代码冲突：
  - 优先通过小步快跑与频繁合并减少冲突；冲突集中在同一文件时，采用“功能开关/条件分支”过渡
  - 评审中强制解决冲突，避免遗留未处理的冲突标记
- 数据冲突：
  - 迁移中严格区分“结构变更”与“数据变更”，必要时分多次迁移
  - 对历史数据进行清洗与映射，保证迁移前后业务连续性
- 配置冲突：
  - 优先使用 .env 覆盖动态配置，避免硬编码
  - 多环境配置分离，通过环境矩阵与 CI 参数化

章节来源
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)

### 沟通机制与问题跟踪
- 沟通渠道：
  - 日常：即时通讯群组/工单系统
  - 重大变更：评审会议与 PR 评论区同步
- 问题跟踪：
  - 使用 Issue 模板记录缺陷、需求与变更项
  - 关联 PR/Commit 与迁移，形成闭环
- CI 与质量门禁：
  - .workflow 中定义的流水线在指定分支自动触发
  - 通过安全扫描与依赖审计，阻断高危变更进入主干

章节来源
- [.workflow/pipeline-20240224.yml: 1-24:1-24](file://.workflow/pipeline-20240224.yml#L1-L24)

## 依赖分析
- 迁移依赖：xia/migration（Phinx 风格），提供迁移服务注册与自动加载
- Composer 自动化：安装/更新后自动执行服务发现、资源发布与迁移
- 环境隔离：.env 优先级最高，动态配置次之，静态配置最低

```mermaid
graph LR
CJ["composer.json"] --> PL["插件/主题/应用"]
CJ --> SRV["服务发现<br/>service:discover"]
CJ --> PUB["资源发布<br/>vendor:publish"]
CJ --> MIG["迁移执行<br/>migrate:run"]
CL["composer.lock"] --> XIA["xia/migration"]
ENV[".env"] --> CFG["配置优先级<br/>.env > data/config > config"]
```

图表来源
- [composer.json: 67-72:67-72](file://composer.json#L67-L72)
- [composer.lock: 1122-1151:1122-1151](file://composer.lock#L1122-L1151)
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)

章节来源
- [composer.json: 67-72:67-72](file://composer.json#L67-L72)
- [composer.lock: 1122-1151:1122-1151](file://composer.lock#L1122-L1151)
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)

## 性能考虑
- 迁移性能：
  - 避免长事务与大表全量扫描，必要时分批处理
  - 合理使用索引与批量写入，减少锁竞争
- 自动化性能：
  - 在 CI 中缓存 Composer 依赖，缩短安装时间
  - 并行执行非依赖任务（测试、扫描），串行执行迁移与部署
- 部署性能：
  - 生产环境使用优化自动加载与 OPcache，减少启动开销

## 故障排查指南
- 迁移失败：
  - 检查迁移文件是否被正确识别与执行
  - 核对数据库连接与字符集设置
  - 若出现破坏性变更，先回滚再评估反向迁移
- 依赖安装异常：
  - 清理缓存并重新安装，确认 Composer 配置与插件允许策略
- 环境配置问题：
  - 确认 .env 是否被正确加载，优先级链路是否被覆盖
- CI 失败：
  - 查看流水线日志，定位安全扫描或依赖问题

章节来源
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)
- [.workflow/pipeline-20240224.yml: 1-24:1-24](file://.workflow/pipeline-20240224.yml#L1-L24)

## 结论
通过规范的分支与评审流程、严谨的迁移管理、完善的自动化与质量门禁，ThinkCMF 项目可在多应用/多插件生态中实现高效协作与稳定交付。建议团队持续完善评审清单、冲突处理预案与应急演练，确保版本演进的可控与可追溯。

## 附录
- 环境变量示例与优先级说明
- 迁移命令速查与最佳实践清单
- CI 流水线配置与触发规则

章节来源
- [.example.env: 1-1:1-1](file://.example.env#L1-L1)
- [AGENTS.MD: 716-741:716-741](file://AGENTS.MD#L716-L741)
- [AGENTS.MD: 576-599:576-599](file://AGENTS.MD#L576-L599)
- [.workflow/pipeline-20240224.yml: 1-24:1-24](file://.workflow/pipeline-20240224.yml#L1-L24)