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

SoSite V3.5 — 完整会话总结

生成日期：2026-06-26

目的：用于开启新对话时快速恢复上下文

一、项目概览

SoSite — 自研轻量 PHP 社区系统（类似简化版 Discuz!），默认 SQLite 数据库，支持 MySQL。

• 版本：V3.5.0
• 根目录：D:\phpstudy_pro\WWW\
• 架构：自制轻量 MVC 框架（非 Composer，纯手写 Autoloader）
• 索引页：index.php → app/init.php → Router 分发
• 启动文件：config.php（Session 配置、数据库路径、常量）
• 数据库文件：protected/forum.db（SQLite，另含备份）

二、核心架构

目录结构（关键部分）

WWW/
├── index.php                    # 前端控制器（路由分发）
├── config.php                   # 全局配置（Session/DB/常量）
├── .htaccess / web.config       # URL 重写
├── app/
│   ├── init.php                 # 应用初始化（autoloader→config→session→view→plugin）
│   ├── Core/
│   │   ├── Autoloader.php       # PSR-4 风格自动加载
│   │   ├── Router.php           # 路由引擎（支持 {param} 占位符）
│   │   ├── Controller.php       # 基础控制器
│   │   ├── Model.php            # 基础模型
│   │   ├── Database.php         # PDO 封装（SQLite/MySQL）
│   │   └── View.php / TemplateCompiler.php  # 模板引擎
│   ├── Controllers/             # 控制器
│   │   ├── Admin/               # 后台控制器（~15个）
│   │   └── *Controller.php      # 前台控制器（~13个）
│   ├── Helpers/                 # 辅助类（~13个）
│   ├── Models/                  # 模型（~17个）
│   └── Views/                   # 视图（~45个）
├── assets/                      # 静态资源（CSS/JS/图片/上传）
├── plugins/                     # 插件目录
├── protected/                   # 保护目录（DB/缓存/Session）
├── plug/                        # 插件在线生成器（独立子程序）
├── docs/                        # 离线文档（17个HTML页面）
└── sositeV3.5/                  # 发布包目录

插件系统

• 设计："钩子即文件"（借鉴 XiunoBBS）
• 核心文件：app/Helpers/Plugin.php
• 共 17 个钩子点：init_after, route_register, admin_route_register, route_before_dispatch, route_after_dispatch, auth_login_after, auth_register_after, thread_create_after, post_create_after, controller_view_before, layout_head_end, nav_main_links, nav_plugin_links, nav_user_menu_items, admin_sidebar_links, home_sidebar_bottom, layout_footer
• 钩子文件按需 include，可直接访问调用处作用域变量
• 缓存机制：plugins/plugins_cache.php

已确认缺失的钩子点（需要新增）

• auth_login_form_end — 登录表单底部（用于密码找回等）
• 新增时需要在： app/Views/auth/login.php 密码框后添加一行 Plugin::hook('auth_login_form_end')

三、会话历史里程碑

阶段 1：插件生成器开发（plug/ 目录）

用户要求开发一个在线生成 SoSite 插件的独立程序。

• 位置：D:\phpstudy_pro\WWW\plug/
• 技术栈：PHP + SQLite（单入口，独立于主程序）
• 入口：index.php（路由分发：?action=login|register|edit|delete|import|download|help|default）
• 核心逻辑：app/lib.php
• 样式：style.css
• 数据库：protected/plug.db
• 数据库表：users, generations

功能演进（用户逐次要求）：

阶段 2：安全加固（plug/）

第三方安全审计 → 用户要求修复，经历了两轮深度加固：

第一轮修复（7 项）

第二轮修复（3 项 + CSS）

CSS 变量化（用户主动做的审查优化）

• 新增 9 个 CSS 变量：--bg-surface, --bg-code, --bg-code-gutter, --border-code, --border-code-inner, --text-code, --text-code-dim, --scrollbar-track/thumb/thumb-hover
• 所有硬编码颜色替换为变量
• 钩子 :has(input:checked) 选中态
• 自定义暗色滚动条
• 响应式 Grid：repeat(auto-fit, minmax(280px, 1fr))

