Merge asset statistics and contextual AI assistant into main

docs/asset-ai-experience-cases.md

@@ -0,0 +1,58 @@
+# 资产 AI 问答体验验收
+
+本轮目标是恢复自然语言理解和连续分析。模型负责理解与查询规划，权限与业务数量继续由现有后端执行。验收需要分开检查“有没有理解”与“算得对不对”，不能仅以接口返回 200 为通过。
+
+## 自动回归的数据与边界
+
+`src/server/routes/asset-assistant/experience.test.ts` 使用合成车辆、模拟 DeepSeek 响应和内存需求记录，不访问真实数据库或模型。集成测试验证模型决策能穿过会话、查询执行和结果组装，不能证明真实模型对任意表达的理解率。
+
+本轮已通过 17 项路由集成回归，包含五轮会话、澄清前后范围、历史结果分支、排名引用的汇总证据、异常到期筛选、历史流转日期及切回当前库存、模型故障、中文历史库存口径，以及需求记录的上下文可读性。执行命令：`node --import tsx --test src/server/routes/asset-assistant/experience.test.ts`。
+
+## 中文真实问法语料
+
+| 场景 | 连续输入 / 操作 | 应有行为 |
+| --- | --- | --- |
+| 口语表达 | 帮我瞅瞅华东现在有多少闲着的车，按城市排一下 | 理解库存意图；若“闲着”口径不明确，用简短说明或一次澄清，不要求用户使用固定关键词 |
+| 指代和继承 | 查华东库存 → 只看嘉兴 → 这里面哪些快到期了？ | 继承华东、嘉兴范围；“到期”可能指异动预计完成时间或合同到期，缺少明确指向时澄清 |
+| 澄清恢复 | 查嘉兴库存 → 看下到期情况 → 我指异动预计完成时间 | 澄清不丢掉嘉兴范围；执行异动时间相关分析 |
+| 排序与取前几名 | 哪些城市库存最多？只看前三名 → 换成最少的三个 | 正确应用降序、升序与 Top 3；展示截取口径，不能把前三名当作全量总数 |
+| 排除条件 | 看华东库存，杭州先不要 → 还是把杭州加回来 | 支持排除和取消排除；展示当前条件 |
+| 修改而非叠加 | 看嘉兴库存 → 不对，我想看杭州 | 城市替换为杭州，不把嘉兴和杭州错误叠加 |
+| 恢复全局 | 看嘉兴异动车辆 → 重新看全部库存 | 清除旧地区、异常等限制，不残留不可见条件 |
+| 任意结果分支 | 看华东库存 → 只看嘉兴 → 回到第一张图，按车型拆 | 从指定历史结果继续，使用华东范围；不能使用最近嘉兴结果 |
+| 图表点击联动 | 按区域看库存 → 点击华东 → 按车型拆开 → 点击 4.5T → 列出异动车 | 保留区域和车型；统计与明细可核对；显示异动类型、预计完成时间 |
+| 交叉对比 | 华东和华南的库存，按车型对比一下 | 地区与车型双维度；对比当前分布，不冒称历史涨跌 |
+| 库存子集 | 这些库存里面有多少异动和待交车？ | 总库存包含两个子集；不能将总库存与子集相加 |
+| 超期定位 | 异动维修还没结束而且已经超期的有哪些？ | 仅包括未完成且超过预计完成时间的车辆，显示明细依据 |
+| 时间口语 | 最近一周交退换怎么样？和前一周比一下 → 换成表格 | 固定相同长度比较期间；切换展示不改变时间和比较条件 |
+| 车辆指定 | 看一下浙A12345当前是什么情况 | 现有权限内查询对应车辆，不因自然文本被固定词表拦截 |
+| 正常零结果 | 嘉兴有待交车吗？（样本中为 0） | 清楚回答 0，保留范围；不标记为未识别或生成失败，不自动进入需求池 |
+| 能力说明 | 你能帮我分析些什么？ → 库存和可运营库存有什么区别？ | 直接说明口径或给可用示例；不把正常帮助对话登记为未满足需求 |
+| 缺少数据 | 能算每台车的租赁毛利吗？ | 说明当前缺哪些数据；不拿运营率替代毛利；记录实际需求且给出相关可用方向 |
+| 原因解释 | 为什么这个城市库存高？ | 先给已知分布证据，区分相关性和原因；没有业务原因数据时明确说明，不编造客户流失等原因 |
+| 模型异常 | 模拟超时、非 JSON、截断或无效计划 | 简单可识别问题可以规则降级，并明确提示；复杂问题不能静默退成全部资产 |
+| 权限一致 | 无权查看的车辆 / 公司 / 历史结果 | 沿用账号权限；模型选择不能扩大可见范围；导出重新核验权限 |
+| 需求反馈 | 未支持问题 → 我的需求 → 标记未解决 → 管理员处理 | 保存用户实际需求，状态可追踪；重复点击同一结果的主动反馈只记录一次 |
+
+## 实机验收方法
+
+1. 用真实模型跑口语、修正、澄清、历史分支四组会话，每组至少五轮；保留问题、生成计划和可核对结果。
+2. 用图表操作和文字提问交替完成同一个分析，核对筛选条件、总数和明细。
+3. 用桌面和手机分别完成输入、停止、重试、切换结果、导出；不得把旧结果误标成当前上下文。
+4. 检查需求池：正常帮助、澄清和零匹配不能污染需求池；不支持的真实需求应可读、可归类。
+5. 报告分别列出通过、失败及未验证项，明确真实模型验证与模拟集成测试的区别。
+
+
+## 本轮验证结果（2026-09-23）
+
+- 全量 176 项自动化测试通过，TypeScript 检查与生产构建通过；含 22 项规划器测试、17 项会话路由体验测试。
+- 真实 DeepSeek Flash 使用合成车辆验证口语库存、车型/型号区分、正负筛选、库存范围重置、Top N 指代、宽泛异常分析、异动详情和历史/预测能力说明。发现的理解偏差修复后重新调用验证通过；这是有限样本验收，不代表所有自然语言均已覆盖。
+- 浏览器合成数据验证桌面 1440×960 与手机 390×844：总库存 4 → 华东 3 → 嘉兴 2 → 取消城市恢复 3；异动 1 台并保留类型和预计完成时间；帮助后可继续提问，旧回答可折叠。手机无页面横向溢出，控制台无错误和警告。
+- 未进行生产部署、生产数据库需求表建表验证或长期真实用户效果评估。本轮保留工作区修改，未提交、推送或发布。
+
+开发复盘：问题根因是封闭词表先行拦截、模型只负责展示、会话没有传递实际问答及结果上下文。改为模型完整规划并用真实中文多轮样本验证。本轮证据属于项目改造，不新增全局开发知识候选。
+
+
+## 合入 main 的补充验证
+
+入口移至资产页右下角，移除原顶部入口与资产页反馈悬浮按钮；保留其他模块既有入口。桌面与 390px 手机已验证打开、关闭后焦点恢复和底部导航不遮挡。合并沿用 main 的数据库模块与只读预览设置，补充只读账号导出/会话清理及需求记录只读测试。合并版本共 276 项测试通过，类型检查与生产构建通过。

