行业资料库：页面、接入与后续更新

新增入口 /library，详情深链接 /library/:entity/:id。本地预览 http://127.0.0.1:4181/library。

已实现

主目录按商品研究、消费洞察、政策与膳食依据、研究沉淀组织，分别进入商品、社媒、政策文件和已有成果。
商品是浏览单位：规格、价格、消费者评价和榜单线索收进同一商品详情；政策条款从所属文件进入。底层仍保留九类结构实体和独立来源记录，已有成果来自现有工作坊公开业务投影，跳回原报告页面。
品类父子目录；平台、品牌、品类、店铺、时间、质量口径等联动筛选；条件同时满足。切换资料类型会显式进入该类型的全范围，不在后台自动放宽当前请求。
全库概览与当前结果分开；分面分布受到其他筛选维度约束，不受本维度限制，图表注明口径。分面最多100项、图表前5项，不冒称完整目录；商品和评价列表完整游标分页。
商品详情内查看关联资料，政策详情阅读全文、条款摘录和应用提示，并可打开原始来源。分类规则、内部编号、校验指纹和文件定位不在阅读界面展示，后台仍保留完整核查信息。
查询失败、未连接、零命中分开显示；路由保留筛选和页游标；检测数据版本变化后自动更新，并将旧版游标退回第一页。
原有采集 ZIP、r2 交付包及生产业务记录未修改。页面本地读取真实研究库，不把它当作已部署的生产接口。

浏览体验更新（2026-11-05）

资料结果前置：压缩全库概览，平台／品牌／品类与查看口径优先显示；店铺、日期等收在“更多筛选”，当前值始终展示为可单独移除的标签。移除一个条件会保留其他条件并回到第一页，不自动放宽请求。
卡片／紧凑列表切换；覆盖统计按需展开，点击分布项仍使用原有精确过滤。视图切换与统计展开不额外发起查询。
商品列表展示已入库评价、规格和价格数量；点入商品，在“商品概况／包装规格／价格记录／消费者评价／榜单线索”间切换。价格直接展示人民币观察价及口径，规格仅展示已有结构化字段，不从标题推算克重。政策、社媒保留各自的阅读形式。
评价在当前商品内按查看范围筛选，并完整游标翻页，长评价与追加评价可展开。评价不提供日期区间筛选，正文上仍展示实际评价日期。关联查询始终固定精确商品ID，不按标题或同名商品归并；未知日期不会用采集日补齐。
商品栏目、栏目筛选和分页均可保存为深链接，刷新仍停留原商品。返回商品列表保留原列表筛选和页游标，移除栏目内部参数。资料版本更新时清理旧游标，同时保持当前商品和栏目。旧的按商品查看评价／价格等链接会转入商品内对应栏目。
阅读页优先展示原文、文件全文、摘录与应用提示；侧栏支持章节定位和资料信息。平台、店铺、时间等字段统一放在“资料信息”；“资料来源”只保留原始页面与资料阅读链接，不重复字段或关联商品标题。引用复制为标题、业务信息及阅读链接。
游标分页增加已访问页的“上一页”，刷新后的深链接仍可回到第一页；详情返回保留原筛选与游标。无结果时提供一键清空，连接失败继续明确区分。
手机端概览默认收起，目录改为类型选择，资料信息可展开，优先保留正文阅读空间。已检查1440／1024／390／320宽度布局。
本次修改本地前端和只读展示投影，复用既有 browse／detail 接口；不改数据库结构、Agent查询合同或已入库资料，未发布生产。
员工页面不展示本地／生产连接状态、资料入库更新时间、更新记录和后台自动更新通知；分类规则的悬浮说明及入库／业务库等内部措辞一并移除。后台版本检测、刷新和来源核查继续工作；资料自身的观察日期、政策生效日期和价格口径保留。

紧凑筛选布局（2026-11-06）

取消资料、商品评价和研究成果的文本搜索入口。旧搜索链接自动移除关键词及其绑定的页游标，保留显式筛选条件，避免出现看不见的搜索约束。Agent的全文检索合同和服务端能力继续保留。
桌面将左侧目录改为顶部四类导航，释放完整内容宽度；手机使用分类下拉选择。删除重复的分类标题和导读区，概览收进页头按钮，所有宽度均默认收起。
平台、品牌、品类和查看口径集中在紧凑的一行；更多筛选收纳店铺和日期，已选条件仍可单独移除。研究成果改用阶段与成员筛选，成员按现有稳定成员ID匹配。
商品卡片按可用宽度自动排布，常见桌面三至四列、平板两列、手机单列。缩小卡片、筛选和详情间距，保留正文可读性和分页；不变更数据库或生产配置。

