fix: complete admin knowledge audit improvements

ai_knowledge_base_v2/development_records/2026-07-13-后台测试问题修复与新增需求实施记录.md

@@ -0,0 +1,45 @@
+# 后台测试问题修复与新增需求实施记录
+
+## 本次已落地
+
+- Agent 预览进入时重新读取知识库状态，默认仅选中已开放且未归档项；管理员仍可手动选择已关闭项用于本次预览。
+- Agent 知识库多选框增加搜索、标签折叠、计数提示、高度上限和弹层层级。
+- Tool 追踪改为独立可折叠节点，后端持久化请求、响应、顺序、状态、耗时、数量、错误与重试字段；空响应明确显示。
+- KnowledgeList 增加 Redis read-through 缓存，Redis 故障自动回源 MySQL，采用代际号统一失效，记录命中/未命中次数和耗时。
+- 知识库新增恢复为 Node ID 两步流程：解析节点后回填只读 Space ID、飞书原标题、后台名称和备注，创建前后端双重校验。
+- 检索日志列表增加数据库 offset/limit 分页，详情仍按需单独获取；新增估算和 500 条一批的清理接口。
+- 新增保留策略配置接口，支持永久保留或自定义天数；清理先删候选明细再删主日志，不触及操作审计表。
+- 看板增加存储快照，区分 MySQL 表占用、Redis 内存和本地文件；默认读最新快照，手动刷新才重新统计，不可获取时不伪造 0。
+- 模型列表操作区保留编辑/测试，启用/删除收入更多菜单；操作区统一高度、间距、禁止换行。知识库表已采用相同的“主操作 + 更多”模式。
+
+## SQL 和索引
+
+迁移 `0009_log_retention_storage_indexes.py` 新增：
+
+- `sys_knowledge_retrieval_log(status, created_at)`
+- `sys_knowledge_retrieval_log(created_at, id)`
+- `sys_ai_request_log(status, created_at)`
+- `sys_operation_log(module, created_at)`
+- `sys_chat_session(is_deleted, updated_at)`
+- `sys_log_retention_policy`
+- `sys_storage_snapshot`
+
+优化前日志列表固定读取最新 300 条，无可控分页；优化后每次默认读 50 条、上限 100 条，且列表不读 `catalog_snapshot/tool_trace/final_answer`。实际 SQL 耗时依赖生产数据量与 MySQL 执行计划，需在迁移后用生产同量级数据执行 `EXPLAIN ANALYZE` 记录，本地不伪造耗时数字。
+
+## Redis Key
+
+- `kb:catalog:generation`：目录代际号。
+- `kb:catalog:v1:{generation}:open`：当前已开放知识库目录，TTL 300 秒。
+- `kb:catalog:v1:{generation}:open:lock`：冷启动重建锁，15 秒。
+- `kb:catalog:metrics`：`hits/misses/hit_ms/miss_ms` 累计指标。
+
+新增、名称/类型/说明卡变更、开放/关闭、发布、回滚、归档/恢复和删除均通过代际号失效。
+
+## 验证与剩余风险
+
+- 管理端 `npm run build` 通过。
+- 后端 Python 全量 AST/字节码编译通过，`git diff --check` 通过。
+- Docker Compose 配置校验通过。
+- 后端容器内 `PYTHONPATH=/app pytest -q`：17 项全部通过。
+- 定期清理已接入后端维护循环，Redis 分布式锁防止多实例重复执行，每日最多执行一次。
+- 7/30 日增长需要至少积累两个存储快照后才可准确计算，首次上线不应显示伪造的 0。