接口设计详录

本页对应《信息安全传输软件软件验收工作与技术总结》"2.4 接口设计"章节，供补全正式 Word 版文档时裁剪抄录。第二章外部接口、第三章后台公共服务接口、第五章配套函数库接口保留原设计口径；第四章 JSBridge 接口与第六章内部 REST API 已按当前工程实际重写：第六章全部路径、方法、参数、响应均以当前后端工程 qxj-backend-admin 导出的 OpenAPI Schema（drf-spectacular）为准并逐项核对代码，旧版文档中 /api/v2/*、/api/keymgr/* 的历史接口不再收录。

一、接口总览

类别	数量	说明
外部接口	15	MCS 系统后台及 MCS 用户与信息安全传输控制软件间的交互接口，含 token 验证、用户认证、密钥协商、数据加解密、访问控制决策、用户/设备/策略管理、密码应用、水印库、L0 溯源库等
后台公共服务接口	3	verify_token（Token 校验）、sm4_gcm_encrypt（明文数据封装）、sm4_gcm_decrypt（密文数据解封装），均为对底层密码库 libnspsmapi.so 的 Python 封装
前端 JSBridge 接口	6	login、getAccessToken、refreshAccessToken、sm4GcmEncrypt、sm4GcmDecrypt、logout，通过 ArkWeb 的 javaScriptProxy 注入 window.jsbridgeHandle
配套函数库接口	5	水印嵌入/提取 3 个（watermark_embed、batch_watermark_embed、watermark_extract）；设备标识生成/提取 2 个（encrypt_device_id、decrypt_device_id）
内部 REST API	79	当前后端 qxj-backend-admin 对外提供的全部 HTTP 操作，统一前缀 `/api/v3/`，分布在 14 个 Django app、37 个路径上：认证与验证码 4、当前用户 2、短信 1、用户管理 7、设备类型 6、设备管理 6、角色管理 6、用户-角色关联 6、地理围栏 6、角色-围栏关联 6、时间规则 6、角色-时间规则关联 6、设备公钥 8、安全日志 6、服务器密钥二维码 1、设备侧 SM2 握手 2
合计	108	—

二、外部接口

外部接口指 MCS 系统后台及 MCS 用户与信息安全传输控制软件间的交互接口，包括 token 验证、用户认证、密钥协商、数据加解密、访问控制决策、用户/设备/策略管理等接口（原表 5-1）。

序号	接口名称	接口描述	接口提供方	接口调用方	交互方式	接口时机	主要参数
1	安全环境初始化接口	安全组件的初始化	传输加密子系统	MCS 后台	本地动态库接口调用	MCS 初始化阶段	——
2	token 验证接口	token 有效性和超时验证，若没有有效 token，需要反馈 http 302 给用户重定向访问鉴权及策略管理子系统进行登录认证和密钥协商	传输加密子系统	MCS 后台	本地动态库接口调用	用户登录 MCS 系统时	token 字符串
3	用户认证接口	执行用户名口令认证、短信验证认证功能，身份鉴别信息被加密和签名保护；执行用户登录限制，当用户输入错误密码超过指定阈值时，禁止登录等	鉴权及策略管理子系统	MCS 系统的用户	https	用户访问 MCS 系统时	用户名、口令、短信验证码、用户接入时 IP、用户接入地理位置、用户接入网络类型
4	密钥协商接口	用户与鉴权服务器进行会话密钥协商	鉴权及策略管理子系统	MCS 系统的用户	https	用户认证通过后，自动进行	——
5	观测需求申请数据解封装接口（后台）	对观测需求申请数据进行解密和验签	传输加密子系统后台接口模块	MCS 后台	本地动态库接口调用	MCS 后台接收到观测需求申请时	用户 ID、待解封装的观测需求申请数据
6	观测需求响应数据封装接口（后台）	对观测需求响应数据进行加密和签名	传输加密子系统后台接口模块	MCS 后台	本地动态库接口调用	MCS 后台反馈观测需求时	用户 ID、待封装的观测需求响应数据
7	观测需求申请数据封装接口（前台）	对观测需求申请进行解密和签名	传输加密子系统前端接口模块	MCS 前端	源码调用	用户认证通过后，发起观测需求请求时	用户 ID、待封装的观测需求申请数据
8	观测需求反馈数据解封装接口（前台）	对观测需求响应数据进行解密和验签	传输加密子系统前端接口模块	MCS 前端	源码调用	MCS 前端收到观测需求响应时	用户 ID、待解封装的观测需求响应数据
9	观测请求访问控制决策接口	根据用户访问观测请求服务时的时间、所在位置，查询访问控制策略，反馈该请求结果是允许或拒绝	鉴权及策略管理子系统	MCS 后台	本地动态库接口调用	用户认证通过后，进行观测需求请求时	用户访问时间、用户位置（GPS）
10	用户管理类页面接口	用户注册、注销、状态管理等	用户管理子系统	MCS 系统的管理员用户	https	用户首次使用 MCS 系统前	用户基本信息、用户状态信息
11	设备管理类页面接口	设备注册、注销、状态管理等，为设备生成加密公私钥和签名公私钥，设备加密和签名私钥安全存储在设备本地	设备管理子系统	MCS 系统的管理员用户	https	设备首次使用、年审、丢失等状态变更时	设备基本信息、设备状态信息
12	访问控制策略管理类页面接口	访问控制策略设置、删除、修改、查看	鉴权及策略管理子系统	MCS 系统的管理员用户	https	按照 MCS 系统的管理员使用需要	访问控制元素（用户角色、接入网络、接入 IP 段、访问时间）和策略动作
13	密码应用接口	调用 PCIE 密码卡，完成北京地面站 MCS 和乌兰察布备份站 MCS 间数据的加密和完整性保护	传输加密子系统	MCS	密码应用接口	MCS 系统传输数据前后	根据密码行业标准 GM/T 0018-2012 密码设备应用接口规范规定的参数
14	图像数据版权保护接口库	提供图片气象数据水印的嵌入和提取功能	图像数据版权保护接口库	图片气象数据管理相关系统	图像数据版权保护接口库	嵌入接口调用时机为气象图片外发前，提取接口调用时机为提取气象图片版权信息时	嵌入接口参数：原始图像、版权信息、用户标识信息。提取接口参数：嵌入后图像
15	L0 数据溯源及篡改检测接口库	提供 L0 数据封装和解封装功能，可检测 L0 数据完整性，并记录操作的系统	L0 数据溯源及篡改检测接口库	气象数据处理相关系统	L0 数据溯源及篡改检测接口库	对 L0 数据进行封装、解封装时	封装接口：原始 L0 数据和处理 handle 句柄。解封装接口：封装后的 L0 数据

三、后台公共服务接口

后台接口供 MCS 后台调用，均为对底层 C 密码库 libnspsmapi.so 的 Python 封装，屏蔽了签名数据解析、指针转换以及内存管理等底层细节。

码表口径警示：旧 C 库设计码表 ≠ 现 SDK 交付码表

本章各函数给出的结果码（verify_token 的 -10~-19、加解密的 -20~-39）是技术总结原文中早期底层 C 密码库 libnspsmapi.so Python 封装的设计口径，仅为保持与原文一致而照录。

当前工程实际交付、业务后端应对接的是独立 Python 包 qxj-backend-sdk，其码表已重新定义，以后端 Python SDK 为准，切勿混用：

Token 校验 VerifyCode：0 完全通过 / 1 仅外层通过（也必须拒绝） / -1~-8（空、解析失败、验签失败、过期、字段缺失、HMAC 失败、无会话密钥、Redis 异常） / -99 未知；
加解密 CryptoErrorCode：0 成功 / -1~-9（空输入、底层调用失败、无会话密钥、帧格式错、认证失败、库未加载、Redis 异常、设备 ID 非法、hex 解析失败） / -99 未知。

现 SDK 高层函数名为 verify_access_token / sm4_gcm_encrypt / sm4_gcm_decrypt，完整码表见 VerifyCode 码表与 CryptoErrorCode 码表。

编者注：原文"2）后台密文数据解封装接口：sm4_gcm_decrypt 函数"小节给出的函数原型为 sm4_gcm_encrypt，"3）后台明文数据封装接口：sm4_gcm_encrypt 函数"小节给出的函数原型为 sm4_gcm_decrypt，两小节标题与正文存在互换；本页按函数名正常归位，细节内容照录原文。

3.1 后台 Token 校验接口：verify_token

功能：供 MCS 后台在接收用户登录 token 时调用，对 token 内容进行解密、验证，反馈 token 验证结果、登录设备 ID、有效期等。通过 Python 调用底层密码库中提供的 SM2 数字签名验证函数，对 Token 中的签名进行验签，从而确认 Token 是否由合法系统生成且在传输过程中未被篡改。主要功能：
1. 对输入的 Token 进行格式解析，提取其中包含的签名值；
2. 调用底层密码库 sm2_verify 接口，对 Token 进行 SM2 签名验证；
3. 若验签成功，则解析 Token 中包含的设备 ID、签发时间、有效期等字段，并返回验证结果；
4. 若验签失败或 Token 格式异常，则返回对应错误码，表示 Token 非法或已被篡改。
调用说明：当 MCS 后台接收到客户端提交的登录 Token 时，上层业务逻辑调用本接口对 Token 进行合法性验证。典型调用场景包括：接口访问身份校验、会话合法性校验、Token 有效期校验等。只有在 Token 验证成功的情况下，系统才允许用户继续访问后续业务接口。
函数原型：

python

def verify_token(token: str, skip_hmac: bool = False) -> (device_id, expire_time, result)

参数说明：

参数	类型	说明
token	string	JWT Token 字符串
skip_hmac	bool	是否跳过 HMAC 和 Redis 验证

返回值：三元组 (device_id, expire_time, result)。device_id[string]：设备 ID（IDA）；expire_time[string]：过期时间（Unix 时间戳，字符串）；result[int]：结果码，含义如下：

code	说明
0	验证成功
-10	Token 为空
-11	Token 格式解析失败
-12	Token 签名验证失败
-13	验签失败或无会话密钥
-14	Token 已过期
-15	Token 中缺少必需字段
-16	Redis 连接失败
-18	HMAC 不匹配
-19	未知错误

注意事项：该函数调用底层动态库 libnspsmapi.so。

3.2 后台明文数据封装接口：sm4_gcm_encrypt

功能：供 MCS 后台调用，调用底层密码库（libnspsmapi.so）执行 SM4-GCM 模式加密。主要功能：
1. 根据输入的明文 plain 分配输出缓冲区，输出缓冲区存放安全头部、密文、消息认证码；
2. 根据 token 验证接口反馈的设备 ID（ida）寻找对应的会话密钥，调用底层 SM4-GCM 加密接口，对输入明文进行加密和完整性认证；
3. 返回加密后的密文（Ciphertext）与消息认证码（MAC Tag）；
4. 若底层加密函数返回非 0 状态码，则抛出异常，表示加密失败。
调用说明：上层业务逻辑在需要进行认证加密（如传输数据加密、Token 保护等）时调用本函数。
函数原型：

python

def sm4_gcm_encrypt(devID: str, plain: str, is_hex: bool = False) -> (ciphertext, result)
# 重载接口:
def sm4_gcm_encrypt_hex(devID: str, plain_hex: str)   # 专用 hex 格式输入
def sm4_gcm_encrypt_str(devID: str, plain_str: str)   # 专用普通字符串输入

参数说明：

参数	类型	说明
devID	string	设备 ID（IDA，从 verify_token 获取）
plain	string	待加密的明文数据
is_hex	bool	可选，明文是否为 hex 格式，默认为 False（普通字符串）

返回值：二元组 (ciphertext, result)。ciphertext[string]：加密后的密文，hex 表示方式的字符；result[int]：结果码，返回 0 表示加密成功且完整性校验成功，失败错误码如下：

code	说明
0	加密成功
-20	明文为空
-21	底层加密库调用失败
-22	未找到对应的会话密钥
-29	未知错误

注意事项：该函数调用底层动态库 libnspsmapi.so。

3.3 后台密文数据解封装接口：sm4_gcm_decrypt

功能：供 MCS 后台调用，用于调用底层密码库 libnspsmapi.so，执行 SM4-GCM 解密与完整性校验。主要功能：
1. 根据输入的密文 cipher 分配输出缓冲区用于存放解密后的明文；
2. 根据安全头部中的发送者（设备）ID，找到会话密钥，调用底层 SM4-GCM 解密及完整性校验接口，按 GCM 模式进行解密和 MAC 重计算；
3. 返回解密后的明文（Plaintext）以及 MAC 验证结果；
4. 若底层解密函数返回非 0 状态码，则抛出异常，表示解密失败或认证信息验证失败。
调用说明：上层业务逻辑在需要进行解密和完整性校验（如传输数据加密、Token 保护等）时调用本函数。
函数原型：

python

def sm4_gcm_decrypt(cipher: str, dev_id: str = None) -> (plaintext, result)

参数说明：

参数	类型	说明
cipher	string	待解密的数据，hex 表示方式的字符串
dev_id	string	可选，设备 ID（IDA），如果不提供则自动从密文安全头部解析

返回值：二元组 (plaintext, result)。plaintext[str]：解密后的明文，hex 表示方式的字符串；result[int]：结果码，返回 0 表示解密成功，失败错误码如下：

code	说明
0	解密且 MAC 验证成功
-30	密文为空
-31	底层加密库调用失败
-32	未找到对应的会话密钥（从安全头部解析发送者 ID 失败）
-33	密文格式错误、非本算法产生或已被篡改
-34	认证失败
-39	未知错误

注意事项：该函数调用底层动态库 libnspsmapi.so。

四、前端 JSBridge 接口

前台接口通过 ArkWeb（方舟 Web）组件的 javaScriptProxy 机制，将客户端原生方法注入到网页全局对象 window.jsbridgeHandle 上，使网页可以借客户端完成加密登录、令牌管理与数据加解密。当前客户端（main 4.1.42 / dev 5.2.88 起）共注册 6 个异步方法：

login / getAccessToken / refreshAccessToken / sm4GcmEncrypt / sm4GcmDecrypt / logout

通用约定：

所有方法均返回 Promise<string>，resolve 一个 JSON 字符串，网页侧 JSON.parse 后得到统一结构 BridgeResult；Promise 在任何情况下都不会被 reject，网页无需 try/catch，只按 code 分支处理。
每次调用都实时校验发起页面 URL：页面 origin 必须属于当前选中服务器的白名单（backendUrl / frontendUrl / businessBackendUrl / businessFrontendUrl），不在白名单内统一返回 code=-60；fail-closed，取不到页面 URL 或白名单为空时一律拒绝。

interface BridgeResult {
  code: number            // 错误码，0 成功
  message: string         // 结果描述（成功为 SUCCESS，失败为具体原因）
  accessToken?: string    // login / getAccessToken / refreshAccessToken 成功时
  refreshToken?: string   // login 成功时
  data?: string           // sm4GcmEncrypt 为帧 hex；sm4GcmDecrypt 为明文
}

4.0 统一错误码总表

code	名称	含义	适用方法
0	SUCCESS	成功	全部
-11	ERROR_EMPTY_INPUT	明文为空或空字符串	sm4GcmEncrypt
-12	ERROR_INPUT_TOO_LONG	明文超过安全长度（64KB）	sm4GcmEncrypt
-14	ERROR_ENCRYPT_FAILED	加密失败（密钥不可用、帧构造失败等）	sm4GcmEncrypt
-21	ERROR_INVALID_CIPHERTEXT	密文为空、格式错误、非本算法产生或已被篡改	sm4GcmDecrypt
-22	ERROR_DECRYPT_AUTH_FAILED	完整性校验失败（GCM tag 不匹配）	sm4GcmDecrypt
-31	ERROR_TOKEN_NOT_FOUND	未找到 Access Token（未登录或已失效）	getAccessToken
-41	ERROR_REFRESH_TOKEN_NOT_FOUND	未找到 Refresh Token（未登录/未绑定）	refreshAccessToken
-44	ERROR_AUTH_SERVER_REJECT	认证服务器拒绝刷新（message 透传后端原因）	refreshAccessToken
-51	ERROR_TOKEN_CLEAR_FAILED	Token 清理失败（服务器拉黑失败不阻断本地清理）	logout
-60	ERROR_PERMISSION_DENIED	非白名单页面调用	全部
-70	ERROR_LOGIN_PAYLOAD_INVALID	登录参数无效（payload 解析失败 / 账密为空）	login
-71	ERROR_LOGIN_NOT_BOUND	未绑定服务器（需先扫码导入服务器信息）	login
-72	ERROR_LOGIN_KEY_EXCHANGE_FAILED	SM2 密钥协商失败	login
-73	ERROR_LOGIN_DEVICE_ID_FAILED	设备 ID 获取失败	login
-74	ERROR_LOGIN_REJECTED	认证服务器拒绝登录（message 透传后端原因）	login
-75	ERROR_LOGIN_EXCEPTION	登录流程异常	login
-99	ERROR_UNKNOWN	未知错误（兜底）	全部

网页只传账密（及验证码/位置），客户端全权完成「组装明文 JSON → SM4-GCM 加密 → POST 加密帧到后端 → 解密响应 → 持久化 token」全流程，网页无需接触 K_client、帧格式与 SM4 运算。payload 未带 position 时客户端主动单次定位补齐。

window.jsbridgeHandle.login(payload: string): Promise<string>
// payload = JSON.stringify({ username, password, verification_code?, position? })

字段	必填	说明
username	是	用户名
password	是	密码
verification_code	否	短信验证码（网页管理端登录可为空）
position	否	位置坐标字符串（如 "116.397,39.908"），缺省时客户端主动定位

成功返回 { code: 0, accessToken, refreshToken, message }；失败返回 -70~-75 或 -60。前置条件为设备已扫码绑定服务器（serverId + serverPubKey 齐全），否则返回 -71 并由客户端弹出扫码引导。登录成功与否以 code === 0 判断，不要依赖 message 文案。

4.2 获取访问令牌接口：getAccessToken

从原生客户端安全存储读取当前登录会话的短期 Access Token，不保证返回时 token 仍有效；失效后由网页调用 refreshAccessToken 刷新。

window.jsbridgeHandle.getAccessToken(): Promise<string>

无参数。成功返回 { code: 0, message: "SUCCESS", accessToken }；失败返回 -31（未登录/无 token）或 -60。Access Token 生命周期较短，网页获取后应立即用于请求头，不要持久化到网页侧。

4.3 令牌刷新接口：refreshAccessToken

客户端用安全存储中的 Refresh Token 向认证服务器换取新 Access Token，成功后更新本地存储并返回新 token；网页全程接触不到 Refresh Token。

window.jsbridgeHandle.refreshAccessToken(): Promise<string>

无参数。成功返回 { code: 0, accessToken: "<新token>" }；失败返回 -41（无 Refresh Token，唯一出路是重新登录）、-44（认证服务器拒绝，message 透传原因）或 -60。并发多个 401 时网页侧应自行合并为一次刷新调用。

4.4 前端明文数据封装接口：sm4GcmEncrypt

对传入的明文字符串加密，返回完整加密帧 hex（64B 安全头部 + SM4-GCM 密文 + 消息认证码）。加密在原生层完成，会话密钥基于 SM2 国密握手协商获得，由 Asset Store Kit（ASSET）在可信执行环境（TEE）中安全存储，无需业务侧传入；IV 由鸿蒙官方随机数接口生成，每次不同。

window.jsbridgeHandle.sm4GcmEncrypt(plainText: string): Promise<string>

参数 plainText 为待加密明文，最长 64KB。成功返回 { code: 0, data: "<帧hex>" }；失败返回 -11（明文为空）、-12（超长，不做截断）、-14（加密失败）或 -60。同一明文每次结果不同属正常现象。

4.5 前端密文数据解封装接口：sm4GcmDecrypt

对 sm4GcmEncrypt 输出的帧 hex 解密，IV 从帧安全头部获得，返回明文字符串。

window.jsbridgeHandle.sm4GcmDecrypt(cipherText: string): Promise<string>

参数 cipherText 为加密帧 hex。成功返回 { code: 0, data: "<明文>" }；失败返回 -21（密文无效/被篡改）、-22（GCM tag 校验失败）或 -60。密文必须来自当前会话密钥，跨会话/跨设备的帧无法解密。

4.6 退出登录接口：logout

通知后端拉黑当前 access/refresh，并清空客户端本地两个 token 与会话密钥；服务器拉黑失败不阻断本地清理，本地清理完成即返回 0。

window.jsbridgeHandle.logout(): Promise<string>

无参数。成功返回 { code: 0, message: "SUCCESS" }；失败返回 -51（本地清理异常）或 -60。退出后网页应清理自身登录状态并跳转登录页。

五、配套函数库接口（水印嵌入提取 / 设备标识生成提取）

5.1 单张图片水印嵌入：watermark_embed

功能：对单张彩色图像执行基于区域感知选择 + DCT 系数对比嵌入的数字水印嵌入流程，执行步骤包括区域选取与水印写入，生成带水印的输出图像。
调用说明：上层业务逻辑在执行单张气象图像的水印嵌入等操作时调用本函数。
函数原型：

python

def watermark_image(image_file_path: str, watermarked_image_file_path: str, data: str)

参数说明：image_file_path[string]：输入 JPG/PNG 图像的绝对/相对路径；watermarked_image_file_path[string]：存储嵌入水印后输出图像的绝对/相对路径；data[string]：待嵌入内容，长度小于 16 字节，超过部分在程序中截断。
返回值：result_code 表示处理结果，返回 0 表示水印嵌入成功，失败错误码如下：

code	说明
-1	待嵌入图片未能成功读取
-2	嵌入内容过长，被截断
-3	参数中嵌入后图片路径不存在或为空，该函数将嵌入水印后图片保存至和原图片同一文件夹
-99	未知错误

依赖库：bchlib 2.1.3、opencv-python 4.11.0.86、numpy 2.0.1。

5.2 批量图片水印嵌入：batch_watermark_embed

功能：对多张输入图像执行批量水印嵌入处理。基于单张图片嵌入函数 watermark_embed，对输入的图像列表逐张执行水印嵌入，并返回全部水印图像。适用于批处理气象图像并行嵌入等场景。
函数原型：

python

def batch_watermark_embed(image_file_path: str, watermarked_image_file_path: str, data: str)

参数说明：image_file_path[string]：输入 JPG/PNG 图像的文件夹绝对/相对路径；watermarked_image_file_path[string]：存储嵌入水印后输出图像的文件夹绝对/相对路径；data[string]：待嵌入内容，长度小于 16 字节，超过部分在程序中截断。
返回值：二元组 (success_num, result_code)。success_num[int]：成功嵌入水印的图片数量；result_code[int]：失败错误或警告码：

code	说明
-1	待嵌入图片文件夹不存在
-2	嵌入内容过长，被截断
-3	参数中嵌入后图片路径不存在或为空，该函数将嵌入水印后图片保存至和原图片同一文件夹
-99	未知错误

依赖库：bchlib 2.1.3、opencv-python 4.11.0.86、numpy 2.0.1。

5.3 单张图片水印提取：watermark_extract

功能：对单张彩色图像执行基于区域感知选择 + DCT 系数对比嵌入的数字水印提取流程。函数从输入图像中自动定位嵌入区域、恢复嵌入的比特序列，完成 BCH 解码与内容重构，并返回最终提取到的水印内容。
函数原型：

python

def watermark_extract(image_file_path: str)

参数说明：image_file_path[string]：输入 JPG/PNG 水印图像的绝对/相对路径。
返回值：二元组。data[string]：成功时返回提取到的内容（二进制字符串），失败时返回空字符串；result_code[int]：返回 0 表示水印提取成功，负数表示失败错误或警告码：

code	说明
-1	输入图片未能成功读取
-2	水印比特序列提取失败（例如图片过大或过小）
-99	未知错误

依赖库：bchlib 2.1.3、opencv-python 4.11.0.86、numpy 2.0.1。

5.4 设备标识生成接口：encrypt_device_id

功能：将 4bit 真实设备 ID 加密为 8bit 加密设备 ID。主要功能：① 验证输入设备 ID 的有效性（必须在 0-15 范围内）；② 生成 4bit 随机数作为填充数据；③ 将设备 ID 分散到 8bit 数据的奇数位（1,3,5,7 位）；④ 将随机数分散到 8bit 数据的偶数位（0,2,4,6 位）；⑤ 应用固定的异或因子（0x82）增加加密强度；⑥ 返回 8bit 加密后的设备 ID。
调用说明：在需要保护设备 ID 隐私、防止设备 ID 被简单识别的场景下调用本函数。
函数原型：uint8_t encrypt_device_id(uint8_t device_id);
参数说明：device_id：设备 ID，类型 uint8_t，取值范围 0~15。
返回值：加密后设备 ID，类型 uint8_t，取值范围 0x00-0xFF。失败错误码：-1（设备 ID 超出 4bit 范围 0-15）。

5.5 设备 ID 提取接口：decrypt_device_id

功能：从 8bit 加密设备 ID 中提取 4bit 原始设备 ID。主要功能：① 应用异或因子还原数据；② 从 8bit 数据的奇数位（1,3,5,7 位）提取设备 ID；③ 重组为 4bit 原始设备 ID；④ 返回解密后的设备 ID。
调用说明：在需要从加密设备 ID 还原原始设备 ID 的场景下调用本函数。
函数原型：uint8_t decrypt_device_id(uint8_t encrypted_id);
参数说明：encrypted_id：加密后设备 ID，类型 uint8_t，表示 8bit 加密后的设备 ID。
返回值：原始设备 ID，类型 uint8_t，表示 4bit 原始设备 ID，取值范围 0-15。

六、内部 REST API

内部 REST API 为当前后端工程 qxj-backend-admin（Django 4.2 + Django REST Framework）对外提供的全部 HTTP 接口，共 37 个路径、79 个操作，按业务归属分布在 14 个 Django app。

6.0 通用约定

基础信息

项	值
统一前缀	`/api/v3/`
本地服务地址	`http://127.0.0.1:4607`
请求/响应格式	`application/json`；设备侧 SM2 握手与加密登录为 `application/octet-stream`；文件上传为 `multipart/form-data`
认证头	`Authorization: Bearer {access_token}`
认证类	`BlacklistJWTAuthentication`：继承 SimpleJWT 的 JWTAuthentication，额外校验 access token 的 jti 是否已被拉黑
JWT 签名	头 alg 标记为 `NSP-SM`，实际为 SM2withSM3 国密签名
令牌生命周期	access 默认 12 小时；refresh 默认 7 天
权限分层	管理端 `/api/v3/admin/*` 要求管理员身份（IsAdminUser）；角色与用户-角色关联的写操作仅超级管理员；设备侧握手接口 AllowAny

分页约定：除设备类型等小数据量接口关闭分页外，列表接口统一返回分页结构，支持 page（页码）、page_size（每页条数，默认 10、最大 100）查询参数；页码非法或超出末页时不返回 404，而是 200 + 空 results（count 仍准确），便于前端表格处理。

json

{ "count": 12, "next": "http://...?page=2", "previous": null, "results": [] }

通用查询参数：列表接口普遍支持 search（关键词模糊检索）与 ordering（排序字段，- 前缀表示降序），并按模块支持若干精确过滤参数（见各节）。

错误响应：参数校验失败返回 400（DRF 字段错误或登录信封 { "success": false, "message": "..." }）；未认证返回 401 { "detail": "身份认证信息未提供。" }；权限不足返回 403；资源不存在返回 404 { "detail": "未找到。" }；删除成功返回 204。

6.1 认证与验证码接口

均为 AllowAny，供用户登录前后直接调用。

操作标识	方法	路径	功能与输入/输出要点
user-login	POST	/api/v3/user/login/	用户登录，支持双模式：`application/json` 明文模式（受 ALLOW_JSON_LOGIN 开关控制）与 `application/octet-stream` 加密模式（SM4-GCM 64B 信封，受 ALLOW_DEVICE_LOGIN 开关控制）。明文请求字段：username、password、verification_code*、device_id（默认空）、position、captcha_verify_param（默认空）。成功返回 `{ "success": true, "data": { "access", "refresh", "user" } }`；失败 400/403 返回 `{ "success": false, "message" }`。加密模式另对请求密文做 SHA256 重放占位（90 秒内同一密文拒绝重复提交）
user-logout	POST	/api/v3/user/logout/	主动登出。请求体 `{ "refresh": "<refresh_token>" }`；将 refresh token 及其派生的 access token 加入黑名单，剩余有效期内均不可用。成功返回 `{ "success": true, "message": "已成功退出登录" }`
token-refresh	POST	/api/v3/token/refresh/	使用 refresh token 换取新 access token：只刷新短 token、不旋转长 token；refresh 过期或已被拉黑则拒绝（401）。请求体 `{ "refresh" }`；成功返回 `{ "success": true, "data": { "access" } }`
captcha-verify	POST	/api/v3/user/captcha/verify/	验证码预验证并颁发登录票据：前端验证码 SDK 校验回调中调用，验证通过后服务端缓存 10 分钟一次性票据（绑定 username），随后加密登录无需再带验证码参数。请求字段 captcha_verify_param、username；成功/失败均返回 `{ "success", "message" }`。IP 级限流默认 20 次/分钟；接口不查询用户表，不泄露账号是否存在

登录校验流程：必填字段校验 → 用户存在、状态激活、未过期 → 临时锁定检查（连续失败 5 次锁定 LOGIN_LOCKOUT_SECONDS 秒，自动恢复，不做永久冻结）→ 验证码/票据校验 → 签发令牌。access/refresh token 均携带 device_id 与 position 自定义声明，供后续访问控制使用。

6.2 当前用户接口

权限 IsAuthenticated，任何登录用户可访问自己的信息。

操作标识	方法	路径	功能与输入/输出要点
current-user	GET	/api/v3/users/me/	返回当前用户精简信息：id、username、real_name、email、phone、description、is_staff、is_superuser、status、status_display、expires_at、date_joined，以及角色列表 roles（元素含 id、name、role_type、role_type_display）
change-own-password	PATCH	/api/v3/users/me/	修改自己的密码。请求字段 old_password、new_password；服务端校验旧密码正确、新密码不与旧密码相同，修改后撤销该账号全部已签发令牌（其他会话需重新登录）。成功返回 `{ "detail": "密码修改成功" }`

6.3 短信验证码接口

操作标识	方法	路径	功能与输入/输出要点
sms-send-code	POST	/api/v3/sms/send_code/	发送登录验证码，AllowAny。支持两种方式：username（按用户名查绑定手机号）或 phone（直接指定手机号），至少传一个、同时传时 phone 优先。安全限制：统一受理不泄露账号是否存在；同一手机号 60 秒内只发 1 次；已有未过期验证码时复用旧码；IP 级限流默认 5 次/分钟。成功返回 `{ "success": true, "message", "expire_seconds" }`，不回传手机号与验证码明文

6.4 用户管理接口（/api/v3/admin/users）

管理端用户 CRUD + 重置密码，共 7 个操作。用户读取字段：id、username、email、real_name、phone、expires_at、login_time_start、login_time_end、allowed_ips、last_login_at、last_login_ip、failed_attempts、register_source（及 register_source_display）、description、status（及 status_display）、status_note、date_joined、is_active、is_staff、is_superuser。

操作标识	方法	路径	功能与输入/输出要点
admin-user-list	GET	/api/v3/admin/users/	分页获取用户，支持 search（username/real_name/email/phone）、ordering、status（0/1/2）与 is_active 过滤
admin-user-create	POST	/api/v3/admin/users/	管理员创建用户。必填 username、password（至少 6 位，服务端哈希存储）；可选 email、real_name、phone、expires_at、login_time_start/end、allowed_ips、description、status、status_note、is_staff、is_superuser。username 唯一；is_active 由 status 自动派生、不可直接指定（201）
admin-user-detail	GET	/api/v3/admin/users/{id}/	按 ID 获取用户完整信息（200）
admin-user-update	PUT	/api/v3/admin/users/{id}/	全量更新用户资料；username 与 password 不可在此修改
admin-user-partial-update	PATCH	/api/v3/admin/users/{id}/	只提交需修改字段
admin-user-delete	DELETE	/api/v3/admin/users/{id}/	删除用户；禁止删除自己、禁止删除最后一个超级管理员、普通管理员不能删除超级管理员（204）
admin-user-set-password	POST	/api/v3/admin/users/{id}/set_password/	管理员重置用户密码，请求体 `{ "password" }`；同时清零失败次数并解除冻结（status 置回激活）。成功返回 `{ "detail": "密码已重置" }`

status 枚举：0=禁用、1=激活、2=冻结；register_source 枚举：1=管理员注册、2=用户自己注册。

6.5 设备类型接口（/api/v3/admin/device_types）

设备类型为小数据量字典，前端下拉一次取全，关闭分页，共 6 个操作。字段：id、type_name*、type_code*、description。

操作标识	方法	路径	功能
device-type-list	GET	/api/v3/admin/device_types/	获取全部设备类型（数组），支持 search、ordering
device-type-create	POST	/api/v3/admin/device_types/	创建设备类型，必填 type_name、type_code（201）
device-type-detail	GET	/api/v3/admin/device_types/{id}/	获取单条类型
device-type-update	PUT	/api/v3/admin/device_types/{id}/	全量更新
device-type-partial-update	PATCH	/api/v3/admin/device_types/{id}/	部分更新
device-type-delete	DELETE	/api/v3/admin/device_types/{id}/	删除类型（204）

6.6 设备管理接口（/api/v3/admin/devices）

共 6 个操作。设备读取字段：id、eqp_unique_identifier、eqp_alias、eqp_type（及 eqp_type_display）、importance（及 importance_display）、os、ip、net_mac、bluetooth、near_link、location、serial、vendor、register_time、update_time、last_annual_review、expires_at、status（及 status_display）、description。

操作标识	方法	路径	功能与输入/输出要点
admin-device-list	GET	/api/v3/admin/devices/	分页获取设备，支持 search、ordering、status（0/1/2/3）与 eqp_type 过滤
admin-device-create	POST	/api/v3/admin/devices/	管理员创建设备，必填 eqp_unique_identifier（唯一）；eqp_alias、eqp_type、importance、os、ip、net_mac、bluetooth、near_link、location、serial、vendor、last_annual_review、expires_at、status、description 均可选（201）
admin-device-detail	GET	/api/v3/admin/devices/{id}/	返回单个设备完整信息
admin-device-update	PUT	/api/v3/admin/devices/{id}/	全量更新；eqp_unique_identifier 不可修改
admin-device-partial-update	PATCH	/api/v3/admin/devices/{id}/	只传需要修改的字段
admin-device-delete	DELETE	/api/v3/admin/devices/{id}/	删除设备；若设备已注册公钥（device_public_keys），须先停用公钥再删（PROTECT）（204）

枚举：importance 1=极低、2=中较低、3=中等、4=较高、5=非常高；os Android=安卓、HarmonyOS=鸿蒙 NEXT；status 0=禁用、1=激活、2=挂失、3=年审中。

6.7 角色管理接口（/api/v3/admin/roles）

共 6 个操作。字段：id、name、role_type（及 role_type_display）、description、created_at、updated_at。

操作标识	方法	路径	功能与输入/输出要点
role-list	GET	/api/v3/admin/roles/	分页获取角色，支持 search、ordering、role_type（0/1/2）过滤
role-create	POST	/api/v3/admin/roles/	创建角色，必填 name、role_type；可选 description（201）。写操作仅超级管理员：role_type=0 的角色会经信号使关联用户被重算为 is_staff+is_superuser，防普通管理员垂直越权
role-detail	GET	/api/v3/admin/roles/{id}/	获取角色详情
role-update	PUT	/api/v3/admin/roles/{id}/	全量更新（写操作仅超级管理员）
role-partial-update	PATCH	/api/v3/admin/roles/{id}/	部分更新（写操作仅超级管理员）
role-delete	DELETE	/api/v3/admin/roles/{id}/	删除角色（204）

role_type 枚举：0=管理员、1=普通用户、2=访客。

6.8 用户-角色关联接口（/api/v3/admin/user_roles）

共 6 个操作。字段：id、user、username（只读派生）、role、role_name（只读派生）。

操作标识	方法	路径	功能与输入/输出要点
user-role-list	GET	/api/v3/admin/user_roles/	分页获取关联，支持 user、role 过滤与 search
user-role-create	POST	/api/v3/admin/user_roles/	为用户分配角色，必填 user、role（201）。创建/删除/变更时由信号统一重算用户 is_staff + is_superuser；写操作仅超级管理员（分配/移除角色是垂直越权入口）
user-role-detail	GET	/api/v3/admin/user_roles/{id}/	获取关联详情
user-role-update	PUT	/api/v3/admin/user_roles/{id}/	全量更新（写操作仅超级管理员）
user-role-partial-update	PATCH	/api/v3/admin/user_roles/{id}/	部分更新（写操作仅超级管理员）
user-role-delete	DELETE	/api/v3/admin/user_roles/{id}/	删除关联并重算用户权限标志位（204）

6.9 地理围栏接口（/api/v3/admin/geofences）

共 6 个操作。字段：id、location_name、longitude、latitude、coord_system（及 coord_system_display）、radius、location、created_at、updated_at。

操作标识	方法	路径	功能与输入/输出要点
geofence-list	GET	/api/v3/admin/geofences/	分页获取围栏，支持 search、ordering、coord_system（WGS84/GCJ-02/BD-09）过滤
geofence-create	POST	/api/v3/admin/geofences/	创建围栏，必填 location_name（唯一）；longitude、latitude、coord_system、radius（默认 100.0 米）、location 可选（201）
geofence-detail	GET	/api/v3/admin/geofences/{id}/	返回单个围栏完整信息
geofence-update	PUT	/api/v3/admin/geofences/{id}/	全量更新
geofence-partial-update	PATCH	/api/v3/admin/geofences/{id}/	部分更新
geofence-delete	DELETE	/api/v3/admin/geofences/{id}/	删除围栏；被角色引用时关联记录 RoleGeofence 随 CASCADE 一并解绑（204）

6.10 角色-围栏关联接口（/api/v3/admin/role_geofences）

共 6 个操作。字段：id、role、role_name（只读派生）、geofence、geofence_name（只读派生）、created_at。一个角色可绑定多个围栏。

操作标识	方法	路径	功能与输入/输出要点
role-geofence-list	GET	/api/v3/admin/role_geofences/	分页获取关联，支持 role、geofence 过滤与 search
role-geofence-create	POST	/api/v3/admin/role_geofences/	为角色绑定围栏，必填 role、geofence（201）
role-geofence-detail	GET	/api/v3/admin/role_geofences/{id}/	获取关联详情
role-geofence-update	PUT	/api/v3/admin/role_geofences/{id}/	全量更新
role-geofence-partial-update	PATCH	/api/v3/admin/role_geofences/{id}/	部分更新
role-geofence-delete	DELETE	/api/v3/admin/role_geofences/{id}/	删除关联（204）

6.11 时间规则接口（/api/v3/admin/time_rules）

共 6 个操作。字段：id、rule_name、mode（及 mode_display）、start_time、end_time、weekdays（及 weekdays_display）、month_days、months、week_parity、valid_from、valid_to、description、is_active、created_at、updated_at。一条规则 = 一个时段 + 周期约束 + 模式。

操作标识	方法	路径	功能与输入/输出要点
time-rule-list	GET	/api/v3/admin/time_rules/	分页获取规则，支持 search、ordering、mode（ALLOW/DENY）与 is_active 过滤
time-rule-create	POST	/api/v3/admin/time_rules/	创建规则，必填 rule_name（唯一）、start_time、end_time；end<start 表示跨夜时段。可选 mode（默认 ALLOW）、weekdays（ISO 周 1-7，空=每天）、month_days（1-31）、months（1-12）、week_parity、valid_from、valid_to、description、is_active（201）
time-rule-detail	GET	/api/v3/admin/time_rules/{id}/	返回单条规则完整信息
time-rule-update	PUT	/api/v3/admin/time_rules/{id}/	全量更新；valid_to 不得早于 valid_from
time-rule-partial-update	PATCH	/api/v3/admin/time_rules/{id}/	部分更新
time-rule-delete	DELETE	/api/v3/admin/time_rules/{id}/	删除规则；被角色引用时 RoleTimeRule 随 CASCADE 一并解绑（204）

mode 枚举：ALLOW=允许（白名单）、DENY=禁止（黑名单）；week_parity：odd=仅单周、even=仅双周、空=不限。多规则冲突时 DENY 优先于 ALLOW。

6.12 角色-时间规则关联接口（/api/v3/admin/role_time_rules）

共 6 个操作。字段：id、role、role_name（只读派生）、time_rule、rule_name（只读派生）、created_at。一个角色可绑定多条时间规则。

操作标识	方法	路径	功能与输入/输出要点
role-time-rule-list	GET	/api/v3/admin/role_time_rules/	分页获取关联，支持 role、time_rule 过滤与 search
role-time-rule-create	POST	/api/v3/admin/role_time_rules/	为角色绑定时间规则，必填 role、time_rule，组合唯一（201）
role-time-rule-detail	GET	/api/v3/admin/role_time_rules/{id}/	获取关联详情
role-time-rule-update	PUT	/api/v3/admin/role_time_rules/{id}/	全量更新
role-time-rule-partial-update	PATCH	/api/v3/admin/role_time_rules/{id}/	部分更新
role-time-rule-delete	DELETE	/api/v3/admin/role_time_rules/{id}/	删除关联（204）

6.13 设备公钥接口（/api/v3/admin/device_public_keys）

设备公钥登记 pad 上报的 SM2 公钥，外键关联 devices.Device，共 8 个操作。读取字段：id、device、device_id（由设备 eqp_unique_identifier 派生，只读）、device_alias（只读）、public_key、timestamp、key_type（及 key_type_display）、status（及 status_display）、created_at、destroyed_at。

操作标识	方法	路径	功能与输入/输出要点
device-public-key-list	GET	/api/v3/admin/device_public_keys/	分页获取，支持 search、ordering、device、status（active/destroyed）、key_type（long_term/short_term）过滤
device-public-key-create	POST	/api/v3/admin/device_public_keys/	登记公钥，必填 device（Device 主键 id）、public_key（SM2 公钥 hex，不带 04 前缀）；可选 key_type、status（201）。同一设备同一公钥在 active 状态下唯一
device-public-key-detail	GET	/api/v3/admin/device_public_keys/{id}/	获取单条公钥详情
device-public-key-update	PUT	/api/v3/admin/device_public_keys/{id}/	全量更新
device-public-key-partial-update	PATCH	/api/v3/admin/device_public_keys/{id}/	部分更新
device-public-key-delete	DELETE	/api/v3/admin/device_public_keys/{id}/	硬删除公钥；device 外键为 PROTECT（204）
device-public-key-deactivate	POST	/api/v3/admin/device_public_keys/{id}/deactivate/	软删除：标记 status=destroyed 并记录 destroyed_at，保留审计痕迹
device-public-key-import-file	POST	/api/v3/admin/device_public_keys/import_file/	批量导入 pad 导出的 .dat 文件（multipart/form-data，字段 file）：每行 `device_id#<十进制 Unix 秒>#<SM2 公钥小写 hex，128 位不带 04 前缀>`，兼容旧版 8 字符 hex 时间戳；device_id 对应设备 eqp_unique_identifier，须先注册设备；重复行自动跳过，错误行记入 errors 返回且不中断后续行

6.14 安全日志接口（/api/v3/admin/security_logs）

安全日志为系统内部生成的审计记录（append-only），接口以查询、统计、导出、清理为主，共 6 个操作。读取字段：id、log_name、log_type（及 log_type_display）、user、username、device、device_identifier、device_alias、ip、result（及 result_display）、description、level（及 level_display）、method、path、status_code、response_time_ms、request_data、created_at。

操作标识	方法	路径	功能与输入/输出要点
security-log-list	GET	/api/v3/admin/security_logs/	分页获取日志，支持 search（log_name/description/path）、ordering、log_type、result（SUCCESS/FAILURE）、level、user、ip 精确过滤，以及 created_after、created_before 日期范围过滤
security-log-detail	GET	/api/v3/admin/security_logs/{id}/	获取单条日志详情
security-log-delete	DELETE	/api/v3/admin/security_logs/{id}/	删除单条日志（仅超级管理员；审计数据建议谨慎删除）（204）
security-log-export	GET	/api/v3/admin/security_logs/export/	按当前过滤条件导出 CSV（带 BOM 兼容 Excel），单次最多 10000 条；返回二进制文件流
security-log-statistics	GET	/api/v3/admin/security_logs/statistics/	Dashboard 概览：总数、成功/失败数、成功率、按级别分布、按类型分布（前 10）、最近失败列表；可传 `?days=N`
security-log-statistics-trend	GET	/api/v3/admin/security_logs/statistics/trend/	按天聚合最近 N 天（默认 7）日志数量并按成功/失败拆分，供折线图；可传 `?days=N`

level 枚举：INFO、LOW、MEDIUM、HIGH、CRITICAL；log_type 覆盖 LOGIN/LOGOUT/REGISTER/TOKEN/ACCESS、用户/设备/角色/权限/密钥/围栏/时间规则/服务器密钥各生命周期事件，以及 ERROR/WARNING/SYSTEM。日志由中间件自动记录写操作、认证路径与 4xx/5xx 响应，request_data 中 password/token/key 等敏感字段自动脱敏。

6.15 服务器密钥二维码接口

操作标识	方法	路径	功能与输入/输出要点
active-server-key-qrcode	GET	/api/v3/admin/server_keys/active_qrcode/	返回当前激活的 SM2 服务器密钥元数据与二维码字符串：id、server_id、algorithm（固定 SM2）、key_type（long_term/short_term）、public_key、timestamp、qrcode_string 等。二维码字符串格式 `server_id#timestamp#public_key`，前端可用 qrcode 库渲染为 PNG；私钥永不通过该接口暴露。无激活密钥时返回 404

6.16 设备侧 SM2 密钥协商接口

两个接口挂在非 admin 前缀下，权限 AllowAny（设备完成握手时尚未登录）；请求与响应均为 application/octet-stream 自定义二进制帧（64B 通信头 + 数据域），不再使用 JSON。

操作标识	方法	路径	功能与输入/输出要点
sm2-build-resp	POST	/api/v3/keymgr/sm2/build_resp/	四包密钥协商第二步：处理客户端 INIT 帧（总长约 280B），设备公钥由服务器按帧内设备标识 IDA 从设备公钥登记表解析，构建并返回 RESP 帧（约 162B）
sm2-build-token	POST	/api/v3/keymgr/sm2/build_token/	四包密钥协商第四步：处理客户端 ACK 帧（约 98B），会话由帧内 SA 匹配待确认会话定位（帧内自证、无需回传会话 ID），构建并返回 TOKEN 帧（约 146B）

成功帧主命令码为 0x00；任一环节失败返回 HTTP 200 + 下行报警帧（主命令码 0x01，报警码 0x8002/0x8003/0x8004）。协议细节见 SM2 密钥协商。

现网资料交叉引用

补全正式 Word 或现场答疑时，建议以以下经源码核对的页面作为扩展依据：

需求	参考页面
核对内部 REST 路径、参数与状态码（REST 视角）	REST API 参考
MCS 前端/网页如何调用登录与加解密	前端 JS SDK
业务后端验签、加解密的真实函数签名与现网码表	后端 Python SDK
第三方业务系统端到端接入步骤与验收清单	业务系统接入指南
四步握手协议与 64B 信封原理	SM2 密钥协商、传输加密机制
接口在总体技术方案中的定位	验收技术总结

使用提示

正式 Word 中若保留本章第二、三、五章的原始设计口径，建议在相应章节首页以脚注或页下注形式注明"本章码表为设计阶段口径，实现以交付 SDK 码表为准"，避免验收测试时出现码值核对不一致的问题。

接口设计详录 ​

一、接口总览 ​

二、外部接口 ​

三、后台公共服务接口 ​

3.1 后台 Token 校验接口：verify_token ​

3.2 后台明文数据封装接口：sm4_gcm_encrypt ​

3.3 后台密文数据解封装接口：sm4_gcm_decrypt ​

四、前端 JSBridge 接口 ​

4.0 统一错误码总表 ​

4.1 加密登录接口：login ​

4.2 获取访问令牌接口：getAccessToken ​

4.3 令牌刷新接口：refreshAccessToken ​

4.4 前端明文数据封装接口：sm4GcmEncrypt ​

4.5 前端密文数据解封装接口：sm4GcmDecrypt ​

4.6 退出登录接口：logout ​

五、配套函数库接口（水印嵌入提取 / 设备标识生成提取） ​

5.1 单张图片水印嵌入：watermark_embed ​

5.2 批量图片水印嵌入：batch_watermark_embed ​

5.3 单张图片水印提取：watermark_extract ​

5.4 设备标识生成接口：encrypt_device_id ​

5.5 设备 ID 提取接口：decrypt_device_id ​

六、内部 REST API ​

6.0 通用约定 ​

6.1 认证与验证码接口 ​

6.2 当前用户接口 ​

6.3 短信验证码接口 ​

6.4 用户管理接口（/api/v3/admin/users） ​

6.5 设备类型接口（/api/v3/admin/device_types） ​

6.6 设备管理接口（/api/v3/admin/devices） ​

6.7 角色管理接口（/api/v3/admin/roles） ​

6.8 用户-角色关联接口（/api/v3/admin/user_roles） ​

6.9 地理围栏接口（/api/v3/admin/geofences） ​

6.10 角色-围栏关联接口（/api/v3/admin/role_geofences） ​

6.11 时间规则接口（/api/v3/admin/time_rules） ​

6.12 角色-时间规则关联接口（/api/v3/admin/role_time_rules） ​

6.13 设备公钥接口（/api/v3/admin/device_public_keys） ​

6.14 安全日志接口（/api/v3/admin/security_logs） ​

6.15 服务器密钥二维码接口 ​

6.16 设备侧 SM2 密钥协商接口 ​

现网资料交叉引用 ​

接口设计详录

一、接口总览

二、外部接口

三、后台公共服务接口

3.1 后台 Token 校验接口：verify_token

3.2 后台明文数据封装接口：sm4_gcm_encrypt

3.3 后台密文数据解封装接口：sm4_gcm_decrypt

四、前端 JSBridge 接口

4.0 统一错误码总表

4.1 加密登录接口：login

4.2 获取访问令牌接口：getAccessToken

4.3 令牌刷新接口：refreshAccessToken

4.4 前端明文数据封装接口：sm4GcmEncrypt

4.5 前端密文数据解封装接口：sm4GcmDecrypt

4.6 退出登录接口：logout

五、配套函数库接口（水印嵌入提取 / 设备标识生成提取）

5.1 单张图片水印嵌入：watermark_embed

5.2 批量图片水印嵌入：batch_watermark_embed

5.3 单张图片水印提取：watermark_extract

5.4 设备标识生成接口：encrypt_device_id

5.5 设备 ID 提取接口：decrypt_device_id

六、内部 REST API

6.0 通用约定

6.1 认证与验证码接口

6.2 当前用户接口

6.3 短信验证码接口

6.4 用户管理接口（/api/v3/admin/users）

6.5 设备类型接口（/api/v3/admin/device_types）

6.6 设备管理接口（/api/v3/admin/devices）

6.7 角色管理接口（/api/v3/admin/roles）

6.8 用户-角色关联接口（/api/v3/admin/user_roles）

6.9 地理围栏接口（/api/v3/admin/geofences）

6.10 角色-围栏关联接口（/api/v3/admin/role_geofences）

6.11 时间规则接口（/api/v3/admin/time_rules）

6.12 角色-时间规则关联接口（/api/v3/admin/role_time_rules）

6.13 设备公钥接口（/api/v3/admin/device_public_keys）

6.14 安全日志接口（/api/v3/admin/security_logs）

6.15 服务器密钥二维码接口

6.16 设备侧 SM2 密钥协商接口

现网资料交叉引用