PreRisk‑Skill
功能开发完成后，基于功能分支相对基线的变更，输出：
- 接口文档
- 代码缺陷 / 系统漏洞 / 安全隐患分析
- 可参考的解决方案
本 Skill 安装位置（以最新覆盖为准）：
- 项目：
.cursor/skills/pre-risk/（当前仓库 Agent 优先使用） - 个人：
~/.cursor/skills/pre-risk/（跨项目可用） - 源文档：
docs/skill/pre-risk/（与上两处保持同步）
触发后立即阅读并按本文件及同目录 checklist / report-template 执行。
何时使用
- 用户提到：PreRisk、PreRisk-Skill、接口文档、风险分析、上线前评审
- 新功能开发完成，需要基于分支做交付物整理
- 需要对照分支 diff 做安全与缺陷预审
工作流（必须按序）
复制并跟踪进度：
PreRisk Progress:
- [ ] 1. 确定分支与基线
- [ ] 2. 收集变更范围
- [ ] 3. 梳理接口并写接口文档
- [ ] 4. 缺陷 / 漏洞 / 安全分析
- [ ] 5. 输出完整 PreRisk 报告
1. 确定分支与基线
在仓库根目录执行（只读）：
git rev-parse --abbrev-ref HEAD
git status -sb
git remote show origin 2>/dev/null | head -n 20
基线分支选择规则（优先级从高到低）：
- 用户明确指定的基线（如
main/master/develop/release/x） - 当前分支的 upstream / merge-base 常见主干（优先
develop，其次master/main） - 若无法判断，询问用户后再继续
git merge-base HEAD <base>
git log --oneline <base>...HEAD
git diff --stat <base>...HEAD
git diff <base>...HEAD
说明：
- 分析对象是本功能分支相对基线的全部提交，不是仅当前未提交改动（除非用户明确要求只看工作区）
- 若存在未提交改动且与功能相关，一并纳入，并在报告中标注「含未提交变更」
2. 收集变更范围
从 diff 中归类文件，并识别技术栈（Boot/Cloud/MVC、Vue/JSP/React、C#、Python 等）：
| 类别 | 典型路径/特征 |
|---|---|
| API / Controller | *Controller.java、@RequestMapping、@ResponseBody、.cs Controller |
| Service / 业务 | *Service*.java、Domain/Application 层 |
| 持久层 | *Dao.java、*Mapper.xml、EF、SQLAlchemy 等 |
| 前端 | *.jsp、*.vue、*.tsx/*.jsx、*.js |
| 网关/云组件 | Gateway、Feign、Nacos 配置 |
| 安全配置 | Shiro/Security、Filter、鉴权中间件 |
| 配置 / 脚本 | *.properties/*.yml、db/*.sql、迁移脚本 |
| 其他 | 定时任务、消息、文件上传、回调 |
重点阅读新增/修改的接口层、鉴权、SQL、上传与对外回调。
详细检查项见 checklist.md（按框架分章 + 业务隐性缺陷）。
3. 梳理接口并写接口文档
对每个对外或对内可调用入口整理：
- HTTP Method、完整路径（含网关/context/
${adminPath}前缀；本仓库多为/a） - 请求参数（Query / Path / Body / Header），字段类型与必填
- 鉴权方式：
user/anon/basicAuth/systemToken/ JWT / Cookie Session 等 - 成功 / 失败响应结构（如
R<code,msg,data>） - 副作用：写库、删库、发消息、调外部系统、上传文件
- 调用方：页面、外部系统、定时任务
接口文档章节使用 report-template.md 中的「接口文档」模板。
本仓库常见模式（写文档时对照）：
- Spring MVC：
@RequestMapping("${adminPath}/...") - 统一返回：
com.weichai.common.dto.R - 集成回调：Body 内
systemToken+ Shiroanon（anon 必须写在${adminPath}/** = user之前）
4. 缺陷 / 漏洞 / 安全 / 业务分析
按识别到的栈加载 checklist.md 对应章节，结构化评审：
A. 代码缺陷（框架相关）
空指针、事务失效、并发覆盖、Feign 重试非幂等、前端陈旧闭包/响应式丢失等。
B. 系统漏洞 / 稳定性
启动失败、配置漂移、无超时雪崩、多实例定时重复、全表删除等。
C. 安全隐患
越权、注入、XSS、密钥泄露、anon 顺序错误、上传路径穿越等。
D. 业务功能缺陷（不易察觉，必做）
结合业务场景推演：状态机非法跳转、主从一致性、空列表覆盖、关联 ID/编号不同步、回调幂等、页签回显未刷新、旁路提交绕过校验等。详见 checklist §11。
业务功能缺陷必须附带「复现流程」（测试同学可照做）：见下方字段表与 report-template.md / examples.md。
每条风险必须包含：
| 字段 | 要求 |
|---|---|
| 等级 | Critical / High / Medium / Low |
| 类别 | 代码缺陷 / 系统漏洞 / 安全隐患 / 业务功能缺陷 |
| 位置 | 文件路径 + 符号/行号或配置项 |
| 说明 | 触发条件与影响 |
| 参考方案 | 可落地的修复建议（不必直接改代码，除非用户要求） |
| 复现流程 | 类别为「业务功能缺陷」时必填；其他类别建议填写（尤其 High+） |
业务功能缺陷 · 复现流程写法（必遵）
对每条「业务功能缺陷」用可执行步骤描述如何测出问题，至少包含：
- 前置条件：账号角色、数据准备、环境/配置、打开的页面或接口
- 操作步骤：编号步骤（UI 点击路径或 API 调用），每步可独立执行
- 期望结果：按需求/产品规则应发生什么
- 实际结果（推演）：按当前代码会怎样，从而暴露缺陷
- 判定要点：用什么现象判定复现成功（提示文案、库表字段、接口响应、页面展示）
格式示例（报告中可嵌在风险表「复现流程」单元格，或表下用有序列表）：
**复现流程**
1. 前置：…
2. 步骤：① … ② … ③ …
3. 期望：…
4. 实际（推演）：…
5. 判定：…
注意：复现流程是假设性测试设计（基于代码推演），标注「未经实机验证」即可；勿写成已实测通过。
5. 输出完整 PreRisk 报告
- 使用 report-template.md 结构输出
- 默认写入：
docs/skill/pre-risk/reports/<branch-name>_<yyyyMMdd>.md
<branch-name>：将/替换为-- 若用户指定其他路径，遵从用户
- 同时在对话中给出摘要（接口数量、Critical/High 条数、最优先修复项）
- 报告语气：简洁、可执行；解决方案标注为「参考」，勿假装已在生产验证
- 不要在未请求时直接修改业务代码或提交 git；只产出文档与建议
质量门槛
- [ ] 基线与分支写清楚，diff 范围可复现
- [ ] 变更涉及的主要接口均有文档（无接口则说明「无新增 HTTP 接口」）
- [ ] Critical / High 风险不得省略；若无则明确写「未发现 Critical/High」
- [ ] 已识别技术栈并按对应框架清单检查
- [ ] 已做业务场景推演（不易察觉功能缺陷），并在报告中单列或明确无发现
- [ ] 每条业务功能缺陷均附带可执行「复现流程」（前置/步骤/期望/实际/判定）
- [ ] 每条风险有位置 + 参考方案
- [ ] 鉴权过滤链顺序 / SQL / 上传 / 对外匿名接口按栈专项检查
附加资源
- 检查清单：checklist.md
- 报告模板：report-template.md
- 示例：examples.md
