kefu/wechat_rpa/UI_COMPONENT_SPEC.md

甄养堂企业微信 AI 自动回复 v2.0 — UI 与交互规格

1. 全局规范

• 参考画布：窗口内容区固定基准为 1630 × 920；Windows 原生标题栏约 45px，完整窗口对应 1630 × 965。小屏幕只做等比可用性收缩，不改变模块顺序。
• 字体：页面标题 HarmonyOS Sans SC Bold / 700；菜单和模块标题 Medium / 500–600；正文 Regular / 400；数字指标 Inter Semibold / 600；Windows 回退 Microsoft YaHei UI。
• 字体文件随程序打包注册；没有安装系统字体时仍使用同一字体资源。
• 左侧导航：点击切换页面；选中态为蓝紫发光圆形图标和浅蓝背景；hover 为浅蓝底；底部监控球在停止时启动监听，在运行时停止监听。
• 数据原则：设计稿里的数值和会话文字是构图示例；运行时显示真实企业微信、队列、档案、AI 与日志数据，不以假数据覆盖业务状态。
• 页面内容区在基准窗口内不显示滚动条；会话正文、任务列表等局部数据区域按需内部滚动。

2. 桌面自动化控制台

顶部状态与任务概览

• 企业微信、AI 服务、发送模式和监听按钮：均展示真实运行状态；自动发送 启动监听，暂停监听 / 恢复监听 安全停止或恢复同一后台线程。
• 监听状态 / 排队 / 今日回复 / 失败：从当前线程、待回复队列和执行日志动态汇总；只读展示，不允许直接改数。
• 任务队列：加载真实待处理会话；筛选和排序图标按既定顺序循环，不改变参考稿的图标、按钮数量或占位尺寸；刷新按钮立即重读队列与档案。

当前任务、执行链路与事件

• 当前处理任务：只读显示客户、已读取消息数、来源消息、回复预览、置信度和模型耗时；没有任务时保持同一卡片区域并显示空状态。
• 终止本任务：二次确认后取消对应未完成回复；转人工：二次确认后停止自动发送并保留档案。
• 自动化执行状态：按真实阶段展示扫描、读取、合并、AI、回填和发送进度；企业微信窗口状态展示窗口识别、当前会话、DPI、人工保护和最小化恢复状态。
• 实时事件：显示最近四条真实事件；查看完整日志 跳转运行日志页。

3. 任务队列

顶部操作

• 自动发送：点击后启动真实监听线程；线程已运行时给出运行中日志，不重复创建线程。
• 暂停监听：点击后安全停止监听；未完成任务保留，恢复监听后继续处理。
• 企业微信、AI 状态胶囊：动态状态展示，不可编辑。

状态带与任务列表

• 处理中 / 等待中 / 待重试 / 平均等待：每 2 秒从真实待回复文件更新。
• 全部 / 处理中 / 等待中 / 待重试：单选筛选；只隐藏不匹配行，不删除任务。
• 任务列表：动态加载、内部滚动、不分页；选择任务后右侧详情同步更新。
• 刷新按钮：立即重读队列和执行记录。
• 空队列：正常运行显示“当前没有待处理任务”，不会伪造设计稿任务；只有 --qt-smoke-test 截图模式在真实队列不足时注入五条隔离的参考构图数据，演示项不能执行删除、转人工或导出。

任务详情

• 会话 ID、等待时间、重试次数、来源消息、当前阶段：只读动态数据。
• 取消任务：要求二次确认；取消未完成自动回复，保留会话档案和执行记录。
• 立即重试：只对所选 retry_wait 任务清除退避并重新排队；发送中、回执不确定、等待人工审核和正常任务受保护。监听未运行时会先启动监听，并在机器人初始化后执行重试。
• 转人工：要求二次确认；取消该任务的后续自动发送并记录转人工日志，会话档案保留。
• 查看完整日志：跳转运行日志页。

4. 会话归档

顶部筛选

• 搜索框：占位文字“搜索客户或会话 ID”，最大 80 字；按客户名、会话 ID 和摘要即时过滤。
• 全部会话 / 今日 / AI 已回复 / 已转人工 / 日期：互斥筛选；筛选仅影响左侧可见列表。
• 导出记录：打开保存对话框，导出全部真实会话及消息为 UTF-8 JSON；取消对话框不写文件。

数据区域

• 最近会话：最多加载 500 份档案，列表内部滚动，不分页；头像、名称、摘要、时间和状态来自档案数据。
• 会话记录：选择左侧会话后加载最近 8 条用于页面展示；区域内部滚动；完整记录仍可从详情和导出读取。
• 客户记忆、业务沉淀：展示长期上下文、挂号登记、回访和人工跟进状态。
• 复制全部记录：打开所选会话的完整记录窗口，可复制完整文本。
• 标记已联系：对选中的真实登记记录更新状态；没有选择时提示。
• 删除所选：二次确认后删除所选会话档案；不可撤销。

5. AI 设置

顶部与分页锚点

