From 914f2d8229c0205569c7c7cdad6816c634dc3d6f Mon Sep 17 00:00:00 2001 From: chenlin Date: Sat, 25 Apr 2026 12:12:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=89=E5=88=98=E5=A4=87=E5=BB=BA?= =?UTF-8?q?=E8=AE=AE=E7=BB=93=E6=9E=84=E9=87=8D=E6=96=B0=E6=95=B4=E7=90=86?= =?UTF-8?q?=E3=80=8AHIS=E9=A1=B9=E7=9B=AE=E5=8F=91=E5=B8=83=E6=A3=80?= =?UTF-8?q?=E6=9F=A5=E6=B8=85=E5=8D=95=20v1.0=E3=80=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/specs/his-release-checklist-v1.0.md | 489 ++++++++++++++++++++++- 1 file changed, 476 insertions(+), 13 deletions(-) diff --git a/docs/specs/his-release-checklist-v1.0.md b/docs/specs/his-release-checklist-v1.0.md index c90b5a6d..fc88aa58 100644 --- 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项目发布的标准化检查依据。每次发布前必须逐项确认。 ## 目录 -- [前端发布前检查清单](#前端发布前检查清单) -- [后端发布前检查清单](#后端发布前检查清单) -- [CI/CD构建门禁规范](#cicd构建门禁规范) -- [代码提交变更说明模板](#代码提交变更说明模板) +- [1. 提交规范（commit-template）](#1-提交规范commit-template) +- [2. 前端检查（frontend-checklist）](#2-前端检查frontend-checklist) +- [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` 对象，非手动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 + + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.1 + + + com.github.spotbugs + spotbugs-maven-plugin + 4.2.0 + +``` + +#### 数据库迁移配置 +```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. **问题分析**：记录根本原因和改进措施 + +#### 责任分工 +- **技术负责人**：执行回滚操作 +- **测试负责人**：验证回滚后功能 +- **项目经理**：协调沟通和进度同步 +- **运维团队**：监控系统状态 + +### 📞 紧急联系人 + +| 角色 | 姓名 | 联系方式 | 职责 | +|------|------|----------|------| +| 技术负责人 | 诸葛亮 | @诸葛亮 | 架构决策和技术指导 | +| 前端负责人 | 赵云 | @赵云 | 前端问题处理 | +| 后端负责人 | 关羽 | @关羽 | 后端问题处理 | +| 测试负责人 | 张飞 | @张飞 | 质量验证和问题复现 | +| 项目经理 | 刘备 | @刘备 | 项目协调和进度管理 | +| 文档负责人 | 陈琳 | @陈琳 | 文档维护和知识沉淀 | ---