Document cmd Book filtering diagnosis and recovery command

docs/maintenance/BOOK.md

@@ -0,0 +1,23 @@
+# Book 与 cmd
+
+Book是master01的Telegram层级笔记模块；数据为`book`、`book_page`、`book_option`、`book_hook`。它与旧后台的`nasa_book`说明书表不同。资源、归属和私有资料入口见[GemDocs模块档案](/Users/hellcat/Documents/GemDocs/AI版/30-私有资源/资源/模块/MOD-book.md)，本文只维护实现及排障。
+
+## 调用链
+
+`GET /cmd`加载`resources/views/cmd.blade.php`，用户提交时POST到`/cmd/send`。`CmdController::ajaxSend()`按`dove_site`表的code读取www与api_path，向目标发送带`shell=cmd`的模拟更新；默认站点master映射至`master.diaodu.us/api/tg/hook`。不要把浏览器所用白色机反代入口与服务器内部的转发目的地混为一处配置。
+
+`HookController::cmd()`把`/book#main`分派到`Services/Tg/Hook/Mod/Book::main()`，后者通过`BookHook::_cd()`把当前用户名的位置改到根目录，再调用`openRe()`重新查询/渲染并更新`book_page`缓存。`Services/Tg/Http::send()`遇到`shell=cmd`只向HTTP响应输出，不发送Telegram。
+
+## 2026-10-20 根目录空白调查
+
+用户反馈右侧线上cmd运行`/book#main`没有内容。只读读取当前页面确认站点master、用户tom、hook为空、命令如上，结果区为空；未重新提交命令。经白色机SSH确认生产`21ab4b84`，CmdController、HookController、Book处理器、Book模型和cmd视图与本地SHA-256一致。
+
+数据库在READ ONLY事务内查询后回滚，仅回传计数、状态和脱敏错误；没有输出笔记正文。`book`共570行，根目录有17条非删除记录，根节点id=1存在，limit=100，根目录缓存page=1、正文342字节。根节点的`like`字段非空（更新时间2026-10-13 16:38:58），无sort和自定义where。`Book::_path('/', 1)`应用该筛选后0条，纯渲染结果0字节；`Book::_path('/', 'all')`跳过视图筛选后17条，纯渲染342字节。服务器正常HTTPS请求`/cmd`返回200且包含命令输入框。
+
+原因：`Models/Book::_path()`将父节点的持久化`like`作为rag搜索条件，`main()`只切换路径，不重置该条件。无匹配时`open()`调用`bookToStr([])`，在没有其他状态标记的情况下输出空串，界面没有说明仍处于筛选状态。现有笔记没有因本次问题消失；未追溯是谁设置筛选，不把节点订阅改动归因为Book故障。
+
+## 恢复与检查边界
+
+在目标站点master，先运行`/book#main`确保当前位置为根目录，再运行`/book#unlike`。`unlike()`仅清空当前父节点的like字段并重新生成该页，不删除笔记。该筛选属于目录记录，是共享状态，不能当作单用户浏览器筛选。
+
+本次为调查，未执行恢复命令、修改数据库、清空缓存、发送Telegram消息或改动生产代码。恢复后的真实cmd显示尚未验收；上述17条/342字节是服务器内只读查询和纯渲染证据。