docs: enrich domain glossary and rewrite open questions for handoff

docs/agents/backend.md

@@ -3,12 +3,11 @@
 ## 领域与代码映射
 
 - `oid` 和 `workspace_id` 是同一个工作空间 ID 的历史命名。
-- `AssistantModel.type`：
-  - `0`：普通小助手；
-  - `1`：高级应用；
-  - `4`：页面嵌入。
+- `AssistantModel.type` 实际值域 `0`–`4`：`0` 普通小助手；`1` 高级应用；`4` 页面嵌入；`2`、`3` 为遗留兼容值，行为分别等同 `0`、`1`，当前无创建入口。
 - `AssistantModel.domain` 表示对接目标系统的域名，不是业务领域。
 - `DataTraining` 是「SQL 示例库」概念的持久化命名。
+- `Chat.chat_type` 目前只有 `chat` 一个有效值；`datasource` 是为未实现的表字段备注自动生成功能预留的遗留值。
+- `ChatRecord.recommended_question` 同时承载两种内容：开场记录中是数据源配置的推荐问题，普通记录中是模型生成的猜测问题。
 
 ## 代码组织
 
@@ -85,7 +84,7 @@ Endpoint 命名沿既有风格：
 1. `POST /chat/start` 与 `POST /chat/assistant/start` 在工作空间内创建会话，并可绑定初始数据源或助手上下文。
 2. `POST /chat/question` 先解析快速命令。普通问题进入 `stream_sql`；`/regenerate` 直接再生。`/analysis` 和 `/predict` 在会话内会直接拒绝（temporary not supported），实际通过 `POST /record/{chat_record_id}/{action_type}` 触发。
 3. `stream_sql` 构造 `LLMService`，创建 `ChatRecord`，并启动异步执行。
-4. 已绑定数据源时，服务先提取关键词并扩展术语，再筛选适用的术语、SQL 示例和自定义提示词，随后组装 SQL 消息。
+4. 已绑定数据源时，服务先提取关键词并扩展术语，再筛选适用的术语、SQL 示例和自定义提示词，随后组装 SQL 消息；筛选的作用域、命中和组合规则见 `docs/agents/knowledge-enhancement.md`。
 5. 未绑定数据源时，先由模型选择数据源；服务随后校验数据源访问权和连接可用性。
 6. 模型生成 SQL 后，服务解析 SQL、对照允许的表元数据校验引用表，并按需应用行权限或助手动态 SQL 变换。
 7. 服务执行最终 SQL，规范化大数字和带限定名的列结果，并持久化查询结果。
@@ -95,4 +94,12 @@ Endpoint 命名沿既有风格：
 
 `ChatFinishStep` 允许一次执行在生成 SQL、查询数据或生成图表后停止。不要假设所有调用方都需要完整图表流程。
 
+### 记录状态与衍生关系
+
+- 记录终态二元：`finish=true` 即终态，`error` 非空即失败。生成 SQL、执行、图表任一阶段失败都写同一个 `error` 字段；失败阶段从已填充字段推断（有 SQL 无数据为执行失败，有数据无图表为图表失败），精确失败点看 ChatLog 的 `error` 标记。
+- 分析和预测各生成一条新的完整记录，复制源记录的问题、图表和数据，以 `analysis_record_id` / `predict_record_id` 指回源记录；衍生记录不能再被分析、预测或再生。
+- 再生记录以 `regenerate_record_id` 指向被再生记录，形成链，沿链回溯可取到原始问题。
+- 开场记录（`first_chat=true`）不能被分析、预测或再生；查找"上一条记录"时排除开场记录。
+- 问题快捷入口按位置分两个标签："猜你想问"是会话级快捷提问入口（开场记录展示数据源配置的推荐问题，输入框区域展示生成的猜测问题）；"继续问"是每次成功回答后的追问入口（生成的猜测问题）。
+
 验证要求与测试选择标准见 `docs/agents/testing.md`。

docs/agents/domain-open-questions.md

@@ -2,63 +2,68 @@
 
 这份文件是待查证目录，不是每项任务都要逐条询问的问卷。只处理影响当前任务的边界，先检查源码、测试和已有文档；仍无法确定且影响业务决策时再询问使用者。问题确认后，把稳定术语移入根目录 `CONTEXT.md`，行为规则放入对应按需文档，再从本文删除对应问题。
 
