AI-Chat/docs/ARCHITECTURE.md

架构说明

技术架构

本项目采用 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 根目录（Nginx 指向此目录）
│   ├── index.php            # 首页入口（自动路由到登录/安装页）
│   ├── api.php              # API 统一入口（路由分发）
│   ├── router.php           # PHP 内置开发服务器路由文件
│   ├── login.php            # 登录页面
│   ├── chat.php             # 聊天主页面
│   ├── config.php           # 配置管理页面
│   ├── install.php          # 安装向导页面
│   ├── assets/              # 前端静态资源
│   │   ├── css/             # 样式文件
│   │   │   ├── style.css    # 全局样式
│   │   │   ├── chat.css     # 聊天界面样式
│   │   │   └── markdown.css # Markdown 渲染样式
│   │   ├── js/              # JavaScript
│   │   │   ├── api.js       # API 调用封装
│   │   │   ├── chat.js      # 聊天核心功能
│   │   │   ├── config.js    # 配置页面逻辑
│   │   │   ├── install.js   # 安装向导逻辑
│   │   │   ├── login.js     # 登录页面逻辑
│   │   │   ├── session.js   # 会话管理
│   │   │   ├── upload.js    # 文件上传
│   │   │   ├── markdown.js  # Markdown 渲染
│   │   │   └── storage.js   # 本地存储
│   │   └── img/             # 图片
│   └── uploads/             # 用户上传文件
├── app/                     # 应用代码（命名空间 App\，PSR-4 自动加载）
│   ├── 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
├── config/                  # JSON 配置文件（安装后生成）
├── 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 加载数据