1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
//! Copyright (c) 2026 Kirky.X. All rights reserved.
//! See LICENSE for full license text.
//! 社交登录协议插件模块。
//!
//! 提供 `SocialLoginProvider` trait 抽象社交登录第三方平台(微信/支付宝),
//! 统一 `get_authorization_url` / `exchange_token` / `get_user_info` 三个 OAuth2 流程方法。
//!
//! ## 子模块
//!
//! - `wechat`:微信扫码登录(`WechatProvider`,需 `social-wechat` feature)
//! - `alipay`:支付宝授权登录(`AlipayProvider`,需 `social-alipay` feature)
//!
//! ## 与 OAuth2 模块的关系
//!
//! `protocol::oauth2` 提供通用 OAuth2 客户端(Authorization Code / Client Credentials / Password),
//! 本模块针对社交平台特化(微信/支付宝的自定义 API 签名、用户信息格式)。
use crateGarrisonResult;
use async_trait;
use Value;
// ============================================================================
// SocialProvider enum:社交平台标识
// ============================================================================
/// 社交登录平台标识。
///
/// 用于 `SocialUserInfo.provider` 字段标识用户来源平台。
// ============================================================================
// SocialUserInfo:社交用户信息
// ============================================================================
/// 社交用户信息。
///
/// `exchange_token` / `get_user_info` 方法的返回类型,承载第三方平台返回的用户字段。
// ============================================================================
// 子模块声明
// ============================================================================
/// 微信扫码登录 provider。
///
/// 启用 `social-wechat` feature 时编译。
/// 支付宝授权登录 provider。
///
/// 启用 `social-alipay` feature 时编译。
// ============================================================================
// SocialBindingService(feature = "db-sqlite")
// ============================================================================
/// 社交账号绑定服务。
///
/// 提供 `find_or_create` 语义:首次社交登录时自动创建绑定关系并生成新 `login_id`,
/// 后续登录返回已有 `login_id`(幂等)。
///
/// # 设计决策(Decision Matrix 方案 A)
///
/// struct 同时持有:
/// - `pool: DbPool`:执行 SQL 查询/插入(`social_bindings` 表)
/// - `dao: Arc<dyn GarrisonDao>`:缓存层抽象(保留扩展点,当前未使用)
///
/// 与 `RoleHierarchyService` 模式一致:GarrisonDao 是 KV 缓存抽象,
/// 不支持 SQL SELECT/INSERT,故 `find_or_create` 实际用 `pool` 查 SQL。
/// `GarrisonDao` trait 的 `find_social_binding` / `insert_social_binding`
/// 默认方法返回 `NotImplemented`,仅为满足 spec trait 契约。
///
/// # 表结构
///
/// ```sql
/// CREATE TABLE social_bindings (
/// id INTEGER PRIMARY KEY AUTOINCREMENT,
/// tenant_id INTEGER NOT NULL DEFAULT 0,
/// login_id INTEGER NOT NULL,
/// provider TEXT NOT NULL,
/// provider_user_id TEXT NOT NULL,
/// union_id TEXT,
/// created_at INTEGER NOT NULL,
/// UNIQUE(tenant_id, provider, provider_user_id)
/// );
/// ```
///
/// `UNIQUE(tenant_id, provider, provider_user_id)` 保证同一租户下同一社交账号仅绑定一个 login_id。
/// `SocialBindingService` 实现模块(feature = "db-sqlite")。
///
/// 从 `mod.rs` 迁移以符合规则 25(mod.rs 接口隔离):
/// impl 块与顶层 `fn provider_to_str` 不允许留在 `mod.rs`。
pub
// ============================================================================
// SocialLoginProvider trait:社交登录抽象
// ============================================================================
/// 社交登录服务提供方 trait。
///
/// 定义三个异步方法覆盖 OAuth2 授权码流程:
/// - `get_authorization_url`:拼接授权页 URL(用户跳转到第三方平台授权)
/// - `exchange_token`:用授权码换取 access_token + provider_user_id(仅完成 code → access_token 一步,nickname/avatar 为 None,调用方需再调 `get_user_info`)
/// - `get_user_info`:用 access_token 获取用户信息(用于已缓存 token 的场景)
///
/// # 实现
///
/// - `WechatProvider`(`social-wechat` feature)
/// - `AlipayProvider`(`social-alipay` feature)