Web工具交付前的自查Checklist
跳到导航
跳到搜索
1. 目标与验收标准
本轮目标是把 omicscloud 中 metabolite web 工具收敛到可完整运行、可交付、可技术审核的状态。当前已暴露的两个问题作为 P0 修复项，同时覆盖代谢模块的主要路线、关键参数组合、报告生成链路和异常输入边界。
- 单离子/单样本 demo3 split 路线的差异结果与参考网站对齐。
- merge 纯鉴定项目不再因分组/KEGG 列识别导致报错。
- split、merge、sjtu 三条路线至少完成一轮代表性项目回归。
- 定量分析、纯鉴定分析、正负离子/单离子输入、常用预处理参数和报告输出均完成自查。
最终交付衡量标准：
- 分析任务运行成功，日志中无
Error等级报错、无Execution halted、无未处理的REPORT_RENDER_ERROR。 - 生成文件完整，包括
result.rda、report.html、report_server.html、report.docx、report.zip以及关键结果表和图片。 - 报告内容完整，字体、格式、排版在全文保持一致。
- 差异数量、Venn/UpSet、鉴定信息、纯鉴定结果和参考网站或需求口径一致。
- 文档、交付说明和自查 Checklist 通过技术部门审核。
2. 当前已知问题
2.1 单离子 demo3 split 结果口径不一致
项目：
project_id=1782216367szeKmg89zLqr project_root=/home/saitoasuka/mnt/omicscloud/data/13/1782216367szeKmg89zLqr
参考网站 预期差异信息：
CKPG_vs_DMPG diff_feature=234 up=38 down=196 diff_feature_name=226DMQG_vs_DMPG diff_feature=370 up=255 down=115 diff_feature_name=341
DMPG_vs_DMQG diff_feature=370 up=115 down=255 diff_feature_name=341
当前风险点：
1.3 差异信息不能使用拆分并按 name 去冗余后的表覆盖 summary。- 参考网站 的 summary 口径是 raw diff，即
results_mode_diffcmp_name和results_mode_diff_namecmp_name。 - 表格拆分/去冗余仍可用于后续展示、功能分析或去冗余明细，但不能改变 1.3 摘要统计。
2.2 merge 纯鉴定报错
项目：
project_id=1782440463xwSjhqb1O1JX
已定位问题：
- 前端在纯鉴定开关之前强制要求分组比较，单组/空 comparison 无法继续。
- 后端把缺失或误识别的 KEGG 列当作真实 KEGG 列，导致 5 个列名赋给 4 列数据：
Error in names(x) <- value : 'names' attribute [5] must be the same length as the vector [4]
修复方向：
- 单个非 QC 分组允许 comparison 为空。
- KEGG 列必须真实存在且不能与
peak/mz/rt/name列重复；否则走自动注释补 KEGG 逻辑。
2.3 报告渲染 pandoc 137
现象：
Killed REPORT_RENDER_ERROR report_server.html: pandoc document conversion failed with error 137
判断：
- 137 是
SIGKILL，通常是 pandoc 转换 HTML 时峰值资源被系统杀掉。 - 不是分析结果失败，也不是 docx 失败。
处理策略：
- 优先使用原 pandoc HTML。
- pandoc 失败时，用
.knit.md生成轻量静态 HTML 兜底，避免网页报告完全缺失。
3. 任务拆分
阶段 A：基线冻结与输入确认
任务明细：
- 固定 VM 路径和项目 ID。
- 备份当前
Report目录。 - 记录当前脚本版本和关键 grep 结果。
- 保存重跑前的
result.rda、差异数量统计.xlsx、Venn/UpSet 图片时间戳。
命令示例：
cd /home/saitoasuka/shiny-server/omicscloud
PROJECT_ID=1782216367szeKmg89zLqr
USER_UID=13
APP_ROOT=/home/saitoasuka/shiny-server/omicscloud
PROJECT_ROOT=/home/saitoasuka/mnt/omicscloud/data/${USER_UID}/${PROJECT_ID}
cp -a "$PROJECT_ROOT/Report" "$PROJECT_ROOT/Report.baseline_$(date +%Y%m%d_%H%M%S)"
grep -n "results_mode_summary_diff_merged" "$APP_ROOT/etc/dep/metabolite_script.r"
grep -n "sample_cols <- intersect(sample_cols, colnames(results_mode_merged))" "$APP_ROOT/etc/dep/metabolite_script.r"交付物：
- baseline 备份目录。
- 一份重跑前日志摘要。
预计时间：
- 0.5 天。
阶段 B：单离子 demo3 split 结果对齐
任务明细：
- 确认
metabolite_script.r已同步到 VM。 - 修正 summary 统计口径：
- 保留表格拆分/去冗余逻辑，但不用于覆盖
1.3 差异信息。 - 完整重跑项目。
- 核对
1.3 差异信息是否恢复为234/370/370。 - 核对 Venn/UpSet 与参考网站。
重跑命令：
mv "$PROJECT_ROOT/Report" "$PROJECT_ROOT/Report.before_raw_summary_$(date +%Y%m%d_%H%M%S)" 2>/dev/null || true
Rscript --vanilla "$APP_ROOT/etc/dep/metabolite_script.r" \
"$PROJECT_ID" "$USER_UID" "$APP_ROOT" "$APP_ROOT" \
> "$PROJECT_ROOT/${PROJECT_ID}_raw_summary_align.log" 2>&1
grep -n "Error in\|Execution halted\|REPORT_RENDER_ERROR\|已保存差异数量统计结果\|Report render status" \
"$PROJECT_ROOT/${PROJECT_ID}_raw_summary_align.log" | tail -120交付物：
- 更新后的
Report/result.rda。 - 更新后的
Report/report.html、report_server.html、report.docx、report.zip。 1.3 差异信息截图或导出表。- Venn/UpSet 截图或图片文件。
- 重跑日志。
预计时间：
- 1 天。
阶段 C：merge 纯鉴定报错修复验证
任务明细：
- 同步
metabolite_func.r和metabolite_script.r到 VM。 - 重启 Shiny 服务或重新加载应用，确保前端校验生效。
- 新建或复跑 merge 纯鉴定项目。
- 验证同一组/单组分组时允许下一步。
- 验证无比较组时后端进入纯鉴定流程。
- 验证无 KEGG 列或 KEGG 列自动识别错误时不会触发 5 列命名错误。
交付物：
- 纯鉴定项目运行日志。
- 成功生成的
Report目录。 - 前端分组页通过截图。
- 报告 HTML/docx/zip。
预计时间：
- 1 天。
阶段 D：报告渲染与格式一致性验证
任务明细：
- HTML 正常 pandoc 渲染时检查无 fallback warning。
- pandoc 被 kill 时检查 fallback HTML 是否生成。
- 检查
report.html、report_server.html是否存在且非错误页。 - 检查 docx 字体、标题层级、表格宽度、图片比例、分页。
- 检查 zip 包是否包含完整结果目录和报告。
关键日志检查：
grep -n "REPORT_RENDER_ERROR\|Execution halted\|Error in" "$LOG" | tail -120
ls -lh "$PROJECT_ROOT/Report"/report.html \
"$PROJECT_ROOT/Report"/report_server.html \
"$PROJECT_ROOT/Report"/report.docx \
"$PROJECT_ROOT/Report"/report.zip \
"$PROJECT_ROOT/Report"/result.rda交付物：
- 报告文件清单。
- 日志检查结果。
预计时间：
- 0.5 天。
阶段 F：完整运行参数矩阵回归
任务明细：
- 建立 metabolite web 的最小回归集和扩展回归集。
- 覆盖 split、merge路线。
- 覆盖定量项目和纯鉴定项目。
- 覆盖有 comparison、无 comparison、单组、两组、多组、多比较组合。
- 覆盖关键预处理参数和差异筛选参数组合。
- 每个组合记录输入配置、项目 ID、日志路径、报告路径、通过/失败结论。
- 对失败组合归类为代码问题、输入问题、资源问题、第三方依赖问题或已知非阻断问题。
交付物：
- 参数矩阵测试记录表。
- 每条路线至少 1 个完整成功项目。
- P0/P1 失败项修复记录。
- 未覆盖项和延期项说明。
预计时间：
- 1-2 天，取决于 VM 运行速度和失败项数量。
4. 完整运行测试范围与参数矩阵
本节用于补足“只验证当前两个 bug”之外的完整运行计划。最终交付不能只看 demo3 和纯鉴定报错，需要证明 omicscloud 代谢模块在主要使用路径下可以稳定跑完。
4.1 最小必测回归集
| 编号 | 路线 | 数据类型 | 目标 | 验收重点 |
|---|---|---|---|---|
| M1 | split | 定量，demo3 单离子 | 对齐参考网站 | 1.3 差异信息=234/370/370，Venn/UpSet 对齐，报告完整
|
| M2 | merge | 纯鉴定，单组 | 验证无 comparison 可运行 | 无 names attribute [5] 报错，报告/zip/docx 完整
|
| M3 | merge | 定量，两组或多组 | 验证常规 merge 定量 | 差异筛选、PCA/PLS-DA、KEGG/MSEA、报告完整 |
| M4 | sjtu | 定量代表项目 | 验证 sjtu 路线未被 split/merge 修复影响 | 运行成功，报告章节完整 |
| M5 | report-only | 已有 result.rda 项目 | 验证报告重渲染 | HTML/docx/zip 可生成，格式一致 |
最小回归集全部通过后，才能进入技术审核。
4.2 扩展参数矩阵
| 参数域 | 必测组合 | 目的 | 通过标准 |
|---|---|---|---|
| 路线 | split、merge、sjtu | 覆盖三条后端分支 | 均可生成完整 Report |
| 分析类型 | 定量、纯鉴定 | 覆盖差异分析和仅鉴定流程 | 对应章节正确出现或正确跳过 |
| 离子模式 | POS、NEG、单离子、正负离子合并 | 覆盖 ion_type 分支 | 鉴定信息、差异信息、图表不串模式 |
| 分组 | 单组、两组、多组 | 覆盖 comparison 生成和空 comparison | 单组纯鉴定允许运行，多组比较正确生成 |
| 比较组 | 0 个、1 个、多个、互为反向比较 | 覆盖 up/down 方向和 Venn/UpSet | 方向一致，数量稳定，无重复覆盖 summary |
| 缺失值过滤 | 默认阈值、较严格阈值、关闭/宽松阈值 | 验证特征数量变化合理 | raw/remove/preprocess 数量单调合理
|
| 归一化 | 默认、无归一化、可选归一化方法 | 验证 PCA/QC/差异链路 | 无 NA/Inf 导致图表失败 |
| 批次校正 | 无 batch、有 batch | 验证 batch 列处理 | 批次校正章节和后续图表正常 |
| 差异筛选 | p 值阈值、FC 阈值、VIP 阈值默认和边界 | 验证差异数量和图表 | 差异数量可解释，空差异时报告不崩 |
| 鉴定列 | 有 name、有 KEGG、无 KEGG、KEGG 与其他列重复 | 验证列识别健壮性 | 无列名长度错误，自动注释逻辑正确 |
| 富集 | 有 KEGG 结果、无 KEGG 结果、MSEA 为空 | 验证空结果处理 | 空结果以表格/提示处理，不报 Error |
| 报告输出 | html、server html、docx、zip | 覆盖报告链路 | 文件存在、非错误页、zip 可解压 |
4.3 建议测试项目清单
| 优先级 | 项目来源 | 建议项目 | 用途 |
|---|---|---|---|
| P0 | 当前问题项目 | 1782216367szeKmg89zLqr
|
split/demo3/单离子/参考网站 对齐 |
| P0 | 当前问题项目 | 1782440463xwSjhqb1O1JX
|
merge/纯鉴定/单组/KEGG 列边界 |
| P1 | 历史成功项目 | 选择 1 个 merge 定量项目 | 防止纯鉴定修复影响常规定量 |
| P1 | 历史成功项目 | 选择 1 个正负离子合并项目 | 验证 ion_type 合并输出 |
| P2 | 人工构造项目 | 空差异结果项目 | 验证差异为空时报告不崩 |
| P2 | 人工构造项目 | 无 KEGG/无 HMDB/无 name 边界项目 | 验证鉴定列缺失时兜底 |
4.4 参数矩阵记录格式
每个测试组合必须记录以下字段，避免只凭截图判断：
测试编号： 项目 ID： 路线：split/merge 分析类型：定量/纯鉴定 离子模式： 分组数量： 比较组数量： 关键参数： 开始时间： 结束时间： 日志路径： Report 路径： 核心输出文件是否完整： Error 等级报错：无/有 报告格式：通过/不通过 业务数值核对：通过/不通过/不适用 结论：通过/失败/阻塞 失败原因分类： 处理人： 复测时间：
4.5 完整运行通过门槛
完整运行交付必须同时满足：
- P0 测试全部通过。
- P1 测试全部通过，或失败项有明确修复计划且不影响本次交付范围。
- 任一报告输出中不得出现未处理的
Error、Execution halted、错误页。 - 空结果、无 KEGG、无 comparison 等边界场景不能导致后端崩溃。
- 报告章节缺省必须是业务上可解释的“无结果/不适用”，不能是缺文件或 R 报错。
- docx、HTML、zip 三类交付文件至少在 P0/P1 项目中全部验证。
5. 潜在风险与备选方案
| 风险 | 影响 | 预防措施 | 备选方案 |
|---|---|---|---|
| VM 脚本未同步 | 重跑结果仍是旧逻辑 | grep 检查关键代码行 | 重新复制脚本并记录 md5sum |
| 只重跑 report-only | 差异数量不更新 | 明确必须完整重跑主脚本 | 移走旧 Report 后重跑完整分析 |
| pandoc 137 | HTML 缺失 | 保留 fallback HTML | 若需完整 HTML，增加 VM 内存或拆分报告 |
| 前端缓存 | 页面显示旧报告 | 清浏览器缓存、确认报告文件时间 | 直接下载新 report.html 验证 |
| 单组纯鉴定被误判为差异分析 | 后端报错或无结果 | 前端允许空 comparison，后端自动识别单组 | 强制设置 ident_only_judge=TRUE 后重跑
|
| KEGG 列误识别 | 5 列/4 列命名错误或 KEGG 结果异常 | KEGG 列有效性判断 | 设置 key_column_kegg=NA，走自动注释
|
| docx 格式不一致 | 技术审核不通过 | 按模板统一标题、表格、图片 | 用 Rmd 模板修复后 report-only 重渲染 |
| Venn 与数量口径不一致 | 审核口径不清 | 明确 Venn 使用 raw diff 还是去冗余 diff | 按参考网站 raw diff 口径统一 |
| 参数矩阵覆盖不足 | 技术审核认为只修了局部 bug | 按 P0/P1/P2 分层列出覆盖范围 | P0/P1 作为交付门槛，P2 作为后续增强 |
| 空结果参数组合触发报错 | 报告中断或章节缺失 | 加入空差异、空富集、无 KEGG 测试 | 空结果统一输出空表和说明 |
| split 修复影响 sjtu 或 merge | 其他路线回归失败 | 三条路线分别跑代表项目 | 分支逻辑隔离，按路线回滚或补丁修复 |
| 参数组合过多导致排期失控 | 交付延期 | 区分最小必测和扩展测试 | P0/P1 先交付，P2 进入后续版本 |
6. 自查计划
6.1 代码自查
Rscript --vanilla -e "parse('etc/dep/metabolite_script.r')"通过。Rscript --vanilla -e "parse('etc/dep/metabolite_func.r')"通过。Rscript --vanilla -e "parse('etc/dep/rerun_metabolite_report_only.R')"通过。git diff --check无空白错误。- grep 确认关键逻辑存在：
grep -n "results_mode_summary_diff_merged <- bind_result_list(results_mode_diff\\[\\[cmp_name\\]\\])" etc/dep/metabolite_script.r grep -n "length(sample_groups) <= 1" etc/dep/metabolite_func.r grep -n "write_minimal_html_report" etc/dep/metabolite_script.r etc/dep/rerun_metabolite_report_only.R
6.2 运行自查
- demo3 完整重跑成功。
- merge 纯鉴定完整重跑成功。
- split、merge 至少各有 1 个代表项目完整重跑成功。
- 定量和纯鉴定至少各有 1 个代表项目完整重跑成功。
- 参数矩阵 P0 项全部通过，P1 项无阻断失败。
- 日志无
Execution halted。 - 日志无未处理
REPORT_RENDER_ERROR。 - 输出文件时间戳晚于重跑开始时间。
6.3 报告自查
1.2 鉴定信息与参考一致。1.3 差异信息与参考一致。- Venn/UpSet 与参考一致。
- KEGG/MSEA/物质分类章节存在且图片不缺失。
- HTML 无明显错位、乱码、错误页。
- docx 标题、字体、表格、图片、分页一致。
- zip 解压后文件完整。
6.4 参数矩阵自查
- 每个测试项目都有项目 ID、日志路径和 Report 路径。
- 每个测试项目都有参数配置记录。
- 每个失败项都有失败原因分类和复测结论。
- P0/P1 测试结论可追溯到日志和报告文件。
- 未覆盖参数有原因说明和后续计划。
7. 交付验收形式
7.1 文件交付
交付路径：
/home/saitoasuka/mnt/omicscloud/data/13/<project_id>/Report
必须包含：
result.rdareport.html report_server.html report.docx report.zip 差异数量统计.xlsx Venn/UpSet 图片
关键结果表 xlsx/csv
7.2 证据交付
- 运行日志。
- grep 检查记录。
- 参数矩阵测试记录表。
- 报告截图：
1.2 鉴定信息1.3 差异信息- Venn/UpSet
- 纯鉴定报告关键章节
- 技术审核用自查 Checklist。
7.3 验收结论格式
项目 ID： 运行时间： 脚本版本： 运行状态：成功/失败 报告文件：完整/缺失 差异数量：通过/不通过 Venn/UpSet：通过/不通过 纯鉴定流程：通过/不通过 参数矩阵：通过/不通过/有非阻断遗留 字体排版：通过/不通过 技术审核结论：通过/需整改
8. 时间节点
| 时间 | 任务 | 输出 |
|---|---|---|
| 1天 | 基线冻结、脚本同步、grep 检查 | baseline 备份、同步确认、关键代码定位 |
| 1天 | P0-1 demo3 split 完整重跑与差异/Venn 核对 | demo3 报告、日志、截图、参考网站 对照 |
| 1天 | P0-2 merge 纯鉴定前后端验证 | 纯鉴定报告、日志、截图 |
| 1天 | P1 merge 定量、正负离子代表项目回归 | P1 参数矩阵记录、报告包 |
| 2-3天 | 扩展参数测试：空差异、无 KEGG、无 comparison、batch 参数 | 扩展问题清单、失败分类 |
| 0.5天 | 报告格式、zip、docx、HTML 全文检查 | 自查记录、排版问题清单 |
| 0.5天 | 修复残留问题并复测 P0/P1 | 最终报告包、复测日志 |
| 0.5天 | 技术部门审核材料整理 | 计划、Checklist、handoff、Excel 记录、参数矩阵 |
9. 当前优先级
- 先修正并验证 demo3 的
1.3 差异信息回到参考网站 的234/370/370。 - 再验证 Venn/UpSet 与参考网站。
- 再验证 merge 纯鉴定不报错。
- 再跑 merge 定量、正负离子代表项目，确认修复没有影响其他路线。
- 再做空差异、无 KEGG、无 comparison、batch 等边界参数测试。
- 最后做报告全文格式、zip 完整性和技术审核文档。