初始化仓库及v1.0.0提交

2026-05-05 03:21:58 +08:00
commit 813bb02672
67 changed files with 5263 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,138 @@
+# 架构说明
+
+## 技术架构
+
+本项目采用 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 加载数据