接口文檔示例 | DRF

**簡要描述：** 

- 企業信息統計接口

**請求URL：** 
- ` http://127.0.0.1/ztx_data/v1/ep_info `
  
**請求方式：**
- GET 

**參數：** 

|參數名|必選|類型|說明|
|:----    |:---|:----- |-----   |
|username |是  |string |用戶名   |
|password |是  |string | 密碼    |


 **返回示例**
``` json
// 成功響應
// 分頁數據
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {
        "count": 28,
        "next": "http://127.0.0.1:8000/process_drf/?page=2&size=5",
        "previous": null,
        "results": [
            {
                "id": 13,
                "code": "process_13",
                "name": "企業門戶",
                "remark": "",
                "sign": "0",
                "rto": null,
                "rpo": null,
                "state": "9",
                "sort": 4,
                "url": "/falconstor",
                "type": "falconstor",
                "color": "#e7505a"
            },
            {
                "id": 14,
                "code": "2",
                "name": "mkl",
                "remark": "hehehehe",
                "sign": "0",
                "rto": 1,
                "rpo": 2,
                "state": "9",
                "sort": 5,
                "url": "/falconstor",
                "type": "falconstor",
                "color": "#32c5d2"
            },
        ]
    }
}
// 單條記錄
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {
        "id": 15,
        "code": "asd",
        "name": "sadad",
        "remark": "hahaha",
        "sign": "0",
        "rto": 2,
        "rpo": 3,
        "state": "1",
        "sort": 6,
        "url": "/falconstor",
        "type": "falconstor",
        "color": "#8e44ad"
    }
}
// POST
{
    "code": 201,
    "msg": "success",
    "errors": {},
    "data": {
        "id": 42,
        "code": "s",
        "name": "a",
        "remark": null,
        "sign": null,
        "rto": null,
        "rpo": null,
        "state": null,
        "sort": null,
        "url": "",
        "type": null,
        "color": ""
    }
}
// PUT
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {
        "id": 15,
        "code": "asd",
        "name": "mkl",
        "remark": "hahaha",
        "sign": "0",
        "rto": 2,
        "rpo": 3,
        "state": "1",
        "sort": 6,
        "url": "/falconstor",
        "type": "falconstor",
        "color": "#8e44ad"
    }
}
// DELETE
{
    "code": 200,
    "msg": "success",
    "errors": {},
    "data": {}
}
```
 **返回參數說明** 

|參數名|類型|說明|
|:-----  |:-----|-----                           |
|groupid |int   |用戶組id，1：超級管理員；2：普通用戶  |

 **備注** 

- 返回企業信息

| 錯誤碼  | 錯誤解釋  |
| ------------ | ------------ |
|  401 | 用戶認證失敗  |
|  403 | 權限校驗失敗  |
|  422 |  入參錯誤 |

- 返回示例
> POST請求

```json
{
    "code": 422,
    "msg": "入參錯誤",
    "errors": {
        "code": "This field may not be blank.",
        "name": "This field may not be blank."
    },
    "data": {}
}
```
> GET請求

