From 0076753c1957234b7a98d9314090cce15e0da0f4 Mon Sep 17 00:00:00 2001 From: chenlin Date: Fri, 24 Apr 2026 17:03:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E4=B8=89=E4=BB=BD?= =?UTF-8?q?=E6=9E=84=E5=BB=BA=E9=97=A8=E7=A6=81=E7=9B=B8=E5=85=B3=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 《前端发布前检查清单》 - 《CI/CD构建门禁规范》 - 《代码提交变更说明模板》 为解决getDepartmentList导入错误等构建问题提供标准化文档支持 --- docs/specs/cicd-gatekeeper.md | 134 +++++++++++++++++++++++++++++++ docs/specs/commit-template.md | 129 +++++++++++++++++++++++++++++ docs/specs/frontend-checklist.md | 82 +++++++++++++++++++ 3 files changed, 345 insertions(+) create mode 100644 docs/specs/cicd-gatekeeper.md create mode 100644 docs/specs/commit-template.md create mode 100644 docs/specs/frontend-checklist.md diff --git a/docs/specs/cicd-gatekeeper.md b/docs/specs/cicd-gatekeeper.md new file mode 100644 index 00000000..8bdee6ab --- /dev/null +++ b/docs/specs/cicd-gatekeeper.md @@ -0,0 +1,134 @@ +# CI/CD构建门禁规范 + +## 🎯 规范目标 + +建立自动化质量门禁，确保每次代码提交都经过严格验证，防止低质量代码进入主干分支，提升系统稳定性和开发效率。 + +## 🔒 门禁层级 + +### 1. 提交前门禁（Pre-commit） +**触发时机**：`git commit` 执行前 +**验证内容**： +- ESLint 代码规范检查 +- Prettier 代码格式化 +- 简单的单元测试（快速执行） + +**工具配置**： +- Husky + lint-staged +- 配置文件：`.husky/pre-commit` + +### 2. 推送前门禁（Pre-push） +**触发时机**：`git push` 执行前 +**验证内容**： +- 完整的单元测试套件 +- 构建验证（`npm run build`） +- 集成测试（核心流程） + +**工具配置**： +- Husky pre-push hook +- 配置文件：`.husky/pre-push` + +### 3. CI流水线门禁（CI Pipeline） +**触发时机**：代码推送到远程仓库后 +**验证内容**： +- 完整的测试套件（单元+集成+端到端） +- 代码覆盖率检查（≥80%） +- 安全扫描（SAST） +- 构建产物验证 +- 部署到测试环境 + +**工具配置**： +- Spug CI/CD 流水线 +- Gitea Webhook 触发 + +### 4. 发布前门禁（Release Gate） +**触发时机**：准备发布到生产环境前 +**验证内容**： +- 生产环境冒烟测试 +- 性能基准测试 +- 安全合规检查 +- 回滚预案验证 + +## ⚙️ 具体配置要求 + +### ESLint 配置 +```javascript +// .eslintrc.js 关键配置 +module.exports = { + plugins: ['import'], + rules: { + // 确保导入的模块实际存在 + 'import/no-unresolved': 'error', + // 确保导入的成员实际存在 + 'import/named': 'error', + // 禁止未使用的导入 + 'import/no-unused-modules': 'warn' + } +}; +``` + +### Husky 配置 +```bash +# .husky/pre-commit +#!/bin/sh +npm run lint-staged + +# .husky/pre-push +#!/bin/sh +npm run test:unit && npm run build +``` + +### 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% + +### 报告机制 +- 每日门禁失败统计 +- 周度质量趋势报告 +- 月度规则优化建议 + +## 🔄 持续改进 + +### 规则演进 +- 每月评审门禁规则有效性 +- 根据项目需求调整检查强度 +- 引入新的质量检查工具 + +### 团队培训 +- 新成员入职培训包含门禁规范 +- 定期分享最佳实践案例 +- 建立常见问题解决方案库 + +--- + +**文档版本**：v1.0 +**最后更新**：2026年4月24日 +**负责人**：陈琳（文档专家） +**技术方案**：诸葛亮（架构师） +**适用范围**：HIS 系统所有项目 diff --git a/docs/specs/commit-template.md b/docs/specs/commit-template.md new file mode 100644 index 00000000..c06d1c26 --- /dev/null +++ b/docs/specs/commit-template.md @@ -0,0 +1,129 @@ +# 代码提交变更说明模板 + +## 📝 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` 命令执行过程 +2. **成功标识**：明确显示构建成功的提示信息 +3. **时间戳**：截图包含当前时间，证明是最新构建 +4. **分支信息**：显示当前工作分支名称 + +### 截图示例 +``` +$ git checkout feature/patient-edit +$ npm run build + +> his-system@1.0.0 build +> vue-cli-service build + +⠇ Building for production... + + DONE Build complete. The dist directory is ready to be deployed. + INFO Check out deployment instructions at https://cli.vuejs.org/guide/deployment.html + +✨ Done in 45.23s. +``` + +## ⚠️ 禁止行为 + +### 严重违规（直接拒绝合并） +- 无构建验证截图 +- 代码存在 ESLint 错误 +- 未填写变更说明 +- 修改无关代码文件 + +### 轻微违规（要求修正后重新提交） +- 描述过于简单 +- 测试覆盖不完整 +- 文档更新滞后 +- 格式不符合规范 + +## 💡 最佳实践 + +### 高质量提交特征 +- **原子性**：每次提交只解决一个问题 +- **可追溯**：关联具体的需求或Bug ID +- **可验证**：提供完整的验证证据 +- **可理解**：描述清晰，他人能快速理解 + +### 团队协作建议 +- 提交前先在本地完整测试 +- 复杂变更提前与团队沟通 +- 及时更新相关文档 +- 主动帮助新人熟悉规范 + +--- + +**文档版本**：v1.0 +**最后更新**：2026年4月24日 +**负责人**：陈琳（文档专家） +**适用范围**：HIS 系统所有开发人员 diff --git a/docs/specs/frontend-checklist.md b/docs/specs/frontend-checklist.md new file mode 100644 index 00000000..3709eb11 --- /dev/null +++ b/docs/specs/frontend-checklist.md @@ -0,0 +1,82 @@ +# 前端发布前检查清单 + +## 📋 基础检查项 + +### 代码质量 +- [ ] 代码已通过 ESLint 检查，无警告和错误 +- [ ] 代码已通过 Prettier 格式化 +- [ ] 无 console.log() 等调试代码残留 +- [ ] 变量命名符合规范，语义清晰 +- [ ] 函数职责单一，复杂度适中 + +### 构建验证 +- [ ] 本地执行 `npm run build` 成功完成 +- [ ] 构建产物无报错，体积合理 +- [ ] 静态资源路径正确，无404错误 +- [ ] 环境变量配置正确（开发/测试/生产） + +### 功能验证 +- [ ] 核心功能流程完整测试通过 +- [ ] 边界条件和异常场景已覆盖 +- [ ] 表单验证逻辑正确 +- [ ] API 接口调用正常，错误处理完善 +- [ ] 路由跳转逻辑正确 + +## 🔧 技术检查项 + +### 模块导入检查 +- [ ] 所有 import 语句引用的模块实际存在 +- [ ] 无未使用的 import 导入 +- [ ] 路径别名（@/）配置正确 +- [ ] 第三方库版本兼容性确认 + +### 性能优化 +- [ ] 组件按需加载（懒加载）已配置 +- [ ] 大数据列表已实现虚拟滚动或分页 +- [ ] 图片资源已压缩，格式合适 +- [ ] 无内存泄漏风险（事件监听器、定时器等） + +### 安全检查 +- [ ] 用户输入已做 XSS 防护 +- [ ] 敏感信息不在前端硬编码 +- [ ] API 请求已做 CSRF 防护 +- [ ] 权限控制逻辑正确 + +## 🌐 兼容性检查 + +### 浏览器兼容 +- [ ] 主流浏览器（Chrome、Firefox、Safari、Edge）显示正常 +- [ ] 移动端适配良好（如适用） +- [ ] 分辨率适配（1366x768、1920x1080等） + +### 设备兼容 +- [ ] 触摸设备操作体验良好 +- [ ] 键盘导航支持完整 +- [ ] 屏幕阅读器兼容性（无障碍） + +## 📱 发布准备 + +### 文档更新 +- [ ] 相关 API 文档已同步更新 +- [ ] 用户操作手册已更新（如适用） +- [ ] 变更日志已记录 + +### 回滚预案 +- [ ] 回滚方案已准备 +- [ ] 数据兼容性已确认 +- [ ] 紧急联系人已明确 + +## ✅ 最终确认 + +### 发布前最后检查 +- [ ] 本地构建截图已附在 PR 中 +- [ ] 测试环境部署验证通过 +- [ ] Code Review 已完成并获得批准 +- [ ] 相关 Bug 已关闭或延期说明 + +--- + +**文档版本**：v1.0 +**最后更新**：2026年4月24日 +**负责人**：陈琳（文档专家） +**适用范围**：HIS 系统所有前端项目