add account.md, account api

product/account.md

@@ -0,0 +1,271 @@
+<center> <font size=28>Smarthome API 说明文档</font> </center>
+
+**<font size=4>版本: 1.0 </font>**
+
+**<font size= 4>发布日期: 2024-03-28 </font>**
+
+<div style="page-break-after: always;"></div>
+
+<font size=7> 历史记录 </font>
+
+
+| 修订日期  | 版本 | 作者       | 说明     |
+| --------- | ---- | ---------- | -------- |
+| 2024-3-28 | V1.0 | alva.huang | 初始版本 |
+|           |      |            |          |
+
+<div style="page-break-after: always;"></div>
+
+[toc]
+
+<div style="page-break-after: always;"></div>
+
+# 前言
+
+## 概述
+
+本文档旨在说明爱智居服务端的API接口，帮助开发人员如何使用smarthome api 进行开发，并详细介绍了各API的功能，调用方式，返回结果和错误码。
+
+## Codebase
+
+此开发文档只针对智能家居控制app，小程序，以及相应的控制端app，面板app等的开发。
+
+# 账户系统
+
+账户系统主要功能是用户注册，登录，修改密码，忘记密码，注销账号。用户信息维护和更新。用户权限控制。角色映射等和用户相关的功能。
+
+## 用户登陆认证
+
+### 微信用户注册登陆接口
+
+用户通过微信小程序登陆，并使用微信code换取token，调用此接口完成注册和登录。
+当用户第一次使用微信小程序登陆，并且没有绑定过账号时，需要传入手机号码和验证码，进行注册绑定手机号码。后续使用微信小程序登陆，不需要传入手机号码和验证码。
+
+POST 请求URL：
+[https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token](https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token)
+
+请求头参数：
+Content-Type: application/x-www-form-urlencoded
+
+请求体参数：
+
+
+| 参数名        | 参数类型 | 默认值         | 说明                                          |
+| ------------- | -------- | -------------- | --------------------------------------------- |
+| client_id     | string   | wechatapp      | 客户端id，微信小程序固定为wechatapp，必须字段 |
+| client_secret | string   | 平台相关的密钥 | 客户端密钥，必须字段                          |
+| grant_type    | string   | password       | 授权类型，固定为password，必须字段            |
+| wechatCode    | string   | code           | wx.login()返回的code,必须传值                 |
+| smsCode       | string   | NULL           | 手机收到的验证码，已绑定的用户可不传          |
+| phoneNumber   | string   | NULL           | 手机号，可不传                                |
+| areaCode      | string   | NULL           | 区号,可不传                                   |
+
+返回结果：
+
+1. 成功，状态码200，返回如下内容：
+
+```json
+{
+  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
+  "expires_in": 1800,           //token有效期，单位秒
+  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
+  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
+  "token_type": "Bearer",       //token类型，Bearer
+  "not-before-policy": 0,
+  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
+  "scope": "profile"     //token权限，profile表示用户信息
+}
+```
+
+2. 微信授权码无效，状态码401，返回如下内容：
+
+```json
+{
+  "error": "wechat_code_invalid",
+  "error_description": "微信授权码无效，过期或已使用"
+}
+```
+
+3. 手机验证码错误，状态码401，返回如下内容：
+
+```json
+{
+  "error": "sms_code_invalid",
+  "error_description": "手机验证码无效"
+}
+```
+
+4. 手机号已绑定其他账号，状态码401，返回如下内容：
+
+```json
+{
+  "error": "invalid_grant",
+  "error_description": "Invalid user credentials"
+}
+```
+
+### 客户端登陆认证接口
+
+POST 请求URL：
+[https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token](https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token)
+
+请求头参数：
+Content-Type: application/x-www-form-urlencoded
+
+请求体参数：
+
+
+| 参数名        | 参数类型 | 默认值         | 说明                                          |
+| ------------- | -------- | -------------- | --------------------------------------------- |
+| client_id     | string   | wechatapp      | 客户端id，微信小程序固定为wechatapp，必须字段 |
+| client_secret | string   | 平台相关的密钥 | 客户端密钥，必须字段                          |
+| grant_type    | string   | password       | 授权类型，固定为password，必须字段            |
+| username      | string   | username       | 用户名                                        |
+| password      | string   | user password  | 用户秘密                                      |
+|               |          |                |                                               |
+
+返回结果：
+
+1. 成功,状态码200
+
+```json
+{
+  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
+  "expires_in": 1800,           //token有效期，单位秒
+  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
+  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
+  "token_type": "Bearer",       //token类型，Bearer
+  "not-before-policy": 0,
+  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
+  "scope": "profile"     //token权限，profile表示用户信息
+}
+```
+
+2. 客户端授权无效，用户名或秘密错误，状态码401
+
+```json
+{
+  "error": "invalid_grant",
+  "error_description": "Invalid user credentials"
+}
+```
+
+3. 客户端id或secret错误，状态码401
+
+```json
+{
+  "error": "invalid_client",
+  "error_description": "Invalid client or Invalid client credentials"
+}
+```
+
+4. 不支持的授权类型，状态码401
+
+```json
+{
+  "error": "unsupported_grant_type",
+  "error_description": "Unsupported grant_type"
+}
+```
+
+## 用户信息管理
+
+### 获取用户信息
+
+  GET 请求URL：
+[https://account.izhiju.cn/realms/zhiju/account](https://account.izhiju.cn/realms/zhiju/account)
+
+请求头参数：
+Content-Type: application/json
+Authorization: Bearer {{token}}
+
+返回结果：
+1. 未授权，状态码401
+```json
+{
+  "error": "HTTP 401 Unauthorized",
+  "error_description": "For more on this error consult the server log at the debug level."
+}
+```
+
+2. 成功，状态码200, 返回如下内容：
+```json
+{
+  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
+  "username": "alva",
+  "firstName": "alva1",
+  "lastName": "huang",
+  "email": "alva@izhiju.cn",
+  "emailVerified": false,
+  "attributes": {
+    "phoneNumber": [
+      "18680533727"
+    ],
+    "picture": [
+      "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg"
+    ]
+  }
+}
+```
+
+### 更新用户信息
+
+  POST 请求URL：
+[https://account.izhiju.cn/realms/zhiju/account](https://account.izhiju.cn/realms/zhiju/account)
+
+请求头参数：
+Content-Type: application/json
+Authorization: Bearer {{token}}
+
+```json
+{
+  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
+  "username": "alva",
+  "firstName": "alva1",
+  "lastName": "huang",
+  "email": "alva@izhiju.cn",
+  "emailVerified": false,
+  "attributes": {
+    "phoneNumber": [
+      "18680533727"
+    ],
+    "picture": [
+      "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg"
+    ]
+  }
+}
+```
+
+返回结果：
+ 1. 未认证授权，状态码401, token错误或过期
+```json
+{
+  "error": "HTTP 401 Unauthorized",
+  "error_description": "For more on this error consult the server log at the debug level."
+}
+```
+
+2. 更新成功，状态码204, 无内容返回
+
+3. 更新失败，状态码400，下面为用户名不可修改返回的错误信息
+```json
+{
+  "errors": [
+    {
+      "field": "username",
+      "errorMessage": "error-user-attribute-read-only",
+      "params": [
+        "${username}"
+      ]
+    },
+    {
+      "field": "username",
+      "errorMessage": "readOnlyUsernameMessage",
+      "params": [
+        "${username}"
+      ]
+    }
+  ]
+}
+```
+### 删除用户信息