hebing

.cursor/rules/business-page.mdc

@@ -0,0 +1,63 @@
+---
+description: 业务办理页（present_business_page / H5）编码约束：禁止字段词典硬编码、标签来自页面
+globs: lightbot-ui/src/components/businessPages/**/*,lightbot-ui/src/utils/businessPageHtmlTemplate.js,lightbot-ui/src/views/BusinessPageManage.vue,lightbot-tool/src/main/java/com/lightbot/businesspage/**/*,lightbot-tool/src/main/java/com/lightbot/tool/builtin/PresentBusinessPageTool.java,lightbot-server/src/main/java/com/lightbot/controller/BusinessPageController.java
+alwaysApply: false
+---
+
+# 业务办理页编码规则
+
+## 禁止事项
+
+```text
+❌ 禁止在平台代码中硬编码业务字段中英映射表
+   （如 accountNo→户号、amount→金额、phone→手机号 等 FIELD_LABELS / switch-case 词典）
+❌ 禁止按 pageType 特化前端渲染分支或后端工具逻辑（除注册表元数据外）
+❌ 禁止要求业务 H5 必须手写 postMessage / LightBot SDK 才能完成办理（内嵌 HTML 走静默桥接）
+❌ 禁止把演示接口整段 JSON（含 status/message）当作用户可见摘要正文
+```
+
+## 必须遵守
+
+```text
+✅ 字段展示名来自页面本身：桥接从 label[for] / 包裹 <label> 采集 fieldLabels，随 submit 回传
+✅ 历史恢复用回灌标记 <!--lightbot-bp-data:{"values":...,"fieldLabels":...}-->，勿再造平台词典
+✅ 办结态展示回执摘要（标题 + 状态 + 字段行），不要继续露出可点的「取消/提交」
+✅ 内嵌 HTML 与外链二选一；内容以能力中心登记为准（DB），不预装业务页组件
+✅ 跨模块调用走 Service / Port；Controller 只做透传
+```
+
+## 标签解析优先级
+
+1. 提交载荷 `fieldLabels[fieldKey]`（页面 DOM 采集）
+2. 否则直接展示 `fieldKey`（字段码本身）
+3. **不要**在 `businessPageResultUtils` 或其它平台模块新增业务中文词典
+
+## DOM 采集兼容（桥接 `collectFieldLabels`）
+
+页面中文/英文章摘要不一致，通常是 DOM 结构差异，不是平台硬编码：
+
+| 结构 | 能否采到标签文案 |
+|------|------------------|
+| `<label>户号 <input id="accountNo"></label>` | ✅ |
+| `<label for="name">姓名</label><input id="name">` | ✅ |
+| `<label>姓名</label><input name="name">`（兄弟节点、无 for） | ✅（相邻 label） |
+| `<div><label>姓名</label><input name="name"></div>` | ✅（同容器唯一 label） |
+| 表单项分栏：`div > [.label列] + [.control列>input]`（报名 AI 页常见） | ✅（向上找表单项） |
+| JSON key 与 input name/id 不一致，但字段顺序一致 | ✅（按 DOM 顺序对齐兜底） |
+| 仅有英文 placeholder、无任何 label 文案 | ❌ 回退显示 field key |
+
+业务页应写可见 `<label>`（或 `data-label` / `aria-label`），不要依赖平台翻译 field key。
+
+**现象对照**：填报页是中文、办结摘要是英文 → 优先查回传路径是否带了 `fieldLabels`，不是平台硬编码词典。
+
+典型坑（已修）：
+
+- `<button type="button">` + `fetch` → 走 fetch 拦截（有 fieldLabels）✓
+- `<form>` + `type="submit"` 若在**捕获阶段**抢先 `emitSubmit(values)` → 无 fieldLabels，且绕过页内校验 ✗
+- 正确：submit 用冒泡；页面 `preventDefault`+`fetch` 时交给 fetch 拦截；仅无 JS 的空 action 表单才 FormData 兜底并 `withFieldLabels`
+
+## 相关文件
+
+- 桥接采集：`lightbot-ui/src/components/businessPages/businessPageBridge.js`（`collectFieldLabels`）
+- 摘要工具：`lightbot-ui/src/components/businessPages/businessPageResultUtils.js`
+- 办结 UI：`lightbot-ui/src/components/businessPages/H5BusinessPageFrame.vue`

.gitignore

