本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：7月5日复制的资料/项目档案.md。

SoSite 项目档案（会话快照）

最后更新：2026-07-01

一、项目架构

目录结构

/
├── index.php                      # 前端控制器（路由入口）
├── config.php                     # 数据库配置（当前仅 MySQL）
├── install.php                    # 安装向导（已清理 SQLite）
├── convert.php                    # 数据库转换工具（未使用，可删）
├── dbconvert.php                  # 独立数据库转换（保留参考）
├── .htaccess                      # URL 重写 + 安全目录隔离
├── app/
│   ├── init.php                   # 应用初始化
│   ├── Core/
│   │   ├── Autoloader.php         # PSR-4 自动加载
│   │   ├── Database.php           # 数据库连接（仅 MySQL + PDO）
│   │   ├── Model.php              # 基础模型
│   │   ├── Controller.php         # 基础控制器（view/json/redirect）
│   │   ├── Router.php             # 路由
│   │   ├── View.php               # 旧版视图引擎
│   │   └── TemplateCompiler.php   # 模板编译器（{{var}} 语法）
│   ├── Controllers/               # 控制器
│   │   └── Admin/                 # 后台控制器
│   ├── Models/                    # 模型
│   ├── Helpers/                   # 工具类
│   │   ├── Auth.php               # 用户认证
│   │   ├── Content.php            # HTML 净化 + base64 解码
│   │   ├── Csrf.php               # CSRF 保护
│   │   ├── Settings.php           # 站点设置缓存 + 运行时计数器
│   │   ├── Search.php             # 全文搜索（MySQL FULLTEXT）
│   │   ├── Vote.php               # 点赞/踩
│   │   ├── Points.php             # 积分/等级
│   │   ├── Tag.php                # 标签管理
│   │   ├── Upload.php             # 文件上传
│   │   ├── Theme.php              # 主题管理
│   │   ├── Captcha.php            # 验证码
│   │   ├── RateLimiter.php        # 频率限制
│   │   └── RememberMe.php         # 自动登录
│   └── Views/                     # 视图模板
│       └── admin/                 # 后台视图
├── assets/
│   ├── css/
│   │   ├── style.css              # 主样式
│   │   └── themes/                # 主题 CSS 文件
│   │       ├── xiuno2.css         # Xiuno2 经典蓝主题
│   │       └── ...
│   ├── js/
│   │   ├── editor.js              # 富文本编辑器
│   │   └── vote.js                # 投票 AJAX
│   ├── uploads/                   # 上传文件
│   └── themes/                    # 主题模板目录
│       └── xiuno2/templates/      # Xiuno2 模板文件
├── plugins/                       # 插件目录
│   ├── daily_checkin/             # 每日签到
│   ├── friend_links/              # 友情链接
│   ├── post_favorite/             # 帖子收藏
│   ├── qa/                        # 问答系统
│   └── dev_docs/                  # 开发文档
├── database/
│   ├── init.php                   # 数据库初始化（仅 MySQL）
│   └── schema.sql                 # MySQL 建表 SQL
└── protected/                     # 受保护数据目录
    ├── sessions/                  # Session 文件
    ├── backups/                   # 数据库备份
    └── .install_done              # 安装锁文件

数据库

• 仅 MySQL（已完成 SQLite 全面清理）
• Database.php 中 getDbType() 始终返回 'mysql'
• Database::query() 保留 INSERT OR IGNORE → INSERT IGNORE 等语意兼容（为插件代码兼容）
• schema.sql = 原名 schema_mysql.sql，schema_sqlite.sql 已删

主题系统

• CSS 文件放 assets/css/themes/xxx.css
• 模板文件放 assets/themes/xxx/templates/ 可覆盖 app/Views/
• 分组逻辑在 app/Helpers/Theme.php 的 $colorOnlyThemes 数组

插件系统

• Hook 机制：Plugin::hook('hook_name', $params) → 执行 plugins/xxx/hook/hook_name.php
• 插件启用/禁用：Plugin.php 的 activate() / deactivate()
• 缓存：plugins/plugins_cache.php

二、本会话已完成的工作

MySQL 兼容性修复

• Database.php → 重写为仅 MySQL
• Model.php → 移除 $dbType
• Settings.php → 全部 6 处 SQLite 分支清理
• Search.php → 移除 SQLite FTS 分支
• Vote.php → 移除 SQLite 分支
• database/init.php → 完整重写，零 SQLite 代码
• install.php → MySQL 专用安装向导
• schema_sqlite.sql → 已删除
• DbConvert.php → 已删除

转换工具（后台）

• DatabaseController.php → 增加 convert() 方法（使用 dbconvert.php 已有函数）
• app/Helpers/DbConvert.php → 已删除

Xiuno2 主题

• 完整主题 assets/themes/xiuno2/templates/ 覆盖全部前台页面
• 配色深蓝 #1f4977
• 已放入经典论坛风格分组（Theme.php）

其他功能

• 后台维护 → 清理孤儿附件（已修复误删头像）
• 插件 MySQL 兼容 → daily_checkin、friend_links、post_favorite、qa
• PostController.php → 发帖错误显示真实信息
• BlogController.php → strftime 改为 MySQL 兼容
• Setting.php → key 保留字加反引号
• Captcha.php → key 保留字加反引号
• Tag.php → INSERT OR IGNORE 改为 MySQL 兼容
• HomeController.php → 添加 threadVotes 传递（修复首页投票数显示 0）
• 收藏列表页 → 取消收藏 AJAX 化
• 后台主题设置 → xiuno2 放入经典组
• Controller::json() → 清理输出缓冲

三、已知待办

高优先级

1. 安装界面美化 — 进度条动画、建表/导入数据时实时条目滚动
2. install.php 步骤三表单样式 — 美化管理员创建表单

中优先级

1. dbconvert.php — 保留还是删除？保留的话建议挪到后台
2. convert.php — 已无用，可删除

低优先级

1. 标签云颜色/大小按频率分级（之前做了又恢复了）
2. 附件清理后的自动重建索引
3. 后台各页面移动端适配

四、技术决策备忘