# Unified Authentication Platform - AI 开发指南

## 1. 项目概述
Unified Authentication Platform (UAP) 是一个统一认证平台，提供简易认证 (Simple Auth)、OIDC、SSO、账号同步等功能。

### 技术栈
- **Frontend**: Vue 3, TypeScript, Vite, Element Plus, Pinia, Axios.
- **Backend**: FastAPI (Python), SQLModel (SQLAlchemy + Pydantic), PostgreSQL.
- **Infrastructure**: Docker, Docker Compose.

### 项目结构
```
/backend
  /app
    /api/v1          # API 路由
    /core            # 核心配置 (Config, Security, DB)
    /models          # SQLModel 数据库模型
    /schemas         # Pydantic 数据验证模型
    /services        # 业务逻辑层
/frontend
  /src
    /api             # Axios API 封装
    /components      # Vue 组件
    /views           # 页面视图
    /store           # Pinia 状态管理
```

## 2. 接口开发规范 (API Convention)

### Base URL
- Base URL: `{{API_BASE_URL}}` (Backend)
- 生产环境: 根据部署域名配置

### 认证方式
1. **Bearer Token**: 用于管理后台 API。Header: `Authorization: Bearer <token>`
2. **Signature (签名)**: 用于 `Simple Auth` 业务 API。需使用 App ID 和 App Secret 计算签名。

---

## 3. 核心业务流程：简易认证 (Simple Auth)

### 3.1 签名算法
所有 `Simple Auth` 接口需校验签名。

**步骤**:
1. 收集所有参数（排除 `sign`）。
2. 按 Key 字母顺序排序。
3. 拼接成 `key1=val1&key2=val2...` 字符串。
4. 使用 `App Secret` 进行 HMAC-SHA256 计算。
5. 转换为 Hex 字符串。

### 3.2 关键接口

#### 登录 (Login)
- **POST** `/api/v1/simple/login`
- **Body**: `{ "app_id": "...", "identifier": "...", "password": "...", "timestamp": 123, "sign": "..." }`
- **Response**: `{ "ticket": "..." }`

#### 验证票据 (Validate)
- **POST** `/api/v1/simple/validate`
- **Body**: `{ "app_id": "...", "ticket": "...", "timestamp": 123, "sign": "..." }`
- **Response**: `{ "valid": true, "user_id": 1, ... }`

#### 免登跳转 (Exchange)
- **POST** `/api/v1/simple/exchange`
- **Body**: `{ "app_id": "...", "target_app_id": "...", "user_mobile": "...", ... }`
- **Response**: `{ "redirect_url": "http://target/callback?ticket=..." }`

---

## 4. 数据库模型概览

- **User**: 用户表 (`backend/app/models/user.py`) - `id`, `mobile`, `hashed_password`, `is_active`.
- **Application**: 应用表 (`backend/app/models/application.py`) - `id`, `app_id`, `app_secret`, `redirect_uris`.
- **UserMapping**: 用户-应用映射表 (`backend/app/models/mapping.py`) - `user_id`, `app_id`, `mapped_key`.
- **LoginLog**: 登录日志 (`backend/app/models/login_log.py`).

## 5. 开发建议
- 后端修改 Model 时，记得运行 `alembic` (如果配置了) 或检查数据库同步。
- 前端添加新 API 时，请在 `src/api` 下创建对应模块文件。
- 使用 `read_lints` 检查代码质量。