# 架构说明

## 技术架构

本项目采用 PHP 8.0 原生 MVC 架构，不使用任何 PHP 框架。

```
┌──────────────────────────────────────────────┐
│                  Nginx                        │
│         (Web 服务器 + 反向代理)                │
└──────────┬───────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────────────┐
│              public/                          │
│         (Web 根目录, 入口文件)                 │
│  api.php, login.php, chat.php, config.php    │
└──────────┬───────────────────────────────────┘
           │
     ┌─────┴─────┐
     │            │
     ▼            ▼
┌─────────┐  ┌──────────────────────────────┐
│ PHP 页面 │  │       API (api.php)          │
│ (视图)   │  │  路由分发 + 中间件处理         │
└────┬────┘  └──────┬───────────────────────┘
     │              │
     ▼              ▼
┌──────────────────────────────────────────────┐
│              Controllers                      │
│    AuthController, ChatController,           │
│    SessionController, MessageController,     │
│    ConfigController, InstallController,      │
│    UploadController                          │
└──────────┬───────────────────────────────────┘
           │
     ┌─────┼─────────────┐
     │     │             │
     ▼     ▼             ▼
┌───────┐ ┌───────┐ ┌──────────────────────┐
│Models │ │Services│ │   Middleware         │
│(数据) │ │(业务)  │ │ Auth/Admin           │
└───┬───┘ └───┬───┘ └──────────────────────┘
    │         │
    ▼         ▼
┌────────┐ ┌─────────────────┐
│ MySQL  │ │ AI Providers     │
│(PDO)   │ │ OpenAI/Claude/   │
│        │ │ NewAPI           │
└────────┘ └─────────────────┘
```

## 目录结构

```
ai-chat/
├── public/                  # Web 根目录
│   ├── api.php              # API 统一入口（路由分发）
│   ├── login.php            # 登录页面
│   ├── chat.php             # 聊天主页面
│   ├── config.php           # 配置管理页面
│   └── install.php          # 安装向导页面
├── app/                     # 应用代码（命名空间 App\）
│   ├── Config/              # 配置类
│   │   ├── Database.php     # 数据库连接（单例 PDO）
│   │   └── AppConfig.php    # 应用配置读写
│   ├── Controllers/         # 控制器
│   │   ├── AuthController.php
│   │   ├── ChatController.php
│   │   ├── SessionController.php
│   │   ├── MessageController.php
│   │   ├── ConfigController.php
│   │   ├── InstallController.php
│   │   └── UploadController.php
│   ├── Middleware/           # 中间件
│   │   ├── AuthMiddleware.php   # JWT 认证
│   │   └── AdminMiddleware.php  # 管理员权限
│   ├── Models/              # 数据模型
│   │   ├── User.php
│   │   ├── Session.php
│   │   ├── Message.php
│   │   ├── Config.php
│   │   └── Personality.php
│   ├── Services/            # 服务层
│   │   ├── AIService.php    # AI 服务路由
│   │   ├── Installer.php    # 安装迁移服务
│   │   └── Providers/       # AI 供应商
│   │       ├── OpenAIProvider.php
│   │       ├── ClaudeProvider.php
│   │       └── NewAPIProvider.php
│   └── Views/               # 视图模板
│       ├── login.php
│       ├── chat.php
│       ├── config.php
│       └── layout/
│           ├── header.php
│           └── footer.php
├── assets/                  # 前端静态资源
│   ├── css/                 # 样式
│   │   ├── style.css        # 全局样式
│   │   ├── chat.css         # 聊天界面样式
│   │   └── markdown.css     # Markdown 渲染样式
│   ├── js/                  # JavaScript
│   │   ├── api.js           # API 调用封装
│   │   ├── chat.js          # 聊天核心功能
│   │   ├── session.js       # 会话管理
│   │   ├── upload.js        # 文件上传
│   │   ├── markdown.js      # Markdown 渲染
│   │   └── storage.js       # 本地存储
│   └── img/                 # 图片
├── config/                  # JSON 配置文件
├── uploads/                 # 用户上传文件
├── docs/                    # 文档
└── composer.json            # Composer 配置
```

## 请求流程

### API 请求流程
1. 客户端发送 HTTP 请求到 `/api/*`
2. Nginx 将请求转发到 `public/api.php`
3. api.php 解析路由，执行对应的中间件和控制器
4. 控制器调用模型/服务层处理业务逻辑
5. 返回 JSON 响应

### SSE 流式响应流程
1. 客户端发送 POST 请求到 `/api/chat/completions`
2. ChatController 设置 SSE 响应头
3. AIService 通过 cURL 连接 AI 供应商 API
4. 使用 CURLOPT_WRITEFUNCTION 回调逐块接收 AI 响应
5. 每块数据通过 SSE 格式发送给客户端
6. AI 响应完成后发送 `[DONE]` 信号

### 页面请求流程
1. 客户端访问 PHP 页面（如 `/chat.php`）
2. Nginx 通过 PHP-FPM 执行 PHP 文件
3. PHP 文件引入布局模板和视图
4. 客户端通过 AJAX 加载数据