# 团队协作

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [AGENTS.MD](file://AGENTS.MD)
- [composer.json](file://composer.json)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)
- [.gitignore](file://.gitignore)
- [.example.env](file://.example.env)
- [public/themes/admin_default/admin/plugin/index.html](file://public/themes/admin_default/admin/plugin/index.html)
- [public/themes/admin_default/admin/api/import.html](file://public/themes/admin_default/admin/api/import.html)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
</cite>

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

## 引言
本指南面向 ThinkCMF 团队协作与工程化实践，围绕代码审查流程、版本控制最佳实践、项目文档管理、开发流程标准化、团队沟通协作工具、知识分享与培训机制以及工具链配置与自动化流程进行系统化梳理。目标是帮助团队建立一致、高效、可追溯的协作方式，提升交付质量与效率。

## 项目结构
ThinkCMF 采用多应用架构与插件化扩展，核心目录与职责如下：
- 根目录：Composer 依赖、环境配置示例、命令行入口、README 等
- app/：前台应用目录
- api/：API 应用目录，独立入口 public/api.php
- data/：动态配置、路由、运行时缓存、日志、私有上传
- public/：Web 根目录，包含插件、静态资源、主题、公开上传
- vendor/：Composer 依赖
- .workflow/：CI 流水线配置（示例：OpenSCA 组件检测）

```mermaid
graph TB
Root["根目录<br/>composer.json/.example.env/README"] --> App["app/<br/>前台应用"]
Root --> Api["api/<br/>API 应用"]
Root --> Data["data/<br/>动态配置/路由/缓存/日志/上传"]
Root --> Public["public/<br/>Web 根目录"]
Public --> Plugins["public/plugins/<br/>插件目录"]
Public --> Static["public/static/<br/>官方静态资源"]
Public --> Themes["public/themes/<br/>主题目录"]
Public --> Upload["public/upload/<br/>公开上传"]
Root --> Vendor["vendor/<br/>Composer 依赖"]
Root --> Workflow[".workflow/<br/>CI 流水线"]
```

图表来源
- [AGENTS.MD](file://AGENTS.MD)
- [composer.json](file://composer.json)

章节来源
- [AGENTS.MD](file://AGENTS.MD)
- [composer.json](file://composer.json)

## 核心组件
- 多应用架构与入口
  - 前台应用入口：public/index.php
  - API 应用入口：public/api.php
- 插件系统
  - 插件根目录：public/plugins/
  - 支持钩子系统与独立功能模块
- Swagger API 文档插件
  - 插件入口与控制器：public/plugins/swagger/SwaggerPlugin.php、AdminIndexController.php
  - OpenAPI 规范生成：OpenApiSpec.php
  - OpenAPI 服务：OpenApi.php
- CI 流水线
  - OpenSCA 组件检测流水线：.workflow/pipeline-20240224.yml

章节来源
- [AGENTS.MD](file://AGENTS.MD)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)

## 架构总览
ThinkCMF 采用 MVC 多应用架构，结合插件与主题系统，形成“应用 + 插件 + 主题”的扩展生态；API 通过 RESTful 设计与 Swagger 文档支撑前后端分离与第三方集成。

```mermaid
graph TB
subgraph "应用层"
Home["前台应用(app/)"]
API["API 应用(api/)"]
end
subgraph "扩展层"
Plugin["插件系统(public/plugins/)"]
Theme["主题系统(public/themes/)"]
end
subgraph "基础设施"
Swagger["Swagger 插件<br/>OpenApiSpec/OpenApi"]
CI["CI 流水线<br/>OpenSCA 组件检测"]
end
Home --> Theme
API --> Swagger
Home --> Plugin
API --> Plugin
Plugin --> Swagger
CI --> Root["根目录"]
```

图表来源
- [AGENTS.MD](file://AGENTS.MD)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)

## 详细组件分析

### 代码审查流程与 PR 标准
- Pull Request 创建
  - 基于稳定的分支（如 8.0）创建功能或修复分支
  - 在 PR 描述中明确变更范围、影响面、测试要点与风险点
- 审查标准
  - 代码规范：遵循 PSR-2/PSR-4，命名统一，注释清晰
  - 安全性：避免敏感信息泄露，校验输入，最小权限原则
  - 性能：避免 N+1 查询，合理使用缓存与索引
  - 兼容性：遵循最低 PHP 版本要求与依赖约束
  - 文档：新增/变更接口需同步更新 Swagger 文档
- 代码质量检查清单
  - 无 exit/die 等阻断式调用
  - 字段内容使用 htmlspecialchars 处理
  - 数据库迁移与回滚测试通过
  - 插件/主题的钩子与命名空间正确
- 审查反馈处理与改进
  - 对每条评论逐项响应与修改
  - 修订后重新触发 CI 检测
  - 关联问题单号，保持历史可追溯

章节来源
- [AGENTS.MD](file://AGENTS.MD)
- [README.md](file://README.md)

### 版本控制最佳实践
- 分支策略
  - 主分支：8.0（稳定版），master（开发版）
  - 功能分支：feature/xxx
  - 修复分支：hotfix/xxx
  - 发布分支：release/8.0.x
- 提交信息规范
  - 格式：type(scope): subject
  - 示例：feat(plugin): 新增插件钩子执行顺序设置
- 合并策略
  - 使用 squash merge 保持主干整洁
  - 合并前确保 CI 通过与审查通过
- 历史记录管理
  - 避免不必要的 rebase，必要时使用 merge commit 保留分支历史
  - 敏感信息（密钥、路径）不得进入提交历史

章节来源
- [.gitignore](file://.gitignore)
- [README.md](file://README.md)

### 项目文档管理
- 编写标准
  - 结构化文档：概述、技术栈、目录结构、架构设计、开发规范、部署指南
  - 统一术语与命名规范，前后文一致
- 版本控制与维护流程
  - 文档与代码同仓库管理，随版本打 Tag
  - 变更记录纳入更新日志，明确版本差异
- 文档与代码一致性
  - API 文档与实现同步更新（Swagger）
  - 配置示例与实际 .env/.example.env 保持一致

章节来源
- [AGENTS.MD](file://AGENTS.MD)
- [.example.env](file://.example.env)

### 开发流程标准化
- 需求分析
  - 明确功能边界、用户场景与验收条件
- 设计评审
  - 架构设计、数据库设计、API 设计、插件/主题扩展点
- 开发规范
  - 命名规范、注释规范、安全规范、性能规范
- 测试流程
  - 单元测试、集成测试、API 测试（Swagger）、兼容性测试
- 发布流程
  - 版本号管理、Tag 发布、生产环境部署、回滚预案

章节来源
- [AGENTS.MD](file://AGENTS.MD)
- [public/themes/admin_default/admin/api/import.html](file://public/themes/admin_default/admin/api/import.html)

### 团队沟通协作工具
- 项目管理
  - 使用 Issue/PR 跟踪任务与缺陷，按里程碑规划迭代
- 即时通讯
  - 团队内部沟通，快速同步进展与问题
- 文档共享
  - 公开文档与内部 Wiki 并行，确保知识沉淀与检索便利

（本节为通用实践建议，无需特定文件引用）

### 知识分享与培训机制
- 技术分享会
  - 定期组织框架演进、架构设计、安全与性能专题分享
- 新人培训
  - 从环境搭建、目录结构、开发规范到部署流程的系统培训
- 经验总结
  - 每次迭代/发布后进行复盘，沉淀最佳实践与常见坑位

（本节为通用实践建议，无需特定文件引用）

### 工具链配置与自动化流程
- Composer 自动化
  - 安装/更新后自动执行：服务发现、资源发布、数据库迁移
- CI 流水线
  - OpenSCA 组件检测流水线，限定分支与检测路径
- 命令行工具
  - Think 命令：服务管理、数据库迁移、资源发布、CLI 工具

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Repo as "代码仓库"
participant CI as "CI 流水线"
participant SCA as "OpenSCA 组件检测"
Dev->>Repo : 推送分支/PR
Repo->>CI : 触发流水线
CI->>SCA : 执行组件检测
SCA-->>CI : 返回检测结果
CI-->>Dev : 通知构建状态
```

图表来源
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)

章节来源
- [composer.json](file://composer.json)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)

## 依赖分析
- 核心依赖
  - ThinkPHP 8.x 框架与 ORM
  - 数据库迁移工具（phinx 风格）
  - Swagger 插件（基于 Doctrine Annotations）
- 开发依赖
  - 调试工具与 IDE 辅助
- 自动化脚本
  - post-autoload-dump 钩子自动执行服务发现、资源发布、迁移

```mermaid
graph LR
Composer["composer.json"] --> TP["topthink/framework"]
Composer --> ORM["topthink/think-orm"]
Composer --> Migration["xia/migration"]
Composer --> Swagger["public/plugins/swagger"]
Composer --> Trace["topthink/think-trace"]
```

图表来源
- [composer.json](file://composer.json)

章节来源
- [composer.json](file://composer.json)

## 性能考虑
- 数据库层面
  - 合理索引、避免全表扫描，使用软删除与状态字段
- 应用层面
  - 控制器与模型职责清晰，避免重复查询
  - 插件与钩子尽量轻量化，减少全局钩子数量
- 部署层面
  - 生产环境关闭调试，优化自动加载与缓存

（本节为通用实践建议，无需特定文件引用）

## 故障排查指南
- Swagger 文档不可用
  - 确认已安装并启用 Swagger 插件，访问后台 API 文档入口
- API 文档生成失败
  - 检查 PHP 版本是否满足 Swagger 插件要求，确认注解语法正确
- CI 组件检测失败
  - 检查流水线配置与检测路径，定位第三方依赖风险

章节来源
- [public/themes/admin_default/admin/api/import.html](file://public/themes/admin_default/admin/api/import.html)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)

## 结论
通过规范化的代码审查、版本控制、文档管理与开发流程，配合 CI 自动化与工具链配置，ThinkCMF 团队能够持续稳定地交付高质量产品。建议在实践中不断沉淀最佳实践，并根据项目演进调整流程与工具。

## 附录
- API 文档与 Swagger
  - 插件入口与控制器：public/plugins/swagger/SwaggerPlugin.php、AdminIndexController.php
  - OpenAPI 规范生成：public/plugins/swagger/swagger/OpenApiSpec.php
  - OpenAPI 服务：public/plugins/swagger/service/OpenApi.php

章节来源
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)