API 接口规范

接口以"动作式子路径"组织（非严格 REST 资源式），统一前缀 + 方法级注解生成。

路由前缀

前缀	用途	鉴权
/pub/*	公开（登录、验证码等）	免登录 $noNeedLogin
/sys/*	基座系统管理	登录 + #[Permission]
/notify/*	通知中心	登录 + RBAC
/plugin/*	插件管理后台、应用插件	登录 + RBAC
/oauth/*	免登票据 issue/consume/exchange	见各端点
/app/{name}/*	插件页面入口与业务接口	插件 $noNeedLogin / 会员鉴权

声明方式：类级 #[RouteGroup('/sys/{module}')] 定前缀，方法级 #[Get]/#[Post] 定子路径，前缀自动拼接。页面入口（无尾斜杠）例外，需在 config/route.php 手动 Route::get。

动作式子路径

方法	路径	HTTP	说明
列表	/index	GET	分页列表
详情	/read?id={id}	GET	单条详情
新增	/save	POST	创建
更新	/update	POST	更新
删除	/delete	POST	删除单条
批量删除	/batchDelete	POST	批量
状态切换	/changeStatus	POST	启用/禁用

读用 GET、写用 POST（删除/切换也走 POST，便于带 body 与统一 CSRF 处理）。业务动作按语义命名（/editPass、/setDefault、/retry、/preview、/test）。

入参约定

• GET 参数走 query（$request->get()），POST 走 body（$request->post()）。
• 列表统一带分页入参，buildMap([...]) 组装可选过滤，搜索器承接关键词与时间范围。
• 前端请求：GET 用 params、POST 用 data。

响应格式

统一 {code, msg, total, data, page}，由 success()/warning()/error()（底层 ret()）产出：

{ "code": 200, "msg": "success", "data": {}, "total": 100, "page": 1 }

{ "code": 400, "msg": "错误信息", "data": null, "total": 0, "page": 1 }

code：200 成功、400 业务/参数错、401 未登录、403 无权限、500 服务器错。

是 msg、是 page

提示文案键名 msg（不是 message），分页页码键名 page（旧文档示例里的 current 已不准确）。前端拦截器据此分流，写接口时对齐。

认证

Authorization/token 头携 Bearer {accessToken}（登录后拿 accessToken/refreshToken，exp 默认 2 小时）。AuthCheck 中间件校验有效性，$noNeedLogin 内的 action 放行。

完整字段与前缀清单见响应与接口前缀。