logs

.gitignore

@@ -46,6 +46,7 @@ htmlcov/
 
 # Logs
 *.log
+*.log.*
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

PROJECT_WIKI.md

@@ -0,0 +1,180 @@
+# 统一认证平台 (UAP) 项目 Wiki
+
+## 1. 项目简介
+
+统一认证平台 (Unified Authentication Platform, UAP) 是一个企业级的身份管理系统，旨在解决多应用间的账号统一、认证标准化及新老系统融合问题。
+
+**核心能力：**
+- **多协议支持**：同时支持现代 OIDC (OpenID Connect) 协议和传统 API Ticket 认证。
+- **账号中心**：以手机号为核心标识，支持密码登录和短信验证码登录。
+- **账号映射**：解决老旧系统账号体系不一致问题，支持将统一手机号映射为特定系统的用户名、邮箱等。
+- **安全集成**：内置图形验证码、短信验证码、操作审计、Webhook 通知等安全机制。
+- **开箱即用**：提供完整的前后端界面和 Docker 容器化部署方案。
+
+---
+
+## 2. 技术栈
+
+### 后端 (Backend)
+- **核心框架**: [FastAPI](https://fastapi.tiangolo.com/) (Python 3.10+) - 高性能异步 Web 框架。
+- **数据库 ORM**: [SQLAlchemy](https://www.sqlalchemy.org/) (2.0+) - 强大的 ORM 工具。
+- **数据验证**: [Pydantic](https://docs.pydantic.dev/) (2.0+) - 数据解析与验证。
+- **认证引擎**: [Ory Hydra](https://www.ory.sh/hydra/) - 经过认证的 OAuth2/OIDC 服务器。
+- **缓存/消息**: Redis - 用于验证码存储、Session 管理和任务队列。
+- **验证码**: `captcha` + `Pillow` - 本地生成图形验证码。
+- **短信服务**: 阿里云 SMS (可扩展 Mock 模式)。
+- **任务调度**: FastAPI BackgroundTasks (轻量级异步任务)。
+- **数据处理**: Pandas - 用于 Excel 数据的导入导出处理。
+
+### 前端 (Frontend)
+- **核心框架**: [Vue 3](https://vuejs.org/) (Composition API)。
+- **语言**: TypeScript。
+- **构建工具**: [Vite](https://vitejs.dev/) - 极速开发环境。
+- **UI 组件库**: [Element Plus](https://element-plus.org/) - 企业级后台组件库。
+- **状态管理**: Pinia。
+- **网络请求**: Axios。
+
+### 基础设施 (Infrastructure)
+- **容器化**: Docker & Docker Compose。
+- **Web 服务器**: Nginx (反向代理与静态资源服务)。
+- **应用服务器**: Uvicorn (ASGI)。
+- **数据库**: MySQL 8.0。
+
+---
+
+## 3. 项目结构
+
+```text
+Unified_Authentication_Platform/
+├── backend/                  # 后端项目根目录
+│   ├── app/
+│   │   ├── api/              # API 路由定义
+│   │   │   └── v1/endpoints/ # 具体业务接口 (Apps, Auth, Users...)
+│   │   ├── core/             # 核心配置 (Config, Security, DB)
+│   │   ├── models/           # SQLAlchemy 数据库模型
+│   │   ├── schemas/          # Pydantic 数据模型 (Request/Response)
+│   │   ├── services/         # 业务逻辑层 (Service Layer)
+│   │   └── main.py           # FastAPI 应用入口
+│   ├── backups/              # 数据库备份目录
+│   ├── Dockerfile            # 后端镜像构建文件
+│   └── requirements.txt      # Python 依赖列表
+├── frontend/                 # 前端项目根目录
+│   ├── src/
+│   │   ├── api/              # API 请求封装
+│   │   ├── components/       # 公共组件
+│   │   ├── store/            # Pinia 状态管理
+│   │   ├── views/            # 页面视图 (Admin, Login, Apps...)
+│   │   └── main.ts           # Vue 入口文件
+│   ├── Dockerfile            # 前端镜像构建文件
+│   └── package.json          # Node.js 依赖列表
+├── docker-compose.yml        # 容器编排文件
+├── README.md                 # 项目主文档
+└── *.md                      # 其他说明文档
+```
+
+---
+
+## 4. 核心模块说明
+
+### 4.1 认证模块 (Auth)
+- **OIDC 集成**: 
+    - 集成 Ory Hydra，实现完整的 Authorization Code Flow。
+    - 提供自定义的 Login Provider (`/auth/login`) 和 Consent Provider (`/auth/consent`) 页面及接口。
+    - 支持 `openid`, `offline`, `profile` scopes。
+- **简易认证 (Simple Auth)**:
+    - 为不支持 OIDC 的老旧系统提供基于 Ticket 的认证机制。
+    - 流程：登录 -> 获取 Ticket -> 重定向 -> 验签换取用户信息。
+- **安全机制**:
+    - 图形验证码：防止暴力破解。
+    - 短信验证码：用于敏感操作（注册、重置密码）。
+    - 签名校验：开放 API (`/api/v1/open/*`) 强制要求 HMAC-SHA256 签名。
+
+### 4.2 应用管理 (Applications)
+- **应用注册**: 管理员可创建应用，分配 `App ID` 和 `App Secret`。
+- **账号映射**: 
+    - 定义应用特定的账号字段（如 `mapped_key`）。
+    - 支持 Excel 批量导入映射关系。
+    - 支持通过 Webhook 实时推送映射变更。
+
+### 4.3 运维管理
+- **日志审计**: 
+    - 登录日志 (`LoginLogs`)：记录所有登录尝试及结果。
+    - 操作日志 (`SystemLogs`)：记录管理员的关键操作。
+    - Webhook 日志：记录对下游系统的推送记录及响应。
+- **数据备份**: 支持数据库的备份与恢复功能。
+
+---
+
+## 5. 环境配置 (.env)
+
+项目配置主要通过环境变量管理。虽然开发环境有默认值，但生产环境建议通过 `.env` 文件覆盖：
+
+| 变量名 | 说明 | 默认值/示例 |
+| :--- | :--- | :--- |
+| `MYSQL_SERVER` | MySQL 地址 | `localhost` |
+| `MYSQL_USER` | MySQL 用户名 | `root` |
+| `MYSQL_PASSWORD` | MySQL 密码 | `secret` |
+| `MYSQL_DB` | 数据库名 | `uap_db` |
+| `REDIS_HOST` | Redis 地址 | `localhost` |
+| `SECRET_KEY` | JWT/加密密钥 | `change_me_...` |
+| `SMS_PROVIDER` | 短信服务商 | `aliyun` 或 `mock` |
+| `ALIYUN_ACCESS_KEY_ID` | 阿里云 AK | - |
+| `ALIYUN_ACCESS_KEY_SECRET` | 阿里云 SK | - |
+
+---
+
+## 6. 安装与运行
+
+### 6.1 容器化部署 (推荐)
+本项目支持一键启动：
+
+```bash
+# 构建并启动所有服务
+docker-compose up -d --build
+```
+
+启动后可访问：
+- **前端页面**: `http://localhost:5173` (开发) 或 `http://localhost` (Nginx)
+- **后端 API 文档**: `http://localhost:8000/docs`
+- **Ory Hydra**: `http://localhost:4444`
+
+### 6.2 本地开发运行
+
+**后端**:
+```bash
+cd backend
+# 创建虚拟环境
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+# 安装依赖
+pip install -r requirements.txt
+# 启动服务
+uvicorn app.main:app --reload
+```
+
+**前端**:
+```bash
+cd frontend
+# 安装依赖
+npm install
+# 启动开发服务器
+npm run dev
+```
+
+---
+
+## 7. 常见问题 (FAQ)
+
+- **Q: 默认管理员账号是什么？**
+  - A: 如果执行了初始化脚本，通常为手机号 `13800000001`，密码 `admin`。
+  
+- **Q: 验证码图片加载失败？**
+  - A: 检查 Redis 连接是否正常，以及字体文件是否存在（通常由 Pillow 自带）。
+
+- **Q: 短信发送失败？**
+  - A: 检查 `SMS_PROVIDER` 配置。开发环境可设置为 `mock`，验证码将直接打印在后端日志中。
+
+---
+
+_最后更新时间: 2026-01-09_
+