阶段 1：权限模型沟通：已确认
阶段 2：套餐字段与档位沟通：已确认
阶段 3：数据库表结构确认：已确认
阶段 4：API 契约确认：会话 + 设置 + 安装安全已确认
阶段 5：页面联调与上线计划：安装页功能开发计划已确认
1. 角色分层：super_admin、tenant_admin、tenant_supervisor、agent。
2. tenant_supervisor 不可管理成员；可查看成员并分配会话。
3. agent 会话可见范围：仅“分配给自己 + 自己参与过”。
4. agent 可发消息/回复/翻译/关闭/标签/附件/备注/转派。
5. agent 删除权限：可删除自己消息 + 自己创建的会话。
6. 转派不按部门限制，弹窗显示的客服都可转派。
7. tenant_admin 对 套餐/账单/密钥 仅只读，不可修改。
1. 对话/月（max_conversations_per_month）保留并由套餐额度生效
2. 限额字段：max_agents、max_ai_tokens_per_month、max_integrations、history_retention_days
3. 功能开关：ai_agent、ai_translation、remove_branding
4. data_encryption 作为营销项，当前不纳入实际功能实现
1. 消息删除：物理删除（直接从数据库删除）。
2. 会话删除：物理删除（直接从数据库删除）。
3. 备注：只保留最新一条，不保留历史版本。
4. 附件存储：Cloudflare（建议使用 R2）。
5. 用户短 ID：自增显示 ID（例如 U-000001）。
6. 转派：不建立历史表，保持简单实现。
1. 采用最简全局未读：使用 conversations.unread_count + conversations.unread。
2. 访客新消息写入时：unread_count + 1，unread = true。
3. 客服打开会话详情时：unread_count = 0，unread = false。
4. 会话列表红点规则：unread_count > 0 显示红点。
5. 说明：该方案为全局已读，不做“按客服个人”未读区分。
1. 在线 LiveChat 系统实时层必须使用 socket.io（P0 必选）。
2. 消息发送走 HTTP（POST），消息下发与状态更新走 socket.io 事件。
3. 轮询不作为主通道，仅作为断线重连后的补偿机制。
4. 首批事件：message.created、conversation.updated、conversation.read、conversation.assigned。
1. GET /api/conversations：会话列表（含 unread_count、最后消息、分配信息）。
2. GET /api/conversations/:id：会话详情 + 右侧用户信息。
3. GET /api/conversations/:id/messages：消息列表。
4. POST /api/messages：发送文本/回复消息。
5. POST /api/messages/upload：上传附件到 Cloudflare R2。
6. POST /api/conversations/:id/read：打开会话即清未读。
7. POST /api/conversations/:id/assign：转派客服。
8. POST /api/conversations/:id/close：关闭会话。
9. DELETE /api/messages/:id：物理删除消息。
10. DELETE /api/conversations/:id：物理删除会话。
1. 按当前 /dashboard/billing UI：不提供租户侧 GET /api/billing/usage 接口。
2. GET /api/subscription/current：当前套餐信息（名称、价格、续费时间、状态）。
3. GET /api/subscription/plans：套餐列表（用于 /dashboard/billing/plans 展示）。
4. GET /api/billing/upcoming：即将扣款列表（type、amount、date）。
5. GET /api/billing/recent?page&pageSize：近期账单列表（type、amount、date、status）。
6. GET /api/billing/payment-method：支付方式卡片信息（品牌、掩码、描述）。
7. POST /api/subscription/cancel：取消订阅（对应 UI 按钮）。
8. POST /api/subscription/change-request：升级/变更申请（对应 UI 的订阅入口）。
1. 安装代码只保留一个租户标识（license/org_id）。
2. widget.js 启动后先请求 GET /api/widget/config/:orgId 获取租户配置。
3. 颜色、默认语言、默认弹窗、按钮位置、头像、表单、超时、安全等均以后端配置为准并自动生效。
4. 去版权由套餐权限控制（remove_branding=false 必须显示平台 Powered by；remove_branding=true 才允许租户控制）。
5. 移除第三方脚本方案，统一使用自有 widget 方案，避免双体系不一致。
1. 当套餐 remove_branding=true 时：租户可选“隐藏 Powered by”或“显示 Powered by xxx（自定义品牌）”。
2. 当套餐 remove_branding=false 时：强制显示平台品牌，不允许隐藏或改成租户品牌。
3. 当前代码现状：settings 预览里是硬编码 Powered by LiveChat，尚未打通“自定义品牌文案/链接”字段。
4. 后续落地字段（已确认）：show_powered_by、powered_by_text、powered_by_link（可选）。
1. Script / React / Vue / SDK 都是“把客服聊天能力嵌入外部网站或 App WebView”的接入方式，不是演示代码。
2. 四种接入方式必须共用同一个 Widget Runtime 与同一套后端接口，禁止做四套不一致实现。
3. 安装代码必须携带租户唯一标识（license/org_id）与 API 基地址，保证能命中正确租户配置。
4. React/Vue 只是对 Runtime 的封装壳；SDK 是 Runtime 的编程接口（open/close/on/send）。
1. 统一必填参数：license（=org_id 对外别名）、apiBaseUrl（这两个由系统自动填充）。
2. 统一可选参数：locale、theme、position、primaryColor、zIndex、debug。
3. 访客识别参数：externalUserId、name、email、avatarUrl、metadata（JSON）。
4. 行为参数：autoOpen（默认 false）、showLauncher（默认 true）、startOpen（默认 false）。
5. 安全参数：nonce（CSP 场景）、trustedOrigin（显式校验来源域名）。
6. 统一约束：四种接入方式参数语义完全一致，只是写法不同；租户端不需要手改参数。
1. 安装页输出的是“已填好参数的成品代码”，不是模板代码。
2. Script：通过 <script> data-* 参数注入（data-license、data-api-base、data-locale...）。
3. React：<LiveChatWidget license apiBaseUrl ... />，底层调用同一 Runtime。
4. Vue：<LiveChatWidget :license="..." :api-base-url="..." />，底层调用同一 Runtime。
5. SDK：LiveChat.init({ license, apiBaseUrl, ... })，再调用 open/close/on/send。
6. App(WebView)：优先 Script 方案；原生 App 通过 JSBridge 向 SDK 透传用户标识与 token。
1. F1 安装页数据源打通：后端返回“已填好参数的四种代码片段”，前端只展示+复制。
2. F2 自动参数注入：租户 UID（license）和线上域名（apiBaseUrl）由后端生成，前端不拼接模板。
3. F3 i18n 修复：清理 settings.sdkDesc 等键名直出，安装页文案全部走翻译字典。
4. F4 一键复制闭环：复制成功提示、复制失败提示、复制内容版本号记录。
5. F5 文档链接可配置：API 文档地址由超管统一配置，安装页直接读取展示。
6. F6 权限控制：仅允许租户管理角色查看并复制安装代码（不开放给普通坐席）。
1. GET /api/widget/install-snippets：返回 Script/React/Vue/SDK 四段最终代码（已注入租户参数）。
2. 返回字段：script/react/vue/sdk、doc_url、updated_at、snippet_version。
3. POST /api/widget/install-snippets/refresh：域名或租户配置变化时重建代码片段缓存。
4. GET /api/widget/install-health：返回 widget.js 可访问性、socket 连通性、配置读取状态。
1. A1 租户打开安装页，不出现占位符（如 YOUR_ORG_ID/YOUR_DOMAIN）。
2. A2 四个 Tab 的代码都可直接复制粘贴并立即生效。
3. A3 任何模板字段变更后，刷新安装页可拿到新代码（含版本号变化）。
4. A4 settings.sdkDesc 等键名不再直出。
5. A5 普通坐席账号不可访问安装代码页。
1. 按默认落库并生效字段（Livechat）：welcome_message、default_language、bg_color、show_team_avatars、form_enabled、auto_open、button_position。
2. 按默认落库并生效字段（翻译）：translation_enabled（总开关）、agent_language（客服语言）。
3. 按默认落库并生效字段（品牌）：show_powered_by、powered_by_text、powered_by_link（受 remove_branding 套餐权限约束）。
4. 双向翻译运行条件：套餐 ai_translation=true 且 translation_enabled=true 且会话页图标开关=开。
5. 超时规则继续使用系统常量 5/10/15/30，不在 Settings 提供编辑入口。
1. tenant_admin：可修改 Settings 中可编辑配置（Livechat、翻译、品牌）。
2. tenant_supervisor：只读，不可改 Settings 配置。
3. agent：只读，不可改 Settings 配置。
4. super_admin：配置平台级能力（如翻译 Provider/Key、安装域名基址），不参与租户日常设置操作。
1. GET /api/organizations/livechat-config：返回租户当前生效的 Livechat + 品牌 + 安全配置。
2. PATCH /api/organizations/livechat-config：仅更新允许字段并立即生效到 widget 端。
3. GET /api/organizations/settings：返回租户通用设置（含翻译总开关/客服语言等）。
4. PATCH /api/organizations/settings：更新租户通用设置并写库。
1. 域名白名单来源：livechat 配置里的 trusted_domains（租户级）。
2. widget.js 初始化时校验当前域名，不在白名单则拒绝启动并返回明确错误。
3. 后端接口（widget 相关）追加 Origin/Referer 校验，双重拦截非法域名请求。
4. 安装页权限：super_admin、tenant_admin、tenant_supervisor、agent 均可查看和复制代码。
5. 安装页输出代码由后端生成并自动注入租户 UID 与线上域名，前端只展示+复制。
1. 加载：外部站点引入脚本后，Runtime 先读取租户配置 GET /api/widget/config/:orgId。
2. 建档：首次访问创建 visitor，创建/恢复 conversation，写入来源页面、语言、设备信息。
3. 实时：前端通过 socket.io 接收新消息、会话状态、分配变更；HTTP 负责发送与持久化。
4. 配置生效：欢迎语、颜色、默认语言、按钮位置、默认弹窗、表单、超时、安全策略实时生效。
5. 品牌生效：remove_branding=false 强制平台品牌；remove_branding=true 才可隐藏或自定义 Powered by。
6. 附件生效：图片/文件走 Cloudflare R2 上传链路，消息里写入附件元数据与可访问 URL。
1. Script 验收：复制脚本到纯 HTML 页面（无需手改），30 秒内可收发消息并进入客服后台会话。
2. React 验收：组件卸载/重挂载后会话不断链，不重复创建 visitor。
3. Vue 验收：路由切换不丢失 Runtime 状态，返回页面后可继续会话。
4. SDK 验收：open/close/on(message)/sendMessage 可用，错误回调可观测。
5. 统一验收：四种方式消息结构一致、翻译逻辑一致、品牌权限一致。
1. 域名白名单：仅允许 trusted_domains 内域名加载并初始化 Widget。
2. 跨域与协议：生产环境统一 HTTPS，配置 CORS 仅放行受信任来源，禁止 *。
3. 租户隔离：每次请求都以 org_id/tenant 上下文校验，绝不允许跨租户读写会话。
4. 滥用防护：访客入口加速率限制、基础风控（IP/UA）与错误降级提示。
1. 验收 A（外站接入）：把 Script 代码粘到任意测试站，Widget 能正常出现并打开会话。
2. 验收 B（实时消息）：访客发消息后 1 秒级出现在 /dashboard/conversations，客服回复实时回到外站。
3. 验收 C（功能一致）：回复/翻译/标签/关闭/转派/备注/附件在外站会话都真实可用。
4. 验收 D（配置一致）：修改 Settings 后刷新外站立即生效（含 Powered by 权限逻辑）。
5. 验收 E（安全）：非白名单域名加载失败并给出可识别错误，不得偷偷放行。
1. 双向翻译 Key 来源：super_admin 在平台后台统一配置（平台级 Provider/API Key）；租户侧不单独维护翻译 Key。
2. 套餐门禁：仅当当前套餐 ai_translation=true 才允许使用双向翻译（免费版默认可用，后续通过套餐额度限制）。
3. 总开关：/dashboard/settings 的“启用翻译”是租户总开关（tenant 级）。
4. 会话开关：/dashboard/conversations 顶部翻译图标是当前会话页开关，默认开启，客服可随时手动关闭。
5. 生效条件：套餐开关 && 租户总开关 && 会话页开关 三者同时为 true 才执行翻译。
1. 访客 -> 客服：访客原文保留，同时自动翻译为客服母语（例如客服中文）。
2. 客服 -> 访客：客服输入原文保留，同时自动翻译为访客语言再发给访客端。
3. 同语种场景不翻译（例如双方都是中文），直接按原文发送与展示。
4. 翻译失败时保留原文并标记失败状态，不阻塞消息主链路。
1. 访客端：只展示目标语言单条内容（不展示双语）。
2. 客服后台：展示双语（原文 + 译文），用于核查表达差异与服务质检。
3. 消息存储：一条消息保存 original_content + translated_content + source_lang + target_lang + translation_status。
1. 当前阶段采用系统默认固定值：5/10/15/30（不可在后台修改）。
2. 规则 1（客服未响应超时，默认开）：agent_response_timeout_minutes=5。
3. 触发：访客发出最新消息后 N 分钟内，当前被分配客服未回复。
4. 动作：自动转派到“在线且可接单”的下一位客服；若无人在线则回到未分配队列，并写一条系统事件消息。
5. 规则 2（会话不活跃，默认开）：inactivity_timeout_minutes=10。
6. 触发：会话双方都无新消息超过 N 分钟。
7. 动作：会话标记为 inactive（不关闭）。
8. 规则 3（自动关闭，默认开）：auto_close_timeout_minutes=15。
9. 触发：会话仍无新消息超过 N 分钟。
10. 动作：会话状态改为 closed，保留历史消息；访客新消息可重新打开会话。
11. 规则 4（删除不活跃访客，默认关）：delete_inactive_visitors_days=30。
12. 触发：访客长期不活跃且未产生有效会话互动。
13. 动作：仅删除“无有效会话历史”的访客档案，避免误删有业务价值数据。
1. 本期超时参数使用系统常量（5/10/15/30），不新增租户可配置字段。
2. conversations 使用现有 status 字段扩展 inactive 状态（open/inactive/closed）。
3. 写入超时动作审计：conversation_events（event_type=timeout_reassign/inactive_marked/auto_closed）。
1. 执行方式：后端调度任务（每 1 分钟扫描一次），统一处理超时，不依赖前端在线状态。
2. 优先级：先执行“未响应转派”→再标记 inactive→再自动关闭。
3. 幂等：同一会话同一规则在同一窗口只执行一次，避免重复转派/重复关单。
1. super_admin：可在平台侧查看超时执行状态与审计事件，不提供参数修改入口。
2. tenant_admin：当前无超时参数修改权限（租户侧不开放）。
3. tenant_supervisor / agent：无超时参数修改权限。
4. 说明：当前 UI 未设计“Settings > Livechat > 超时”入口，且本期不提供超时参数 API。
1. 阶段 5：按安装页功能开发清单执行 F1 -> F6。
2. 阶段 5：完成 Security 白名单与权限联调后进入部署清单。