# 系统交互模型

系统交互模型，描述了软件产品的网站类型项目中系统基础功能模块的流程、数据模型以及相应 API 输入输出标准格式，包含以下内容：

用户登录，包含登录形式及流程
认证授权方式
数据模型输出

目标在于各端作为 数据服务供应商 或 数据应用消费者 在交互上统一行为，面向标准接口开发，使得项目新建之初可依照 系统交互模型 快速完成系统基础功能建设，从而更从容而有序应对企业后续不断增加的项目和业务

# 基础原则

# API 路径命名规则

基于数据交互格式标准 - API 交互规则规则, 在路径命名中应用开发规范 - 路由命名规则规则，简言之特性如下

路径使用功能/业务描述性命名，例：/user/profile/del/{id}
单词均使用小写方式书写
词组使用 - 符号分隔，例：/config/user-role/list

# 对象、属性命名规则

对于数据接口中输出的对象名，以及对象中的属性等内容，应使用驼峰命名法（Camel Case）

✖
{
  "user_info": {
    "Name": "zhangsan",
    "age": 18,
    "phone_number": "13655555555",
    "admin_type": 1
  }
}

✔
{
  "userInfo": {
    "name": "zhangsan",
    "age": 18,
    "phoneNumber": "13655555555",
    "adminType": 1
  }
}

xxx_yyy_zzz 命名格式仅推荐应用于数据库（表名及表字段名）环境

在编程环境中，即使是变量的声明都应尽可能不使用该格式，在自动化语法检查工具中，也有相应的检查/推荐规则：ESLint - "camelcase" 规则 (opens new window)，但常量的命名是个例外

// javascript
const MASTER_ADMIN = 1
const STATUS_ENABLED = 1
const STATUS_DISABLED = 2

// java
public static final String STATUS_ENABLED = 1;
public static final String STATUS_DISABLED = 2;

# 流程示意

# 数据模型

罗列了系统功能相关的基础数据模型，此处仅列举满足系统功能的模型及元素，后续可根据实际情况进行增补修订

# 用户

{
  "id"         : number, // 用户 id
  "name"       : string, // 用户名称
  "avatar"     : string, // 用户头像
  "companyId"  : string, // 用户当前所属公司 id
  "companyName": string, // 公司名称
  "companyLogo": string, // 公司 logo
  "adminType"  : number  // 管理员类型（0：普通用户 1：主管理员 2：子管理员）
}

# 公司

{
  "id"  : number, // 公司 id
  "name": string, // 公司名称
  "logo": string  // 公司 logo
}

# 菜单

{
  "id"      : number, // 菜单 id
  "name"    : string, // 菜单名称
  "icon"    : string, // 菜单图标
  "parentId": number, // 菜单父节点 id
  "sort"    : number, // 排列顺序
  "code"    : string, // 菜单编码
  "status"  : number  // 菜单状态（1：启用，0：禁用）
}

系统菜单应全量输出，但需要在 status 属性中体现该菜单节点的状态

注意

code 字段为菜单项目的编码，是前端系统中作为功能模块的唯一标识编码而定义，该编码由前端统一进行定义

# 权限

{
  [code]: {
    // 权限数据节点输出，内容根据具体系统情况而定
  },
  ...
}

此处的 code 与上述菜单模型中的 code 属性对应，代表了某个功能模块

# API 接口

系统功能模块 API 接口，内容仅为请求成功后返回的数据格式，完整数据交换格式请参考：数据交互格式标准

# 图形验证码初始化

图形验证码使用的是极验图形验证码，根据返回的数据初始化图形验证码插件

接口路径： /auth/captcha-init

// 入参
无

// 返回数据
// 该格式为极验插件的标准数据格式
{
  "code": 0,
  "data": {
    "success": number,
    "gt": string,
    "challenge": string,
    "newCaptcha": boolean
  }
}

# 密码登录

使用 用户名 和密码进行登录

接口路径：/auth/pwd-login

// 入参
{
  "username": string, // 用户名
  "password": string  // 密码
}

// 返回数据
{
  "code": 0,
  "data": {
    "access": {
      "accessToken": string,
      "expiresIn": number
    }
  }
}

# 获取手机短信验证码

使用 手机号 获得验证码用于系统登录，成功访问接口后，相应手机号的手机将收到包含验证码的短信

接口路径：/auth/sms-code

// 入参
{
  "phone": string // 手机号
}

// 返回数据
无

# 手机短信验证码登录

使用 手机号 和 验证码 进行登录

接口路径：/auth/sms-login

// 入参
{
  "phone": string, // 手机号
  "code": string   // 短信验证码
}

// 返回数据
{
  "code": 0,
  "data": {
    "access": {
      "accessToken": string,
      "expiresIn": number
    }
  }
}

# 获取当前用户数据

在使用密码登录或手机短信验证码登录登录成功后，获取当前用户的系统功能模型集合，系统根据该模型集合自行进行数据转换、过滤以及缓存，完成网站基础框架功能初始化

接口路径：/auth/profile

// 入参
无

// 返回数据
{
  "code": 0,
  "data": {
    "user": {
      // 用户模型
    },
    "companys": [
      {
        // 公司模型
      }, {
        ...
      }
    ],
    "menus": [
      {
        // 菜单模型
      }, {
        ...
      }
    ],
    "permission": {
      [菜单节点编码]: {
        // 权限数据节点
      },
      ...
    }
  }
}

数据节点与数据模型的对应关系

数据节点	数据模型
user	用户模型
companys	公司模型
menus	菜单模型
permission	权限模型

# 切换公司

切换用户当前所属公司，该操作相当于用户重新登录，所以需要重新分发用户的访问令牌。在完成公司切换的操作后，前端系统会自行再次访问获取当前用户数据接口，更新用户信息中当前所属公司等相关信息

接口路径：/auth/switch-company

// 入参
{
  "companyId": number // 待切换的公司 id
}

// 返回数据
{
  "code": 0,
  "data": {
    "access": {
      "accessToken": string,
      "expiresIn": number
    }
  }
}

事实上有多个接口均为获取用户访问令牌的功能：

数据格式及处理规则请参考数据交互格式标准 - 登录授权

← 数据交互格式标准系统框架 →