# Naming 契约 — PHP 命名规范

## 文件命名

| 类型 | 规则 | 示例 |
|------|------|------|
| Action | `{模块名小写}.php` | `users.php`, `rolePermission.php` |
| Model | `{类名}.php`（首字母大写） | `Users.php`, `Role.php` |
| 视图 | `{模块名}/{视图名}.view.php` | `users/index.view.php` |
| 配置 | 语义化小写 | `database.php`, `common.php` |

## 类命名

| 类型 | 规则 | 示例 |
|------|------|------|
| Action 类 | `{模块名首字母大写}Action` | `usersAction`, `rolePermissionAction` |
| Model 类 | 语义化，无后缀 | `Users`, `Role`, `Permission` |
| 例外 | 模块名首字母大写，但文件名小写开头 | 文件 `users.php`，类 `usersAction` |

## 方法命名

### Action 方法（保留名，不得用于其他用途）

| 方法 | 来源 | 用途 |
|------|------|------|
| `grid()` | GridActions trait | DevExtreme load |
| `save()` | GridActions trait | insert / update |
| `remove()` | GridActions trait | delete |
| `export()` | GridActions trait | Excel 导出 |
| `index()` | 惯例 | 页面渲染 |
| `callBefore()` | Action 基类 | 登录校验钩子 |

### 自定义方法规则

- 动词开头：`list`, `get`, `find`, `bind`, `update`, `check`, `derive`
- 不用缩写：`listDepartments` 而不是 `listDepa`
- Model 中只暴露业务方法，不暴露内部辅助（私有方法加 `private`）

## 变量与参数

- PHP 变量：camelCase（`$adminId`, `$depaIds`）
- 数组 key：与数据库字段名保持一致（`admin_user_id`, `sys_role_name`）
- 循环变量：语义化（`$row`, `$role`, `$depaId`），不用 `$i` 做业务含义

## 路由 URL 规则

格式：`/{模块名}/{方法名}`

| URL | 对应 | 说明 |
|-----|------|------|
| `/users/index` | `usersAction::index()` | 页面 |
| `/users/grid` | `usersAction::grid()` | 数据接口 |
| `/users/save` | `usersAction::save()` | 增改接口 |
| `/users/remove` | `usersAction::remove()` | 删除接口 |
| `/users/export` | `usersAction::export()` | 导出接口 |

模块名与 Action 文件名一致（小写），camelCase 多词模块如 `rolePermission`。

## 视图变量

- `View::set()` 赋值的变量在模板里直接用变量名
- 变量名语义化：`$pageTitle`, `$departments`, `$roles`
- 禁止在模板里用 `$data` 这类无意义名称