本篇目标

• 定义并实现ReviewJobStore抽象。老实说，
• 用JSON文件实现持久化。
• 提供/api/reviews/{id}查询接口。
• 提供/api/reviews/{id}/report.md下载报告接口。
• 实现ReportTool 与 ReviewReportService
• 完成前端结果页及报告复制功能。

为什么先做状态管理？使用者痛点一览

评审任务的生命周期：

CREATED → RUNNING → COMPLETED ──┐
│
└─ FAILED

User Pain Points：

• 页面刷新后结果丢失：若状态只保存在内存，使用者刷新浏览器会失去所有评审信息。话说回来，
• 后端重启导致历史不可见：重新启动后无法查看之前的评审报告。影响团队协作，
• 无法通过jobId 从加载结果来看。User 在不同设备或时间想查看同一评审，却找不到对应记录。其实，
• 报告难以复用：A/B测试、PR评论或知识库中无法直接引用已生成的Markdown报告。

综上，从项目起步阶段就需要可靠的状态存储与报告输出机制。

再看主要状态对象，ReviewJob

// ReviewJob.java
public record ReviewJob(
String id,String sessionId,String repoPath,DiffMode diffMode,String baseRef,List focusCategories。ReviewStatus status,Instant createdAt,Instant startedAt,Instant finishedAt,List findings,String reportPath,String errorMessage) {}

设计要点：避免在Service层手写大量构造参数，减少错误率；使用record天然不可变，提高线程安全性。

状态流转方法

// ReviewJob.java
public ReviewJob running {
return new ReviewJob(id。sessionId,repoPath,diffMode,baseRef,focusCategories,ReviewStatus.RUNNING,createdAt,Instant.now,null,findings,reportPath,null);}
public ReviewJob completed {
return new ReviewJob(id,sessionId,repoPath,diffMode,baseRef。focusCategories,ReviewStatus.COMPLETED,createdAt,startedAt,Instant.now,List.copyOf,nextReportPath,null);}
public ReviewJob failed {
return new ReviewJob(id,sessionId,repoPath,diffMode,baseRef。focusCategories,ReviewStatus.FAILED,createdAt,startedAt,Instant.now,findings,reportPath,errorMessage);}

定义ReviewJobStore 接口

// ReviewJobStore.java
public interface ReviewJobStore {
ReviewJob save;Optional findById;}

从简化接口来看，仅关注保存与查询。后续可按需 分页、删除等功能，但先保证完整链路跑通。

用 JSON 文件做持久化

生产环境可以换成 MySQL/Redis/对象存储，但入门阶段不引入外部依赖更易上手。

文件布局示例

实现代码

// JsonFileReviewJobStore.java
public class JsonFileReviewJobStore implements ReviewJobStore {
private final Path jobDir;private final Path reportDir;private final ObjectMapper objectMapper = new ObjectMapper
.registerModule)
.configure;public JsonFileReviewJobStore{
this.jobDir = Objects.requireNonNull;this.reportDir = jobDir.resolveSibling;}
@Override public synchronized ReviewJob save {
Path file = jobDir.resolve+".json");try{objectMapper.writeValue,job);}
catch{throw new UncheckedIOException;话说回来，}
return job;}
@Override public Optional findById{
if.matches)return Optional.empty;Path file = jobDir.resolve;if)return Optional.empty;try{return Optional.of,ReviewJob.class));}
catch{throw new UncheckedIOException;}
}
// REVIEW_ID 正则可放到单独工具类中
}
java
private static final Pattern REVIEW_ID =
Pattern.compile;

从安全检查提示来看，永远不要把URL直接拼方法！


如果不校验，攻击者可通过方法穿越获取任意文件。

JSON文件名必须符合固定模式，否则解析失败。

读取时务必校验ID合法性，防止“../”注入。

在多实例部署时要考虑并发读写冲突，可使用锁或JVM同步块。

日志中不要泄露完整方法信息给外部请求者。

报表目录应设置为只读或仅限服务进程访问，以防止恶意覆盖。

