docs: 添加三份构建门禁相关文档

- 《前端发布前检查清单》 - 《CI/CD构建门禁规范》 - 《代码提交变更说明模板》为解决getDepartmentList导入错误等构建问题提供标准化文档支持
2026-04-24 17:03:53 +08:00
parent 957d426042
commit 0076753c19
3 changed files with 345 additions and 0 deletions
--- a/docs/specs/cicd-gatekeeper.md
+++ 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 系统所有项目
--- a/docs/specs/commit-template.md
+++ 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 系统所有开发人员
--- a/docs/specs/frontend-checklist.md
+++ 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 系统所有前端项目