# PRD: Zibll 小工具全量 1:1 深度复刻

> 来源：用户指令（/plan 参数）。参考主题：`C:\Users\Xing\Desktop\zibll`

## 背景与问题

AKSRT 主题的小工具系统当前存在多处缺陷：

1. **卡片堆叠问题**：`assets/css/frontend/post-card.css` 中 `.posts-item { display: block !important }`（行 32）覆盖了 `.posts-item.card { display: inline-block }`（行 75），导致卡片全部纵向堆叠、宽度 calc 失效。
2. **分页函数缺失**：`aksrt_render_pagination()` 在 `main` 分支未定义，仅存在于 worktree 分支；`index.php:40`、`archive-resources.php:173`、`search.php:281` 三处无 `function_exists` 守卫直接调用，归档/搜索/首页有文章时即致命错误。
3. **重复渲染路径**：`archive-resources.php:162-171` 手写 `.posts-row.ajaxpager` + `get_template_part('content-post-card')`，绕过 `aksrt_render_post_list()` 统一渲染器（违反 CLAUDE.md 行 147）。
4. **通用表单链路半成品（双路）**：`inc/modules/widgets-register.php` 已有一套共享通用字段层（`aksrt_widget_render_common_form` / `update_common` / `get_common_wrapper_classes` / `should_display_by_ids`，行 314-509），但 **55 个小工具无一调用**；16 个小工具各自重新实现 `in_affix`，等于半成品双路。
5. **小工具缺失/不对齐**：需对照 Zibll 参考主题（约 44 个现代 CSF 小工具 + 9 个旧版）逐一 1:1 对齐字段、渲染、AJAX 链路。
6. **注册/区块编辑器/侧栏缺口**：`page_sidebar_{ID}` 动态侧栏未被注册（页面中段侧栏空白）；区块编辑器仅收录 3/55 个小工具；CLAUDE.md 路径漂移（`inc/classes/widgets/` 实际为 `src/AKSRT/Widgets/`）。

## 目标

按照 Zibll 参考主题**全量 1:1 深度复刻**小工具系统，完成「设置 → 注册 → 后台表单 → 渲染过滤 → 前端渲染」全链路，消除卡片堆叠与致命错误，统一为单一路径。

## 约束

- **不写双路与迁移兼容代码**：直接替换旧实现，不保留旧 option 兼读、不新增 shim（遵循 CLAUDE.md「重写优先于兼容」）。
- **可搬运参考主题资源**：允许把 Zibll 的图片/图标等资源搬入 AKSRT（后续逐步替换）。
- 表单系统走「复用现有共享层」路线，**不移植 CSF (Codestar) 框架**。
- 单一计划、分阶段推进；每阶段可独立演示与验证。

## 用户故事

- **US1（管理员）**：每个小工具都能通过统一的共享表单层配置 Zibll 等价的通用字段（显示设备 PC/移动、文章 ID 显隐、侧栏吸顶、入场动画、布局背景、标题/副标题/链接），不再有逐小工具重复实现。
- **US2（访客）**：文章卡片在 list/card/mini 三种模式下正确布局，不堆叠、不塌陷。
- **US3（访客）**：首页/归档/搜索页分页正常（数字 / 加载更多 / 无限滚动），无致命错误。
- **US4（管理员）**：Zibll 的每一个小工具在 AKSRT 都有对等实现，可挂载到正确的挂载区域。
- **US5（开发者）**：全链路（设置 → 注册 → 表单 → 渲染过滤 → 前端渲染）一致且单一通路。
- **US6（开发者）**：参考主题的图片/图标/CSS/JS 资源已入库，小工具渲染视觉与 Zibll 一致（后续替换）。
- **US7（访客/管理员）**：论坛版块/话题与商城商品小工具与 Zibll 对齐。

## 范围外

- 不新增任何向后兼容 / 数据迁移层（PRD 明确）。
- 参考图片为临时搬运，后续替换不属于本计划。
- 不移植 CSF 框架本体。