22-auth-menu.rst.txt

菜单管理
================

应用(app)管理
---------------

创建应用
^^^^^^^^^^^^^^^

| ``Verb:`` POST 
| ``Path:`` /api/v1/auth/apps
| ``Header:`` (authorization, {$atoken}), (Content-Type: application/json)

Request Body：

  .. code-block:: python

    { 
      "name": "xxx",
      "note": "xxx"
    }

Response Body:

  .. code-block:: python

    {
      "unid": "xxx",
      "name": "xxx",
      "note": "xxx"
    }

.. attention:: 
  1. 创建应用的时候服务程序需要同时创建菜单根节点。

列出应用
^^^^^^^^^^^^^^^

| ``Verb:`` GET 
| ``Path:`` /api/v1/auth/apps
| ``Header:`` (authorization, {$atoken})
| ``Params:`` 

	- offset, limit
	- order: 默认asc
	- sortby: 默认name
	- is_active：取值为true或false
	- name, name__like: 当type==api时使用，分别表示精确和模糊匹配。

Request Body：无

Response Body:

  .. code-block:: python

    {
      "total_num": 100,   # 总数量
      "list_size": 10,    # 本次返回的列表项数量
      "offset": 10,       # 本次返回项目的起始索引
      "list_data":
      [
         {
            "unid": "xxx",
            "name": "xxx",
            "note": "xxx"
         }
         ...
      ]
    }


修改应用
^^^^^^^^^^^^^^^

| ``Verb:`` POST
| ``Path:`` /api/v1/auth/apis/{$app_unid}
| ``Header:`` (authorization, {$atoken})

Request Body：

  .. code-block:: python

    { 
      "name": "xxx",
      "note": "xxx"
    }


Response Body: 

  .. code-block:: python

    {
      "unid": "xxx",
      "name": "xxx",
      "note": "xxx"
    }


删除应用
^^^^^^^^^^^^^^^

| ``Verb:`` DELETE
| ``Path:`` /api/v1/auth/apis/{$app_unid}
| ``Header:`` (authorization, {$atoken})

Request Body：无

Response Body: 正确无，错误返回相应的结构。

.. attention:: 如果应用下包含菜单，那么删除会失败。


菜单管理
------------

创建菜单
^^^^^^^^^^^^^^^

| ``Verb:`` POST 
| ``Path:`` /api/v1/auth/apps/{$app_unid}/menus
| ``Header:`` (authorization, {$atoken}), (Content-Type: application/json)

Request Body：

  .. code-block:: python

    { 
      "position":   1,       # 必填，菜单项的相对位置
      "name":       "xxx",   # 必填，菜单项显示的名称
      "note":       "xxx"    # 可选，菜单项说明
      "parent":     "xxx"    # 可选，父节点菜单项的unid，没有表示虚拟根节点。
    }

.. attention:: 
  1. 应用的根节点在创建应用的时候由服务程序自动创建，本接口只能创建非根节点。
  2. 如果一个应用已经有一个虚拟根节点，那么再创建应该报错。

Response Body:

  .. code-block:: python

    {
      "unid":       "xxx",   # 必填，认证服务分配的菜单unid
      "position":   1,       # 必填，菜单项的相对位置
      "name":       "xxx",   # 必填，菜单项显示的名称
      "note":       "xxx"    # 可选，菜单项说明
      "parent":     "xxx"    # 可选，父节点菜单项的unid，没有表示虚拟根节点。
      "perm_unid":  "xxxx",  # 必填，对应的权限unid
    }

.. attention:: 创建菜单的同时要创建一个与该菜单项关联的权限。

获取菜单
^^^^^^^^^^^^^^^

| ``Verb:`` GET
| ``Path:`` /api/v1/auth/apps/{$app_unid}/menus
| ``Header:`` (authorization, {$atoken})
| ``Params:`` 

  - shape, 表示获取菜单结果的形状，tree表示树形结构，list表示列表结构，默认tree。

.. note:: 
  1. 只有请求者属于管理员角色时，才能处理shape=list的情况，非管理员给出本参数时要拒绝。
  #. 只有请求者属于管理员角色时，才能处理给出role参数的情况，非管理员给出role参数时要拒绝。

