diff --git a/docs/specs/backend-checklist.md b/docs/specs/backend-checklist.md new file mode 100644 index 00000000..1d331242 --- /dev/null +++ b/docs/specs/backend-checklist.md @@ -0,0 +1,162 @@ +# 后端发布前检查清单 + +## 📋 基础检查项 + +### Maven编译验证 +- [ ] 本地执行 `mvn compile` 编译通过,无ERROR +- [ ] 执行 `mvn package -DskipTests` 打包成功 +- [ ] 依赖版本无冲突(`mvn dependency:tree` 检查) +- [ ] 无编译警告(或已有书面说明可忽略) + +### 构建产物验证 +- [ ] JAR/WAR包生成完整,大小合理 +- [ ] `application.yml` 等配置文件已打包进产物 +- [ ] 第三方依赖jar包完整(lib目录无缺失) + +--- + +## 🔧 Spring Boot 配置检查 + +### 多环境配置 +- [ ] `application-dev.yml`(开发)配置正确 +- [ ] `application-test.yml`(测试)配置正确 +- [ ] `application-prod.yml`(生产)配置正确 +- [ ] 启动参数 `--spring.profiles.active` 指定正确环境 +- [ ] 生产环境未启用devtools热部署 + +### Actuator安全 +- [ ] 生产环境 `/actuator` 端点已禁用或限制访问 +- [ ] `/actuator/env`、`/actuator/heapdump` 等敏感端点已关闭 +- [ ] 健康检查端点 `/actuator/health` 返回信息已脱敏 + +### 启动校验 +- [ ] 数据库连接池配置合理(HikariCP最大/最小连接数) +- [ ] Redis/消息中间件连接配置正确 +- [ ] 启动日志无ERROR级别异常 + +--- + +## 🗄️ MyBatis Plus 规范检查 + +### 实体-表映射 +- [ ] 所有实体类标注 `@TableName`,表名与实际一致 +- [ ] 主键字段标注 `@TableId(type = IdType.AUTO)` 或对应策略 +- [ ] 非表字段标注 `@TableField(exist = false)` +- [ ] 字段命名符合下划线转驼峰规则 + +### SQL安全 +- [ ] 所有查询使用参数化查询(`QueryWrapper` / `LambdaQueryWrapper`) +- [ ] 禁止字符串拼接SQL(`"WHERE name = '" + name + "'"`) +- [ ] 批量操作使用MyBatis Plus `saveBatch` / `updateBatchById` +- [ ] 复杂SQL使用XML映射,避免注解内嵌长SQL + +### 事务管理 +- [ ] 涉及多表写操作的方法标注 `@Transactional` +- [ ] 事务边界合理,不包含外部HTTP调用 +- [ ] 异常回滚配置正确(`rollbackFor = Exception.class`) +- [ ] 事务方法未被同一类内方法直接调用(自调用失效问题) + +### 分页插件 +- [ ] `PaginationInnerInterceptor` 已正确配置 +- [ ] 分页查询使用 `Page` 对象,非手动limit/offset + +--- + +## 🔌 RESTful API 设计检查 + +### 统一返回格式 +- [ ] 所有接口返回 `{code, msg, data}` 统一结构 +- [ ] 成功返回 `code=200`,业务错误使用自定义错误码 +- [ ] 异常通过 `@ControllerAdvice` + `@ExceptionHandler` 统一处理 + +### HTTP状态码 +- [ ] 资源创建返回 `201 Created` +- [ ] 资源删除返回 `204 No Content` +- [ ] 参数校验失败返回 `400 Bad Request` +- [ ] 未认证返回 `401 Unauthorized` +- [ ] 无权限返回 `403 Forbidden` +- [ ] 资源不存在返回 `404 Not Found` + +### 参数校验 +- [ ] 请求参数使用 `@Valid` / `@Validated` 注解校验 +- [ ] 必填字段标注 `@NotBlank` / `@NotNull` +- [ ] 数值范围标注 `@Min` / `@Max` +- [ ] 格式校验使用 `@Pattern`(如手机号、身份证号) +- [ ] 校验失败返回明确错误信息(非500堆栈) + +### API版本管理 +- [ ] 接口路径包含版本号(`/api/v1/`、`/api/v2/`) +- [ ] 废弃接口标注 `@Deprecated`,并在文档中说明 +- [ ] 不兼容变更必须升级版本号 + +--- + +## 🔒 安全与合规检查 + +### 数据脱敏 +- [ ] 患者身份证号在日志中脱敏(`***` 掩码) +- [ ] 患者手机号在日志中脱敏(前3后4,中间`****`) +- [ ] 敏感字段序列化时使用 `@JsonSerialize` 自定义脱敏器 +- [ ] 接口返回中非必需字段不暴露(如密码、salt) + +### 权限控制 +- [ ] 所有涉及患者数据的接口标注 `@PreAuthorize` +- [ ] 数据级权限校验(医生只能访问本科室患者) +- [ ] 越权访问返回 `403`,非 `404` 或 `500` +- [ ] 敏感操作(删除、修改诊断)需二次确认或额外权限 + +### 审计日志 +- [ ] 处方修改记录操作人、时间、变更内容 +- [ ] 病历删除操作记录完整审计链 +- [ ] 审计日志独立存储,不可被业务用户删除 +- [ ] 关键业务操作记录IP地址和操作终端 + +--- + +## ⚡ 性能检查 + +### 数据库查询 +- [ ] 无N+1查询问题(使用 `JOIN` 或批量查询) +- [ ] 大表查询必须有分页限制 +- [ ] 慢查询已优化(执行时间 < 500ms) +- [ ] 索引已覆盖高频查询条件 + +### 接口性能 +- [ ] 核心接口响应时间 < 1秒 +- [ ] 列表接口支持分页,无全量返回 +- [ ] 大文件下载使用流式传输,非全量加载到内存 + +--- + +## 📝 文档与发布准备 + +### 文档更新 +- [ ] API接口文档已同步更新(路径、参数、返回值) +- [ ] 数据库变更脚本已提供(DDL/DML) +- [ ] 配置变更说明已记录(新增/修改的配置项) +- [ ] 影响范围说明已明确(哪些模块、哪些接口受影响) + +### 回滚预案 +- [ ] 数据库变更可回滚(提供反向SQL脚本) +- [ ] 配置变更可快速回退 +- [ ] 紧急回滚流程已明确(谁、怎么做、多长时间) +- [ ] 回滚后数据一致性已验证 + +--- + +## ✅ 最终确认 + +### 发布前最后检查 +- [ ] `mvn compile` 构建成功(附终端截图) +- [ ] 关键单元测试通过 +- [ ] 测试环境部署验证通过 +- [ ] Code Review 已完成并获得批准 +- [ ] 相关Bug已关闭或延期说明 + +--- + +**文档版本**:v1.0 +**最后更新**:2026年4月24日 +**负责人**:关羽(后端开发) +**适用范围**:HIS 系统所有后端模块(his-server) +**补充说明**:本清单与陈琳的《前端发布前检查清单》对称互补,共同构成HIS系统发布前完整质量保障体系