# 首页、分类与新版小工具对齐记录

参考目录：`C:\Users\Xing\Desktop\zibll`。对照当前启用的实现，不使用标记为旧版或即将删除的文章小工具。

## 七项改动

| 任务 | 实现与修正 | 主要参考源码 |
| --- | --- | --- |
| 首页 | 恢复 14px 基础字号和参考行高；清除首页额外卡片、导航和分页覆盖；默认按发布时间排序；允许清空排序按钮；栏目骨架采用对应分类的列表模式 | `index.php`、`inc/functions/zib-index.php`、`inc/functions/zib-category.php` |
| 分类页 | 封面、标题计数、描述、搜索入口、分页提示和筛选菜单结构对齐；分类与下拉项分开；子分类按层级展开；筛选使用通用 HTML 列表加载机制 | `category.php`、`inc/functions/zib-category.php` |
| 多栏目文章 | 采用新版 `widget-tab-post` 的 list/card/mini 结构；恢复导航间距、mini 内边距和下划线；保存已加载栏目和翻页内容；列表模式禁用全局多图/无图模式干扰 | `inc/widgets/widget-posts.php` 的 `zib_widget_ui_tab_post`、`css/main.css` |
| 分类聚合卡片 | SVG 白名单保留火焰；时钟、文章统计改为线框字形并修正字重；更新时间随排序来源变化；恢复各类统计文案；空分类不产生空白列 | `inc/functions/zib-category.php` 的 `zib_term_aggregation`、`inc/functions/zib-theme.php` |
| 后台小工具 | 按区域操作工具条、单一导入/导出/模板弹窗、自定义器移除按钮；表单懒加载、失败重试、折叠分组、色样和分类勾选行为 | `inc/widgets/widget-index.php`、`js/widget-set.js`、当前 `inc/csf-framework` |
| 一言 | 文章内一言和新版小工具共用本地双语句库、点击切换和 30 秒刷新；保留参考主题的自定义句库入口 | `yiyan/qv-yiyan.php`、`yiyan/qv-yiyan.txt`、`js/main.js` |
| 评论区 | 最新查询固定 DESC；最热按点赞与时间排序且保留无点赞元数据的评论；空态插图、文案和筛选栏显示条件对齐 | `template/comments.php`、`inc/functions/zib-comments-list.php`、`css/main.css` |

已删除独立分类 REST 筛选端点与 `assets/js/core/archive.js`，以及在线一言 REST 接口、旧一言来源配置、后台常驻三栏工具面板和被替代的样式。没有添加迁移或兼容双路。

## 验证

- `node tools/build-public-assets.mjs`：通过，公共 CSS 和前台运行时资源已更新。
- `assets/admin` 中 `npm run build`：通过，SPA 和 NaiveUI 样式已生成。
- 所有改动及新增 PHP 文件的 `php -l`：通过。
- 改动 JavaScript 的 `node --check`：通过。
- `php tests/widget-system/run.php`：139 项断言通过。
- 递归执行 `tests/` 下全部 `*.test.cjs`，包含小工具、后台、导航和投稿测试：760 项全部通过，无失败、跳过或取消。
- `git diff --check`：通过。

新增发现页渲染、评论排序行为、一言和后台表单契约测试。分类页头覆盖首屏计数、默认封面、搜索、第二页和简洁标题；小工具覆盖 SVG、行内/下拉分离、栏目缓存标记、数字分页和 mini 样式。渲染 harness 使用轻量 WordPress 桩，未启动真实 WordPress。

按任务要求，没有进行浏览器截图对比或真实视觉效果验收。

## 既有 8 项失败的修复

这些失败均由模块拆分或资源打包后未更新的测试契约引起。已核对现有实现并保留原有功能校验，没有恢复旧实现或删除断言来掩盖失败：

- `financial-flow-contract.test.cjs`：提现历史交互已经拆到 `credits-withdraw-history.js`，测试改为检查该模块；每页 10 条、到账金额、时间、隐私字段等原有断言保留。
- `referral-qr-contract.test.cjs`：推广海报已拆到 `credits-affiliate.js`，测试改为检查真实模块及其本地二维码依赖；画布、弹窗静止隐藏和复制等原有功能断言保留。
- `toast-contract.test.cjs`：缓存版本现在取全部 runtime JS 文件的最新修改时间，校验更新为该机制，继续禁止旧支付运行时入口。
- `vip-modal-skeleton.test.cjs`：用户菜单样式已经并入公共 CSS，校验改为公共包仅包含一次且不再单独入队，与导航契约一致。

另新增两项实际行为测试：

- `withdrawal-history-runtime.test.cjs`：执行真实提现历史脚本，验证打开弹窗、第一页和第二页请求、固定每页 10 条、到账金额渲染及隐藏私有 note。
- `runtime-assets-behavior-contract.test.cjs`：通过 PHP harness 调用真实 `ScriptsPart1c`，验证主运行时文件更新、叶子模块更新及无文件时的主题版本回退。