# LQAdminPlatform - OAuth2 单点登录认证中心

## 项目简介

LQAdminPlatform 是一个基于 FastAPI 的 OAuth2 单点登录认证中心，提供统一的用户认证、授权管理和样本中心功能。

## 功能模块

### 1. 系统管理
- 用户管理
- 角色管理
- 菜单管理
- 权限管理
- 系统日志
- 仪表盘
- 应用管理

### 2. 授权管理
- SSO 验证凭证
- 授权码生成与管理
- Access Token 管理
- 用户信息获取
- JWT Token 管理
- 子系统登录认证

### 3. 样本中心
- 知识库管理
- 文档管理
- 知识片段管理
- 标签管理
- 检索引擎
- 图片管理

## 环境准备

### 创建虚拟环境
```bash
# 使用 conda
conda create --name lq_oauth2 python=3.12
conda activate lq_oauth2

# 或使用 venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
```

### 安装依赖
```bash
pip install -r requirements/base.txt

# 开发环境额外依赖
pip install -r requirements/dev.txt
```

## 快速开始

### 1. 配置环境变量

复制 `.env.example` 到 `.env` 并配置：

```env
# 数据库配置
DATABASE_URL=mysql://user:password@localhost:3306/sso_db

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379

# 应用配置
APP_NAME=LQAdminPlatform
HOST=0.0.0.0
PORT=8000
DEBUG=True

# JWT配置
JWT_SECRET_KEY=your-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30
```

### 2. 初始化数据库

```bash
python scripts/init_db.py
```

### 3. 启动服务

#### 开发环境（推荐）
```bash
# 使用新的启动脚本（自动查找可用端口）
python run_server.py



#### 生产环境
```bash
# 使用 uvicorn
uvicorn app.server.app:app --host 0.0.0.0 --port 8000

# 使用 gunicorn（推荐）
gunicorn app.server.app:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

### 4. 访问服务

- **API 文档**: http://localhost:8000/docs
- **ReDoc 文档**: http://localhost:8000/redoc
- **健康检查**: http://localhost:8000/health

## 项目结构

```
LQAdminPlatform/
├── src/
│   ├── app/
│   │   ├── server/          # 服务器启动模块
│   │   ├── logger/          # 日志配置
│   │   ├── base/            # 基础连接（MySQL、Redis、Milvus）
│   │   ├── core/            # 核心模块（异常等）
│   │   ├── models/          # 数据模型
│   │   ├── schemas/         # 数据结构
│   │   ├── utils/           # 工具类
│   │   ├── config/          # 配置文件
│   │   ├── system/          # 系统管理模块
│   │   ├── oauth/           # 授权管理模块
│   │   └── sample/          # 样本中心模块
│   └── views/               # 视图路由
├── scripts/                 # 脚本文件
├── test/                    # 测试文件
├── requirements/            # 依赖文件
├── run_server.py           # 启动脚本（新）
└── full_server.py          # 启动脚本（旧，保留兼容）
```

详细的项目结构说明请查看 [REFACTOR_README.md](./REFACTOR_README.md)

## 授权中心

### 授权后台
```bash
cd LQAdminPlatform
python run_server.py
# 访问: http://localhost:8000/docs
```

### 授权前台
```bash
cd LQAdminFront
npm install 
npm run dev-local
# 访问: http://localhost:3000
# 默认账号: admin / Admin123456
```

## 授权子系统案例

### 子系统后台
```bash
cd subsystem-demo/backend
python main.py
# 访问: http://localhost:8001/docs
```

### 子系统前台
```bash
cd subsystem-demo/frontend
npm install 
npm run dev
# 访问: http://localhost:3001
```

### 子系统配置

在子系统中配置以下环境变量：

```env
CLIENT_ID=eqhoIdAyAWbA8MsYHsNqQqNLJbCayTjY
CLIENT_SECRET=LKJm5XHJFhhgxSv9nQhoQNNI3wrKyWGZCaPQ4qc43Lf5qfXdLAHoGAHhCYqApEpr
SSO_SERVER_URL=http://localhost:8000
```

## API 端点

### 系统管理
- `GET /api/v1/system/dashboard` - 仪表盘
- `GET /api/v1/system/users` - 用户列表
- `GET /api/v1/system/roles` - 角色列表
- `GET /api/v1/system/menus` - 菜单列表
- `GET /api/v1/system/logs` - 系统日志

### 授权管理
- `GET /api/v1/oauth/authorize` - OAuth2 授权
- `POST /api/v1/oauth/token` - 获取令牌
- `GET /api/v1/oauth/userinfo` - 用户信息
- `POST /api/v1/oauth/revoke` - 撤销令牌

### 样本中心
- `GET /api/v1/sample/knowledge-bases` - 知识库列表
- `GET /api/v1/sample/documents` - 文档列表
- `POST /api/v1/sample/documents` - 上传文档
- `POST /api/v1/sample/search` - 检索文档

## 开发指南

### 添加新功能

1. 在对应模块下创建 model（如需要）
2. 在对应模块下创建 schema
3. 在 views 目录下创建或更新视图路由
4. 在 server/app.py 中注册路由

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest test/test_auth.py

# 查看覆盖率
pytest --cov=app
```

### 代码规范

项目使用以下工具保证代码质量：

- **Black**: 代码格式化
- **isort**: 导入排序
- **flake8**: 代码检查
- **mypy**: 类型检查

```bash
# 格式化代码
black src/

# 排序导入
isort src/

# 检查代码
flake8 src/
```

## 部署

### Docker 部署

```bash
# 构建镜像
docker build -t lqadmin:latest .

# 运行容器
docker run -d -p 8000:8000 --env-file .env lqadmin:latest
```

### Docker Compose 部署

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

## 常见问题

### 1. 端口被占用

启动脚本会自动查找可用端口（8000-8010），或手动指定：

```bash
PORT=8001 python run_server.py
```

### 2. 数据库连接失败

检查 `.env` 文件中的 `DATABASE_URL` 配置是否正确。

### 3. Redis 连接失败

Redis 为可选组件，连接失败不会影响核心功能，但会影响缓存和会话管理。

## 更新日志

### v1.0.0 (2024-01-15)
- ✅ 完成项目结构重构
- ✅ 按功能模块划分（system、oauth、sample）
- ✅ 统一日志配置
- ✅ 统一数据库连接管理
- ✅ 新增模块化视图路由

详细更新日志请查看 [REFACTOR_README.md](./REFACTOR_README.md)

## 贡献指南

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 联系方式

如有问题，请联系开发团队。