OpenStatusHQ 状态报告端点优化方案

现状分析

OpenStatusHQ 项目当前的状态报告系统存在一个关键问题：当用户通过API更新状态报告后，再次获取该报告时，返回的是旧版本的数据。系统只返回一个包含更新记录ID的数组，用户需要额外发起请求才能获取最新版本的状态信息。

当前实现存在以下技术痛点：

1. 数据一致性：API返回的并非最新状态，而是初始创建时的状态
2. 请求效率：用户需要发起多次请求才能获取完整的最新信息
3. 数据结构：更新记录与原始记录分离，缺乏统一视图

问题根源

问题的核心在于数据库设计层面。当前系统将状态报告的初始版本和更新版本分别存储在两个不同的表中：

1. status_report表存储初始版本
2. status_report_update表存储后续更新版本

这种分离式设计导致API无法直接返回最新状态，必须通过额外的查询才能获取完整信息。

优化方案

数据库结构调整

建议采用版本链式设计，每个状态报告都包含完整的版本历史：

1. 创建状态报告时，自动在status_report_update表中创建版本0记录
2. 每次更新都新增一条版本记录，并更新主表的版本链

API响应格式优化

优化后的API响应应直接包含最新状态，同时保留版本历史：

初始创建响应示例：

{
    "title": "测试状态报告",
    "status": "调查中",
    "id": 1,
    "status_report_updates": [0]
}

更新后的响应示例：

{
    "title": "更新后的测试状态报告",
    "status": "监控中",
    "id": 1,
    "status_report_updates": [0,1]
}

技术实现要点

1. 事务处理：确保主表和版本表的更新操作原子性
2. 缓存策略：对频繁访问的最新状态实施缓存
3. 索引优化：为版本查询建立合适的数据库索引
4. API设计：
   • GET /status_reports 返回包含最新状态的报告列表
   • GET /status_reports/:id/versions 返回特定报告的所有版本
   • GET /status_reports/:id/versions/:version_id 返回特定版本详情

实施建议

1. 数据迁移：为现有报告创建版本0记录
2. API版本控制：考虑引入API版本号以保持向后兼容
3. 客户端适配：更新客户端代码以适应新的响应格式
4. 性能测试：确保新设计在高负载下的表现

预期收益

1. 用户体验提升：单次请求即可获取最新状态
2. 系统可维护性：清晰的数据版本管理
3. 扩展性：便于未来添加更多版本相关功能
4. 一致性保证：消除数据不一致的风险

这种优化将使OpenStatusHQ的状态报告系统更加健壮和用户友好，同时为未来的功能扩展奠定良好基础。