校天犬开发规范

校天犬开发规范.md

@@ -0,0 +1,220 @@
+# 校天犬开发规范
+## 一 路由
+### 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` 分支，提交前先拉取
+