# Unified Authentication Platform (UAP)

统一认证平台 (Unified Authentication Platform) 是一个集成了 **OIDC 标准协议** 与 **简易 API 认证** 的身份管理系统。支持多应用接入、账号映射、手机号一键登录以及老旧系统平滑集成。

## 🌟 核心功能

- **多协议支持**: 同时支持 OIDC (Authorization Code Flow) 和简易 Ticket 认证，满足新老系统需求。
- **账号映射**: 支持将统一平台的手机号映射为下游业务系统的账号 (User ID / Username) 和邮箱，解决账号体系不通的问题。
- **统一管理**: 完整的后台管理界面，支持应用创建、密钥管理、映射导入导出 (Excel)。
- **安全可靠**: 
    - 简易模式采用 HMAC-SHA256 签名机制。
    - OIDC 模式基于经过实战检验的 Ory Hydra。
- **Webhook 通知**: 用户资料变更实时推送到下游业务系统。

## 🚀 快速启动 (Docker Compose)

本项目已完全容器化，只需一条命令即可启动所有服务（前端、后端、数据库、Redis、OIDC 服务）。

### 前置条件
- 安装 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/)。

### 启动命令
在项目根目录下运行：

```bash
docker-compose up -d --build
```

系统初始化可能需要 1-2 分钟（尤其是 MySQL 和 Hydra 首次运行）。
后端服务会自动等待数据库就绪后才启动。

### 访问地址

| 服务 | 地址 | 说明 |
| :--- | :--- | :--- |
| **前端页面** | http://localhost:5173 | 统一管理后台 & 登录页 (开发环境端口) |
| **后端 API** | http://localhost:8000/docs | Swagger UI 接口文档 |
| **Ory Hydra**| http://localhost:4444 | OIDC 公共端点 (Authorize/Token) |
| **MySQL** | localhost:3308 | 用户名: `uap_user` / 密码: `uap_pass` |

> 注意：如果使用 Nginx 部署，前端访问地址通常为 `http://localhost` (80端口)。

---

## 📖 接入指南

详细的接入文档请登录控制台查看 **"使用帮助"** 页面。

### 1. 注册与登录
1. 打开浏览器访问前端页面。
2. 首次使用请点击登录页的 **"立即注册"** 或通过 API 创建管理员账号。
3. 默认管理员账号 (如果通过脚本初始化): `13800000001` / `admin`

### 2. OIDC 标准协议 (推荐)
适用于现代 Web 应用。
- **Issuer**: `http://localhost:4444`
- **Scopes**: `openid`, `offline`, `profile`
- **用户信息**: ID Token 中包含 `phone_number`, `preferred_username` (映射账号), `email` (映射邮箱)。

### 3. 简易 API (Ticket)
适用于老旧系统或需要纯后端集成的场景。
- **流程**: 用户在平台登录 -> 重定向带 Ticket -> 业务后端验证 Ticket。
- **验证接口**: `POST /api/v1/simple/validate`
- **签名算法**: HMAC-SHA256

### 4. 统一登录接口 (Direct API)
允许第三方系统自行构建登录页面。
- **接口**: `POST /api/v1/simple/login`
- **参数**: `app_id`, `identifier` (手机/账号/邮箱), `password`
- **返回**: `ticket` (后续流程同 Ticket 模式)

### 5. 账号映射
支持 Excel 批量导入。
- **列头支持**: `手机号`, `映射账号`, `映射邮箱`
- **Excel 模板**: 可在管理后台直接下载。

---

## 🛠 开发环境
- **Backend**: FastAPI, SQLAlchemy, Uvicorn
- **Frontend**: Vue 3, TypeScript, Element Plus, Vite
- **Auth Engine**: Ory Hydra (OIDC Provider)
- **Database**: MySQL 8.0, Redis

如有代码变更，请重新构建：
```bash
docker-compose up -d --build
```