• 基础设置 / 知识与工具 / 安全策略：互斥选中；点击滚动定位到对应模块，不重排页面。
• 测试 AI：先做配置预检，再异步调用真实 ai_chat.call_ai_text；只有收到非空响应才显示成功，模型未保存或请求失败会返回真实错误。
• 保存并发布：校验 MCP JSON 后保存客服名、主模型、上下文轮数、最大回复、温度、工具开关和工具轮数；成功或失败给出短时状态反馈。

表单限制

• 客服名称：可编辑，最大 40 字；空值回退云端客服名。
• 人格提示词：明确标注为只读安全模板摘要，避免在 UI 层绕过现有 build_system_prompt 安全拼装逻辑。
• 当前模型：点击可输入模型标识并持久化为 AI_MODEL；备用模型由云端策略管理，本地点击只显示说明，不伪装成已切换。
• 上下文：1–50 轮；最大回复：50–32000 tokens；温度：0.00–2.00。
• MCP 最大轮数：1–20；高级 JSON 根节点必须为数组，否则禁止保存并显示错误。
• 立即同步：执行真实云端配置同步；管理知识：打开本地数据目录。
• 数据区为动态状态展示；知识库、工具和安全策略卡片不分页。

6. 自动化设置

模式与保存

• 自动发送：AI 回复通过全部安全校验后自动按 Enter，并按真实聊天证据核对回执。
• 审核后发送：完成识别、AI 生成和全部发送前校验，只把回复填入企业微信输入框，绝不按 Enter；任务持久化为“等待人工审核”，人工发送后再按真实聊天证据完成归档。
• 两个模式按钮互斥，写入 send_mode；运行中修改会热更新，下一条回复起生效，经典界面共享同一配置。
• 保存设置：立即保存；输入控件修改后 500ms 自动保存，成功或失败短时显示状态。

输入与开关

• 扫描间隔：0.2–300.0 秒。
• 连续消息等待：使用运行时允许的消息合并最小值和最大值。
• 发送前等待：独立参数 0–30 秒，发生在任何剪贴板/输入操作之前，可被停止或删除任务打断；等待结束重新执行任务与安全检查。
• 人工操作保护恢复：独立参数 0–3600 秒，默认 5 秒，不与发送前等待共用。
• 固定回复：最大 120 字；空值保存时使用安全默认回复。
• 人工操作保护开关：开启后只在鼠标达到静止时间后自动操作。
• 重新检测：调用真实企业微信窗口检测并报告句柄或失败原因。
• 诊断、用药调整、投诉退款是内置只读风险类别，使用禁用状态而非空点击；规则管理 跳转到“AI 设置 → 安全策略”。

7. 运行日志

顶部操作

• 实时刷新：默认开启；点击暂停可见事件流更新，再次点击恢复。暂停不影响后台日志落盘。
• 导出日志：打开保存对话框，导出当前内存日志为 UTF-8 文本。
• 清空日志：清空内存日志、五行事件流和警告计数；不删除已经落盘的历史日志文件。
• 监控中：只读状态胶囊。

事件流

• 全部 / 连接 / 识别 / AI / 发送 / 警告：互斥筛选。
• 搜索框：最大 80 字，按标题、详情和状态即时过滤。
• 页面保留最近 5 条结构化事件；完整内存日志最多 2000 个文本块，后台磁盘日志独立保留。
• 系统健康、回复链路、异常追踪和最近活动均为动态或运行状态展示，不分页。

8. 系统设置

基础、数据和通知

• 开机启动、启动后监听、最小化到托盘、关闭窗口后台运行、四类通知：可切换；点击“保存设置”后写入本地设置并跨重启保留。
• 最小化到托盘关闭时，运行中的窗口保持在任务栏；开启时进入监控胶囊。关闭窗口后台运行关闭时会正常停止并退出，开启时运行中关闭主窗进入监控胶囊。
• 界面语言当前固定为简体中文；缩放比例选项保存为 Qt 启动偏好，默认“自动”，重启后生效。
• 日志保留：7–365 天。
• 打开目录：打开应用数据目录。
• 立即备份：新建时间戳备份目录，复制存在的设置、档案、队列和登记数据。
• 清理缓存：二次确认后只删除视觉状态和误判缓存，不删除会话及队列。

维护与诊断

• 连接测试：显示本地服务状态。
• 检查更新：读取缓存的发布状态并显示版本信息。
• 导出诊断：保存版本、设置、数据目录和文件清单为 JSON。
• 恢复默认设置：二次确认后恢复系统选项，不删除业务数据。
• 查看许可信息：显示软件版本及随包字体许可说明。
• 系统状态带为只读结果展示，不分页。

9. 原有功能兼容层

• 原 PySide6 页面继续作为真实数据和业务动作的后端，不再作为可见页面重复占位；HTML 七页只负责按参考稿呈现。
• 队列、档案、AI、自动化、日志和系统设置仍复用既有存储、线程、安全校验与导出逻辑，换肤不会绕过原有安全检查或丢失已有数据。