gochat/docs/fix-plan-2026-07-08.md

GoChat 问题修改计划清单

• 基于: test-report-2026-07-08.md
• 创建日期: 2026-07-08
• 状态说明: [ ] 待办 [~] 进行中 [x] 已完成

---

ISS-03: widget/i18n 缺失 locale 文件导致全局白屏 [P0]

• 状态: [x] 已临时修复
• 目标: 恢复全局页面可用性

已完成

• 将 widget/i18n/index.js 改为只导入存在的 en.json 和 zh_CN.json
• 验证 Campaigns / Dashboard 等页面恢复正常加载

后续可选优化

• 补充缺失的 38 个 locale JSON 文件 (从 Chatwoot 上游拉取或按需创建)
• 或改为动态 import 按需加载 locale, 避免 bundle 过大
• 检查 widget/i18n/locale/ 目录为何缺失文件 (是否 decoupling 时遗漏)

---

ISS-01: Reports 图表永久卡在 "Loading chart data..." [P0]

• 状态: [ ] 待办
• 目标: 修复 reporting_events_rollups 表结构与 GORM 模型不匹配, 使 timeseries 报表 API 正常返回
• 阻断: 需要确认修复方向 (改迁移 vs 改模型)

Step 1: 确认修复方向

• 对比 Chatwoot 上游 reporting_events_rollups 表结构, 确认正确列名
• 确认 GORM 模型 (reporting_event.go:68-78) 与迁移 SQL (000001_init_schema.up.sql:337-353) 哪个是期望结构
• 检查 analytics_query_helpers.go 和 rollups service 中所有引用该表的查询, 确认期望的列名

Step 2: 编写迁移文件

• 新建迁移文件 NNNNN_fix_reporting_events_rollups.{up,down}.sql
• up: ALTER TABLE 调整列名/类型使其与 GORM 模型一致
  • 期望列: date (date), dimension_type (varchar), dimension_id (int), metric (varchar), count (bigint), sum_value (float), sum_value_business_hours (float)
  • 删除旧列: dimension, dimension_value, metric_name, value, value_in_business_hours, period
  • 调整唯一索引: UNIQUE(account_id, date, dimension_type, dimension_id, metric)
• down: 回滚操作
• 迁移文件命名需遵循 backend/migrations/ 的 sequential 编号规则

Step 3: 修改代码 (如选择改模型)

• 若决定改 GORM 模型适配现有表, 则修改 reporting_event.go:68-78 的字段映射
• 同步修改 analytics_query_helpers.go 中所有查询条件 (.Where("date = ?") 等)
• 修改 rollups service 中 ComputeDailyRollup 等方法的写入逻辑

Step 4: 验证

• 运行迁移: cd backend && go run cmd/migrate/main.go up
• 重启后端
• curl 测试: GET /api/v2/accounts/1/reports 返回 200
• 浏览器验证: Reports > Conversations 页面图表正常加载, 不再卡在 "Loading chart data..."
• 控制台无 JS 异常

---

ISS-02: Settings > General 页面白屏 [P0]

• 状态: [ ] 待办
• 目标: AccountId / BuildInfo 组件添加空值保护, 确保页面正常渲染

Step 1: 修复 AccountId.vue

• AccountId.vue:11 添加可选链和空值回退:

  const getAccountId = computed(() => currentAccount.value?.id?.toString() ?? '');
  

• 验证模板中 <woot-code :script="getAccountId" /> 在空字符串时正常渲染

Step 2: 排查 BuildInfo 组件

• 定位 BuildInfo 组件文件 (在 settings/account/Index.vue 中引用)
• 检查 BuildInfo 依赖的数据源, 添加空值保护
• 确认 BuildInfo 渲染失败是否与 currentAccount 相关

Step 3: 排查 SidebarGroup mounted hook 错误 (关联 ISS-04)

• 检查 components-next/sidebar/Sidebar.vue 中 SidebarGroup 的 mounted hook
• 确认是否依赖某个在路由切换时未初始化的 store getter 或 feature flag
• 添加保护或确保数据在 mounted 前已加载

Step 4: 根因排查 (账户数据未加载)

• 确认 accounts/getAccount getter 为何返回空对象 — 检查 account 记录是否在 store records 中
• 追踪登录后 account 数据的加载流程: auth.js → accounts/fetch action → records 填充
• 确认是否存在时序问题: 组件渲染时 account 数据尚未异步加载完成
• 考虑在路由守卫中确保 account 数据加载完成后再进入 Settings 页面

Step 5: 验证

• 浏览器访问 /app/accounts/1/settings/general, 页面正常渲染
• Account ID 区域显示正确的 ID 数字
• 控制台无渲染异常
• 其他 Settings 子页面不受影响

---

ISS-04: 每次页面导航产生 29 个 JS 异常 (SidebarGroup) [P2]

• 状态: [ ] 待办 (与 ISS-02 Step 3 关联)
• 目标: 消除 SidebarGroup mounted hook 的异常噪音

Step 1: 定位异常

• 在 SidebarGroup 组件的 mounted hook 中添加 try-catch 或排查依赖
• 确认异常是否来自某个 store getter 返回 undefined 或 feature flag 未初始化
• 使用 browser_console 抓取完整异常堆栈 (当前 message 为空, 需要更详细的捕获)

Step 2: 修复

• 添加空值保护或确保依赖数据在 mounted 前已加载
• 或在组件中添加 v-if 守卫, 数据就绪后再渲染 SidebarGroup

Step 3: 验证

• 导航至任意 Settings 子页面, browser_console 报 0 个 JS 异常

---

ISS-05: 非致命控制台警告 [P3]

• 状态: [ ] 待办 (低优先级, 可批量处理)
• 目标: 清理控制台噪音

Vue Router 根路由警告

• 在路由配置中添加根路径 / 的重定向规则 (redirect 到 /app/login 或 /app/accounts/:accountId/dashboard)
• 文件: frontend/.../routes/index.js 或 frontend/.../router/index.js

onClose prop 弃用

• 全局搜索 onClose prop 使用, 替换为 @close 事件
• 约 4 处, 可批量替换

ServiceWorker / Lit 警告

• ServiceWorker: 开发环境正常现象, 可在 vite.config.ts 中条件禁用 SW 注册
• Lit 多版本: 检查 package.json 依赖树, 确认是否有重复 Lit 依赖, 执行 pnpm dedupe