docs: 添加三份构建门禁相关文档
- 《前端发布前检查清单》 - 《CI/CD构建门禁规范》 - 《代码提交变更说明模板》 为解决getDepartmentList导入错误等构建问题提供标准化文档支持
This commit is contained in:
134
docs/specs/cicd-gatekeeper.md
Normal file
134
docs/specs/cicd-gatekeeper.md
Normal file
@@ -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 系统所有项目
|
||||||
129
docs/specs/commit-template.md
Normal file
129
docs/specs/commit-template.md
Normal file
@@ -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 系统所有开发人员
|
||||||
82
docs/specs/frontend-checklist.md
Normal file
82
docs/specs/frontend-checklist.md
Normal file
@@ -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 系统所有前端项目
|
||||||
Reference in New Issue
Block a user