项目概览

基于 webman 的后台管理系统 API 服务，提供 RBAC 权限管理。PHP >= 8.1，Eloquent + Redis。

目录导航

目录	说明	文档
app/	业务代码（控制器、模型、中间件、Service 等）	app/CLAUDE.md
config/	全部配置文件（含插件配置）	config/CLAUDE.md
database/	Phinx 数据库迁移	database/CLAUDE.md

请求流程

客户端 RSA 加密请求体
    → AccessMiddleware（CORS 头）
    → LangMiddleware（Accept-Language 设置语言）
    → AdminAuthMiddleware（解密、Token 校验、注入 $request->data 和 $request->admins）
    → 控制器方法
    → success()/fail() 返回 JSON

这是全局中间件链，顺序不可变。解密后的请求参数从 $request->data 取（数组），不要用 $request->all()。

API 响应

{"code": 0, "message": "成功", "data": {}}

成功：success($request, $data, $message)
失败：fail($request, $code, $data, $message)
错误码：config/code.php（0=成功，9xxxxx=业务错误），message 走 Symfony 翻译
异常处理：app/exception/Handler.php 统一捕获，BusinessException 自动渲染为 fail() 响应

路由

所有路由在 config/route.php 手动注册，前缀 /admin-api，默认路由已关闭
命名格式：[业务模块-功能描述]，使用中文
全部 POST 接口（加密通信场景）

代码规范

PHPDoc 注释

所有类和 public/protected 方法必须有中文 PHPDoc，包含完整 @param/@return/@throws：

/**
 * 认证相关 - 登录
 *
 * @param string $username 账号
 * @param string $password 密码
 * @return string 登录凭证
 * @throws BusinessException
 */
public static function login(string $username, string $password): string

类注释：简述职责
方法注释：描述做什么（不描述怎么实现）
框架约定方法（boot()、consume() 等）可精简，但至少要一行说明

类型系统

所有方法必须有参数类型和返回类型声明。充分利用 PHP 8.1+ 特性，避免技术债：

✅ 推荐（PHP 8.1+）	❌ 禁止（旧式写法）
`function foo(string $name): ?User`	`function foo($name)` 无类型
`enum Enable: int`（放 `resource/enums/`）	class 常量模拟枚举
`readonly` 修饰不变量	`@var` 注释 + 约定不修改
`match($val) { ... }`	`switch` 做纯值匹配
`$obj?->method()` nullsafe	`$obj ? $obj->method() : null`
构造函数属性提升 `__construct(private Service $s) {}`	构造函数逐字段赋值
`fn($x) => $x * 2` 箭头函数	`function($x) { return $x * 2; }`

架构分层

Controller → 参数获取 + 调 Service（或简单 Eloquent 查询）+ 返回
Service   → 全部静态方法，禁止 new。成功 return，失败 throw BusinessException。不依赖 $request
Model     → boot() 只放纯数据转换，不写业务逻辑

详细分层规范见 app/service/CLAUDE.md 和 app/controller/CLAUDE.md。

常用命令

php start.php start          # 开发模式（带热重载）
php start.php start -d       # 生产模式
php start.php restart        # 重启（改 process.php/server.php 必须 restart）
php start.php status         # 查看状态
vendor/bin/phinx migrate     # 执行迁移（手动执行，AI 不得执行）
vendor/bin/phinx create Xxx  # 创建迁移

FilesExpand file tree

CLAUDE.md

Latest commit

History