本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/程序目录树.md。

FlintHub 程序代码目录树

生成日期：2026-09-06

说明：本文档列出程序（根目录 d:\phpstudy_pro\WWW）的完整代码目录结构，并逐文件说明用途。运行时数据（data/、data1/ 内部文件）与纯文档（docs/、各类 .md 报告）按目录概括说明。

一、项目概述

FlintHub 1.0 是一款轻量级 PHP 社区系统，核心架构为 SplitDB（纯 SQLite 分片引擎）：

• 无 MySQL 依赖，业务主库 business.sqlite + 分片桶 bucket/ + 外置正文 extern/ + 独立 Session 库
• 前端控制器模式：index.php → 路由 → 控制器 → 视图（app/Views）
• 插件体系：plugins/ 下每个插件独立目录（控制器 + 钩子 + 独立 SQLite 数据），可后台启用/禁用
• 多语言：lang/ 下 zh / en / zh_tw 三套语言包
• 技术栈：PHP + SQLite + 原生 JS（Alpine.js / htmx 内置于系统）、PWA Service Worker

二、总体统计

app 层 PHP 代码行数约 26,849 行。

三、根目录

d:\phpstudy_pro\WWW\
├── index.php              前端控制器 — 路由分发入口，接收全部 Web 请求，初始化计时
├── config.php             全局配置 — 数据目录、上传、邮件、主题、Session、路径常量
├── version.php            版本信息单一来源 — install.php 与 config.php 共同引用
├── install.php            Web 安装程序 — 环境检测 / SplitDB 初始化 / 管理员创建分步向导
├── cron_trigger.php       Cron 定时触发入口（队列任务 Web 消费端，供虚拟主机定时访问）
├── backfill_excerpts.php  存量帖子摘要回填（Web 分批版，供无命令行环境使用）
├── crawl_xiunox_stats.php 论坛站点统计爬虫（CLI，抓取首页解析注册数/主题数/回复数）
├── upgrade_p115.php       V1.0.115 数据层升级脚本（extern 命名空间迁移，一次性使用后需删除）
├── upgrade_p41.php        历史升级脚本（P41 版本用后即删）
├── tz.php                 时区探针（诊断用）
├── sw.js                  PWA Service Worker — 静态资源 Cache-First、HTML Network-First
├── nginx-server.conf      Nginx 服务器配置模板
├── web.config             IIS 服务器配置
├── .htaccess              Apache 配置（重写规则、目录保护）
├── favicon.ico / favicon.svg / logo.svg / flinthub-badge.svg / flinthub-badge2.svg  站点图标/徽章
├── update.zip             更新包压缩文件
├── Splitdb V2.3 白皮书.txt / SplitDB_v2.3_白皮书.md   SplitDB 引擎架构白皮书
├── report.json            审计/统计报告数据（JSON）
├── _diff_out.txt          文件差异输出（临时）
└── *.md                   各类修复实施报告、审计报告、开发计划（详见 docs/ 与根目录文档清单）

根目录还包含若干重要文档（非代码）：FlintHub_双模型交叉裁决修复实施报告_20260905.md、FlintHub代码审计报告.md、插件开发规范.md、插件开发计划.md、第三方登录插件开发计划.md、综合设置插件开发计划.md、代码统计报告.md、修复计划20260820.md、审计结果20260821.md、开发各阶段.md、说明.md 等。

四、app/ 应用核心层（157 文件）

app/
├── init.php               应用初始化 — 自动加载、配置、Session、插件、维护模式
├── report.json            审计数据（JSON）
├── SplitDB.zip            SplitDB 引擎压缩包（部署用）
├── Core/                  核心基础组件（6 PHP + 1 md）
├── Controllers/           前台控制器（13） + 后台控制器 Admin/（17）
├── Helpers/               辅助类库（24 PHP + 1 md）
├── Models/                数据模型 ORM（10 PHP + 1 md）
├── SplitDB/               SQLite 分片引擎（14 PHP + 文档）
└── Views/                 视图模板（63 个）

4.1 app/Core/ — 核心基础

4.2 app/Controllers/ — 前台控制器（13 个）

4.3 app/Controllers/Admin/ — 后台控制器（17 个）

4.4 app/Helpers/ — 辅助类库（24 个）

4.5 app/Models/ — 数据模型（10 个）

4.6 app/SplitDB/ — SQLite 分片引擎（14 个核心类）

4.7 app/Views/ — 视图模板（63 个）