阶段 3：内容采集

用户要求采集其他网站内容导入本地数据库：

• https://www.52pojie.cn/forum-16-1.html — 采集 39 条（Discuz! X3.x 架构，反爬严格，从第 2 页开始避开限制）
• https://www.chinaz.com/news/ — 采集 17 条（无限制，内容在 div.pcontent > p）

数据库现状：threads 表共 98 条帖子，精品专区（category_id=4）71 条（含导入数据）

字段注意：threads.last_reply_at 曾为空字符串导致不显示在最新列表 → 修复 SQL：

UPDATE threads SET last_reply_at = created_at WHERE last_reply_at IS NULL OR last_reply_at = ''

阶段 4：文档更新

• docs/ 下共 17 个 HTML 文件，54 处 V3.0.0 → V3.5.0
• 页脚抽取为独立文件：docs/_footer.html + docs/footer.js
• 根据 V3.5 功能更新所有文档内容（含插件系统章节）

阶段 5：第三方核心文件审查

• 第三方的建议以 code-review-todo.md 备忘，最终结论：
• 3-6 条修改难度大、必要性不高 → 决定不修改
• 安全补丁（3 个点）已打进 sositeV3.5/install.php

四、用户偏好与提示

交流风格

• 全程中文
• 技术问题直接，不拖泥带水
• 不喜欢未授权修改 — 必须先问再改（"我让你先看一下，不要轻易修改代码"）
• 要求简洁回答，不要长篇大论
• 喜欢分点、分模块的清晰结构

用户角色

• 个人开发者/站长
• 熟悉 PHP，但有安全审计盲区
• 希望项目达到上线标准
• 重视安全 > 功能 > 美观

五、当前项目状态

已完成功能矩阵

软肋 / 缺失功能

已知配置问题

• SOSITE_VERSION 常量仍定义为 'V3.0.0'（config.php 第 3 行）
• config.php 中 define('DB_PATH', __DIR__ . '/protected/forum.db'); — 数据库文件在 web 可访问目录内，生产环境需通过 web.config 或 Nginx 配置禁止 *.db 下载
• 插件系统 Plugin::hook() 通过 extract($params) 传递变量，钩子文件内可能产生变量名冲突

六、下一步建议（按优先级排序）

P0 — 生产部署必需

1. 禁止 .db 文件直接访问 — 在 web.config 或 .htaccess 中添加 *.db 拦截规则
2. 关闭 display_errors — php.ini 中 display_errors = Off, log_errors = On
3. 配置 HTTPS — 否则 Session Cookie 明文传输（config.php 已有 cookie_secure 自动检测）

P1 — 建议近期实现

1. 通知系统（插件） — post_create_after 钩子触发，route_register 注册 /notifications 路由，nav_user_menu_items 加铃铛图标。纯插件，0 改核心
2. 密码找回（插件 + 改一行 core） — 需在 app/Views/auth/login.php 密码输入框后加一行 Plugin::hook('auth_login_form_end')，插件实现"忘记密码"页面、令牌校验、邮件发送
3. SOSITE_VERSION 常量更新 — config.php 中 'V3.0.0' → 'V3.5.0'

P2 — 长期考虑

1. 公开用户主页 — 展示用户的帖子/回帖列表
2. API 接口 — 为小程序或 App 预留
3. 数据库自动备份 — 后台添加一键备份入口
4. 错误日志系统 — 统一异常捕获和记录
5. 富文本编辑器支持 — 降低普通用户门槛

用户明确表态过的决定

• "那就不改了" — 第三方建议中 3-6 条（核心文件重构）因难度大、必要性不高，已放弃
• 插件生成器的安全补丁、IDOR 修复、Zip Slip 防护 — 已全部采纳并应用
• 不修改核心代码 → 功能优先通过插件实现

七、关键文件路径速查