Ai Forge

开发流程指南 ​

1. 环境要求 ​

  • PHP >= 8.4
  • PHP 扩展：pdo、mbstring、openssl、redis、bcmath、ctype、json、fileinfo、tokenizer、xml
  • Composer >= 2.x
  • MySQL 8.0+ / PostgreSQL / SQLite
  • Redis 6.0+
  • Node.js >= 20.x（前端资源构建）
  • 推荐使用 Laravel Herd 作为本地开发环境

2. 快速开始 ​

bash
# 一键安装（推荐）
composer run setup

# 启动开发环境
composer run dev

手动步骤：

bash
composer install
cp .env.example .env
php artisan key:generate
# 配置 .env 数据库连接后
php artisan migrate
php artisan storage:link
npm install
npm run build

本地访问地址：http://laravel-skel-forge.test（Herd 自动提供）。

3. 开发命令 ​

命令说明
composer run setup一键安装（依赖、密钥、迁移、存储链接、前端构建）
composer run dev启动开发环境（server/queue/pail/vite）
composer run test运行全部测试
composer run check-style检查代码风格（Pint）
composer run fix-style修复代码风格（Pint）
php artisan route:list查看路由列表
php artisan route:list --path=admin查看后台路由
php artisan horizon启动队列服务（生产用 Supervisor 守护）
php artisan pail查看实时日志
php artisan schedule:work本地运行调度器

4. 代码规范 ​

  • 遵循 PSR-12 编码标准
  • 使用 PHP 8.4 特性：构造器属性提升、命名参数、枚举、match 表达式
  • 所有 PHP 文件强制 declare(strict_types=1) 和文件头 License 注释
  • 所有方法添加参数类型声明和返回类型声明
  • 使用 PHPUnit 12 新属性语法（#[Test]、#[CoversClass]、#[Group]、#[TestDox]）
  • 修改 PHP 文件后必须运行 vendor/bin/pint --dirty --format agent
  • 使用 php artisan make: 命令创建文件，传递 --no-interaction 参数
  • AI Agent 使用 php artisan make:agent / php artisan make:tool（自定义 stub 在 stubs/）

5. 全局辅助函数（bootstrap/helpers.php） ​

函数说明
cpu_count(): int获取 CPU 核心数
per_page(Request $request, int $limit = 15): int获取分页大小（限制 1~100）
mobile_replace(?string $value): string手机号脱敏
settings(string $key, $default): mixed快捷读取系统设置
validation_exception($field, $message): void快速抛出表单验证异常

文档来源：PRD 第 10 章