app/Views/
├── layouts/
│   └── main.php            主布局 — 全局外壳（导航、移动端抽屉、页脚、页头钩子）
├── _components/
│   ├── left_sidebar.php    左侧边栏（按站点模式显示模块）
│   ├── mobile_sidebar.php  移动端抽屉导航
│   └── right_sidebar.php   右侧用户面板（积分 + 主题数/博客数 + 发帖/写博客按钮）
├── home/
│   ├── index.php           门户首页（站点模式 portal/forum 下使用）
│   ├── index_default.php   默认首页模板
│   ├── index.php.bak       首页模板备份
│   └── FlintHub 燧石门户首页原型.html  首页 UI 原型
├── forum/
│   ├── index.php           论坛首页 — 版块列表 + 全站帖子排序分页
│   └── category.php        版块分类页 — 分类下帖子列表
├── thread/
│   ├── show.php            帖子详情 — 楼层列表、回复表单、灯箱、投票
│   └── edit.php            帖子编辑（含管理员颜色调色板）
├── post/
│   ├── create.php          发帖表单
│   └── edit.php            回帖编辑表单
├── blog/
│   ├── index.php           博客列表页
│   ├── detail.php          博客文章详情
│   └── edit.php            写博客/编辑表单
├── auth/
│   ├── login.php           登录页
│   ├── register.php        注册页
│   ├── forgot_password.php 忘记密码
│   ├── reset_password.php  重置密码
│   └── message.php         认证提示消息页
├── message/
│   ├── inbox.php           私信收件箱
│   ├── sent.php            私信发件箱
│   ├── compose.php         写私信
│   └── view.php            私信详情
├── profile/
│   └── index.php           个人资料页
├── search/
│   └── index.php           搜索结果页
├── tags/
│   ├── index.php           标签列表页
│   └── show.php            标签关联帖子页
├── theme/
│   └── settings.php        用户主题设置页
├── errors/
│   ├── 404.php             404 错误页
│   └── 429.php             限流 429 错误页
├── admin/                  后台视图（27 个）
│   ├── index.php           后台仪表盘
│   ├── _sidebar.php        后台公共侧边栏
│   ├── blog_categories.php 博客分类管理
│   ├── blog_manage.php     博客管理
│   ├── categories.php      板块管理
│   ├── groups.php          用户组管理
│   ├── levels.php          等级管理
│   ├── tags.php            标签管理
│   ├── threads.php         帖子管理（含颜色设置）
│   ├── thread_edit.php     帖子编辑
│   ├── trashed.php         回收站
│   ├── users.php           用户管理
│   ├── user_edit.php       用户编辑
│   ├── plugins.php         插件列表
│   ├── plugin-edit.php     插件配置编辑
│   ├── themes.php          主题管理
│   ├── database.php        SplitDB 数据库控制台
│   ├── maintenance.php     维护工具
│   ├── permissions.php     权限配置
│   ├── verify.php          管理员二次验证
│   ├── settings_basic.php  基本设置
│   ├── settings_display.php 显示设置
│   ├── settings_mode.php   站点模式设置（门户/论坛/博客）
│   ├── settings_system.php 系统设置
│   ├── mail_settings.php   邮件设置
│   ├── search_settings.php 搜索设置
│   └── queue_settings.php  队列设置
├── admin/database/
│   ├── overview.php        数据库概览（分片/桶状态）
│   └── settings.php        数据库设置
├── admin/logs/
│   └── audit.php           审计日志页

五、cli/ — 命令行工具（79 文件）

cli/ 目录下为命令行脚本，按用途分组：

5.1 队列与常驻进程

5.2 数据迁移（MySQL → SQLite / 格式升级）

5.3 归档与瘦身

5.4 索引与维护

5.5 冒烟测试（smoke_*，19 个）

5.6 验证脚本（_verify_*，20 个）

均为一次性回归验证脚本（验证某项修复/功能是否生效），如：

_verify_fixes_20260820.php（当日修复回归）、_verify_plugin_permissions.php（插件权限）、_verify_points_mall.php（积分商城）、_verify_qa.php（问答）、_verify_task_center.php（任务中心）、_verify_single_page.php（单页）、_verify_remember_multi.php（多端记住登录）、_verify_red_packet_thread.php（红包帖）、_verify_rp_btn_text.php、_verify_query_opt.php（查询优化）、_verify_news_aggregator.php、_verify_home_mode.php（站点模式）、_verify_list_excerpt.php、_verify_footer_sep.php、_verify_plugin_back_url.php、_verify_settings_config.php、_verify_theme_options.php、_verify_basepath_compat.php、_verify_update68.php。

5.7 调试/诊断工具（_dbg/_debug/_diag/_tmp/_probe 等，15 个）

六、assets/ — 静态资源