商品评论与价格排序（2026-11-06）

移除“更多筛选”折叠区。主栏按平台、品牌、品类筛选；评论数量与价格仅用于排序，不提供区间、不减少当前条件命中的商品。商品目录不再显示对商品本身无过滤作用的“查看口径”，评价详情仍可切换推荐分析与全部评价。
评论数量支持从多到少、从少到多，依据精确商品ID下已收录的全部评价（含默认和待确认），不使用平台显示评论总量。无记录的商品标注“暂未收录评价”，不声称平台没有评论。
价格支持从低到高、从高到低，统一按卡片价格区间的最低历史观察价排序，无有效价格的商品始终排在最后；不当作当前售价。两项排序互斥，选择后一项即替换前一项，可恢复默认排序。
后端先对完整筛选结果排序再分页，同值按稳定记录顺序排列；游标绑定排序及数据版本。切换排序回第一页，刷新与商品详情往返保留排序。Agent检索合同支持相同 sort 参数：reviews_asc、reviews_desc、price_asc、price_desc。
旧区间链接自动移除 reviewCount、price 与旧游标，保留平台、品牌等明确条件。商品内评价和价格仍按精确商品ID关联，列表排序不传入商品内部的评价查询。
商品评价与价格记录去掉日期起止筛选，旧链接自动清理日期条件及对应游标，保留商品、查看范围和列表排序；每条记录的评价日期或价格观察时间继续展示。
本次核查：4,639个商品中43个有评价，共2,360条；京东28个、天猫15个。多数商品只采到了商品信息；采集覆盖记录还包含服务受阻、尝试失败或部分获取状态。默认分析规则过滤后有771条评价，不能把其余记录当作不存在。

阅读界面信息边界

商品详情采用紧凑阅读布局：返回与刷新同排，标题和引用操作合并；概况内商品信息与关联资料并列，手机自动纵排。评论合并为连续分隔列表，正文优先，日期、评分和购买规格作为辅助信息；长评价与追加评价仍可展开全文。栏目、条数与查看范围合并为紧凑工具栏，价格和规格按可用宽度并排。商品来源保留为底部横栏，政策、条款等长文阅读页继续采用原有正文布局。1440、1024、390和320宽度已验证，无横向溢出。

页面按资料类型选择业务字段，不直接遍历数据库全部列：商品展示品牌、品类、店铺；评价展示原文、购买规格、评分与日期；价格展示人民币元金额、价格口径和观察时间；政策展示状态与生效日期。未知字段不会自动进入页面。
分类依据、规则代码、问题代码、技术编号、JSONL行号、校验指纹、处理版本及压缩包名称留给后台核查，不在列表、详情、更新记录或复制引用中展示。校验指纹用于判断文件内容是否改变，属于运维核验信息。
保留影响研究判断的业务说明：政策状态截至日期、摘要与法规原文的区别、价格口径、资料覆盖与时间未知。移除内部字段不代表对资料完整性或真实性作额外承诺。
看板只读投影中的商品摘要改为店铺信息，并补齐条款对应的政策标题和原始链接。数据库原件、Agent查询规则与内部来源指纹保持原样。

架构与授权

页面 → 同源 POST /api/library → Node只读服务 → Python board_library.py → 当前代际 SQLite。

浏览器只允许 summary / browse / detail / version，复用 Agent 的 retrieval.prepare/search/aggregate，禁止传 SQL、磁盘路径和写命令。Node服务并发上限4、输入24KB、超时25秒，读取数据库时使用 mode=ro、immutable 和 query_only。

本地 src/dev/serve.mjs 仅监听127.0.0.1，接口以 localPreview=true 标识预览环境，员工页面不显示环境与连接状态。正式服务 server/library-api.mjs 仅监听127.0.0.1，启动要求 KSF_LIBRARY_API_TOKEN；生产默认拒绝匿名直连。

生产同源网关必须先校验当前访问者的资料授权，再在服务端转发 Bearer；不得把令牌放前端、URL或静态文件，不应对全互联网无条件注入令牌。项目当前没有已经核实的资料库网关身份接入，因此本次没有修改生产网关或公开研究底料。服务通过 KSF_LIBRARY_REGISTRY 指向私有代际目录，KSF_LIBRARY_PYTHON 指向Python3。无需新增Parse云函数。

