# 校天犬开发规范
## 一 路由
### 1、命名为单词复数，多个单词组成用`-`分割

### 2、方法
`create` 添加之前查预备数据
`store` 添加
`destroy` 删除
`update` 更新
`edit` 编辑（更新之前查数据）
`index` 对应没有权限判断的列表数据，首页等
`list` 后台用户调取数据列表（一般有权限判断）

其他方法命名以这些单词为基础，例如：`storeItem`，`recordList` 等等

### 3、每个路由要取一个唯一的名字，名字和路径类似，例如：`study-banners.store`
```php
    // banner
    Route::post('study-banners/store', 'StudyBannersController@store')->name('study-banners.store');
    Route::post('study-banners/destroy', 'StudyBannersController@destroy')->name('study-banners.destroy');
    Route::post('study-banners/update', 'StudyBannersController@update')->name('study-banners.update');
    Route::post('study-banners/edit', 'StudyBannersController@edit')->name('study-banners.edit');
    Route::post('study-banners/list', 'StudyBannersController@list')->name('study-banners.list');
```
## 2、控制器
### 1、控制器命名为单词的复数，例如：`CardsController`
### 2、所有接口控制器继承 `ApisController`
### 3、返回值
#### 3.1 返回模型数据要用`API RESOURCE` 处理后返回例如：
```php
$activity = Activity::latest()->first();
$activity = new ActivityResource($activity);
return $this->success($activity);
```
[resource 文档](https://learnku.com/docs/laravel/7.x/eloquent-resources/7503 "resource 文档")
#### 3.2 直接返回数组数据
```php
return $this->success([
   'no' => '20200702001164102',
]);
```
对应返回值如下：
```json
// 单独数据体
{
    "status": "success",                // 成功返回固定值
    "code": 200,                        // 固定 200
    "data": {                           // 数据包
        "no": "20200702001164102"       // 具体数据
    },
    "msg": "操作成功",                  // 提示消息
    "msgTime": 1500,                   // 提示消息展示时长，表示 1.5 秒
}
// 数据列表
{
    "status": "success",                // 成功返回固定值
    "code": 200,                        // 固定 200
    "data": {                           // 接口主体数据包
        {
            "id": 1,
            "desc": "最高50%佣金，日入千元不是梦",
            "name": "高额佣金",
            "image": "https://card.xmfinger.com/frontend/icons/vip_im.png"
        },
        {
            "id": 2,
            "desc": "轻松拥有自己的线上商城",
            "name": "商城功能",
            "image": "https://card.xmfinger.com/frontend/icons/vip_shop.png"
        }, 
    },
    "meta": {  // 其他附带数据，用 meta 包含
        "vip_privileges": [
            {
                "id": 1,
                "desc": "最高50%佣金，日入千元不是梦",
                "name": "高额佣金",
                "image": "https://card.xmfinger.com/frontend/icons/vip_im.png"
            },
            {
                "id": 2,
                "desc": "轻松拥有自己的线上商城",
                "name": "商城功能",
                "image": "https://card.xmfinger.com/frontend/icons/vip_shop.png"
            },
    }
    "msg": "操作成功",                  // 提示消息
    "msgTime": 1500,                   // 提示消息展示时长，表示 1.5 秒
}
```
#### 3.3 直接返回消息
```php
return $this->message('操作成功');
```
对应返回值如下：
```json
{
    "status": "success",                // 成功返回固定值
    "code": 200,                        // 固定 200
    "msg": "操作成功",                  // 提示消息
    "msgTime": 1500,                   // 提示消息展示时长，表示 1.5 秒
}
```
#### 3.4 返回分页信息操作
```php
<?php
use App\Api\Helpers\PaginateHelper;
class AskLeavesController extends ApiController
{
    use PaginateHelper;
    public function index(Request $request)
    {
	    // 从路由获取当前机构，大部分方法都要用
        $institution = get_institution_from_route();
		// 当前授权的用户
        $user = $request->user();
		// 查询数据库，获取分页数据
        $res = AskLeave::query()
            ->where('child_id', $child->id)
            ->orderBy('id', 'desc')
            ->with('child', 'courseSetting', 'user')
            ->paginate(12);
		// 处理成统一格式的分页数据
        $res = $this->paginate($res， AskLeaveResrouce::class);
		// 其他附带数据
        $res['meta']['child'] = new ChildResource($child);
        // 返回
        return $this->res( $res);
	}
}
```
返回示例：
```json
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 130,
            "count": 1,
            "leaave": 0,
            "leave": 0,
            "reason": "有事不能来",
            "date": "2019-12-10 00:00:00",
            "date_name": "2019-12-10 周二",
            "user_name": "onetobigs",
            "course_setting_name": "幼儿书法",
            "created_at": "2020-07-06 14:30:43",
            "updated_at": "2020-07-06 14:30:43",
            "created_date": "2020-07-06 周一"
        }
    ],
    "links": {
        "first": "http://xiaotq.demo/api/ask-leave/index?page=1",
        "last": "http://xiaotq.demo/api/ask-leave/index?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "form": 1,
        "last_page": 1,
        "path": "http://xiaotq.demo/api/ask-leave/index",
        "per_page": 12,
        "to": 1,
        "total": 1,
        "child": {
            "id": 34,
            "name": "媛媛",
            "avatar": "https://wx.qlogo.cn/mmopen/vi_32/QNPjGP8JnqNUUuxzgFw9UM3xk44WDB4OXmxPyEpCNzrWDE8ibVIDeEmNSWd556He3Se4oBoGuJvN1ThtAw1Vo6Q/132",
            "en_name": "",
            "gender": 2,
            "gender_name": "女",
            "birthday": "2019-12-05",
            "school": "",
            "first_letter": "Y",
            "relation": "爸爸",
            "type": 1,
            "type_name": "常规学员",
            "status": 0,
            "status_name": "正常",
            "tags": [],
            "phone": "13055246008",
            "address": "软件园三期A区06栋(厦门市集美区)",
            "signing": true,
            "check": false
        }
    },
    "msg": "操作成功",
    "msgTime": 1500,
    "server_time": 1594017047,
    "msgShow": false
}
```
### 4、错误返回
```php
error_msg('错误提示信息');
```
对应效果
```json
{
    "status": "error",
    "code": 400,
    "msg": "错误提示信息",
    "msgTime": 1500,
    "server_time": 1594017221,
    "msgShow": false
}
```
## 三、其他规范
### 1、代码规范参考下面链接
[代码规范](https://learnku.com/docs/laravel-specification/7.x "代码规范")
### 2、代码自动格式化
```shell
composer global require squizlabs/php_codesniffer
```
![格式化设置1](https://cdn.learnku.com/uploads/images/202007/06/10907/5YgeivhMdu.png!large "格式化设置1")

### 3、git 开发分支在 `dev` 分支，提交前先拉取