docs/asset-ai-safe-analysis.md

@@ -0,0 +1,36 @@
+# 资产 AI 会话分析与需求反哺
+
+## 会话能力
+
+- DeepSeek Flash 理解完整自然语言、当前分析状态、近期问答和可回到的历史结果，生成完整统计方案。支持口语、纠正、否定、切换主题和连续追问。
+- 内部程序执行筛选和计算；图表点击、文字追问、历史结果分支共享同一分析条件。澄清后补充条件仍承接最近有效的分析范围。
+- 区域、城市、车型、型号、部门、运营状态支持多层下钻和双维度交叉统计；支持排除条件、指定车辆、排名和排序。Top N 仅限制分组展示，总量、占比和明细仍基于完整筛选范围，界面明确显示口径。
+- 库存包含异动和待交车，子集不重复累加。支持超预计完成时间、未来 7 天到期、未填写预计完成时间的异动车辆定位，明细保留异动类型与预计完成时间。
+- 交退换车按日趋势支持上一等长周期比较，单次最多 93 天；替换交车包含在交车中，基期零不计算增长率。资产历史快照、成本、预测等数据能力尚未接入，说明原因并给下一步建议。
+- 展示包含指标、结论、图表、统计表、异常入口、车辆明细、导出。历史回答默认折叠，可展开或作为追问起点；当前范围可修改、清除或另起话题。
+
+## 模型接入
+
+按本轮产品要求，停用此前新增的封闭词表、未知文本拦截与实体代号投影。有 `DEEPSEEK_API_KEY` 时默认启用模型；显式 `ASSET_AI_EXTERNAL_ENABLED=0` 才使用本地规则。Compose 默认值已改为 1，既有容器如果显式设置了 0，需要重新配置并部署。
+
+模型请求包含当前问题原文、最近会话文本、结构化分析条件、历史结果候选、当前结果的分组与指标和当前可见车辆的维度目录；问题明确提及某辆车时也包含匹配的车辆标识。历史回答和当前结果上下文包含之前计算得到的汇总数值。**这些内容会发送到 DeepSeek API。** 没有将完整数据库、轨迹或业务台账行打包发送；模型不执行 SQL。正常统计结论仍由内部确定性程序产生。
+
+保留应用既有登录与数据权限、服务端密钥及查询执行机制。界面显示本次使用 DeepSeek 还是本地规则；模型超时、坏 JSON 或服务异常时给出降级提示，不把规则结果伪装成 AI。不会为本轮额外增设安全审批或词表限制。
+
+## 需求反哺
+
+未识别、暂不支持、执行生成失败会自动记录；每个结果也可标记“未解决”。正常帮助、针对性澄清和零匹配数据不作为需求失败。成功的本地降级只显示提示，不冒充理解能力完整的模型回答。
+
+内部 MySQL 表 `bi_asset_ai_gaps` 保存未完成的问题文本（最多 600 字、常见 Key 格式隐藏）、原因、用户、次数和处理状态，不保存完整会话。按用户、问题与原因去重；用户对同一个结果重复点击“未解决”只记一次。普通用户查看本人记录；沿用反馈管理角色查看全部、设置待评估/已纳入计划/已解决/暂不处理。已解决需求再次出现会重新打开。
+
+最近出现超过 90 天的记录会清理。数据库不可用时明确显示未保存。需求记录用于产品改进，不自动训练模型，不建立长期个人记忆，不向模型同步需求池。
+
+## 部署与会话生命周期
+
+环境变量和 Portainer 操作见 [部署说明](portainer-deepseek.md)。需求表复用现有 MySQL 连接，首次访问自动创建；预建 SQL 在 `src/server/db/schema/asset-ai-gaps.ts`。表不可用不影响正常统计。沿用 `main` 既有只读预览配置时不写入或清理需求记录。
+
+会话仅在应用进程内保存，闲置 1 小时失效；每用户最多 10 个会话，每会话最多 100 步。重启后可用原问题开启新对话，但不能恢复旧的分析范围。多副本需要粘性路由或共享会话存储。取消本轮新增的每日/每分钟问数额度，仅阻止同用户同时重复执行请求。
+
+## 验证
+
+自动化场景覆盖自然语言规划真实影响查询、连续纠正和排除、澄清上下文、历史分支、Top N 统计口径、异常期限、清除筛选、帮助与零结果、能力缺口与反馈、模型故障降级和现有权限。见 [体验验收语料](asset-ai-experience-cases.md)。浏览器与真实模型探针均使用合成车辆，不向业务库写测试记录。

