Unified_Authentication_Platform/frontend/public/ai-dev-guide.md

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 检查代码质量。