本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：备忘md/SOSITE_开发全记录.md。

SoSite V3.0.0 开发全记录

生成日期：2026-06-21

对话轮次：700+ 轮

用途：新任务启动时的上下文参考

一、项目概况

SoSite V3.0.0 是一个自研 MVC 架构的论坛 + 博客系统，从零开始构建，非现有框架改造。

核心技术栈

目录结构要点

app/
  Controllers/     — 控制器
  Core/            — 核心（Router、Controller、Database、TemplateCompiler）
  Helpers/         — 辅助类（Settings、Auth、Theme、RememberMe、Content、Upload）
  Models/          — 数据模型
  Views/           — 视图模板
    admin/         — 后台管理视图
    home/          — 首页视图
    theme/         — 风格设置视图
    layouts/       — 主布局
assets/
  css/             — 样式文件
    themes/        — 各主题样式
  themes/          — 主题包目录
protected/         — 缓存文件（settings_cache.php 等）
index.php          — 入口文件（含路由注册）

二、已完成的核心功能

2.1 论坛系统

• [x] 板块分类（无限层级）
• [x] 发帖/回帖
• [x] 帖子编辑/删除
• [x] 帖子置顶/精华
• [x] 赞踩投票
• [x] 帖子附件上传
• [x] 帖子浏览量统计

2.2 博客系统

• [x] 博客文章 CRUD
• [x] 博客分类
• [x] 博客封面图
• [x] 博客浏览量统计

2.3 用户系统

• [x] 用户注册/登录/退出
• [x] 记住登录（RememberMe — SHA256 Token + DB 比对）
• [x] 用户个人资料
• [x] 用户头像（URL 方式）
• [x] 短消息系统
• [x] 积分/等级系统

2.4 搜索系统

• [x] 全站关键词搜索
• [x] 标签搜索（标签云）

2.5 后台管理

• [x] 控制台 — 统计卡片（用户数/在线/主题/回复）+ 最新用户/帖子
• [x] 站点设置 — 站点名称/描述/公告、分页设置、注册开关、附件开关
• [x] 分类管理 — CRUD
• [x] 用户管理 — 列表/编辑/删除
• [x] 短消息管理
• [x] 主题管理 — 列表/预览/设为默认/上传 ZIP/删除/自定义 CSS 面板
• [x] 标签管理
• [x] 积分规则管理
• [x] 附件管理
• [x] 数据维护

2.6 前端特性

• [x] 响应式布局（PC + 移动端）
• [x] 多主题系统（30+ 主题，含 Discuz5/phpBB/IPB 等经典论坛风格）
• [x] 主题预览切换
• [x] 用户自定义主题设置
• [x] 公告栏（后台可配置）
• [x] 标签云
• [x] 在线用户统计

2.7 安全特性

• [x] CSRF Token 验证
• [x] 参数化 SQL 查询
• [x] XSS 输出转义（htmlspecialchars）
• [x] Cookie Secure/HttpOnly/SameSite
• [x] 密码哈希存储
• [x] RememberMe Token 安全验证

三、重大架构决策

3.1 模板编译器取代原生 PHP 模板

• 语法：{$var}、{if}/{else}/{/if}、{loop}、{include}、{extend}、{section}/{yield}
• 编译为 PHP 缓存，提高性能
• 与 Blade 风格类似

3.2 主题系统设计

• 主题包位于 assets/themes/<主题名>/
• 元数据支持两种格式：config.json 和 style.css 头部注释
• 主题模板目录可覆盖 app/Views/ 中的文件
• 配色主题共享模板文件（仅 CSS 不同）
• 预览机制：?preview_theme=xxx
• 优先级：用户选择 > 后台默认

3.3 设置缓存

• Settings::buildCache() 将 settings 表全部键值对导出为 PHP 文件
• 原子写入（.tmp + rename）防止并发损坏
• 减少数据库查询

3.4 插件系统（规划中未实现）

• Hook 埋点：content_filter、sidebar_right、nav_links_append 等 10 个点位
• PHP 类插件（一个目录 + Plugin.php + manifest.json）
• PluginManager 管理生命周期

四、CSS 架构

加载顺序（主布局 app/Views/layouts/main.php）

