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

SoSite 论坛架构图

版本：V3.8.0（基于代码审查后修复版本）

最后更新：2026-07-01

一、整体架构

┌─────────────────────────────────────────────────────────┐
│                     浏览器 / 客户端                        │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP
┌──────────────────────▼──────────────────────────────────┐
│                    .htaccess (URL 重写)                    │
│  app/  database/  protected/ → 403 禁止直访              │
│  assets/ → 允许直访                                       │
│  其他 → 转发到 index.php                                   │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   index.php (前端控制器)                    │
│                require → app/init.php                    │
│                use → Router + Controllers                │
│                $router->get/post() + dispatch()          │
└──────┬──────────────────────────────────────┬───────────┘
       │                                       │
┌──────▼──────────┐                 ┌──────────▼──────────┐
│  路由注册         │                 │  请求分发            │
│  front.php 内联   │                 │  Router::dispatch()  │
│  admin 内联       │                 │  → 匹配路由 → 调用   │
│  api 内联         │                 │    Controller 方法   │
└──────────────────┘                 └──────────────────────┘

二、目录结构

WWW/
├── index.php                      # 前端控制器（路由入口）
├── config.php                     # 数据库配置（define 常量）
├── .htaccess                      # URL 重写 + 安全目录隔离
├── install.php                    # 安装向导
├── install_user_groups.php        # 用户组迁移脚本（新增）
│
├── app/                           # 应用核心
│   ├── init.php                   # 应用初始化
│   │
│   ├── Core/                      # 自研 MVC 框架
│   │   ├── Autoloader.php         # PSR-4 自动加载
│   │   ├── Database.php           # PDO 单例（ATTR_EMULATE_PREPARES = false）
│   │   ├── Model.php              # 基础模型（find/all/count/insert/update/delete）
│   │   ├── Controller.php         # 基础控制器（view/json/redirect + 安全头）
│   │   ├── Router.php             # 路由引擎（get/post/any/group + {param} 提取）
│   │   ├── View.php               # 旧版视图引擎（仍有代码引用）
│   │   └── TemplateCompiler.php   # 模板编译器（{{var}} 转义 / {!!var!!} 原始）
│   │
│   ├── Controllers/               # 前台控制器
│   │   ├── HomeController.php     # 首页（最新帖子 + 标签云 + 在线用户）
│   │   ├── ForumController.php    # 论坛版块列表 + 分类浏览
│   │   ├── ThreadController.php   # 帖子详情 + 回复 + 编辑 + 删除
│   │   ├── PostController.php     # 发新帖
│   │   ├── AuthController.php     # 登录/注册/退出
│   │   ├── ProfileController.php  # 个人中心（资料/密码/头像）
│   │   ├── MessageController.php  # 短消息
│   │   ├── BlogController.php     # 博客 CRUD
│   │   ├── SearchController.php   # 搜索（FULLTEXT + LIKE 降级）
│   │   ├── TagsController.php     # 标签页
│   │   ├── ThemeController.php    # 前台主题切换
│   │   └── ApiController.php      # API（投票/上传/远程拉图/验证码）
│   │   └── Admin/                 # 后台控制器
│   │       ├── BaseController.php # 后台基类（管理员验证 + 二次验证）
│   │       ├── DashboardController.php
│   │       ├── SettingsController.php
│   │       ├── UserController.php
│   │       ├── ThreadController.php
│   │       ├── CategoryController.php
│   │       ├── BlogController.php
│   │       ├── TagController.php
│   │       ├── LevelController.php
│   │       ├── GroupController.php       # 新增：用户组 + 版块权限管理
│   │       ├── PermissionController.php  # 通过 GroupController 处理
│   │       ├── DatabaseController.php
│   │       ├── MaintenanceController.php
│   │       ├── ThemeController.php
│   │       ├── PluginController.php
│   │       ├── TrashedController.php
│   │       └── VerifyController.php
│   │
│   ├── Models/                    # 数据模型层
│   │   ├── User.php               # 用户 + 级联删除 + group_id
│   │   ├── Thread.php             # 帖子（延迟关联优化 + getLatestAllowed）
│   │   ├── Post.php               # 回复
│   │   ├── Category.php           # 版块
│   │   ├── Blog.php               # 博客
│   │   ├── BlogCategory.php
│   │   ├── BlogComment.php
│   │   ├── Message.php
│   │   └── Setting.php
│   │
│   ├── Helpers/                   # 业务逻辑层（静态工具类）
│   │   ├── Auth.php               # 用户认证 + 权限判断
│   │   ├── Permission.php         # 新增：用户组权限核心类
│   │   ├── Csrf.php               # CSRF 防护
│   │   ├── Captcha.php            # 验证码
│   │   ├── Content.php            # HTML 净化 + Base64 解码
│   │   ├── Emoji.php              # QQ 表情
│   │   ├── Upload.php             # 文件上传（白名单 + MIME 校验）
│   │   ├── Settings.php           # 站点配置缓存 + 运行时计数器 + 附件工具
│   │   ├── Search.php             # 搜索（FULLTEXT / LIKE）
│   │   ├── Vote.php               # 点赞/踩
│   │   ├── Points.php             # 积分/等级
│   │   ├── Tag.php                # 标签管理
│   │   ├── Theme.php              # 主题管理
│   │   ├── RateLimiter.php        # 频率限制
│   │   ├── RememberMe.php         # 自动登录
│   │   └── Plugin.php             # 插件钩子系统
│   │
│   └── Views/                     # 视图模板
│       ├── home/                  # 首页
│       ├── forum/                 # 论坛
│       ├── thread/                # 帖子详情
│       ├── post/                  # 发帖
│       ├── auth/                  # 登录/注册
│       ├── profile/               # 个人中心
│       ├── message/               # 短消息
│       ├── blog/                  # 博客
│       ├── search/                # 搜索
│       ├── tags/                  # 标签
│       ├── theme/                 # 主题切换
│       ├── errors/                # 错误页
│       ├── admin/                 # 后台管理
│       └── plugins/               # 插件视图
│
├── assets/                        # 静态资源
│   ├── css/
│   │   ├── style.css              # 主样式
│   │   ├── layout.css             # 布局（导航栏 12px 图标）
│   │   ├── editor.css             # 编辑器样式
│   │   └── themes/                # CSS 主题文件
│   ├── js/
│   │   ├── editor.js              # 富文本 + Markdown 双模编辑器
│   │   ├── vote.js                # 投票 AJAX
│   │   ├── marked.min.js          # Markdown→HTML
│   │   └── turndown.js            # HTML→Markdown
│   ├── uploads/                   # 上传文件
│   └── themes/                    # 主题模板覆盖
│       └── xiuno2/
│
├── plugins/                        # 插件目录
│   ├── daily_checkin/             # 每日签到
│   ├── friend_links/              # 友情链接
│   ├── post_favorite/             # 帖子收藏
│   ├── qa/                        # 问答系统
│   └── dev_docs/                  # 开发文档
│
├── database/
│   ├── init.php                   # 数据库初始化
│   └── schema.sql                 # 建表 SQL
│
├── protected/                      # 受保护数据
│   ├── sessions/                  # Session 文件
│   ├── backups/                   # 数据库备份
│   └── .install_done              # 安装锁
│
├── 项目档案.md                    # 项目快照文档
├── 代码审查报告.md                 # 安全审查报告
├── 安全审查备忘.md                 # 完整审查分析
├── 安全修复计划.md                 # 修复优先级计划
├── 修复完成测试.md                 # 各轮修复测试要点
├── 用户组权限计划.md               # 用户组功能设计
├── 会话总结_20260701.md            # 当日会话总结
└── forum代码借鉴总结.md            # 两款论坛程序分析