@@ -33,6 +33,7 @@ lightbot-ui/.env.local
 # Logs
 *.log
 logs/
+.run/
 
 # Claude Code
 .claude/

PRODUCT.md

@@ -0,0 +1,187 @@
+# LightBot 产品定位方案
+
+> 企业版 · 单企业部署 · 建设平台 + 对外 API 集成  
+> 状态：**已确认并落地改造** · 2026-07-30
+
+---
+
+## 1. 一句话定位
+
+LightBot 是企业 AI 能力的**配置与发布中台**：内部建设者共同维护 Agent、知识库、数据中心、工具等企业资产；正式服务通过**企业 API Key** 被外部产品化平台调用，终端用户不登录 LightBot。
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│  LightBot（企业内部建设平台）                            │
+│  登录用户 = 建设者 / 管理员                               │
+│  维护：知识库 · 数据中心 · 工具 · Agent · Prompt …       │
+│                                                         │
+│              │ 企业 API Key                              │
+│              ▼                                          │
+│  外部产品化平台（业务系统 / App / 门户）                  │
+│  终端用户 = 只在外部产品中使用，不注册、不登录 LightBot   │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 部署与边界假设
+
+| 项 | 结论 |
+| --- | --- |
+| 部署形态 | **单企业部署**（一台实例 = 一家企业） |
+| 多租户 | **不做**（无租户 / 部门树 / 行业隔离） |
+| 账号来源 | 首个管理员初始化后，**仅管理员创建账号**；关闭公开自助注册 |
+| 数据隔离原则 | **企业资产共享**；仅**平台内调试会话**按建设者隔离；正式长期记忆按 **API Key + externalUserId** |
+| 正式消费入口 | **仅企业 API Key**（非个人 Key、非终端用户账号） |
+
+---
+
+## 3. 角色定义
+
+| 角色 | 是谁 | 工作场所 | 职责摘要 |
+| --- | --- | --- | --- |
+| **管理员** | 平台负责人 | LightBot | 账号、企业 API Key、系统配置、全站治理与危险操作 |
+| **建设者**（原「普通用户」） | 知识 / Agent / 工具维护人员 | LightBot | **共同维护**企业能力资产；平台内对话仅作调试 |
+| **终端用户** | 业务最终用户 | **外部产品** | 不接触 LightBot；经外部系统 + 企业 API Key 使用 Agent |
+
+### 权限一句话
+
+```text
+管理员  = 人 + Key + 系统（及危险操作）
+建设者  = 企业能力资产的共同维护者
+API Key = 外部产品调用已发布 Agent 的企业凭证
+终端用户 = 只存在于外部产品，不进 LightBot
+```
+
+---
+
+## 4. 两类入口
+
+### 4.1 LightBot 控制台（建设侧）
+
+- 建设者与管理员登录使用。
+- 看到**同一套**企业资产清单（不再按创建人隐藏 Agent / 知识库等）。
+- 建设者可创建、编辑、维护资产；管理员额外管理人、Key、系统配置。
+- 平台内 Chat = **建设调试**，不是对外正式服务形态。
+
+### 4.2 对外 API（消费侧）
+
+- 鉴权：**仅企业 API Key**。
+- 调用对象：已发布且在 Key 策略允许范围内的 Agent。
+- 会话：由外部平台传入或由 API 创建，归属**企业集成身份**，不挂在某个建设者个人名下。
+- 终端用户身份：由外部业务系统自行处理；LightBot **不为终端用户建账号**。
+
+---
+
+## 5. 资源归属与权限矩阵
+
+| 资源 | 归属 | 建设者 | 管理员 | 外部（企业 API Key） |
+| --- | --- | --- | --- | --- |
+| Agent / 工作流 | 企业 | 读写维护（含删除，见 §6） | 同左 + 治理 | 按策略**调用**已发布能力 |
+| 知识库 / 文档 / RAG | 企业 | 读写维护（含删除库，见 §6） | 同左；删库等危险操作可再收紧 | 间接（经 Agent） |
+| 数据中心（模型 / 数据池） | 企业 | 读写维护 | 同左 | 间接 |
+| Tool / MCP / Skill / SubAgent | 企业 | 读写维护 | 同左 | 间接 |
+| 模型 Provider / 默认模型 | 企业 | 可维护；**默认模型变更建议管理员确认或仅管理员** | 全权 | 间接 |
+| Prompt / 评测 | 企业 | 读写维护 | 同左 | 无控制台 |
+| 自动化任务 | 企业 | 读写维护 | 同左 | 无 |
+| **API Key** | **企业** | **无管理入口** | 创建 / 轮换 / 禁用 / 删除 / 绑定 Agent / 限流 | 持 Key 调用 |
+| 平台内会话 / 消息 | **个人（调试）** | 仅本人 | 可选审计（非默认） | — |
+| API 产生的会话 | 企业集成 | **只读排查** | 全权（含清理） | 创建 / 续聊 |
+| Dashboard（含企业 Token 概览） | 企业 | **只读** | 全权 | 无 |
+| LLM Trace | 企业 | **只读排障** | 全权（含清理） | 无 |
+| 用户账号 / 我的账号 | 建设者本人 | 仅本人资料与改密 | 创建建设者 / 管理员 | 无 |
+| 系统配置 / 落地页写 / 企业 Token 限额 | 企业 | 无 | 可写 | 无 |
+| **长期记忆（正式）** | **API Key + externalUserId** | 无配置写权限；调试用 `debug_user_{建设者ID}` | 企业默认策略 + Key 分策略；记忆治理 | 传 `externalUserId` 且策略启用 |
+
+---
+
+## 6. 已采纳的推荐决策
+
+| 决策点 | 采纳结论 |
+| --- | --- |
+| 建设者能否删除「他人创建」的 Agent / 知识库？ | **能**。企业资产无个人所有权；建设者共同维护。危险操作中，**企业 API Key 的禁用/删除、系统配置、用户账号**仍仅管理员。知识库物理删除若需二次确认，产品上可做确认框，但不按「创建人」限制权限。 |
+| API 会话 / Trace 建设者是否可见？ | **可见只读**，便于联调排障；删除 / 清理仅管理员。 |
+| 知识库成员邀请是否为主路径？ | **否**。默认企业内建设者共同可维护；不把「邀请成员」作为主协作模型（实现阶段可弱化或移除个人隔离列表）。 |
+| API Key 维度 | **企业维度**。不挂个人；建设者离职不影响 Key；UI 仅管理员「企业 API Key」。 |
+| 平台内 Chat | 建设调试；会话列表**严格个人隔离**。 |
+| Dashboard / Trace | 对企业建设者**开放只读**；运营级清理与敏感配置归管理员。 |
+
+---
+
+## 7. 企业 API Key（正式消费形态）
+
+### 7.1 产品效果
+
+- 设置入口为 **「企业 API Key」**，仅管理员可见与操作。
+- Key 归属企业，不归属某个员工；删除建设者账号不影响 Key。
+- 外部集成统一使用企业 Key；服务端按 Key 策略鉴权（启用状态、允许的 Agent、限流、过期等）。
+- 内部映射为**企业服务身份**，对外不暴露个人用户。
+
+### 7.2 管理员能力
+
+1. 创建 Key（名称、备注、过期时间）  
+2. 绑定可用 Agent（全部或白名单）  
+3. 启用 / 禁用 / 轮换 / 删除  
+4. 查看企业维度调用量与各 Key 日配额消耗  
+5. **长期记忆治理**：按外部用户查看 / 清空该 Key 下记忆  
+
+### 7.3 建设者
+
+- 控制台**无** API Key 管理页。  
+- 联调所需 Key 由管理员创建后线下发放。
+
+### 7.4 长期记忆与 Token（信息架构）
+
+| 能力 | 主入口 | 说明 |
+| --- | --- | --- |
+| 正式长期记忆 | 开放 API（`externalUserId`）+ 管理员「企业 API Key → 记忆治理」 | 策略：系统管理「长期记忆」企业默认；各 Key 可分策略覆盖。控制台调试用 `debug_user_{建设者ID}`，与正式命名空间隔离 |
+| 企业 Token 用量 | Dashboard 概览；管理员「系统管理 → 企业 Token」 | 不再放在「我的账号」 |
+| 我的账号 | 基本信息 / 改密 / 头像框等 | 仅建设者本人账号相关 |
+
+---
+
+## 8. 控制台体验原则（文案与信息架构）
+
+| 现状倾向 | 目标效果 |
+| --- | --- |
+| 「我的 Agent」 | 「Agent」（企业列表） |
+| 「我的知识库」 | 「知识库」（企业列表） |
+| 「我的 API Key」 | 管理员：「企业 API Key」；建设者：无此入口 |
+| 「个人配置 / Token 用量」 | 移除；记忆与 Token 归企业集成 / Dashboard / 系统管理 |
+| 按 `user_id` 过滤资产列表 | 登录后见**全企业**资产（建设者可写） |
+| Dashboard / Trace 语义含糊 | 明确为**企业运营 / 排障**视图（建设者只读） |
+
+侧栏：建设者隐藏「用户管理、企业 API Key、系统配置写」等管理员能力；保留资产维护与只读看板 / Trace。
+
+---
+
+## 9. 明确不做
+
+- 多租户 SaaS、按客户 / 部门的数据硬隔离  
+- 「每人一套 Agent 工作区」作为产品主模型  
+- 个人维度 API Key  
+- 为终端用户在 LightBot 开账号、以其身份聊天作为正式交付  
+- 公开自助注册（管理员初始化后关闭）
+
+---
+
+## 10. 验收标准
+
+1. 两个建设者账号登录后，看到并维护**同一套** Agent、知识库、数据中心模型、Tool。  
+2. 建设者**不能**管理企业 API Key；管理员可以创建、轮换、禁用。  
+3. 外部系统仅凭企业 API Key 调用已授权 Agent 完成集成；**无需**为终端用户在 LightBot 注册。  
+4. 建设者账号删除后，企业资产与企业 API Key **仍可用**。  
+5. 平台内 Chat 仅作调试；建设者 A **看不到**建设者 B 的会话列表与内容。  
+6. 建设者可**只读**查看企业 Dashboard / Trace / API 会话以便排障；清理类操作仅管理员。
+
+---
+
+## 11. 与实现的关系
+
+本文档定义**产品效果与边界**，作为后续改造的唯一产品依据。实现时按本文角色与资源矩阵收口列表过滤、写权限与 API Key 归属；技术细节（表结构、接口、前端路由）不在本文展开。
+
+相关文档：
+
+- 工程与模块：[ARCHITECTURE.md](ARCHITECTURE.md)、[docs/architecture/module-boundaries.md](docs/architecture/module-boundaries.md)  
+- 版本规划：[ROADMAP.md](ROADMAP.md)  
+- 使用入口：[README.md](README.md)、[QUICKSTART.md](QUICKSTART.md)

