jiaxuan-tao Web 交付风险评审
这不是“跑完一串检查就说通过”的工具。它把关键用户路径、实际证据、发现的问题和未覆盖范围组织成可追溯的发布建议。
验收范围仅限用户指定项目；未指定时先说明将检查当前工作目录。脚本只读、不安装依赖、不修改项目文件，也不上传数据。
输出原则
- 先定义本次发布要让谁完成什么任务，再决定检查什么。
- 每个“通过”都附上执行过的命令、页面操作或检查结果；没有证据的事项只能写“未覆盖”。
- 将事实、风险判断和发布建议分开陈述，避免把主观判断伪装成自动化结论。
- 不以发现问题数量计分；风险取决于核心任务影响、用户可达性、绕过方式和证据确定性。
1. 范围与关键路径
开始时确认或根据项目文档提炼以下内容：
- 发布目标：本次要交付的新能力或要修复的问题。
- 目标用户与核心任务：用户打开产品后必须能够完成的 1 至 3 条任务。
- 验收环境：项目路径、启动方式、浏览器尺寸、是否需要登录或外部服务。
- 明确排除项：例如真实支付、第三方登录、生产数据或无凭证的接口。
将每条关键路径写成“起点 → 操作 → 可观察结果”。例如：首页 → 填写表单并提交 → 看到成功状态且结果可再次访问。
2. 证据采集
按可获得的环境依次采集证据，不要为了完成流程而安装依赖或猜测命令。
项目检测
python3 scripts/inspect_web_project.py <项目目录>
记录包管理器、已有脚本、候选构建目录和警告。检测到配置不等于构建成功。
构建与已有测试
仅在依赖已经就绪、且项目提供明确脚本时，运行已有命令，例如：
npm test
npm run build
记录完整退出结果。构建失败时，不将与该构建相关的路径列为已验证。
静态引用检查
对已存在的静态输出目录运行：
python3 scripts/check_static_site.py <静态目录>
它只检查 HTML 中可静态确定的本地页面链接与资源引用。外链、锚点、动态路由和越出站点目录的引用必须作为跳过项或警告记录。
浏览器辅助验收
读取 浏览器验收清单，用当前可用的浏览器能力逐条验证关键路径：
- 打开页面并等待渲染稳定，记录控制台错误和失败请求。
- 先观察已渲染的页面，再使用稳定元素定位执行路径操作。
- 检查成功、加载、空数据和错误状态是否可理解。
- 在窄屏与宽屏下检查明显溢出、遮挡、不可点击或无法返回的问题。
3. 风险分级
基于证据对每个问题分级；同一问题的级别应写明原因。
| 等级 | 判断条件 | 发布处理 |
|---|---|---|
| 阻塞 | 用户无法进入产品，或核心任务无法完成、数据明显错误、存在不可接受的隐私或安全暴露 | 不建议发布；先修复并复验 |
| 高 | 重要路径对一部分用户不可用，或没有可理解的绕过方式 | 默认不发布；只有明确缩小发布范围时才可有条件发布 |
| 中 | 非核心流程受影响、存在临时绕过方式，或当前证据不足但影响尚未确认 | 可以有条件发布，但需列入后续修复与监控 |
| 低 | 文案、轻微视觉、非关键体验或不影响任务完成的问题 | 可发布；记录在后续迭代 |
不要把未覆盖项自动定为缺陷。它们是决策风险：需要说明为什么未覆盖、影响什么，以及是否足以阻止当前发布。
4. 未覆盖范围
单独列出未实际验证的关键条件，例如：登录账户、付费流程、真实第三方 API、生产权限、特定设备或数据量。
- 若未覆盖项属于核心任务且没有替代证据，不能给出“可发布”。
- 若它不属于本次发布范围，说明排除理由和后续验证人或条件。
- 不用“未发现问题”描述没有执行过的检查。
5. 发布建议
根据关键路径覆盖、风险分级和未覆盖范围给出唯一结论：
- 可发布：所有定义的关键路径都有足够证据，且没有阻塞或高风险；未覆盖项不影响本次目标。
- 有条件发布：没有阻塞问题，但存在明确的中风险、可接受的高风险降级方案或非关键未覆盖项；必须写清条件、受影响用户和最小后续动作。
- 不建议发布：存在阻塞问题、未验证的核心路径，或高风险会破坏本次发布目标。
使用以下结构输出：
Web 交付风险评审 · YYYY-MM-DD
发布目标：<本次交付什么>
范围与环境：<项目路径、运行方式、浏览器或数据条件>
关键路径与证据
1. <路径>：通过 / 失败 / 未覆盖
证据：<命令、页面操作、检查结果>
风险
- [阻塞 / 高 / 中 / 低] <问题>
影响：<谁无法完成什么>
依据：<可复现证据>
建议：<最小修复或降级动作>
未覆盖范围
- <事项、原因、对本次发布的影响>
发布建议：可发布 / 有条件发布 / 不建议发布
理由：<将关键路径、风险和未覆盖范围连成明确判断>
下一步：<按优先级排列的最小动作>
不要在存在阻塞问题、关键路径失败或核心范围未覆盖时写“可发布”。