```json
{
    "code": 422,
    "msg": "error",
    "errors": {
        "param": "Process matching query does not exist."
    },
    "data": {}
}

項目示例：

# @file           :views.py
# @description    :企業信息應用視圖
# @date           :2021/07/01 18:02:52
# @author         :miaokela
# @version        :1.0
from rest_framework.generics import GenericAPIView
from django.http import Http404

from company import extra_models
from ZTXDMS.utils.response import APIResponse
from ZTXDMS.utils.pagination import RestPagination
from company.serializers import (
    CompanyListSerializer,
    CompanyDetailSerializer,
    AgencyListSerializer,
    AgencyDetailSerializer,
)
from company.conf import sqls


class CompanyAPIView(GenericAPIView):
    queryset = extra_models.QccQccCrawler.objects.using('company').exclude(is_delete='1').order_by('-update_time')
    serializer_class = CompanyListSerializer
    pagination_class = RestPagination

    def get(self, request):
        queryset = self.get_queryset()
        if request.query_params:
            company_name = request.query_params.get('company_name', '').strip()
            queryset = queryset.filter(company_name__contains=company_name)
            # TODO 數據庫沒有的數據從企查查站點采集

        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)

        ser = self.get_serializer(page, many=True)

        return APIResponse(code=200, data=ser.data)


class CompanyDetailAPIView(GenericAPIView):
    queryset = extra_models.QccQccCrawler.objects.using('company').exclude(is_delete='1').order_by('-update_time')
    lookup_field = 'id'

    def delete(self, request, id):
        try:
            qcc = self.get_object()
            qcc.is_delete = '1'
            qcc.save()
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['記錄不存在，刪除失敗。']})

        return APIResponse(code=200)

    def get(self, request, id):
        try:
            ser = CompanyDetailSerializer(self.get_object())
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['記錄不存在。']})
        else:
            return APIResponse(code=200, data=ser.data)


class AgencyAPIView(GenericAPIView):
    queryset = list(extra_models.Quanguo.objects.using('company').raw(sqls.AGENCY_JOIN_COMPANY))
    serializer_class = AgencyListSerializer
    pagination_class = RestPagination

    def get(self, request):
        queryset = self.get_queryset()
        if request.query_params:
            agency = request.query_params.get('agency', '').strip()
            city = request.query_params.get('city', '').strip()

            params_filters = []
            if agency:
                params_filters.append('qg.agency LIKE "%%{0}%%"'.format(agency))
            if city:
                params_filters.append('qg.city LIKE "{0}%%"'.format(city))
            filter_string = ' AND '.join(params_filters)
            if filter_string:
                c_sql = ' AND '.join([sqls.AGENCY_JOIN_COMPANY, filter_string])
                queryset = list(extra_models.Quanguo.objects.using('company').raw(c_sql))
        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)

        ser = self.get_serializer(queryset, many=True)

        return APIResponse(code=200, data=ser.data)


class AgencyDetailAPIView(GenericAPIView):
    queryset = list(extra_models.Quanguo.objects.using('company').raw(sqls.AGENCY_JOIN_COMPANY))
    lookup_field = 'id'

    def delete(self, request, id):
        try:
            agency = self.get_object()
            agency.is_delete = '1'
            agency.save()
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['記錄不存在，刪除失敗。']})

        return APIResponse(code=200)

    def get(self, request, id):
        try:
            ser = AgencyDetailSerializer(self.get_object())
        except Exception as e:
            print('error:{0}'.format(e))
            return APIResponse(code=404, msg='failed', errors={'id': ['記錄不存在。']})
        else:
            return APIResponse(code=200, data=ser.data)

    def get_object(self):
        """
        無法使用self.get_object() List不具備get()方法
        """
        try:
            # Perform the lookup filtering.
            lookup_url_kwarg = self.lookup_url_kwarg or self.lookup_field

            assert lookup_url_kwarg in self.kwargs, (
                    'Expected view %s to be called with a URL keyword argument '
                    'named "%s". Fix your URL conf, or set the `.lookup_field` '
                    'attribute on the view correctly.' %
                    (self.__class__.__name__, lookup_url_kwarg)
            )

            filter_kwargs = {self.lookup_field: self.kwargs[lookup_url_kwarg]}
            sql = ' '.join([
                sqls.AGENCY_JOIN_COMPANY, 'AND qg.id={id}'.format(**filter_kwargs)
            ])
            agency = extra_models.Quanguo.objects.using('company').raw(sql)[0]
        except Exception as e:
            print(e)
            raise Http404()
        else:
            return agency

from django.conf.urls import url
from company import views


urlpatterns = [
    url(r'companies/$', views.CompanyAPIView.as_view()),
    url(r'companies/(?P<id>\d+)$', views.CompanyDetailAPIView.as_view()),
    url(r'agencies/$', views.AgencyAPIView.as_view()),
    url(r'agencies/(?P<id>\d+)$', views.AgencyDetailAPIView.as_view()),
]

# @file           :serializers.py
# @description    :自定義序列化器
# @date           :2021/07/01 17:42:06
# @author         :miaokela
# @version        :1.0
from rest_framework import serializers

from rest_framework import serializers


class CompanyListSerializer(serializers.Serializer):
    """
    列表頁字段序列化：
        - 企業名稱
        - 企業法人
        - 注冊資本
        - 組織機構代碼
        - 公司行業
        - 公司類型
    """
    id = serializers.IntegerField()
    company_name = serializers.CharField()
    legal_representative = serializers.CharField()
    registered_capital = serializers.CharField()
    organization_code = serializers.CharField()
    industry = serializers.CharField()
    is_agency = serializers.CharField()


class CompanyDetailSerializer(serializers.Serializer):
    """
    詳情頁字段序列化：
        - 企業名稱
        - 統一機構信用代碼
        - 法定代表人
        - 工商注冊號
        - 注冊資本
        - 納稅人識別號
        - 實繳資本
        - 組織機構代碼
        - 營業期限自
        - 營業期限至
        - 登記狀態
        - 注冊機關
        - 注冊地址
        - 公司類別
    """
    id = serializers.IntegerField()
    company_name = serializers.CharField()
    unified_social_credit_code = serializers.CharField()
    legal_representative = serializers.CharField()
    business_registration_number = serializers.CharField()
    registered_capital = serializers.CharField()
    taxpayer_identification_number = serializers.CharField()
    paid_in_capital = serializers.CharField()
    organization_code = serializers.CharField()
    operating_period_std = serializers.CharField()
    operating_period_edt = serializers.CharField()
    operating_status = serializers.CharField()
    registration_authority = serializers.CharField()
    registered_address = serializers.CharField()
    is_agency = serializers.CharField()


class AgencyListSerializer(serializers.Serializer):
    """
    代理公司列表序列化器:
        - 代理公司
        - 組織機構代碼
        - 企業法人
        - 地區
        - 業務聯系人
        - 業務聯系電話
    """
    id = serializers.IntegerField()
    society_code = serializers.CharField()
    agency = serializers.CharField()
    liaison = serializers.CharField()
    contact_information = serializers.CharField()
    address = serializers.CharField()
    institutional = serializers.CharField()
    put_time = serializers.CharField()
    city = serializers.CharField()

 
class AgencyDetailSerializer(serializers.Serializer):
    """
    代理公司列表序列化器:
        - 業務聯系人
        - 業務聯系電話
        - 企業名稱
        - 統一機構信用代碼
        - 法定代表人
        - 工商注冊號
        - 注冊資本
        - 納稅人識別號
        - 實繳資本
        - 組織機構代碼
        - 營業期限自
        - 營業期限至
        - 登記狀態
        - 注冊機關
        - 注冊地址
        - 公司類別
    """
    id = serializers.IntegerField()
    company_name = serializers.CharField()
    unified_social_credit_code = serializers.CharField()
    legal_representative = serializers.CharField()
    business_registration_number = serializers.CharField()
    registered_capital = serializers.CharField()
    taxpayer_identification_number = serializers.CharField()
    paid_in_capital = serializers.CharField()
    organization_code = serializers.CharField()
    operating_period_std = serializers.CharField()
    operating_period_edt = serializers.CharField()
    operating_status = serializers.CharField()
    registration_authority = serializers.CharField()
    registered_address = serializers.CharField()
    liaison = serializers.CharField()
    contact_information = serializers.CharField()
    is_agency = serializers.CharField()

# @file           :exception.py
# @description    :自定義錯誤相應
# @date           :2021/07/01 17:26:14
# @author         :miaokela
# @version        :1.0
from django.http import Http404
from rest_framework import exceptions, views
from django.core.exceptions import PermissionDenied
from rest_framework.response import Response


def exception_handler(exc, context):
    """
    自定義 exception_handler 錯誤信息返回
    Returns the response that should be used for any given exception.

    By default we handle the REST framework `APIException`, and also
    Django's built-in `Http404` and `PermissionDenied` exceptions.

    Any unhandled exceptions may return `None`, which will cause a 500 error
    to be raised.
    """
    if isinstance(exc, Http404):
        exc = exceptions.NotFound()
    elif isinstance(exc, PermissionDenied):
        exc = exceptions.PermissionDenied()

    if isinstance(exc, exceptions.APIException):
        headers = {}
        if getattr(exc, 'auth_header', None):
            headers['WWW-Authenticate'] = exc.auth_header
        if getattr(exc, 'wait', None):
            headers['Retry-After'] = '%d' % exc.wait

        if isinstance(exc.detail, (list, dict)):
            if isinstance(exc.detail, list):
                errors = exc.detail
            else:
                errors = {k: v[0] for k, v in exc.detail.items()}
        else:
            errors = exc.detail

        views.set_rollback()
        return Response({
            'code': 400, 'msg': 'failed', 'errors': errors, 'data': {}
        }, status=exc.status_code, headers=headers)

    return None

# @file           :pagination.py
# @description    :自定義分頁
# @date           :2021/07/01 17:23:46
# @author         :miaokela
# @version        :1.0
from rest_framework.pagination import LimitOffsetPagination
from ZTXDMS.utils.response import APIResponse
from collections import OrderedDict


class RestPagination(LimitOffsetPagination):
    default_limit = 20  # 默認從第一條開始(offset=0),往后5條為一頁
    limit_query_param = 'limit'
    offset_query_param = 'offset'
    max_limit = 40

    def get_paginated_response(self, data):
        return APIResponse(code=200, data=OrderedDict([
            ('count', self.count),
            ('next', self.get_next_link()),
            ('previous', self.get_previous_link()),
            ('results', data)
        ]))

# @file           :response.py
# @description    :重寫DRF Response相應類
# @date           :2021/07/01 17:12:51
# @author         :miaokela
# @version        :1.0
from rest_framework.response import Response


class APIResponse(Response):
    def __init__(self, code=200, msg='success', data=None, status=None, headers=None, errors=None, **kwargs):
        errors = {k: v[0] for k, v in errors.items()} if errors else {}

        dic = {'code': code, 'msg': msg, "errors": errors}
        if data:
            dic = {
                'code': code,
                'msg': msg,
                'data': data,
            }
        dic.update(kwargs)
        super().__init__(data=dic, status=status, headers=headers)

### 簡要描述：

> 企業信息統計接口

### 獲取多企業信息

**請求URL：**

- `http://127.0.0.1:8000/v1/companies/`