assets/
├── css/
│   ├── style.css           基础核心样式（重置、布局）
│   ├── modern.css          现代 UI 样式（mn- CSS 系统）
│   ├── portal.css          门户首页样式（基于 --mn-* 主题变量）
│   ├── admin.css           后台样式（后台固定 CSS 变量）
│   ├── editor.css          编辑器样式
│   └── fontawesome.css     FontAwesome 字体图标库
├── js/
│   ├── auth.js             登录/注册表单密码强度检测
│   ├── editor.js           所见即所得编辑器（contenteditable + Selection/Range）
│   ├── pow.js              PoW 工作量证明前端（表单提交前计算 nonce）
│   └── thread.js           帖子详情页脚本（图片灯箱：缩放/拖拽平移、楼层交互）
├── lib/
│   ├── fhajax.js           前端 AJAX 库（htmx 风格动态请求封装）
│   ├── fhstate.js          前端状态管理（Alpine.js 风格响应式状态）
│   ├── qrcode.min.js       二维码生成库
│   ├── marked.min.js       Markdown 解析库
│   ├── turndown.js         HTML→Markdown 转换库
│   └── turndown-plugin-gfm.js  GFM 扩展插件
├── fonts/
│   ├── fontawesome-webfont.ttf
│   └── fontawesome-webfont.woff2   FontAwesome 字体文件
├── img/
│   └── emoji/qq/           QQ 表情 gif 集（Emoji 解析器使用）
├── medals/
│   └── medal1~11.svg       勋章图片（11 枚，medal 插件使用）
├── pwa/
│   ├── manifest.webmanifest  PWA 清单
│   ├── icon-192.png / icon-512.png / maskable-512.png / apple-touch-icon.png  PWA 图标
├── uploads/                用户上传文件（covers 博客封面、seed_avatars 种子头像、图片）
├── themes/                 主题目录（当前为空，主题文件按需部署）
└── plugins_cache.json      插件扫描缓存（Plugin 助手生成）

七、plugins/ — 插件体系（28 个插件，576 文件）

7.1 插件通用结构

每个插件遵循统一规范：

plugins/<插件名>/
├── Plugin.php              插件主类 — 钩子注册、生命周期（install/uninstall/activate）
├── plugin.json             插件元数据（名称、版本、权限声明 permissions、路由）
├── AdminController.php     后台控制器（继承 app 后台基类，需声明 route:admin 权限）
├── FrontController.php     前台控制器
├── <其他控制器>.php        业务专用控制器（如 CheckinController、DiceController）
├── hook/                   钩子文件（init_after、post_create_after、route_after_dispatch 等）
├── assets/                 插件前端资源（script.js / style.css）
├── lang/                   语言包（zh.php / en.php / zh_tw.php）
├── cli/                    插件 CLI 脚本（如 ai_assistant 的 seed/worker）
├── data/                   插件独立 SQLite 数据库 + 锁目录
└── 说明.md / 说明文档.md    插件使用说明

7.2 插件清单

八、cms插件/ — CMS 插件（56 文件）

cms插件/cms/
├── Plugin.php / plugin.json / AdminController.php / FrontController.php
├── assets/   前端资源（script.js / style.css / theme-corp.css / theme-news.css）
├── cli/      插件 CLI 脚本
├── data/     插件数据
├── hook/     钩子文件
├── lang/     语言包
└── views/    插件视图

用途：内容管理系统（CMS）扩展插件，提供企业/新闻类内容发布功能（含企业版与新闻版两套主题样式）。

九、protected/ — 受保护目录（Web 不可访问）

十、data/ 与 data1/ — 运行时数据

data/
├── bucket/          分片桶
│   ├── active/      活动桶（按季度 2026Q3 组织）
│   └── archive/     归档桶
├── extern/          外置正文存储（按 年/季度/分片ID 组织，含 .txt 存量与 .bin/.idx）
├── lock/            文件锁（cron_trigger.lock 等）
├── log/             运行日志
├── meta/            元数据库（global_id.sqlite、sessions.sqlite、task_queue/*、main_index.sqlite、business.sqlite）
└── runtime/         运行时缓存（pages/*.html 访客页缓存、搜索重建断点 JSON 等）

data1/ 为独立的第二套数据目录（预演/测试环境），结构同 data/，另含 business.sqlite 与 extern_backup_pre_ns/（extern 命名空间迁移前备份）。

⚠️ 数据安全约定：D:\data 为关键备份目录，禁止修改；data/、data1/ 均为运行时数据，不属代码。

十一、lang/ — 语言包（3 个）

语言包为纯数据数组，由 app/Helpers/I18n.php 懒加载；插件语言包位于各插件 lang/ 目录。

十二、docs/ — 开发文档（105 个）

按内容分类：

十三、update/ — 版本更新包（21 个版本目录）

update/
├── 60   多语言改造
├── 66 / 67 / 68 / 70 / 71   早期功能迭代
├── 76 / 78 / 80 / 82 / 83 / 85 / 86 / 87 / 88 / 99   持续迭代
├── 100  摘要回填 backfill_excerpts.php 等
├── 105  当前版本基线（V1.0.105）
├── 112  迭代
├── 115  extern 命名空间迁移（P0-1 修复 + 权限强制模式）
└── 120  extern 合并偏移修复（ExternMerger / migrate_extern_to_bin）

每个版本目录标准结构：version.php（版本源）+ 更新说明.md + app/、cli/、lang/、plugins/、assets/ 等增量文件目录。升级时按序覆盖到根目录。

十四、其他说明

• semgrep/ — Semgrep 静态代码扫描配置（安全审计用）
• .atomcode/ — 编辑器/工具配置
• 代码组织约定：Controllers 只做编排，业务逻辑在 Models / Helpers / SplitDB 中；插件不允许直写核心库用户/积分表（走 User::updateGroupId()、Points::deduct()/award()）；核心 Model::update() 受 $fillable 白名单约束。
• 版本单一来源：version.php 中的 FLINTHUB_VERSION 为唯一版本源。