Metadata-Version: 2.4
Name: ErisPulse-UniBind
Version: 1.0.0
Summary: 跨平台用户身份绑定模块，通过验证码关联不同平台的同一用户
Author-email: wsu2059q <wsu2059@qq.com>
License: MIT
Project-URL: homepage, https://github.com/ErisPulse/ErisPulse-UniBind
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# UniBind - 跨平台用户身份绑定

UniBind 是一个基于 ErisPulse 框架的跨平台用户身份绑定模块，通过验证码将不同平台的同一用户关联到统一身份，并可选通过适配器中间件对下游模块透明地替换事件中的用户身份。

## 功能特性

- **统一身份管理**：跨平台用户身份绑定，一个身份关联多个平台账号
- **验证码机制**：6位数字验证码，5分钟有效，安全可靠
- **强制替换**：适配器中间件级事件改写，对下游模块完全透明
- **自定义显示身份**：每个绑定可独立指定替换后的平台和用户ID
- **扩展字段**：通过 `extra` JSON 存储自定义用户属性
- **对外 API**：提供完整的编程接口供其他模块调用

## 安装

```bash
epsdk install UniBind
```

## 配置

在 `config.toml` 中可自定义以下配置（均有默认值，无需手动添加）：

```toml
[UniBind]
verify_code_expire = 300     # 验证码有效期（秒）
verify_code_length = 6       # 验证码长度
max_accounts_per_user = 10   # 每个统一用户最大绑定账号数
```

## 使用方法

### 创建身份

在任意平台发送：

```
/bind
```

自动创建统一身份并生成验证码，返回验证码用于在其他平台绑定。

### 跨平台绑定

在另一个平台发送：

```
/bind 384729
```

输入验证码后选择显示身份，完成绑定。

### 查看绑定信息

```
/bind.info
```

### 列出所有绑定账号

```
/bind.accounts
```

### 设置扩展字段

```
/bind.set name 新名称
/bind.set email user@example.com
```

### 强制替换

开启后，中间件会将事件中的用户身份替换为指定的显示身份，对下游模块透明：

```
/bind.force
```

选择显示身份后开启。再次发送可关闭。

### 解绑

```
/bind.unbind
```

解绑当前平台账号。如果是最后一个绑定，统一身份将被删除。

## 命令列表

| 命令 | 说明 |
|------|------|
| `/bind` | 创建身份或生成验证码（已绑定时显示信息） |
| `/bind <验证码>` | 通过验证码绑定到已有身份 |
| `/bind.info` | 查看当前绑定信息 |
| `/bind.accounts` | 列出统一身份下所有平台账号 |
| `/bind.set <key> <value>` | 设置扩展字段 |
| `/bind.force` | 开启/关闭强制替换 |
| `/bind.unbind` | 解绑当前平台账号 |

## 强制替换（中间件）

当用户通过 `/bind.force` 开启强制替换后，适配器中间件会自动改写事件数据：

```
原始事件 (telegram, tg456) → 强制替换为 (yunhu, U1001)

改写后事件:
  platform: "yunhu"
  user_id: "U1001"
  unibind_original: { platform: "telegram", user_id: "tg456" }
```

下游模块无需感知 UniBind 的存在，直接使用改写后的身份即可。

## 对外 API

其他模块可通过 `sdk.UniBind` 访问以下接口：

```python
# 通过平台账号解析统一身份
aid = sdk.UniBind.resolve("yunhu", "U1001")      # → "uuid-xxx" 或 None

# 获取统一用户信息
user = sdk.UniBind.get_user("uuid-xxx")            # → {"aid", "name", "avatar", "extra", ...}

# 获取所有绑定账号
accounts = sdk.UniBind.get_accounts("uuid-xxx")    # → [{"platform", "user_id", "name", ...}, ...]

# 获取扩展字段
extra = sdk.UniBind.get_extra("uuid-xxx")          # → {"email": "...", ...}

# 批量查询
mapping = sdk.UniBind.resolve_batch([
    ("yunhu", "U1001"),
    ("telegram", "tg456"),
])
# → {"yunhu:U1001": "uuid-xxx", "telegram:tg456": "uuid-xxx"}

# 检查是否开启强制替换
is_force = sdk.UniBind.is_force_enabled("yunhu", "U1001")

# 获取替换后的显示身份
display = sdk.UniBind.get_display_identity("yunhu", "U1001")
# → {"platform": "yunhu", "user_id": "U1001"} 或 None
```

## 项目结构

```
ErisPulse-UniBind/
├── pyproject.toml
├── README.md
├── LICENSE
└── ErisPulse_UniBind/
    ├── __init__.py
    └── Core.py
```

## 许可证

MIT License