1. style.css        — 基础核心（变量、重置、工具类、公共组件）
2. layout.css       — 布局（导航栏、侧边栏、页脚、响应式）
3. forum.css        — 论坛专有样式
4. pages.css        — 其他页面样式
5. components.css   — 通用组件（flex、间距、字体、按钮、卡片、表单）
6. themes/common.css— 主题公共装饰
7. themes/<主题>.css— 当前主题配色
8. admin.css        — 后台管理样式
9. editor.css       — 编辑器样式

关键 CSS 类

五、关键 Bug 修复记录

5.1 记住登录功能

• 问题：用户反馈"记住登录"无效
• 排查路径：RememberMe::check() → setRememberCookie() → SHA256 token 比对 → Session 写入
• 结论：逻辑完整，功能正常，用户记错

5.2 dz5 模板布局重构

• 反复修改 5+ 次：

1. 导航栏用户信息移到副导航 → 导航栏空了
2. 副导航改为两行 → 用户要原来的欢迎语格式
3. 副导航只显示站点描述 → 忽略欢迎语
4. 欢迎语被改成站点描述 → 用户纠正
5. header 站点名称被误删 → 用户指正恢复

• 最终方案：导航栏只有链接，副导航左（欢迎语）+ 右（用户操作）

5.3 模板内嵌 CSS

• 问题：在模板中用 <style> 标签写 CSS
• 用户批评："模板里面不要有css代码，你这样犯大忌了"
• 修复：所有 <style> 移入 assets/css/style.css

5.4 PHP 语法错误

• 问题：<?php $this->section('content'); ?> 和 <?php $announcement = ... ?> 错误合并为一行
• 自行修正：未反馈

5.5 主题优先级

• 问题：后台设置默认主题后，游客/默认用户看不到效果
• 修复：Theme::getCurrent() 中空 Cookie 跳过逻辑 $_COOKIE['site_theme'] !== ''

5.6 后台 Checkbox 对齐

• 问题：后台站点设置中的"允许注册"/"允许附件" checkbox 和文字不在同一行
• 根因：.admin-content .form-group input 设置了 width: 100% 覆盖了 checkbox
• 修复：input:not([type="checkbox"]) 排除 checkbox + label 用 flex 对齐

5.7 mobile content-card padding

• 问题：移动端 content-card 内容被挤压
• 调整过程：20px → 12px → 6px（首页/论坛/博客），风格页面独立 14px

六、新增文件清单（按时间顺序）

控制层

视图层

辅助层

样式

文档

七、修改过的文件清单（完整）

标注 [已恢复] 的表示后来用备份还原了

入口/路由

控制器

视图

dz5 模板

CSS

缓存

八、当前已知问题/未完成

功能缺失（对照 FluxBB）

高优先级：

1. [ ] 快速回复 — 主题底部直接回复框
2. [ ] 帖子浏览量 — 主题表加字段自增
3. [ ] 用户组系统 — 多角色、权限控制
4. [ ] 板块版主 — 指定特定用户为版主
5. [ ] 封禁系统 — 按用户名/邮箱/IP 封禁
6. [ ] 帖子移动/合并 — 版主挪帖到其他板块
7. [ ] 标记全部已读
8. [ ] 在线用户详细列表 — 显示具体名单

中优先级：

1. [ ] 邮箱验证注册
2. [ ] 密码找回/重置
3. [ ] 主题/板块订阅（邮件通知）
4. [ ] RSS/Atom 订阅
5. [ ] 词语过滤（敏感词替换）
6. [ ] 举报帖子
7. [ ] 搜索增强（作者搜索、未回复、新帖）

低优先级：

1. [ ] 板块排序
2. [ ] 分类排序
3. [ ] 时区设置
4. [ ] GZip 压缩
5. [ ] SMTP 配置
6. [ ] 多语言支持
7. [ ] 头像上传

存在的 Bug

• 无已知严重 Bug（所有已发现 Bug 已修复）

九、参考资源

• FluxBB 代码位置：D:\phpstudy_pro\WWW\fluxbb\
• FluxBB 功能对比报告：D:\phpstudy_pro\WWW\fluxbb_vs_sosite_功能对比报告.md
• CI4 框架分析报告：此前已生成
• 插件系统规划报告：此前已生成

十、本次开发记录截止点

• 最后完成的工作：后台服务器信息区块（因性能问题已还原）
• 最后讨论的话题：权限系统改进建议（方案一/二/三）
• 未开始的任务：权限系统改造（待讨论确定方案后开始）