+2026-09-24 全量查证过一轮（主仓库 + sqlbot-xpack 可读源码）：各节"已确认"为代码事实，对应词条已入 `CONTEXT.md`；标注【待答】的问题需要产品/设计判断，均附代码现状，回答后按开头流程归档（"设计 vs 待修"类问题需二选一：按现状入档+风险注记，或转待修项）。
+
 ## 工作空间与用户
 
-- 用户在工作空间中的角色如何定义？`UserWsModel.weight` 的取值和含义是什么？
-- 系统管理员、工作空间管理员、普通用户、数据源管理员之间的权限边界是什么？
-- 用户是否可以同时属于多个工作空间？切换工作空间对会话、数据源、模型和助手上下文有什么影响？
+已确认：成员权重 0=普通成员、1=工作空间管理员（-1 为"无关联记录"哨兵）；系统管理员为内置 id=1 的 admin 账号，与成员权重正交；用户可同时属于多个工作空间，当前工作空间是用户表上的单值；数据源可见性=工作空间归属。
+
+【待答】
+- "数据源管理员"这一角色叫法是否存在于产品文案？代码中不存在该角色：数据源管理接口全部要求工作空间管理员，行/列权限面向普通用户配置。
+- 用户-工作空间关联表（sys_user_ws）无 (uid, oid) 唯一约束，理论上可出现重复关联行。接受现状还是待修？
 
 ## 数据源与元数据
 
-- 数据源的完整生命周期是什么？创建、连接校验、元数据同步、启用/禁用、删除分别如何界定？
-- Excel 数据源在领域上是普通数据源的一种，还是有独立生命周期和限制？
-- 表关系、表备注、字段备注、embedding 的业务含义和维护责任分别是什么？
-- 高级应用动态数据源与普通数据源在领域上的差异是什么？
+已确认：创建时不校验连接（校验是独立步骤，重新勾选表前强制执行）；元数据同步无定时任务，仅创建、重新勾选表、单表字段同步三个触发点；数据源级无启用/禁用（仅表/字段级）；Excel 为物化进内置库的导入型数据源；表关系人工维护、无自动推断；备注为"同步值 + 用户值"双轨且用户值优先；表级/数据源级两级 embedding；动态数据源每次会话实时拉取宿主 API、不落库。
 
-## 知识增强
-
-- 术语、SQL 示例、自定义提示词的作用域规则是否完全一致？
-- 当同一问题命中多个术语、多个 SQL 示例或多个自定义提示词时，选择和组合规则是什么？
-- embedding 相似度、关键词匹配和高级应用/数据源绑定之间的优先级是什么？
+【待答】
+- 删除数据源时不清理推荐问题（ds_recommended_problem）和行/列权限（ds_permission、ds_rules），成为孤儿数据。接受现状还是待修？
+- CoreDatasource.status 全代码只见赋值 "Success"；是否存在其他历史取值或预期取值（如连接失败标记）？
 
 ## 权限
 
-- 工作空间权限、数据源权限、行权限、列权限、API 权限如何叠加？
-- 权限冲突时使用交集、并集还是显式拒绝优先？
-- 页面嵌入、高级应用和 MCP 场景下的用户身份与数据权限如何映射？
+已确认：数据源可见性=工作空间归属（硬边界，校验失败拒绝）；行权限多条命中 AND、列权限多条命中求交；无 deny 语义；admin（id=1）绕过行/列权限；高级应用不走本地行/列权限、改用宿主表级 rule；行权限经 LLM 改写 SQL 执行；列权限只作用于提供给模型的表结构和数据预览。
+
+【待答】
+- 行权限的强制执行方式是"LLM 改写 SQL"，无确定性的 WHERE 注入或结果集二次过滤兜底。按现状入档+风险注记，还是列待加固项？
+- 行/列权限未命中任何规则即不限制（fail-open）；white_list_user 字段在权限两个模型中已定义但全代码无读取。同上二选一。
 
 ## 助手与集成
 