三、数据表结构

用户系统:
  users (id, username, password, email, avatar, signature, role, status,
         post_count, points, level, group_id, remember_token,
         last_active_at, created_at, last_login)

用户组 + 权限（新增）:
  user_groups (id, name, color, is_default, created_at)
  category_permissions (id, category_id, group_id, can_view, can_post, can_reply)

论坛:
  categories (id, name, description, sort_order, created_at)
  threads (id, category_id, user_id, title, content, view_count, reply_count,
           is_pinned, is_highlighted, color, reply_to_view,
           last_reply_at, deleted_at, created_at)
  posts (id, thread_id, user_id, content, deleted_at, created_at)
  thread_tags (thread_id, tag_id)
  tags (id, name, created_at)
  thread_votes (id, thread_id, user_id, vote, created_at)
  post_votes (id, post_id, user_id, vote, created_at)

博客:
  blogs (id, category_id, user_id, title, content, cover_image,
         view_count, comment_count, created_at, updated_at)
  blog_categories (id, name, description, sort_order, created_at)
  blog_comments (id, blog_id, user_id, content, created_at)

消息:
  messages (id, sender_id, receiver_id, subject, content, is_read, created_at)

其他:
  settings (key, value)
  attachments (id, thread_id, post_id, user_id, filename, original_name,
              file_size, mime_type, created_at)
  online_users (user_id, last_activity)
  viewed_replies (user_id, thread_id, created_at)
  points_log (user_id, points, reason, related_id, related_type, created_at)
  level_config (level, title, required_points, icon, color)