**請求方式：**

- GET

**請求參數：**

|    參數名    | 必選 |  類型  | 默認值 |   說明   |
| :----------: | :--: | :----: | :----: | :------: |
| company_name |  否  | string |   無   | 企業名稱 |

**響應參數**

|        參數名        |  類型  | 說明                                 |
| :------------------: | :----: | ------------------------------------ |
|          id          |  int  | 企業ID                               |
|     company_name     | string | 企業名稱                             |
| legal_representative | string | 法人代表                             |
|  registered_capital  | string | 注冊資本                             |
|  organization_code  | string | 組織機構代碼                         |
|       industry       | string | 行業                                 |
|      is_agency      | string | 公司類別（"1"：代理機構，"0"：其它） |

**響應結果示例**

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "count": 1404,
        "next": "http://114.67.84.76/v1/companies/?limit=20&offset=20",
        "previous": null,
        "results": [
            {
                "id": 96,
                "company_name": "鄭州澤正生物科技有限公司",
                "legal_representative": "張洋洋",
                "registered_capital": "500萬元人民幣",
                "organization_code": "MA9GXRYX-8",
                "industry": "醫葯制造業",
                "is_agency": "0"
            },
            ...  // 默認20條記錄
        ]
    }
}
```

### 獲取單企業信息

**請求URL：**

- `http://127.0.0.1:8000/v1/companies/{:id}`

