docs: 按刘备建议结构重新整理《HIS项目发布检查清单 v1.0》

2026-04-25 12:12:41 +08:00
parent 2f57b3e7c1
commit 914f2d8229
1 changed files with 476 additions and 13 deletions
--- a/docs/specs/his-release-checklist-v1.0.md
+++ b/docs/specs/his-release-checklist-v1.0.md
@@ -1,16 +1,111 @@
 # HIS项目发布检查清单 v1.0
-> **文档说明**：本清单整合了前端、后端、CI/CD构建门禁和代码提交规范四个部分，作为HIS项目发布的标准化检查依据。每次发布前必须逐项确认。
+> **文档说明**：本清单整合了提交规范、前端检查、后端检查、CI/CD门禁四个部分，作为HIS项目发布的标准化检查依据。每次发布前必须逐项确认。
 ## 目录
- [前端发布前检查清单](#前端发布前检查清单)
+- [1. 提交规范（commit-template）](#1-提交规范commit-template)
- [后端发布前检查清单](#后端发布前检查清单)  
+- [2. 前端检查（frontend-checklist）](#2-前端检查frontend-checklist)
- [CI/CD构建门禁规范](#cicd构建门禁规范)
+- [3. 后端检查（backend-checklist）](#3-后端检查backend-checklist)
- [代码提交变更说明模板](#代码提交变更说明模板)
+- [4. CI/CD门禁（cicd-gatekeeper）](#4-cicd门禁cicd-gatekeeper)
 - [5. 发布确认与回滚预案](#5-发布确认与回滚预案)
 ---
-## 前端发布前检查清单
+## 1. 提交规范（commit-template）
 ### 📝 PR/Commit 模板
 #### 标题格式
 ```
 <类型>(<模块>): <简短描述>
 示例：
 feat(patient): 添加患者基本信息编辑功能
 fix(doctor): 修复医生排班显示异常问题
 docs(api): 更新预约挂号接口文档
 refactor(nurse): 重构护士站护理记录组件
 ```
 #### 正文模板
 ```markdown
 ## 🔍 变更背景
 - **问题描述**：详细说明要解决的问题或实现的需求
 - **影响范围**：列出受影响的模块、页面、功能
 - **相关链接**：禅道任务ID、需求文档链接等
 ## 🛠️ 变更内容
 - **主要修改**：核心代码变更点
 - **技术方案**：采用的技术方案和设计思路
 - **兼容性**：是否涉及API或数据结构变更
 ## 🗄️ 数据库变更
 - **表结构变更**：列出新增/修改的表和字段
 - **数据迁移**：是否需要数据迁移脚本
 - **回滚方案**：数据库变更的回滚策略
 ## ✅ 验证情况
 - **测试覆盖**：单元测试、集成测试覆盖情况
 - **手动验证**：手动测试的场景和结果
 - **构建验证**：本地构建截图（必填）
 ## 📋 检查清单
 - [ ] 代码已通过 ESLint 检查
 - [ ] 本地构建成功（附截图）
 - [ ] 核心功能已测试验证
 - [ ] 文档已同步更新
 - [ ] Code Review 已完成
 ## 👥 相关人员
 - **开发者**：@开发者姓名
 - **测试者**：@测试者姓名  
 - **审核人**：@架构师姓名
 ```
 ### 🏷️ 提交类型说明
 | 类型 | 说明 | 示例 |
 |------|------|------|
 | feat | 新功能 | `feat: 添加用户登录功能` |
 | fix | Bug修复 | `fix: 修复表单验证错误` |
 | docs | 文档更新 | `docs: 更新API文档` |
 | style | 代码格式调整 | `style: 格式化代码` |
 | refactor | 代码重构 | `refactor: 重构组件结构` |
 | test | 测试相关 | `test: 添加单元测试` |
 | chore | 构建/依赖等 | `chore: 升级依赖版本` |
 | perf | 性能优化 | `perf: 优化列表加载速度` |
 ### 📁 模块命名规范
 | 模块 | 说明 |
 |------|------|
 | patient | 患者管理相关 |
 | doctor | 医生工作站相关 |
 | nurse | 护士站相关 |
 | admin | 后台管理相关 |
 | common | 公共组件/工具 |
 | api | API接口相关 |
 | auth | 认证授权相关 |
 | payment | 支付相关 |
 ### 🖼️ 构建验证截图要求
 #### 必须包含的信息
 1. **终端窗口**：显示 `npm run build:prod` 命令执行过程
 2. **成功标识**：明确显示构建成功的提示信息
 3. **时间戳**：截图包含当前时间，证明是最新构建
 4. **分支信息**：显示当前工作分支名称
 ### ⚠️ 禁止行为
 #### 严重违规（直接拒绝合并）
 - 无构建验证截图
 - 代码存在 ESLint 错误
 - 未填写变更说明
 - 修改无关代码文件
 ---
 ## 2. 前端检查（frontend-checklist）
 ### 📋 基础检查项
@@ -22,7 +117,7 @@
 - [ ] 函数职责单一，复杂度适中
 #### 构建验证
- [ ] 本地执行 `npm run build` 成功完成
+- [ ] 本地执行 `npm run build:prod` 成功完成
 - [ ] 构建产物无报错，体积合理
 - [ ] 静态资源路径正确，无404错误
 - [ ] 环境变量配置正确（开发/测试/生产）
@@ -88,21 +183,389 @@
 ---
-## 后端发布前检查清单
+## 3. 后端检查（backend-checklist）
-（此处省略详细内容，使用关羽提供的完整版本）
+### 📋 基础检查项
 #### 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<T>` 对象，非手动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已关闭或延期说明
 ---
-## CI/CD构建门禁规范
+## 4. CI/CD门禁（cicd-gatekeeper）
-（此处省略详细内容，使用之前创建的完整版本）
+### 🎯 规范目标
 建立自动化质量门禁，确保每次代码提交都经过严格验证，防止低质量代码进入主干分支，提升系统稳定性和开发效率。
 ### 🔒 门禁层级
 #### 1. 提交前门禁（Pre-commit）
 **触发时机**：`git commit` 执行前  
 **验证内容**：
 - ESLint 代码规范检查
 - Prettier 代码格式化
 - 简单的单元测试（快速执行）
 **工具配置**：
 - Husky + lint-staged
 - 配置文件：`.husky/pre-commit`
 #### 2. 推送前门禁（Pre-push）
 **触发时机**：`git push` 执行前  
 **验证内容**：
 - 完整的单元测试套件
 - 构建验证（`npm run build:prod`）
 - 集成测试（核心流程）
 **工具配置**：
 - Husky pre-push hook
 - 配置文件：`.husky/pre-push`
 #### 3. CI流水线门禁（CI Pipeline）
 **触发时机**：代码推送到远程仓库后  
 **验证内容**：
 - 完整的测试套件（单元+集成+端到端）
 - 代码覆盖率检查（分阶段目标：Q1≥30%，Q2≥50%，Q3≥80%）
 - 安全扫描（SAST）
 - 构建产物验证
 - 部署到测试环境
 **工具配置**：
 - Spug CI/CD 流水线
 - Gitea Webhook 触发
 #### 4. 发布前门禁（Release Gate）
 **触发时机**：准备发布到生产环境前  
 **验证内容**：
 - 生产环境冒烟测试
 - 性能基准测试
 - 安全合规检查
 - 回滚预案验证
 ### ⚙️ 具体配置要求
 #### ESLint 配置
 ```javascript
 // eslint.config.js 关键配置
 import globals from "globals";
 import pluginVue from "eslint-plugin-vue";
 import parserVue from "vue-eslint-parser";
 import importPlugin from "eslint-plugin-import";
 export default [
  {
    name: "app/files-to-lint",
    files: ["**/*.{js,mjs,jsx,vue}"],
  },
  {
    name: "app/files-to-ignore",
    ignores: ["**/dist/**", "**/node_modules/**", "**/help-center/**"],
  },
  ...pluginVue.configs["flat/recommended"],
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
      },
      parser: parserVue,
      ecmaVersion: "latest",
      sourceType: "module",
    },
    plugins: {
      import: importPlugin,
    },
    rules: {
      // 确保导入的模块实际存在（核心规则，防止构建失败）
      "import/no-unresolved": "error",
      // 确保导入的命名导出实际存在
      "import/named": "error",
      // 确保默认导出存在
      "import/default": "error",
      // 确保命名空间导出存在
      "import/namespace": "error",
    },
  },
 ];
 ```
 #### Java 后端配置
 ```xml
 <!-- pom.xml 关键插件 -->
 <plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.8.1</version>
 </plugin>
 <plugin>
  <groupId>com.github.spotbugs</groupId>
  <artifactId>spotbugs-maven-plugin</artifactId>
  <version>4.2.0</version>
 </plugin>
 ```
 #### 数据库迁移配置
 ```yaml
 # application.yml Flyway配置
 flyway:
  enabled: true
  locations: classpath:db/migration
  baseline-on-migrate: true
 ```
 #### Husky 配置
 ```bash
 # .husky/pre-commit
 #!/bin/sh
 npm run lint-staged
 # .husky/pre-push  
 #!/bin/sh
 npm run test:unit && npm run build:prod
 ```
 #### lint-staged 配置
 ```json
 // package.json
 {
  "lint-staged": {
    "*.{js,vue}": ["eslint --fix", "prettier --write"],
    "*.{css,scss}": ["stylelint --fix", "prettier --write"]
  }
 }
 ```
 ### 🚫 失败处理机制
 #### 自动处理
 - **构建失败**：自动阻止 PR 合并
 - **测试失败**：标记 PR 为失败状态
 - **安全漏洞**：立即通知安全团队
 #### 人工处理
 - **紧急修复**：可申请临时绕过（需架构师批准）
 - **误报处理**：提交豁免申请并说明原因
 - **规则调整**：通过 RFC 流程申请规则变更
 ### 📊 监控与度量
 #### 关键指标
 - 门禁通过率 ≥ 95%
 - 平均修复时间 ≤ 2小时
 - 误报率 ≤ 5%
 #### 报告机制
 - 每日门禁失败统计
 - 周度质量趋势报告
 - 月度规则优化建议
 ### 🔄 持续改进
 #### 规则演进
 - 每月评审门禁规则有效性
 - 根据项目需求调整检查强度
 - 引入新的质量检查工具
 #### 团队培训
 - 新成员入职培训包含门禁规范
 - 定期分享最佳实践案例
 - 建立常见问题解决方案库
 ---
-## 代码提交变更说明模板
+## 5. 发布确认与回滚预案
-（此处省略详细内容，使用之前创建的完整版本）
+### 📋 发布前最终确认清单
 #### 前端确认
 - [ ] 本地构建成功（`npm run build:prod`）
 - [ ] 核心功能流程测试通过
 - [ ] 模块导入检查通过（无import错误）
 - [ ] 兼容性测试完成
 #### 后端确认
 - [ ] Maven编译成功（`mvn compile`）
 - [ ] 单元测试通过
 - [ ] 数据库脚本验证通过
 - [ ] API接口测试通过
 #### 协同确认
 - [ ] 前后端接口契约一致
 - [ ] 联调测试通过
 - [ ] Code Review 已完成
 - [ ] 测试环境部署验证通过
 ### 🚨 回滚预案
 #### 触发条件
 - [ ] 生产环境出现严重Bug
 - [ ] 性能严重下降
 - [ ] 数据一致性问题
 - [ ] 安全漏洞暴露
 #### 回滚步骤
 1. **立即停止**：暂停新流量进入
 2. **版本回退**：部署上一个稳定版本
 3. **数据回滚**：执行数据库回滚脚本（如有）
 4. **验证恢复**：确认系统功能正常
 5. **问题分析**：记录根本原因和改进措施
 #### 责任分工
 - **技术负责人**：执行回滚操作
 - **测试负责人**：验证回滚后功能
 - **项目经理**：协调沟通和进度同步
 - **运维团队**：监控系统状态
 ### 📞 紧急联系人
 | 角色 | 姓名 | 联系方式 | 职责 |
 |------|------|----------|------|
 | 技术负责人 | 诸葛亮 | @诸葛亮 | 架构决策和技术指导 |
 | 前端负责人 | 赵云 | @赵云 | 前端问题处理 |
 | 后端负责人 | 关羽 | @关羽 | 后端问题处理 |
 | 测试负责人 | 张飞 | @张飞 | 质量验证和问题复现 |
 | 项目经理 | 刘备 | @刘备 | 项目协调和进度管理 |
 | 文档负责人 | 陈琳 | @陈琳 | 文档维护和知识沉淀 |
 ---