首次接入

在受控宿主准备私有目录（目录0700、文件0600、运行用户属主），复用已经核验的r2包中的 library/library.sqlite。以下路径为宿主示例，不在聊天中传任何凭据。

python3 -B server/voc-library/update_library.py \
  --incoming /private/r2/library/library.sqlite --registry /private/industry-library --label '首批资料接入'

# 上一步为只读计划；核对后应用，保存stdout作为回执。
python3 -B server/voc-library/update_library.py \
  --incoming /private/r2/library/library.sqlite --registry /private/industry-library --label '首批资料接入' --apply

目录 current.json 是原子切换指针，versions/ 保存不可变数据库；不是把SQLite放到站点静态目录。

后续新增资料

保留采集原件，先用现有受控导入器将新批次构建为独立候选数据库；新格式首次补字段映射，新数据类型首次补结构。不能把任意文件改扩展名就导入。
update_library.py --incoming <候选.sqlite> --registry <目录> 输出只读计划，核结构、完整性、外键和检索投影数量。
加 --apply 合并到一个新代际：已有商品/评价等沿稳定ID关联，相同内容复用；发生业务字段变更时将旧/新记录存入 record_versions，旧代际仍保留。新价格观察不覆盖旧观察。来源路径或来源ID发生冲突时重映射并保留原批次指纹；字典同code定义冲突直接停止。
新代际重建全文与字段索引、校验后原子切换 current.json。导入异常时不切换；同一已导入代际再次提交返回 already-imported。变更回执含各表新增/变更/重复数，更新记录保留在后台供维护核查，员工页面不展示。

页面每30秒核版本，可手动刷新。Agent通过更新后的 query_voc.py/voc_db.py 使用相同 --registry 或 KSF_LIBRARY_REGISTRY，每次查询解析同一个指针；尚未更新脚本的旧安装版不能直接声称已同步。发布查询模块时同步更新其清单，保留旧Skill备份，不能改冻结r2压缩包。

python3 -B server/voc-library/update_library.py --incoming /private/new/library.sqlite \
--registry /private/industry-library --label '第二批京东商品资料' --apply

python3 -B server/voc-library/query_voc.py contract --registry /private/industry-library

# 回退也先不带 --apply 核对；只切换指针，不删除任一代际。
python3 -B server/voc-library/update_library.py --registry /private/industry-library \
--rollback <旧generation> --apply

合并功能针对当前v2九类结构。新格式需要字段映射；新实体类型需要版本升级。评价ID不是独立消费者ID，社媒评论数不是已采评论数，榜单标识不是完整Top100/400。未知时间不能用入库日补，政策状态只是截至原资料日期的声明。

发布文件范围

前端：src/pages/view-library.js、src/pages/library-product-detail.js、src/pages/library-styles.js、src/core/library.js、src/services/library-service.js、src/app.config.js、src/layout/kf-app.js、src/layout/kf-nav.js、src/utils/router.js、src/pages/view-workbench.js、src/components/icons.js。

服务端：server/library-api.mjs；server/voc-library/board_library.py、update_library.py、voc_db.py、retrieval.py、schema.sql、taxonomy.json、query_voc.py。dev/serve仅本地用，不作为生产服务。

正式静态发布前需先核对同名文件现网版本，合并并保留现网员工称呼、机会卡和成员分组等既有功能，不能用整个旧站点覆盖。后端接通并验收授权后再发布前端入口；保留原文件备份可回退。

本地验证

node scripts/check.mjs
node --test test/*.test.js server/test/member-groups.test.mjs server/test/board-actions.test.mjs
cd server/voc-library
python3 -B -m unittest test_board_library test_retrieval test_voc_db -v

test_retrieval 与 test_voc_db 使用测试生成的数据。test_board_library 需要受控交付的真实研究库，可通过环境变量 KSF_TEST_VOC_DB 指定其绝对路径；缺少该库时会明确跳过，不将私有数据库放入Git。

浏览器验收 scripts/verify-library-browser.py；证据位于 work/library-preview/browser-validation.json 与截图。同一组真实数据下“京东＋康师傅＋拌面”命中96个商品。测试单独构建的新增样本仅位于临时目录，不进入本地展示库或生产。

industry-library-20261105.md 14 KB Постоянная ссылка История Исходник