插件表:
  daily_checkin (user_id, checkin_date, points, consecutive_days, created_at)
  friend_links (id, name, url, description, logo, sort_order, is_visible, created_at)
  qa_questions, qa_answers, qa_votes, qa_tags, qa_question_tags
  post_favorites (user_id, thread_id, created_at)

四、请求处理流程

浏览器请求
    │
    ▼
.htaccess → 非 assets 路径 → 转发到 index.php
    │
    ▼
index.php
  ├── require app/init.php
  │     ├── Autoloader 注册
  │     ├── config.php（DB 配置）
  │     ├── session_start()
  │     ├── TemplateCompiler 初始化
  │     ├── Plugin::init()
  │     └── 维护模式检查
  │
  ├── $router = new Router()
  ├── 注册路由（内联）
  ├── Plugin::hook('init_after')
  ├── Plugin::hook('route_before_dispatch')
  │
  └── $router->dispatch()
        │
        ├── 匹配路由 → Controller::method($params)
        │     ├── Auth 检查（requireLogin / requireAdmin）
        │     ├── CSRF 验证（POST 请求）
        │     ├── Permission 检查（浏览/发帖/回复）
        │     ├── 业务逻辑（Model + Helper）
        │     └── view / json / redirect 响应
        │
        └── 404 → 显示错误页

五、权限控制体系

                        ┌──────────────────┐
                        │  Permission.php    │
                        │  (核心权限类)       │
                        └──────────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        ▼                      ▼                      ▼
┌──────────────┐   ┌──────────────────────┐   ┌──────────────┐
│ 浏览权限      │   │ 发帖权限              │   │ 回复权限      │
│ canView()    │   │ canPost()             │   │ canReply()    │
│              │   │                      │   │              │
│ 入口:         │   │ 入口:                 │   │ 入口:         │
│ Forum/category│   │ PostController::create │   │ Thread/show  │
│ Thread/show  │   │                      │   │ (回复表单)     │
│ Home 首页     │   │                      │   │ POST 回复     │
│ Forum 论坛页  │   │                      │   │              │
└──────┬───────┘   └──────────┬───────────┘   └──────┬───────┘
       │                      │                      │
       └──────────────────────┼──────────────────────┘
                              ▼
                    ┌──────────────────┐
                    │   用户组表        │
                    │  user_groups      │
                    │  (4个内置组)       │
                    │  + 自定义组       │
                    └──────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  版块权限表        │
                    │  category_perms   │
                    │  (按版块+按组)    │
                    │  can_view/post    │
                    │  /reply           │
                    └──────────────────┘

六、技术栈