若使用云存储，可对SSE进行加密，提高数据安全级别。

定期清理旧文件可避免硬盘空间耗尽；建议保留最近30天内的评审记录。

对大规模项目而言，单文件写入可能成为瓶颈。可考虑切分或压缩存档方式升级为数据库方案。

请考虑采用乐观锁或版本号来防止写冲突导致的数据丢失或覆盖现象。

如果将来迁移至云端对象存储。请确保Bucket权限仅授予必要角色，并开启版本控制以防止误删覆盖导致的数据恢复困难。

若业务需求出现跨域调用，需要对API进行鉴权。否则任何人都能随意查询历史评审信息，这会造成敏感信息泄露风险。怎么说呢，请结合业务实际设计最小权限策略并进行细粒度控制。返回顶部↩︎︎︎︎︎︎︎︎︎︎︎︎︎️‍⚡️️‍⚡️️‍⚡️️‍⚡️️‍⚡️️‍⚡️️‍⚡️✦✦✦✦✦✦✦✦✦✧🛠🏗👻🕵📈🔧💥🐛⛏🌋🌞🚀🎬📖🎉✨🚫🙅🤷🕶💻🗃☂🥸💰🍿🚪➜➡🗣🔐😎🥴😱❌📚🔍💬🔎📌📍➖◀▶✅🚫⌛🔄↔⇢⇧⇨⬆⬇⬅➡↕↖↘➝☑✔☑✓❖✅🏁🎯🚩🔝🏆👑🛑🤝💙🤝🏻🏼🏳✅🌟⭐★☆★*✨🌠🌤🌩⭐☆✨☀🌊🧊🔥❄☁☂⛈🎆🎇💥🔥👍👎👏👏👏🙌🤜🤛🤚👋🙋🙌🙍🙎😭😂😔😢😬😁😍😘😳🥺🤣🤪🤭🥰😠🥵🤒👍🏻🏼👨‍💻👩‍💻🔥😉🙂😍❤️❤️♥❤🍕🍔🍟🍺🍷🍸 🍾🥂',style=font-weight:bold;color:#000，background-color:white;padding-left:.15rem;padding-right:.15rem;margin-right:.75rem;margin-left:.75rem;margin-top:-1px;border-radius:10px;font-size:.875rem;text-decoration:none!important，display:inline-block;其实，text-align:center;width:auto，height:auto;background-image:none;border-style:none;border-color:#E4E7ED;background-repeat:no-repeat;background-position:center center;background-size:auto auto;color:black，font-family:"JetBrains Mono","Consolas","Courier New",monospace。-apple-system,BlinkMacSystemFont,"Helvetica Neue",Helvetica,"Arial",sans-serif;-webkit-font-smoothing:subpixel-antialiased;font-smoothness:auto;-webkit-text-size-adjust:none;margin-bottom:0px;">

保护报告方法这方面，验证 review ID 的工具类
java
// ReviewIdValidator.java
private static final Pattern REVIEW_ID =
Pattern.compile;public static String validate {
if .matches) {
throw new IllegalArgumentException;}
return id，}

这类小工具常被忽略，却决定了本地文件存储是否安全。报表由ReportTool<\/span>
渲染这方面，<\/p>
java
// ReportTool.java
for ) {
sb.append).append
.append.getCode).append
.append).append
.append).append);话说回来，// 后续补充行号、证据、影响、建议等详细内容
}

DONE!   .
Reports are meant for humans – include summary,task information,each finding’s evidence / impact / suggestion。and model configuration notes.


Report Generation & Saving Service  — 封装渲染与持久化流程
java
// ReviewReportService.java
public String generateAndSave{
Path reportPath = reportDir.resolve+".md");var sb = new StringBuilder;ReportTool.render;// 自定义渲染逻辑
 sb.append.append;try{Files.write.getBytes);老实说，}
catch{throw new UncheckedIOException;}
return reportPath.toString;// 返回绝对方法供后续使用


}

public Mono -="" mono.fromcallable="" path="" readreport{="" report="reportDir.resolve;" return=""> Files.readString);}
>