.. note:: 
  1. 当请求不给出role参数时，后台只需给出atoken对应的用户所属角色的可操作性菜单的并集，以树的形式返回。
  2. 当请求给出role参数时，后台认为请求用户希望编辑菜单，这时首先要检查该用户是否属于管理员组，如果不属于管理员组则拒绝。否则给出完整的菜单树，但是要指出每个菜单项对该角色是否可访问。


以下参数只有在shape=tree时才有作用。

  - role, 表示获取指定角色的允许访问的菜单的树形结构，如果没有本参数则给出完整菜单树。


以下参数只有在shape=list时才有作用。

	- name, name__like: 分别表示精确和模糊匹配  

  - offset：起始偏移量，默认0  
  
  - limit：本次返回最大值，默认100  

Response Body:

shape==tree时，

  .. code-block:: python

    {
      "app_unid": "xxxx",
      "app_name": "xxxx",
      "menu_tree": [           # 列表顺序按照position从小到大排列。
        {
          "position": 1,
          "unid": "xxxx",
          "name":"xxxx", 
          "note":"xxxx", 
          "perm_unid": "xxxx",
          "is_usable": true,      # 本菜单项对指定角色是否可用
          "child": [],
        },
        {...}
      ]
    }


shape==list时，

  .. code-block:: python

    {
      "total_num": 100,   # 总数量
      "list_size": 10,    # 本次返回的列表项数量
      "offset": 10,       # 本次返回项目的起始索引
      "list_data":[
         {
           "unid":       "xxx",   # 必填，认证服务分配的菜单unid
           "position":   1,       # 必填，菜单项的相对位置
           "name":       "xxx",   # 必填，菜单项显示的名称
           "note":       "xxx"    # 可选，菜单项说明
           "parent":     "xxx"    # 可选，父节点菜单项的unid，没有表示虚拟根节点。
           "perm_unid": "xxxx",
         },
         ...
    }


修改菜单
^^^^^^^^^^^^^^^

| ``Verb:`` POST
| ``Path:`` /api/v1/auth/apps/{$app_unid}/menus/{$menu_unid}
| ``Header:`` (authorization, {$atoken})

Request Body：

  .. code-block:: python

    { 
      "position":   1,       # 可选，菜单项的相对位置
      "name":       "xxx",   # 可选，菜单项显示的名称
      "note":       "xxx"    # 可选，菜单项说明
      "parent":     "xxx"    # 可选，父节点菜单项的unid，没有表示虚拟根节点。
    }

Response Body：

  .. code-block:: python

    {
      "unid":       "xxx",   # 必填，认证服务分配的菜单unid
      "position":   1,       # 必填，菜单项的相对位置
      "name":       "xxx",   # 必填，菜单项显示的名称
      "note":       "xxx"    # 可选，菜单项说明
      "parent":     "xxx"    # 可选，父节点菜单项的unid，没有表示虚拟根节点。
    }


删除菜单
^^^^^^^^^^^^^^^

| ``Verb:`` DELETE
| ``Path:`` /api/v1/auth/apps/{$app_unid}/menus/{$menu_unid}
| ``Header:`` (authorization, {$atoken})

.. attention:: 如果该菜单下有子菜单，那么删除失败，否则成功。注意同时也要删除对应的权限。

Request Body：无

Response Body: 正确无，错误返回相应的结构。


替换某个角色在某个应用的菜单
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| ``Verb:`` POST 
| ``Path:`` /api/v1/auth/roles/{$role_id}/apps/{$app_unid}/menus
| ``Header:`` (authorization, {$atoken}), (Content-Type: application/json)

Request Body：

  .. code-block:: python

    { 
      "list_size": 10,    # 菜单项数量
      "list_data":[
         {
           "unid":      "xxx",   # 必填，认证服务分配的菜单unid
           "perm_unid": "xxxx",
         },
         ...
    }

Response Body: 

  .. code-block:: python

    {
        "code": 200,
        "enote": "OK"
    }