QUICKSTART.md

@@ -29,7 +29,11 @@ psql -v ON_ERROR_STOP=1 -U postgres -h localhost -f sql/2026-07-28-init.sql
 psql -v ON_ERROR_STOP=1 -U postgres -h localhost -d lightbot -f sql/insert-sql.sql
 ```
 
-验证：
+该脚本会创建 `lightbot` 数据库并执行 `CREATE EXTENSION vector`。执行账号需要具备建库与创建扩展权限。
+
+已有库升级时不要重跑快照；请按 [SQL 迁移说明](sql/README.md) 执行尚未应用的增量脚本（含企业会话来源、`caller_context` 等）。
+
+验证连接：
 
 ```bash
 psql -U postgres -h localhost -d lightbot -c "\dt"
@@ -132,11 +136,11 @@ pnpm dev
 
 ## 5. 首次使用
 
-1. 打开 <http://localhost:5173>，完成注册或管理员初始化。
-2. 在“模型管理”中检查模型提供商和默认模型配置。
-3. 创建 Agent，发起流式对话。
-4. 需要 RAG 时，再启动 MinIO 与 Milvus，创建知识库并上传文档。
-5. 需要知识图谱时，再连接 Neo4j；需要 Dify 能力时，先配置加密密钥再保存 Dify 连接信息。
+1. 访问前端页面并完成管理员初始化（公开注册已关闭，后续账号由管理员创建）。
+2. 在模型管理中配置可用模型并设置默认模型。
+3. 创建 Agent，或从内置 Agent/工作流模板开始。
+4. 创建会话，选择 Agent 后发起流式对话。
+5. 需要 RAG 时，再启动 MinIO 与 Milvus，创建知识库并上传文档；需要知识图谱时再连接 Neo4j。
 
 ## 6. 常见问题
 

README.md

@@ -14,6 +14,7 @@
 
 <p align="center">
   <a href="QUICKSTART.md">快速启动</a> ·
+  <a href="权限配置.md">权限与数据隔离</a> ·
   <a href="docs/deployment.md">部署指南</a> ·
   <a href="docs/architecture/module-boundaries.md">模块边界</a> ·
   <a href="sql/README.md">数据库与迁移</a> ·