# 开发指南

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [public/index.php](file://public/index.php)
- [.gitignore](file://.gitignore)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)
- [AGENTS.MD](file://AGENTS.MD)
- [public/static/js/wind.js](file://public/static/js/wind.js)
- [public/static/js/ueditor/third-party/video-js/video.dev.js](file://public/static/js/ueditor/third-party/video-js/video.dev.js)
- [public/static/js/ueditor/third-party/highcharts/highcharts.src.js](file://public/static/js/ueditor/third-party/highcharts/highcharts.src.js)
- [public/static/js/ueditor/third-party/SyntaxHighlighter/shCore.js](file://public/static/js/ueditor/third-party/SyntaxHighlighter/shCore.js)
</cite>

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

## 简介
本开发指南面向 ThinkCMF 8.x 开发者，围绕开发环境搭建、IDE 配置与调试、版本控制、代码规范与最佳实践、调试与性能分析、测试策略、代码审查与质量保障、常见开发场景、CI/CD 与自动化部署、开发效率工具与团队协作等方面进行系统性说明。内容基于仓库中的 README、Composer 配置、入口文件、工作流脚本与辅助前端脚本等文件整理而成。

## 项目结构
- 入口与运行
  - Web 根目录：public，入口文件为 public/index.php
  - 应用入口通过 vendor/autoload.php 加载并执行 HTTP 应用
- 包管理与自动加载
  - 使用 Composer 管理依赖，PSR-4 映射 app、api、plugins、themes 等命名空间
- 配置与环境
  - 环境变量优先级：.env > data/config 动态配置 > config 静态配置
  - 推荐使用 .env 进行调试与数据库等配置
- 版本控制与忽略
  - .gitignore 忽略 IDE、构建产物、日志与 .env 等
- 持续集成
  - .workflow/pipeline-20240224.yml 提供开源组件扫描流水线示例

```mermaid
graph TB
A["Web 根目录<br/>public"] --> B["入口文件<br/>public/index.php"]
B --> C["自动加载<br/>vendor/autoload.php"]
C --> D["HTTP 应用执行"]
E["Composer 配置<br/>composer.json"] --> C
F[".env 环境变量"] --> D
G[".gitignore"] --> H["版本控制忽略项"]
I[".workflow/pipeline-20240224.yml"] --> J["CI 流水线"]
```

**图示来源**
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [composer.json:46-56](file://composer.json#L46-L56)
- [.gitignore:1-17](file://.gitignore#L1-L17)
- [.workflow/pipeline-20240224.yml:1-23](file://.workflow/pipeline-20240224.yml#L1-L23)

**章节来源**
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [composer.json:46-56](file://composer.json#L46-L56)
- [.gitignore:1-17](file://.gitignore#L1-L17)
- [.workflow/pipeline-20240224.yml:1-23](file://.workflow/pipeline-20240224.yml#L1-L23)

## 核心组件
- 应用入口与运行
  - public/index.php 定义根路径、数据目录、应用目录，加载 vendor 并执行 HTTP 应用
- 包管理与自动加载
  - composer.json 声明最小 PHP 版本、必需扩展、依赖包与 PSR-4 映射
- 配置体系
  - AGENTS.MD 展示了 .env 的典型键位与配置优先级
- 版本控制与 CI
  - .gitignore 控制忽略项；.workflow/pipeline-20240224.yml 提供流水线示例

**章节来源**
- [public/index.php:15-37](file://public/index.php#L15-L37)
- [composer.json:30-42](file://composer.json#L30-L42)
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)
- [.workflow/pipeline-20240224.yml:1-23](file://.workflow/pipeline-20240224.yml#L1-L23)

## 架构总览
ThinkCMF 采用多应用架构与插件机制，入口文件负责初始化运行环境，Composer 负责依赖与自动加载，配置体系支持 .env 与动态配置，前端静态资源通过 public 提供。

```mermaid
graph TB
subgraph "运行时"
IDX["入口<br/>public/index.php"]
AUTO["自动加载<br/>vendor/autoload.php"]
APP["HTTP 应用"]
end
subgraph "依赖与配置"
CJ["Composer<br/>composer.json"]
ENV[".env"]
CFG["动态配置<br/>data/config"]
end
subgraph "前端资源"
PUB["public 静态资源"]
JS["JS 辅助脚本<br/>wind.js 等"]
end
IDX --> AUTO --> APP
CJ --> AUTO
ENV --> APP
CFG --> APP
PUB --> IDX
JS --> PUB
```

**图示来源**
- [public/index.php:27-33](file://public/index.php#L27-L33)
- [composer.json:46-56](file://composer.json#L46-L56)
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)
- [public/static/js/wind.js:564-599](file://public/static/js/wind.js#L564-L599)

## 详细组件分析

### 组件一：应用入口与运行流程
- 入口职责
  - 定义 CMF_ROOT、CMF_DATA、APP_PATH、WEB_ROOT
  - 引导 vendor autoload
  - 创建并运行 HTTP 应用，发送响应并结束
- 关键点
  - APP_DEBUG 已移至 .env 控制
  - 通过 App()->http 执行请求生命周期

```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant Entry as "入口<br/>public/index.php"
participant Auto as "自动加载<br/>vendor/autoload.php"
participant Http as "HTTP 应用"
participant Resp as "响应"
Browser->>Entry : 请求到达
Entry->>Auto : 加载自动加载器
Entry->>Http : 创建并运行应用
Http-->>Resp : 生成响应
Resp-->>Browser : 返回响应
Entry->>Entry : 发送响应并结束
```

**图示来源**
- [public/index.php:27-37](file://public/index.php#L27-L37)

**章节来源**
- [public/index.php:12-37](file://public/index.php#L12-L37)

### 组件二：Composer 与自动加载
- 依赖与扩展
  - PHP 版本要求、必需扩展、核心包映射
- 自动加载
  - PSR-4：app、api、plugins、themes
  - PSR-0：extend/
- 生命周期脚本
  - post-autoload-dump 中触发服务发现、发布资源、迁移执行

```mermaid
flowchart TD
Start(["Composer 安装"]) --> Dump["执行 post-autoload-dump"]
Dump --> Discover["service:discover"]
Discover --> Publish["vendor:publish"]
Publish --> Migrate["migrate:run"]
Migrate --> End(["完成"])
```

**图示来源**
- [composer.json:67-72](file://composer.json#L67-L72)

**章节来源**
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:46-56](file://composer.json#L46-L56)
- [composer.json:67-72](file://composer.json#L67-L72)

### 组件三：配置与环境
- 环境变量优先级
  - .env > data/config 动态配置 > config 静态配置
- 常用键位
  - APP_DEBUG、APP_DEFAULT_TIMEZONE、数据库相关键位
- 部署建议
  - 生产环境关闭调试，设置只读数据库与安全凭据

**章节来源**
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)

### 组件四：版本控制与忽略
- 忽略项
  - IDE 目录、构建产物、日志、.env、Docker 数据目录等
- 建议
  - 将 .env 作为敏感配置忽略，仅保留 .example.env 示例

**章节来源**
- [.gitignore:1-17](file://.gitignore#L1-L17)

### 组件五：持续集成与自动化
- 流水线示例
  - .workflow/pipeline-20240224.yml 展示了开源组件检测步骤
- 建议扩展
  - 添加静态分析、单元测试、覆盖率、安全扫描、构建产物归档等阶段

```mermaid
flowchart TD
Push["推送事件"] --> Stage["阶段：组件检测"]
Stage --> Step["步骤：OpenSCA 检测"]
Step --> Retry{"重试次数"}
Retry --> |0| Done["完成"]
```

**图示来源**
- [.workflow/pipeline-20240224.yml:16-23](file://.workflow/pipeline-20240224.yml#L16-L23)

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

### 组件六：前端辅助脚本与调试
- wind.js
  - 条件加载与回调去重等工具函数，可用于前端资源按需加载
- video.js
  - 日志输出与播放错误处理，便于媒体播放调试
- highcharts
  - 图表格式化与日期处理工具，有助于数据可视化调试
- SyntaxHighlighter
  - 代码高亮与缩进处理，适合文档与演示页面

```mermaid
graph LR
W["wind.js"] --> L1["条件加载/回调去重"]
V["video.dev.js"] --> L2["日志输出/错误处理"]
H["highcharts.src.js"] --> L3["格式化/日期处理"]
S["shCore.js"] --> L4["代码高亮/缩进处理"]
```

**图示来源**
- [public/static/js/wind.js:564-599](file://public/static/js/wind.js#L564-L599)
- [public/static/js/ueditor/third-party/video-js/video.dev.js:1250-3240](file://public/static/js/ueditor/third-party/video-js/video.dev.js#L1250-L3240)
- [public/static/js/ueditor/third-party/highcharts/highcharts.src.js:414-545](file://public/static/js/ueditor/third-party/highcharts/highcharts.src.js#L414-L545)
- [public/static/js/ueditor/third-party/SyntaxHighlighter/shCore.js:1477-2718](file://public/static/js/ueditor/third-party/SyntaxHighlighter/shCore.js#L1477-L2718)

**章节来源**
- [public/static/js/wind.js:564-599](file://public/static/js/wind.js#L564-L599)
- [public/static/js/ueditor/third-party/video-js/video.dev.js:1250-3240](file://public/static/js/ueditor/third-party/video-js/video.dev.js#L1250-L3240)
- [public/static/js/ueditor/third-party/highcharts/highcharts.src.js:414-545](file://public/static/js/ueditor/third-party/highcharts/highcharts.src.js#L414-L545)
- [public/static/js/ueditor/third-party/SyntaxHighlighter/shCore.js:1477-2718](file://public/static/js/ueditor/third-party/SyntaxHighlighter/shCore.js#L1477-L2718)

## 依赖分析
- 运行时依赖
  - PHP 版本与扩展要求
  - 核心包：cmf-app、cmf-api、cmf-install、cmf-appstore、cmf-root
- 自动加载映射
  - PSR-4：app、api、plugins、themes
  - PSR-0：extend/
- 生命周期脚本
  - 安装后自动执行服务发现、资源发布与迁移

```mermaid
graph TB
CJ["composer.json"] --> PHP["PHP >= 8.1"]
CJ --> EXT["扩展：json,curl,pdo,mbstring,zip"]
CJ --> PKG["核心包：cmf-app / cmf-api / cmf-install / cmf-appstore / cmf-root"]
CJ --> PSR4["PSR-4：app / api / plugins / themes"]
CJ --> PSR0["PSR-0：extend/"]
CJ --> Scripts["post-autoload-dump：discover/publish/migrate"]
```

**图示来源**
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:46-56](file://composer.json#L46-L56)
- [composer.json:67-72](file://composer.json#L67-L72)

**章节来源**
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:46-56](file://composer.json#L46-L56)
- [composer.json:67-72](file://composer.json#L67-L72)

## 性能考虑
- 生产部署
  - 关闭调试、优化自动加载、合理设置缓存与静态资源 CDN
- 前端资源
  - 合理拆分与懒加载，避免重复引入与阻塞渲染
- 数据库
  - 使用连接池、索引优化、查询缓存与分页策略
- 配置优先级
  - 将高频变更项置于 .env，减少动态配置层压力

[本节为通用建议，无需特定文件引用]

## 故障排查指南
- 入口与自动加载
  - 若出现类找不到或自动加载失败，检查 vendor 是否存在、composer dump-autoload 是否执行
- 配置优先级
  - 确认 .env 键位正确且已生效，动态配置未覆盖关键项
- 媒体播放与图表
  - 利用 video.js 的日志输出定位播放错误；借助 highcharts 的格式化函数核对数据格式
- 前端按需加载
  - wind.js 的条件加载与回调去重可用于排查资源加载顺序问题

**章节来源**
- [public/index.php:27-33](file://public/index.php#L27-L33)
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)
- [public/static/js/ueditor/third-party/video-js/video.dev.js:3201-3203](file://public/static/js/ueditor/third-party/video-js/video.dev.js#L3201-L3203)
- [public/static/js/ueditor/third-party/highcharts/highcharts.src.js:498-520](file://public/static/js/ueditor/third-party/highcharts/highcharts.src.js#L498-L520)
- [public/static/js/wind.js:564-599](file://public/static/js/wind.js#L564-L599)

## 结论
本指南从入口与运行、依赖与自动加载、配置与环境、版本控制与 CI、前端辅助脚本等多个维度梳理了 ThinkCMF 的开发要点。建议在开发中严格遵循环境与配置优先级、保持 .gitignore 的合理设置、结合 CI 流水线完善质量保障，并利用前端脚本与日志能力提升调试效率。

[本节为总结，无需特定文件引用]

## 附录

### A. 开发环境与 IDE 配置建议
- PHP 版本与扩展
  - PHP >= 8.1，启用 json、curl、pdo、mbstring、zip
- IDE 建议
  - PHPStorm/VSCode 配置 PSR-4 自动补全与断点调试
  - 为 public/index.php 设置 Web 根目录为 public
- .env 管理
  - 复制 .example.env 为 .env，设置调试与数据库参数

**章节来源**
- [composer.json:30-42](file://composer.json#L30-L42)
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)

### B. 调试工具与技巧
- 日志与错误追踪
  - 使用 video.js 的日志输出定位播放错误
  - 在 .env 中开启调试以获取更详细的错误信息
- 前端资源加载
  - wind.js 的条件加载与回调去重可用于排查资源加载问题
- 图表与数据
  - highcharts 的格式化与日期处理辅助核对数据

**章节来源**
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)
- [public/static/js/ueditor/third-party/video-js/video.dev.js:1250-3240](file://public/static/js/ueditor/third-party/video-js/video.dev.js#L1250-L3240)
- [public/static/js/wind.js:564-599](file://public/static/js/wind.js#L564-L599)
- [public/static/js/ueditor/third-party/highcharts/highcharts.src.js:414-545](file://public/static/js/ueditor/third-party/highcharts/highcharts.src.js#L414-L545)

### C. 版本控制与分支策略
- 忽略项
  - IDE、构建产物、日志、.env、Docker 数据目录
- 分支与合并
  - 建议采用 Feature 分支与 Pull Request 流程，配合 CI 自动检测

**章节来源**
- [.gitignore:1-17](file://.gitignore#L1-L17)

### D. 持续集成与自动化部署
- 流水线示例
  - 参考 .workflow/pipeline-20240224.yml 的组件检测步骤
- 建议扩展
  - 静态分析、单元测试、覆盖率、安全扫描、构建产物归档与部署

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

### E. 常见开发场景
- 复杂查询
  - 使用 ORM 与索引优化，避免 N+1 查询
- 异步处理
  - 使用队列与计划任务，分离耗时操作
- 并发控制
  - 使用锁与幂等设计，确保数据一致性

[本节为通用建议，无需特定文件引用]

### F. 代码规范与最佳实践
- 命名约定
  - 类与命名空间遵循 PSR-4；控制器、模型、服务按模块划分
- 代码风格
  - 统一缩进与换行；注释清晰描述意图与边界条件
- 注释标准
  - 公共接口与复杂逻辑提供说明；变更与风险点明确标注

[本节为通用建议，无需特定文件引用]

### G. 单元测试与集成测试
- 测试框架
  - 建议使用 PHPUnit 或 ThinkPHP 内置测试能力
- 覆盖率
  - 建议关键业务模块达到 80%+ 覆盖率
- CI 集成
  - 在流水线中加入测试与覆盖率报告

[本节为通用建议，无需特定文件引用]

### H. 代码审查与质量保证
- 审查清单
  - 代码风格、安全性、性能、可维护性与测试覆盖
- 质量门禁
  - 未达标的 PR 不允许合并

[本节为通用建议，无需特定文件引用]

### I. 开发效率工具与团队协作
- 工具
  - IDE 断点调试、Git 工作流、CI/CD、静态分析
- 协作
  - 规范化的分支命名、PR 描述与代码评审流程

[本节为通用建议，无需特定文件引用]