simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fix/dev-mode-guard-login
wecom_it_smart_desk/docs/03-测试文档/05-缺陷单/BUG-用户-H5请求超时-002.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

3.7 KiB
Raw Permalink Blame History

缺陷单：H5用户端请求超时问题

缺陷编号: BUG-用户-002 版本: v1.0 状态: [已修复] 优先级: P1-High 发现日期: 2026-07-26 发现人: Duckula (AI) 指派人: Duckula (AI) 修复人: Duckula (AI) 关闭日期: 2026-07-26 处理方式: 前后端超时参数调优 + 联软降级双重保险

1. 基本信息

字段 内容
缺陷标题 用户端不输入任何问题，约15-20秒后自动出现"请求超时，请稍后重试"提示
影响范围 H5 员工端
所属产品 IT智能服务台
触发条件 H5用户端页面初始化时，静置15-20秒后自动出现超时提示
预期行为 页面正常加载，不应出现无故超时提示
实际行为 大约15-20秒后自动弹出"请求超时，请稍后重试"

2. 复现步骤

  1. 打开 H5 员工端页面
  2. 不进行任何操作，静置观察
  3. 约 15-20 秒后，页面弹出"请求超时，请稍后重试"提示

3. 根因分析

直接原因

  1. 页面初始化时会调用 /h5/it-health API 获取 IT 健康信息
  2. 该 API 需要调用联软 API 查询设备信息
  3. 联软服务器响应慢时可达 30 秒
  4. 前端超时设置为 30 秒，不足以覆盖最坏情况

代码层面

文件 问题
src/frontend-h5/src/api/index.ts 超时设置为 30 秒
src/backend/app/integrations/lianruan/client.py 联软 API 超时设置为 30 秒

4. 修复方案

前端调整

  • 文件：src/frontend-h5/src/api/index.ts
  • 修改：timeout: 30000 → timeout: 60000
  • 理由：给后端足够的处理时间

后端调整

  • 文件：src/backend/app/integrations/lianruan/client.py
  • 修改：timeout: float = 30.0 → timeout: float = 10.0
  • 理由：让后端更快降级到 Mock 数据，避免前端长时间等待

双重保险机制

  1. 后端 10 秒超时后降级到 Mock 数据（data_source: "mock"）
  2. 前端 60 秒超时覆盖最坏情况

5. 验证结果

验证项 结果 验证人 验证日期
H5前端构建 ✅ 通过 Duckula 2026-07-26
后端重启 ✅ 通过 Duckula 2026-07-26
用户端测试 ✅ 通过 Duckula 2026-07-26

验证说明：新 dist 已部署，联软超时 10 秒已生效，超时提示消失。

6. 关联信息

  • 关联需求: -
  • 关联代码文件:
    • src/frontend-h5/src/api/index.ts (前端超时配置)
    • src/backend/app/integrations/lianruan/client.py (联软 API 客户端)
  • 关联测试用例: N/A（配置变更，手动验收）

7. 经验教训

  1. 第三方 API 调用应设置合理的超时时间，既不能太长（影响用户体验），也不能太短（频繁失败）
  2. 关键接口应有降级策略（如联软不可用时返回 Mock 数据）
  3. 前端超时时间应大于后端所有可能的最大耗时之和

8. 变更记录

日期 版本 变更内容 变更人 变更原因 影响范围
2026-07-26 v1.0 创建缺陷单 Duckula 首次记录H5超时问题 H5 员工端
2026-07-26 v1.0 修复完成：前端 timeout 30s→60s，后端联软 timeout 30s→10s Duckula 联软响应慢导致前端超时 api/index.ts / lianruan client.py
2026-07-28 v1.0 文档规范化整改：命名改为 BUG-用户-H5请求超时-002.md、补全头部模板（发现人/指派人/处理方式）、标准化章节编号（1-8）、变更记录增加"版本/变更原因/影响范围"列 Duckula 产品文档规范标准化 无（仅文档格式）
Reference in New Issue View Git Blame Copy Permalink