后端开发规范

技术栈与架构

• 后端统一采用 Spring Boot + MyBatis，按 MVC 分层开发：Controller -> Service -> Mapper -> Database。Controller 负责控制层，Service 承载业务规则，MyBatis Mapper 负责模型持久化，View 由前端展示。

分层与接口

• Controller 只处理 HTTP、鉴权与参数校验；业务规则放 Service；持久化放 MyBatis Mapper。不要在 Controller 拼业务逻辑或在前端复制业务计算。
• API 契约先定义类型、校验、分页和错误格式，再由前端逐页接入；变更字段时保持兼容或同步更新消费者。
• 只以已发布结果区对外提供 SLA、基线、预测、诊断和告警数据；诊断只返回候选原因、证据与建议，不返回伪确认根因。
• ROLE_ADMIN 与 ROLE_USER 必须由后端授权。前端可见性、参数校验和 UI 禁用均不能替代服务端校验。

Trace 与日志

• 最外层 Filter 读取 X-Trace-Id；缺失或不合法时创建。将其写入响应头并放入 MDC，处理结束后清理 MDC。
• 所有访问、异常、任务和审计日志必须携带 traceId。异步、调度、消息处理显式传播或创建 traceId，不依赖线程本地 MDC 自动继承。
• HTTP 完成日志至少含：traceId、method、path、status、durationMs；可用时增加 actor、businessId（告警号、任务号、报告号）。
• 写操作与任务日志使用明确事件名，例如 alarm.claimed、report.queued、schedule.failed，并记录对象、结果与失败原因。
• 错误响应至少返回 code、message、timestamp、traceId；禁止返回堆栈、SQL、密钥、token 或敏感配置。
• 审计记录的 request_id 写入同一个 traceId，确保 HTTP、异步任务与审计能串联查询。

安全与运行

• CORS 允许并暴露 X-Trace-Id；反向代理、网关和异步消费者必须透传或创建它。
• 查询、排序字段使用参数化和白名单；日志脱敏；任何角色都不可修改或删除审计日志。
• CSV 由后端内网任务处理，浏览器不得上传、清洗或回写；不向前端暴露数据库、文件系统或网元控制能力。

验证

• 变更前查找所有调用方，修改后运行相关 Maven 测试。
• 接口改动验证：请求头、响应头、错误响应、应用日志及 tb_audit_log.request_id 使用同一 traceId。
• 新增非平凡逻辑至少有一个最小自动化检查；异常路径必须验证可读错误与日志事件。