docs: 补充验收中新发现问题工单
This commit is contained in:
meijiali
@@ -926,6 +926,8 @@ WO-10 收尾与 P1 评估
|
||||
| WO-15 | 公网部署方案与上线验收 | P0 | 从本机 Docker 演示推进到可公网访问的部署 |
|
||||
| WO-16 | UI 产品化改版 | P1 | 在不破坏主链路的前提下提升页面观感和演示质感 |
|
||||
| WO-17 | 默认规模数据量解释与展示优化 | P1 | 把“未达到 1250”解释为真实内容/评论不足，并在 UI 中清楚呈现 |
|
||||
| WO-18 | 长时间 running 但无进度排查 | P0 | 定位任务是否真实运行，避免页面状态与数据库事实不一致 |
|
||||
| WO-19 | Internal Network Error / 500 统一排查 | P0 | 让按钮、刷新、搜索、导出失败时给出可理解错误，不再黑盒报错 |
|
||||
|
||||
### WO-11 全站 Internal Server Error 排查与兜底
|
||||
|
||||
@@ -1291,11 +1293,169 @@ feat: 展示默认规模目标与实际抓取差异
|
||||
|
||||
- 是否需要在报告里显示“样本不足，不代表完整舆情”的提示。
|
||||
|
||||
### WO-18 长时间 running 但无进度排查
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户反馈任务详情页显示“运行中”，但等待接近 3 小时仍无明显进度。
|
||||
- 用户提供的任务 ID：`d1107382-9343-4d8f-9f4f-a1232712bacb`。
|
||||
- 2026-07-03 本地核查结果：
|
||||
- `data/app.db` 中该任务记录不存在。
|
||||
- 该任务对应的热点、内容、评论、报告数量均为 0。
|
||||
- 当前 `data/app.db` 仍是旧 schema，`tasks` 表缺少 `current_stage` 和 `last_progress_at` 字段。
|
||||
- Docker 日志中出现过针对该任务 ID 的 SQL 查询，并伴随 `sqlite3.OperationalError: disk I/O error`。
|
||||
- 这说明当前问题不能简单归类为“TikHub 慢”，需要先确认页面、容器、数据库文件和任务状态是否一致。
|
||||
|
||||
依赖：
|
||||
|
||||
- 依赖 WO-11 中的数据库 I/O 兜底与恢复策略。
|
||||
- 依赖 WO-13 中的任务阶段和最近进度字段。
|
||||
- 依赖 Docker 当前只运行一套 `hot-comments-tool-app-1` 容器。
|
||||
- 开发前必须先确认当前浏览器页面访问的是最新容器和最新镜像。
|
||||
|
||||
目标：
|
||||
|
||||
- 明确判断一个显示为 running 的任务到底是否真实存在、是否仍有后台线程在执行、是否已经被数据库错误中断。
|
||||
- 页面不再只显示“运行中”，而是能显示最近进度时间、阶段、已抓数量和卡住提示。
|
||||
- 对数据库中不存在的任务 ID，页面应显示“任务不存在或数据已恢复/迁移”，而不是长期运行中。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 增加任务详情排查命令或文档步骤：
|
||||
- 查 `tasks` 表。
|
||||
- 查热点、内容、评论、报告数量。
|
||||
- 查最近容器日志。
|
||||
- 查 DB schema 是否包含进度字段。
|
||||
- 后端在启动时确保旧 SQLite 自动补齐 `current_stage`、`last_progress_at`。
|
||||
- 如果旧页面打开了不存在的任务 ID，应返回清晰 404 页面或友好提示。
|
||||
- 如果任务 running 但 `last_progress_at` 长时间不变，应在页面提示“可能等待外部接口或后台任务已异常，请查看日志/刷新状态”。
|
||||
- 记录一次针对 `d1107382-9343-4d8f-9f4f-a1232712bacb` 的复盘结果。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 浏览器打开的是旧任务 URL，但数据库已经恢复或切换。
|
||||
- Docker 容器运行的是旧镜像，本地代码已经更新但容器没有 rebuild。
|
||||
- SQLite WAL / SHM 文件和主库不一致导致查询异常。
|
||||
- 后台线程已停止，但任务状态仍停留在 running。
|
||||
- 任务记录存在，但所有计数都为 0。
|
||||
- 任务记录不存在，但前端仍在轮询该 ID。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 对 `d1107382-9343-4d8f-9f4f-a1232712bacb` 的状态有明确结论，并写入完成记录。
|
||||
- 不存在的任务详情页不会误导用户以为仍在抓取。
|
||||
- running 任务页面能看到阶段、最近进度时间和数量。
|
||||
- running 任务长时间无变化时，页面出现明确提示。
|
||||
- Docker 重建后旧 DB schema 自动补齐进度字段。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
fix: 排查并修复任务 running 无进度状态
|
||||
```
|
||||
|
||||
Git 流程：
|
||||
|
||||
- 从当前 MVP-2 commit 后开始新改动。
|
||||
- 先提交测试或复现记录，再提交修复代码。
|
||||
- 完成后运行相关测试和 Docker 健康检查。
|
||||
- 单独 commit，不与 UI 大改或公网部署混在一起。
|
||||
- 验收通过后再 push。
|
||||
|
||||
待确认：
|
||||
|
||||
- 对“长时间无变化”的阈值，第一版是否使用 10 分钟作为提示阈值。
|
||||
- 不存在的任务 ID 页面是否保留 404，还是跳回首页并显示提示。
|
||||
|
||||
### WO-19 Internal Network Error / 500 统一排查与前端错误提示
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户反馈点击查找、刷新、导出等功能时会看到 `Internal Network Error` 或 `Internal Server Error`。
|
||||
- 当前 Docker 日志已确认首页请求曾因 `sqlite3.OperationalError: disk I/O error` 返回 500。
|
||||
- MVP-2 已新增数据库异常兜底，但当前运行容器可能仍是旧镜像，且前端对不同失败类型的提示还不够统一。
|
||||
|
||||
依赖：
|
||||
|
||||
- 依赖 WO-11 的数据库异常处理、备份和恢复策略。
|
||||
- 依赖 WO-12 的导出失败前端提示。
|
||||
- 依赖 WO-18 先确认当前容器、数据库和任务状态一致。
|
||||
- 需要保留服务端详细日志，不能为了前端友好提示吞掉真实错误。
|
||||
|
||||
目标：
|
||||
|
||||
- 区分并展示三类错误：
|
||||
- 数据库不可用：提示“数据库暂时不可用，正在恢复或请稍后重试”。
|
||||
- 网络请求失败：提示“网络连接异常，请检查服务是否运行”。
|
||||
- 业务不可用：例如报告不存在、任务已存在 running、参数错误。
|
||||
- 前端按钮不再“点不动”或静默失败。
|
||||
- 页面刷新和局部 API 失败时，不直接暴露裸 500。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 梳理所有前端 `fetch` 调用：
|
||||
- 创建任务。
|
||||
- 任务详情轮询。
|
||||
- 任务列表轮询。
|
||||
- Markdown / CSV 导出。
|
||||
- 为非 2xx 响应读取 `detail` 并展示。
|
||||
- 为网络异常展示统一文案。
|
||||
- 后端 API 错误统一返回 JSON `{ "detail": "..." }`。
|
||||
- 页面路由发生数据库异常时展示友好错误页。
|
||||
- 增加测试覆盖：
|
||||
- `/api/tasks` 数据库异常返回 503 JSON。
|
||||
- 页面路由数据库异常返回 503 友好页。
|
||||
- 导出接口 404 / 503 前端能提示明确原因。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 服务未启动，浏览器 fetch 直接失败。
|
||||
- 容器正在重启，短时间连接被拒绝。
|
||||
- 数据库 I/O error。
|
||||
- 任务不存在。
|
||||
- 报告尚未生成。
|
||||
- 评论为空但 CSV 仍应下载表头。
|
||||
- 轮询接口失败时不能无限弹窗打扰用户。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 点击创建任务、刷新、导出、查看报告时，失败都有明确提示。
|
||||
- 数据库异常不再展示裸 `Internal Server Error` 页面。
|
||||
- 导出按钮失败后能恢复可点击状态。
|
||||
- 轮询失败时页面有温和提示，不误报任务完成。
|
||||
- 服务端日志仍保留完整异常栈，方便继续排查。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
fix: 统一网络和服务端错误提示
|
||||
```
|
||||
|
||||
Git 流程：
|
||||
|
||||
- 独立于 WO-18 提交，避免把任务状态修复和全局错误提示混在一起。
|
||||
- 每完成一个错误入口的修复，可以按需拆成小 commit。
|
||||
- 每个 commit 信息写清楚入口，例如 `fix: 优化导出失败提示`、`fix: 优化任务轮询错误提示`。
|
||||
- 本地验收后再 push。
|
||||
|
||||
待确认：
|
||||
|
||||
- 前端错误提示第一版使用页面内 alert 区域，还是保留浏览器 `alert()`。
|
||||
- 轮询失败是否需要显示“最近一次状态同步失败”的时间。
|
||||
|
||||
## 14. MVP-2 推荐执行顺序
|
||||
|
||||
建议先处理阻塞主链路和演示可信度的问题：
|
||||
|
||||
```text
|
||||
WO-18 长时间 running 但无进度排查
|
||||
↓
|
||||
WO-19 Internal Network Error / 500 统一排查
|
||||
↓
|
||||
WO-11 全站 500 排查与兜底
|
||||
↓
|
||||
WO-12 导出点击失效修复
|
||||
@@ -1314,6 +1474,7 @@ WO-17 默认规模数据量解释优化
|
||||
原因：
|
||||
|
||||
- 500 和导出失效会直接破坏验收，优先级最高。
|
||||
- 当前验收中新发现 running 状态和数据库事实不一致，因此 WO-18 / WO-19 应先于继续做公网部署和 UI 大改。
|
||||
- 进度透明化解决“黑盒运行”的核心体验问题。
|
||||
- Demo 数据和公网部署强相关，应该在部署前明确。
|
||||
- UI 改版适合在主链路稳定后进行，避免把 bug 和视觉修改混在一起。
|
||||
|
||||
Reference in New Issue
Block a user