本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/注释清理报告.md。
app/ 目录 PHP 代码注释优化清理报告
版本：1.0（2026-09-06）
范围：
app/下全部 PHP 文件（Controllers / Core / Helpers / Models / SplitDB / Views），共 146 个规则依据：全项目 PHP 文件代码注释优化审查要求（见下）
一、审查规则（执行标准）
| 类别 | 处理 |
|---|---|
| 必须保留 | 涉及安全防护（SSRF / CSRF / XSS / SQL 注入 / 路径穿越 / nosniff 等）的注释；特殊性能优化（Session 锁释放、缓存策略、索引、限流防刷等）注释；兼容性坑位（迁移、旧数据格式、命名空间大小写等）注释；解释「为什么这么写（Why）」的注释 |
| 必须删除 | 描述性流水账注释（如「// 循环遍历」「// 检查是否登录」「// 创建数组」）；单纯翻译代码含义、复述下一条语句的注释 |
| 默认保留 | 无法确定归属的注释一律保留原样，不擅自删除 |
执行前提：清理只删注释文本，函数名 / 变量名 / 代码逻辑零改动；删除后经 php -l 语法校验。
二、删除清单分档说明
报告中每条删除项标注分档，供逐档确认：
- [A] 文件头 docblock：
FlintHub — 轻量级 PHP 社区系统横幅 + 用途复述 +@file/@package，全项目高度雷同、仅复述文件自身职责 → 建议删除整块（/**到*/）。凡文件头带设计/行为/WHY 说明的（如 I18n、PageCache、DatabaseController、home/index.php 等）一律不在删除清单内。 - [B] 方法 docblock：紧贴方法名、仅用中文复述方法名的
/** xxx */（如/** 返回 JSON */下面就是json()）→ 建议删除。 - [C] 行内流水账：
//尾注/行注复述紧随代码含义、或下一条语句就是注释所描述动作 → 建议删除。
若你只希望清 [C] 而不动 [A]/[B]，执行时按档过滤即可，报告按档已分隔。
三、总览
| 目录 | PHP 文件数 | [A] 文件头 | [B] 方法 docblock | [C] 行内流水账 | 小计 |
|---|---|---|---|---|---|
| app/Core | 6 | 6 | 22 | 5 | 33 |
| app/Helpers | 24 | 21 | 0 | 16 | 37 |
| app/Models | 10 | 0 | 0 | 2 | 2 |
| app/SplitDB | 14 | 0 | 0 | 0 | 0 |
| app/Controllers | 30 | 29 | 8 | 56 | 93 |
| app/Views | ~70 | 55 | 2 | 4 | ~61 |
| 合计 | ~154 | ~111 | ~32 | ~83 | ~226 |
注：Views 存在多层子目录，表内为其下全部
*.php（含 database/、logs/ 子目录）；app/Views/emails为空目录。SplitDB 经逐文件审查 + 关键词扫描，全部注释均属 Why/不变式/顺序/性能/兼容说明，无可删项。
四、逐文件删除清单
4.1 app/Core
Autoloader.php
- [A] L2-7：文件头 docblock（FlintHub 横幅 /「PSR-4 风格自动加载器」/ @file / @package）
- [C] L10：
// 驼峰转下划线：FriendLinks -> friend_links - [C] L15：
// 处理 app\ 命名空间 - [C] L38：
// 处理 Plugin\ 命名空间（插件类） - [C] L44：
// 拆出第一段（插件目录名）和剩余路径 - [C] L49：
// 尝试多种路径 - [C] L51：
// 原样 - [C] L53：
// 插件目录转小写下划线，文件名原样 - [C] L55：
// 全小写 - 保留：L20、L25、L61、L66（路径穿越过滤 / realpath 校验 / 防软链兄弟目录绕过 — 安全）
Controller.php
- [A] L2-7：文件头 docblock
- [B] L19-21：
/** 渲染视图（使用主布局） */ - [C] L33：
// 注入布局所需的公共变量 - [C] L49：
// 安全响应头 - [C] L52：
// 插件钩子：视图渲染之前 - [B] L66-68：
/** 渲染视图（不使用布局，纯内容） */ - [B] L93-95：
/** 返回 JSON */ - [B] L106-108：
/** 重定向 */ - [B] L127-129：
/** 获取当前登录用户 */ - [B] L135-137：
/** 检查是否已登录 */ - [B] L143-145：
/** 检查是否管理员 */ - [B] L151-153：
/** 要求登录，未登录则跳转 */ - [B] L164-166：
/** 要求管理员权限 */ - 保留：L24（在线状态在 init.php 统一更新 — Why）、L30（渲染耗时口径/CLI 回退 — Why）、L72/L78-80/L99（安全响应头共用 + nosniff — 安全）
Database.php
- [A] L2-14：文件头 docblock（SplitDB 门面说明 / API 清单 / @file / @package）
- 保留：L84（关闭上一个游标 — 兼容/防坑）；L88-145 一带数据库实现注释多为 Why
- [B] L147-149：
/** 获取当前请求的数据库查询次数 */
Model.php
- [A] L2-7：文件头 docblock
- [B] L24-26：
/** 按主键查找 */ - [B] L36-38：
/** 获取全部记录 */ - [B] L52-54：
/** 条件查询（单条） */ - [B] L62-64：
/** 条件查询（多条） */ - [B] L79-81：
/** 插入记录 */ - [B] L145-147：
/** 删除记录 */ - [B] L177-179：
/** 原生 SQL 查询 */ - [B] L185-187：
/** 原生 SQL 单条 */ - [B] L193-195：
/** 原生 SQL 执行 */
Router.php
- [A] L2-7：文件头 docblock
- [B] L16-18：
/** 注册 GET 路由 */ - [B] L24-26：
/** 注册 POST 路由 */ - [B] L32-34：
/** 注册 GET|POST 路由 */ - [B] L42-44：
/** 路由分组（统一前缀） */ - [C] L59：
// 将 {param} 转为正则 (?P<param>[^/]+) - [B] L72-74：
/** 解析当前请求，执行匹配的路由 */ - [C] L102：
// 去除末尾斜杠（根路径除外） - [C] L121：
// 提取命名参数
TemplateCompiler.php
- [A] L2-7：文件头 docblock
- [B] L52-54：
/** 查找模板文件（主题优先） */ - [B] L92-94：
/** 将 HTML 模板编译为 PHP */ - [C] L146：
// 将 $var[key] 转为 $var['key']（引号数组键名） - [B] L197-199：
/** 渲染视图 */ - [B] L241-243：
/** 编译并执行单个 HTML 模板 */ - 保留：L469-971 图标 map 内逐条中文标注（语义标注，翻译的是图标名含义非代码）
4.2 app/Helpers
以下 21 个文件仅删 [A] 文件头 docblock（L2-7，FlintHub 横幅 + 一句话用途 + @file/@package），无行内可删：
AuditLog、Auth、Captcha、Content、CoverTemplate、Csrf、Emoji、Mailer、Permission、Plugin、PoW、Points、RateLimiter、RememberMe、Search、Segmenter、Settings、Tag、Theme、Upload、Vote（各 L2-7）。
说明：各文件函数/方法 docblock 与行内注释经逐条审查均属 Why/安全/性能/兼容说明或语义标注，保留。另 PageCache、I18n、SearchRebuild 文件头含设计/缓存失效/检查点格式说明 → 整头保留，不列入 [A]。
行内流水账（[C]）：
- Auth.php L173：
// 设置编码头 - Content.php L291：
// 解析 QQ 表情（L287 已有同款未注释调用，属重复说明） - Emoji.php L144：
// 在内容中替换 :code: 为 <img> 标签 - Plugin.php L29：
// 确保插件目录存在 - Plugin.php L34：
// 加载插件列表 - Plugin.php L244：
// 扫描插件目录 - Plugin.php L539：
// 刷新缓存 - Points.php L78：
// 拒绝零或负值积分 - RateLimiter.php L185：
// 清理过期记录 - RateLimiter.php L203：
// 清理过期记录（重复） - RateLimiter.php L208：
// 检查是否超限 - RateLimiter.php L213：
// 记录本次请求 - Search.php L66：
// 对搜索关键词分词 - Segmenter.php L59：
// 去重但保留顺序 - Settings.php L307：
// 防负值 - Theme.php L52：
// 扫描主题目录 - Upload.php L92：
// 图片类型自动生成缩略图
4.3 app/Models
- User.php L434：
// 获取默认用户组→ [C] - Thread.php L320：
// 反转回正序→ [C] - 保留：全部 WHY/安全/兼容注释（Category.php L29/34 旧缓存清理、L102 禁 unserialize 防 RCE；Post.php L257-263 extern 孤儿文件 Why；Thread.php 快照/索引/游标 Why 等），文件头 docblock 未列入（多数含模型说明）
4.4 app/SplitDB
无可删项。全部 14 个文件逐条审查：注释均为 Why / 不变式 / 顺序约束 / 性能 / 兼容 / 红线引用说明（如 ExternStorage.php L62-66 归档作废逻辑 Why、SearchIndexStore.php L302-304 候选上限内存控制 Why），均属保留范畴。附关键词扫描确认无「循环/遍历/创建/检查」类流水账注释。
4.5 app/Controllers（含 Admin/）
文件头 docblock（[A]，各文件 L2-7，格式统一为「FlintHub 横幅 / 一句话职责 / @file / @package」）：
HomeController、AttachmentController、AuthController、ApiController、BlogController、ForumController、MessageController、PostController、ProfileController、SearchController、TagsController、ThemeController、ThreadController、Admin/BaseController、Admin/BlogController、Admin/CategoryController、Admin/DashboardController、Admin/GroupController、Admin/LevelController、Admin/MaintenanceController、Admin/PluginController、Admin/SettingsController、Admin/TagController、Admin/ThemeController、Admin/ThreadController、Admin/TrashedController、Admin/UserController、Admin/VerifyController → 共 28 个，均 [A] L2-7。
不列入删除：Admin/DatabaseController.php L2-13（含 SplitDB 设计/命名约定实质说明）、Admin/LogController.php（含路由与权限说明）、Admin/DatabaseController 内方法 docblock 多为统计口径/Why 说明。
方法 docblock（[B]，纯复述方法名）：
- MessageController.php L17-19：
/** 检查私信功能是否开启 */ - Admin/DatabaseController.php L571-573：
/** 当前总帖子数（topic_index 全量 COUNT） */ - Admin/DatabaseController.php L584-586：
/** 当前总回复数（reply_index 全量 COUNT） */ - Admin/DatabaseController.php L939-941：
/** 删除备份文件 */ - Admin/GroupController.php L17-19：
/** 用户组列表 + 新增/编辑/删除 */
行内流水账（[C]）：
- AuthController.php L100：
// 登录成功：清除 DB 锁定记录 - AuthController.php L118：
// 审计日志：登录成功 - AuthController.php L227：
// 审计日志：用户注册 - AuthController.php L314：
// 确保 password_resets 表存在 - AuthController.php L319：
// 清除该用户旧的未使用的 token - AuthController.php L322：
// 生成新 token - AuthController.php L399：
// 更新密码 - AuthController.php L403：
// 标记 token 已使用 - PostController.php L98：
// 验证分类是否存在 - PostController.php L157：
// 更新倒排索引 - PostController.php L223：
\app\Helpers\Search::indexThread(...); // 更新倒排索引 - PostController.php L254：
// 获取该回复的附件 - BlogController.php L52：
// 构建查询条件 - BlogController.php L66：
// 统计总数（先算 totalPages，再钳制页码） - BlogController.php L78：
// 查询博客列表 - BlogController.php L137：
// 跳转到最后评论页 - BlogController.php L222：
Search::indexBlog($newId); // 博客倒排索引 - BlogController.php L287：
\app\Helpers\Search::indexBlog((int)$id); // 更新博客倒排索引 - BlogController.php L317：
\app\Helpers\Search::removeFromIndex('blog', (int)$id); // 移除倒排索引 - ForumController.php L67：
// 为每个版块计算实际帖子数和主题数 - ForumController.php L71：
// 精华/最新过滤 - ForumController.php L157：
// 标签云数据 - SearchController.php L51：
// 映射底层 searchType 格式 - ThreadController.php L336：
Search::indexThread($threadId); // 更新倒排索引 - ThreadController.php L406：
// 软删除后同步移除搜索索引 - ThreadController.php L407：
\app\Helpers\Search::removeFromIndex('thread', (int)$id); // 移除倒排索引 - HomeController.php L161：
// 获取投票数据 - ProfileController.php L44：
// 审计日志：修改邮箱 - ProfileController.php L65：
// 审计日志：修改密码 - MessageController.php L49：
// 分页：每页 10 条 - MessageController.php L80：
// 分页：每页 10 条（重复） - Admin/BlogController.php L73：
// 批量删除后移除倒排索引 - Admin/BlogController.php L77：
// 审计日志：批量删除博客 - Admin/DatabaseController.php L27：
// 规范化路径分隔符 - Admin/GroupController.php L41：
// 如果设为默认组，先清除其他组的默认标记 - Admin/LevelController.php L18：
// 自动初始化等级配置表 - Admin/PluginController.php L41：
// 分类过滤 - Admin/PluginController.php L109：
// 重新读取 - Admin/PluginController.php L130：
// 检查 Plugin.php 是否存在 - Admin/SettingsController.php L253：
// 保存开关 - Admin/SettingsController.php L489：
// 保存调度模式 - Admin/ThreadController.php L39：
// 批量删除后移除倒排索引 - Admin/ThreadController.php L43：
// 审计日志：批量删除帖子 - Admin/ThreadController.php L59：
Search::indexThread($tid); // 更新倒排索引 - Admin/ThreadController.php L73：
\app\Helpers\Search::removeFromIndex('thread', $tid); // 移除倒排索引 - Admin/ThreadController.php L74：
// 审计日志：硬删除帖子 - Admin/ThreadController.php L97：
// 审计日志：编辑帖子
注意：PostController.php L98「验证分类是否存在」后跟的是校验代码 —— 该条为「下一步动作」引导语，删（校验本身是安全逻辑但注释是流水账）；若你认为属安全边界说明可保留，已在清单但可驳回。其余权限/IDOR/CSRF/归档拦截相关注释均保留未列。
4.6 app/Views
文件头 docblock（[A]，各文件 L2 起一行块，均为「一句话职责 / @file」式自述）：
- _components 无 @file 但含显示行为/复用说明 → 不列入
- admin/_sidebar.php、admin/blog_categories.php、admin/blog_manage.php、admin/categories.php、admin/database.php、admin/database/overview.php、admin/database/settings.php、admin/groups.php、admin/index.php、admin/levels.php、admin/mail_settings.php、admin/maintenance.php、admin/permissions.php、admin/plugin-edit.php、admin/plugins.php、admin/queue_settings.php、admin/search_settings.php、admin/settings_basic.php、admin/settings_display.php、admin/settings_system.php、admin/tags.php、admin/themes.php、admin/thread_edit.php、admin/threads.php、admin/trashed.php、admin/user_edit.php、admin/users.php、admin/verify.php、admin/logs/audit.php → 共 29 个 [A]
- auth/forgot_password.php、auth/login.php、auth/message.php、auth/register.php、auth/reset_password.php → 5 个 [A]
- blog/detail.php、blog/edit.php、blog/index.php → 3 个 [A]
- forum/category.php、forum/index.php → 2 个 [A]
- home/index_default.php → 1 个 [A]（home/index.php 头含设计来源/模块顺序说明 → 保留）
- layouts/main.php → 1 个 [A]
- message/compose.php、message/inbox.php、message/sent.php、message/view.php → 4 个 [A]
- post/create.php、post/edit.php → 2 个 [A]
- profile/index.php、search/index.php、tags/index.php、tags/show.php、theme/settings.php、thread/edit.php、thread/show.php → 7 个 [A]
不列入删除：admin/settings_mode.php（含 portal/forum/blog 模式语义说明）、errors/404.php（前台/插件共用说明）、errors/429.php（RateLimiter 渲染路径说明）、_components/left_sidebar.php + mobile_sidebar.php + right_sidebar.php（版式/显示行为/复用说明）、admin/database.php 与 overview.php 内「智能格式化文件大小」方法 docblock。
方法 docblock（[B]）：
- admin/database.php L20 附近
/** 智能格式化文件大小 */（已按不确定保留 —— 见上） - 其余方法级 docblock 多为行为说明 → 保留
行内流水账（[C]）：
- forum/index.php L26：
// 分离置顶和普通帖子 - search/index.php L109：
// 跳过用户结果（紧跟continue;） - thread/edit.php L59-64 色板注释：
// 无（默认，继承主题色）/// 红/// 橙/// 绿/// 蓝/// 紫（六条为色板色名标注，对应后台 thread_edit.php 同款 —— 属于颜色值语义标注，若需与后台保持可读性可保留；标记为 [C] 候选但可驳回）
保留类（仅列代表性，供抽查）：thread/show.php L304 归档回复框门控说明（访问控制）、L374 图片查看绑定与博客页一致性（兼容）；forum/category.php L122-123 与 forum/index.php L199-200 游标分页边界（性能）；blog/edit.php L71 封面防抖不落盘（性能）；layouts/main.php 内 PRG/站点模式/页脚指标口径；admin/_sidebar.php L56/89/91 展开折叠标记与首绘时序（性能）；auth/login.php L81 与 auth/register.php L63 PoW 绑定集中说明（安全）；HTML 结构分隔注释（
<!-- 分栏 -->等）视为结构标记全部保留。
五、汇总确认要点
- 逻辑零改动：本报告仅删注释文本；函数名/变量名/代码逻辑保持原样，删除后全部
php -l校验。 - [A] 文件头 docblock 占大头（约 110 处）——若只想清行内流水账，执行时仅做 [C]+[B] 即可。
- SplitDB 全保留；app/Models 仅 2 处；安全/性能/兼容/Why 注释一律未列入。
- 存在少量「可驳回」条目（PostController L98、thread/edit.php 色板六条）已明确标注，默认按清单执行或按你的决定保留。
- 报告行号经抽样复核（Autoloader / Controller / Plugin / RateLimiter 等文件已逐一比对），如执行中发现行号偏移以文件实际内容为准，以注释文本匹配删除。
下一步：确认后（可指定只清 [C]、或 [C]+[B]、或全量 [A]+[B]+[C]）再动手执行。