docs/portainer-deepseek.md

@@ -1,5 +1,7 @@
 # Portainer 部署资产 AI 问数
 
+配置 Key 后默认使用 DeepSeek Flash 理解自然语言与会话上下文；`ASSET_AI_EXTERNAL_ENABLED=0` 可显式关闭模型。此前版本显式配置了 0 的 Stack，请改为 1。模型会收到问题原文、近期会话、分析条件和相关维度目录，详情见 [会话分析说明](asset-ai-safe-analysis.md)。
+
 DeepSeek Key 由 Node 服务端在运行时读取，变量名为 `DEEPSEEK_API_KEY`。模型固定为 `deepseek-flash`，接口为 `https://api.deepseek.com/chat/completions`，部署节点需要能够访问该 HTTPS 地址。
 
 ## Stack 配置
@@ -11,15 +13,16 @@ services:
   ln-bi:
     environment:
       DEEPSEEK_API_KEY: "${DEEPSEEK_API_KEY:-}"
+      ASSET_AI_EXTERNAL_ENABLED: "${ASSET_AI_EXTERNAL_ENABLED:-1}"
 ```
 
-1. 等待 main 分支的 Woodpecker 构建与镜像推送成功。本次版本 1.2.1 对应镜像 `harbor.lnh2e.com/lingniu-v1/ln-bi:main-1.2.1`。
-2. Portainer → Stacks → 现有 `ln-bi` Stack。确认 Compose 的 `image` 使用上述镜像，且保留现有数据库、认证、网络和端口配置。
+1. 等待当前分支的 Woodpecker 构建与镜像推送成功，取得本次构建对应的镜像标签。
+2. Portainer → Stacks → 现有 `ln-bi` Stack。确认 Compose 的 `image` 使用本次构建的镜像，且保留现有数据库、认证、网络和端口配置。
 3. 在 **Environment variables** 中新增名称 `DEEPSEEK_API_KEY`，值粘贴实际 API Key。Compose 必须包含上面的变量引用，才能将 Stack 变量传入容器。
 4. 点击 **Update the stack** 并重新部署，确保拉取新镜像。Git 管理的 Stack 需要从仓库拉取新版 Compose；Web Editor 管理的 Stack 则直接更新编辑器内容。
 5. 登录应用，在资产管理中打开「AI 问数」，查询“当前库存按区域统计”验证。
 
-后续更换 Key 只需更新 Stack 环境变量并重新部署/创建容器，无需重新构建镜像。仅重启旧容器不会刷新其环境变量。未配置 Key 时 AI 问数返回配置提示，其他资产功能可继续使用。
+后续更换 Key 只需更新 Stack 环境变量并重新部署/创建容器，无需重新构建镜像。仅重启旧容器不会刷新其环境变量。未配置 Key 或显式关闭模型时使用本地规则，并在界面提示，其他资产功能可继续使用。
 
 ## 检查是否注入