openlark_security/
lib.rs

1//! OpenLark 安全服务模块
2//!
3//! 提供飞书开放平台的完整安全服务，包括访问控制(ACS)和安全合规管理。
4//!
5//! ## 架构设计
6//!
7//! 采用 Project-Version-Resource (PVR) 三层架构：
8//!
9//! ```text
10//! openlark-security/src/
11//! ├── models/           # 共享数据模型
12//! ├── acs/              # 访问控制系统 (Project)
13//! │   └── v1/          # API版本v1 (Version)
14//! └── security_and_compliance/  # 安全合规管理 (Project)
15//!     ├── v1/          # API版本v1 (Version) - 审计日志
16//!     └── v2/          # API版本v2 (Version) - 设备记录管理
17//! ```
18//!
19//! ## 快速开始
20//!
21//! ```rust,no_run
22//! use openlark_security::prelude::*;
23//!
24//! #[tokio::main]
25//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
26//!     let config = SecurityConfig::new("app_id", "app_secret");
27//!     let security = SecurityServices::new(config);
28//!
29//!     // 获取门禁用户列表
30//!     let users = security.acs.v1().users().list()
31//!         .page_size(20)
32//!         .send()
33//!         .await?;
34//!
35//!     println!("用户数量: {}", users.users.len());
36//!     Ok(())
37//! }
38//! ```
39//!
40//! ## API覆盖
41//!
42//! ### acs (v1) - 访问控制系统
43//! #### 用户管理 (user)
44//! - `users.get()` - 获取单个用户信息
45//! - `users.list()` - 获取用户列表
46//! - `users.patch()` - 修改用户部分信息
47//!
48//! #### 人脸识别 (user.face)
49//! - `user_faces.get()` - 下载人脸图片
50//! - `user_faces.update()` - 上传人脸图片
51//!
52//! #### 权限规则 (rule_external)
53//! - `rule_external.create()` - 创建或更新权限组
54//! - `rule_external.get()` - 获取权限组信息
55//! - `rule_external.delete()` - 删除权限组
56//! - `rule_external.device_bind()` - 设备绑定权限组
57//!
58//! #### 访客管理 (visitor)
59//! - `visitors.create()` - 添加访客
60//! - `visitors.delete()` - 删除访客
61//!
62//! #### 设备管理 (device)
63//! - `devices.list()` - 获取门禁设备列表
64//!
65//! ### security_and_compliance (v2/v1) - 安全合规管理
66//! #### 设备记录管理 (device_record - v2)
67//! - `device_records.mine()` - 获取客户端设备认证信息
68//! - `device_records.create()` - 新增设备
69//! - `device_records.list()` - 查询设备信息
70//! - `device_records.get()` - 获取设备信息
71//! - `device_records.update()` - 更新设备
72//! - `device_records.delete()` - 删除设备
73//!
74//! #### 设备申报审批 (device_apply_record - v2)
75//! - `device_apply_records.approve()` - 审批设备申报
76//!
77//! #### 审计日志管理 (openapi_log - v1)
78//! - `openapi_logs.list_data()` - 获取OpenAPI审计日志数据
79
80#![deny(missing_docs)]
81#![warn(clippy::all)]
82#![warn(missing_copy_implementations)]
83#![warn(missing_debug_implementations)]
84
85// 错误处理模块
86pub mod error;
87
88// 共享数据模型
89pub mod models;
90
91// Project: acs - 访问控制系统
92pub mod security;
93
94// 重新导出主要类型
95pub use security::acs::{AcsProject, AcsV1Service};
96pub use security::security_and_compliance::{
97    SecurityAndComplianceProject, SecurityAndComplianceV1Service, SecurityAndComplianceV2Service,
98};
99
100// 重新导出错误类型
101pub use crate::error::SecurityError;
102
103/// 安全服务统一入口
104#[derive(Debug)]
105pub struct SecurityServices {
106    /// 安全配置
107    pub config: std::sync::Arc<crate::models::SecurityConfig>,
108    /// ACS门禁控制项目
109    pub acs: AcsProject,
110    /// 安全合规项目
111    pub security_and_compliance: SecurityAndComplianceProject,
112}
113
114impl SecurityServices {
115    /// 创建新的安全服务实例
116    pub fn new(config: crate::models::SecurityConfig) -> Self {
117        let config = std::sync::Arc::new(config);
118
119        Self {
120            acs: AcsProject::new(config.clone()),
121            security_and_compliance: SecurityAndComplianceProject::new(config.clone()),
122            config,
123        }
124    }
125
126    /// 获取配置信息
127    pub fn config(&self) -> &crate::models::SecurityConfig {
128        &self.config
129    }
130}
131
132/// 安全服务客户端 — Arc 包装的 [`SecurityServices`]，支持零成本克隆。
133///
134/// 用法：`client.security.acs...`
135#[derive(Debug, Clone)]
136pub struct SecurityClient {
137    inner: std::sync::Arc<SecurityServices>,
138}
139
140impl SecurityClient {
141    /// 从安全配置创建客户端实例。
142    pub fn new(config: crate::models::SecurityConfig) -> Self {
143        Self {
144            inner: std::sync::Arc::new(SecurityServices::new(config)),
145        }
146    }
147}
148
149impl std::ops::Deref for SecurityClient {
150    type Target = SecurityServices;
151
152    fn deref(&self) -> &Self::Target {
153        &self.inner
154    }
155}
156
157impl Default for SecurityServices {
158    fn default() -> Self {
159        Self::new(crate::models::SecurityConfig::default())
160    }
161}
162
163/// 结果类型别名
164pub type SecurityResult<T> = Result<T, crate::error::SecurityError>;
165
166/// 预导出模块
167pub mod prelude {
168    pub use super::{
169        AcsProject, SecurityAndComplianceProject, SecurityClient, SecurityResult, SecurityServices,
170    };
171
172    // 避免v1命名空间冲突，明确导出需要的类型
173    pub use super::models::*;
174    pub use super::security::acs::{AcsProject as Acs, AcsV1Service};
175    pub use super::security::security_and_compliance::{
176        SecurityAndComplianceV1Service, SecurityAndComplianceV2Service,
177    };
178}
179
180#[cfg(test)]
181mod tests {
182
183    #[test]
184    fn test_serialization_roundtrip() {
185        // 基础序列化测试
186        let json = r#"{"test": "value"}"#;
187        assert!(serde_json::from_str::<serde_json::Value>(json).is_ok());
188    }
189
190    #[test]
191    fn test_deserialization_from_json() {
192        // 基础反序列化测试
193        let json = r#"{"field": "data"}"#;
194        let value: serde_json::Value = serde_json::from_str(json).expect("JSON 反序列化失败");
195        assert_eq!(value["field"], "data");
196    }
197}
openlark_security/lib.rs

openlark_security/
lib.rs