**請求方式：**

- GET

**請求參數：**

| 參數名 | 必選 | 類型 | 默認值 |  說明  |
| :----: | :--: | :--: | :----: | :----: |
|   id   |  是  | int |   無   | 企業ID |

**響應參數**

|             參數名             |  類型  | 說明                                 |
| :----------------------------: | :----: | ------------------------------------ |
|               id               |  int  | 企業ID                               |
|          company_name          | string | 企業名稱                             |
|   unified_social_credit_code   | string | 統一社會信用代碼                     |
|      legal_representative      | string | 法人代表                             |
|  business_registration_number  | string | 工商注冊號                           |
|       registered_capital       | string | 注冊資本                             |
| taxpayer_identification_number | string | 納稅人識別號                         |
|        paid_in_capital        | string | 實繳資本                             |
|       organization_code       | string | 組織機構代碼                         |
|      operating_period_std      | string | 營業期限自                           |
|      operating_period_edt      | string | 營業期限至                           |
|        operating_status        | string | 登記狀態                             |
|     registration_authority     | string | 注冊機關                             |
|       registered_address       | string | 注冊地址                             |
|           is_agency           | string | 公司類別（"1"：代理機構，"0"：其它） |

**響應結果示例**

```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 10,
        "company_name": "宜山縣婦聯巾幗經濟服務部",
        "unified_social_credit_code": "-",
        "legal_representative": "陸美鮮",
        "business_registration_number": "4527021002240",
        "registered_capital": "2萬元人民幣",
        "taxpayer_identification_number": "-",
        "paid_in_capital": "-",
        "organization_code": "-",
        "operating_period_std": "3199-06-22",
        "operating_period_edt": "無固定期限",
        "operating_status": "注銷",
        "registration_authority": "河池市宜州區市場監督管理局",
        "registered_address": "慶遠解放路5號查看地圖附近企業",
        "is_agency": "0"
    }
}
```

### 刪除企業信息

**請求URL：**

- `http://127.0.0.1:8000/v1/companies/{:id}`

**請求方式：**

- DELETE

**請求參數：**

| 參數名 | 必選 | 類型 | 默認值 |  說明  |
| :----: | :--: | :--: | :----: | :----: |
|   id   |  是  | int |   無   | 企業ID |

**響應參數**

| 參數名 | 類型 | 說明 |
| :----: | :--: | ---- |
|   無   |  無  | 無   |

**響應結果示例**

```json
{
    "code": 200,
    "msg": "success",
    "errors": {}
}
```

### 簡要描述

> 全局響應與狀態碼

### 狀態碼

| 狀態碼 |     描述     |
| :----: | :----------: |
|  200  |   成功響應   |
|  404  |  記錄不存在  |
|  422  | 參數校驗失敗 |

### 成功響應

```json
{
    "code": 200,
    "msg": "success",
    "data": {}
}
```

### 錯誤響應

* 新增/修改校驗失敗

```json
{
    "code": 422,
    "msg": "failed",
    "errors": {
        "code": "This field may not be blank.",
        "name": "This field may not be blank."
    },
    "data": {}
}
```

* 刪除/查詢記錄不存在

```json
{
    "code": 404,
    "msg": "failed",
    "errors": {
        "id": "記錄不存在，刪除失敗。"
    }
}
```