-- `AssistantModel.type` 目前确认 `0` 普通小助手、`1` 高级应用、`4` 页面嵌入；是否还有其他历史值或保留值？
-- 普通小助手、高级应用、页面嵌入在目标系统认证、数据源获取和页面能力上的完整差异是什么？
-- `app_id`、`app_secret`、`domain` 与目标系统信任关系如何建模？
+已确认：type 实际值域 0/1/2/3/4，2≡0、3≡1（遗留兼容值、无创建入口，已记入 backend.md）；普通小助手/高级应用/页面嵌入三形态的认证、数据源获取、页面能力差异已查明；domain 是 origin 精确白名单、仅握手类接口校验、运行期 API 不校验；app_id 仅反查、app_secret 作 HMAC 验签。
 
-## Chat 流程与产物
-
-- `Chat.chat_type`、`Chat.origin`、`first_chat`、`regenerate_record_id` 等状态字段的完整业务含义是什么？
-- 分析记录、预测记录和普通问答记录的生命周期与展示关系是什么？
-- 生成失败、执行失败、图表失败时，`ChatRecord` 的最终状态如何界定？
-- 猜测问题和推荐问题在产品展示上是否使用相同入口？二者是否需要统一命名？
+【待答】
+- /system/assistant/info/{id}、/system/assistant/app/{appId} 在认证白名单内且响应未剔除 app_secret：通过 origin 校验的页面即可获取应用的 app_id 与 app_secret。按现状入档+风险注记，还是列待加固项？
+- type=3 除与 type=1 共用动态数据源分支外是否曾有专属语义？（代码无单独分支，历史命名无法追溯。）
 
 ## 模型配置
 
-- 供应商、模型类型、基础模型、模型名称、默认模型、工作空间映射之间的准确关系是什么？
-- 系统默认模型和工作空间可用模型的决策顺序是什么？
-- 自定义模型在助手和 MCP 场景中的约束是什么？
+已确认：模型名称是显示名、基础模型是真实模型标识；默认模型为系统全局唯一标志（首个模型自动成为默认、禁删），无"工作空间默认模型"概念；工作空间映射决定可选范围；选型链为助手自定义模型 → MCP 指定模型 → 系统默认，指定模型校验失败静默回退；embedding 使用固定本地模型，不走供应商/默认模型体系。
+
+【待答】
+- 助手/MCP 指定模型会校验其属于当前工作空间的映射，但回退到系统默认模型时不校验默认模型是否映射到该工作空间。设计如此还是缺陷？
+- model_type 字段存而不用（前端仅 0=大语言模型有效，运行时引擎实际由 protocol 决定）。遗留预留还是待实现？
 
 ## 仪表板
 
-- 仪表板只能由会话图表创建，还是也可以独立创建和编辑？
-- 仪表板组件、会话记录、图表配置之间的归属关系是什么？
-- 仪表板查看和编辑权限如何与工作空间、数据源权限叠加？
+已确认：可独立创建（含文件夹、文本、Tab 组件），非只能来自会话图表；图表组件是会话图表的整份配置快照（无外键引用），查看时按快照内数据源+SQL 实时重执行，数据源被删则该组件标记失败；仅创建者本人可见可改；无分享无导出。
+
+【待答】
+- 仪表板纯私有（无分享/协作）是否为产品定位？
+- 删除会话不级联删除其记录（无外键、无清理）；删除文件夹不级联删除子节点（孤儿在资源树上不显示）。接受现状还是待修？
 
 ## MCP 与嵌入
 
-- MCP 调用者、工作空间和数据源之间的授权关系是什么？
-- 页面嵌入、小助手嵌入、MCP 在产品分类上的边界是什么？
+已确认：MCP 为独立服务进程（8001 端口），暴露 7 个工具；调用者以真实用户身份接入，数据源授权=其工作空间全部数据源（无显式授权列表）；行/列权限按该用户生效；另有 Open API 形态（API Key 验签映射到真实用户）；页面嵌入、小助手嵌入、MCP 的认证边界已查明。
+
+【待答】
+- mcp_model_list（仅凭 oid 即返回该工作空间模型列表）与 mcp_assistant（构造内置用户、无调用方鉴权）两个无鉴权入口：产品上有外层防护预期（网关/内网部署）还是待修？
+- mcp_question 不校验会话归属：持有有效 token 加 chat_id 即可向他人会话提问（主应用 /chat/question 有权限装饰器而 MCP 路径没有）。设计如此还是待修？
+- Open API（API Key）是否作为第四种对外暴露形态在 CONTEXT.md 立词条？
 
 ## xpack 商业概念
 
-- 许可证能力项、版本限制和功能开关如何影响领域对象？
-- 认证源、平台集成、审计日志和商业权限的领域边界是什么？
-- xpack 侧是否需要独立 `CONTEXT.md` 来维护商业扩展术语？
+已确认：许可证仅整体有效/失效门控（无功能级能力项，硬校验为 product 与有效期）；有效时才挂载外观、自定义提示词、认证源、平台集成、审计五组路由（到期动态摘除）；行/列权限路由不受许可证门控；认证源=SSO 身份源、平台集成=企业 IM 对接、审计=查询侧在 xpack、写入侧在主仓库。词条已入 CONTEXT.md"商业扩展（xpack）"小节。
+
+【待答】
+- 许可证数据的 edition、count 字段已定义但代码不消费（可能在 validator 二进制内部检查）。按现状记录，还是属于待实现？

docs/agents/knowledge-enhancement.md

@@ -0,0 +1,41 @@
+# 知识增强
+
+术语、SQL 示例和自定义提示词在问数流程中按作用域注入模型上下文。概念定义见根目录 `CONTEXT.md`；本文记录作用域、命中和组合的行为规则，修改相关知识逻辑前先对照本文确认预期行为。
+
+## 作用域规则
+
+三类知识的作用域维度不完全一致：
+
+| 维度 | 术语 | SQL 示例 | 自定义提示词 |
+|---|---|---|---|
+| 工作空间级（全局） | 支持 | 不支持 | 支持 |
+| 数据源级 | 支持多选 | 仅单选 | 支持多选 |
+| 高级应用级 | 支持 | 支持 | 支持 |
+| 任务环节分类 | 无 | 无 | 生成 SQL / 分析 / 预测 |
+
+- SQL 示例必须绑定一个数据源或一个高级应用，没有工作空间级示例；两者都为空时不注入任何示例。
+- 数据源场景取并集：工作空间级知识 + 绑定当前数据源的知识。
+- 高级应用场景取替换：只注入绑定该高级应用的知识，工作空间级知识不生效。这是有意设计，不是缺陷。
+- 作用域的工作空间解析：普通小助手按助手所属工作空间；页面嵌入助手按当前用户的工作空间；高级应用按助手所属工作空间并使用应用绑定。
+
+## 命中与组合规则
+
+- 组合语义是“命中即注入”：命中多少条注入多少条，不做全局排序或择优。
+- 术语：优先用 LLM 提取的关键词匹配（无关键词时用原始问题），按逗号拆分逐词匹配；同义词命中归并到主词条目。
+- SQL 示例：用完整问题做双向包含匹配（问题包含示例问题，或示例问题包含问题）。
+- 自定义提示词：不做问题匹配，作用域内全部注入。
+- 关键词/包含匹配与 embedding 召回是并集关系，不是优先级关系：embedding 只是补充召回渠道，不淘汰关键词命中的结果。
+- `EMBEDDING_ENABLED=false` 时退化为纯关键词/包含匹配。
+- embedding 召回按相似度降序取 top N（默认 5）、相似度阈值默认 0.4，由 `EMBEDDING_*_SIMILARITY` / `EMBEDDING_*_TOP_COUNT` 配置。
+- 注入顺序固定：自定义提示词 → 术语 → SQL 示例，各自独立成段附在 schema 信息之后。
+- 术语另有一个独立用途：提取的关键词经术语同义词扩展后用于表匹配，与术语注入互不影响。
+
+## 已知边界
+
+- 关键词/包含匹配的命中数量没有上限，极端情况下可能注入大量内容（token 风险）；只有 embedding 召回受 top N 限制。
+
+## 代码入口
+
+- 命中与作用域查询：`backend/apps/terminology/curd/terminology.py`、`backend/apps/data_training/curd/data_training.py`、`sqlbot-xpack/src/sqlbot_xpack/custom_prompt/curd/custom_prompt.py`。
+- 注入编排：`backend/apps/chat/task/llm.py` 的 `filter_terminology_template` / `filter_training_template` / `filter_custom_prompts`。
+- `backend/apps/settings/models/setting_models.py` 的 `term_model` 是无引用的遗留代码，与术语功能无关，不要在其上扩展。