张翔
9f8bf041c3
fix: 修复测试配置和依赖检查 perf: 优化雪花算法性能 refactor: 清理冗余代码和未使用的导入 style: 统一代码格式和注释 test: 添加单元测试和集成测试 ci: 更新CI配置和构建脚本 chore: 更新依赖和配置文件
313 lines
6.1 KiB
Markdown
313 lines
6.1 KiB
Markdown
# 系统质量提升 - 执行指南
|
||
|
||
## 📋 概述
|
||
|
||
本文档指导您如何在新的独立会话中批量执行系统质量提升计划。
|
||
|
||
## 🎯 目标
|
||
|
||
将系统完成度从 68% 提升至 90% 以上，包括：
|
||
- 单元测试覆盖率 >= 80%
|
||
- 所有 Handler 函数式迁移完成
|
||
- 前端页面功能完整
|
||
- CI/CD 自动化完善
|
||
- 性能优化和监控完善
|
||
|
||
## 🚀 快速开始
|
||
|
||
### Step 1: 打开新的 IDE 会话
|
||
|
||
在 Trae IDE 中打开新的会话，工作目录设置为：
|
||
```
|
||
/Users/zhangxiang/Codes/Novalon/novalon-manage-system-quality
|
||
```
|
||
|
||
### Step 2: 验证环境
|
||
|
||
```bash
|
||
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system-quality
|
||
|
||
# 检查当前分支
|
||
git branch
|
||
|
||
# 应该显示：* feature/system-quality-improvement
|
||
|
||
# 检查工作目录
|
||
pwd
|
||
|
||
# 应该显示：/Users/zhangxiang/Codes/Novalon/novalon-manage-system-quality
|
||
```
|
||
|
||
### Step 3: 调用 executing-plans 技能
|
||
|
||
在新会话中，首先调用 `executing-plans` 技能：
|
||
|
||
```
|
||
@executing-plans
|
||
```
|
||
|
||
### Step 4: 加载计划文档
|
||
|
||
执行计划时，引用以下文档：
|
||
```
|
||
docs/plans/2026-03-12-system-quality-improvement.md
|
||
```
|
||
|
||
## 📁 Worktree 结构
|
||
|
||
```
|
||
/Users/zhangxiang/Codes/Novalon/
|
||
├── novalon-manage-system/ # 主工作目录（原分支）
|
||
├── novalon-manage-system-quality/ # 质量提升分支（新会话）
|
||
└── novalon-manage-system-refactor/ # 重构分支（其他工作）
|
||
```
|
||
|
||
## 🔄 执行流程
|
||
|
||
### Phase 1: 质量基础设施（2-3周）
|
||
|
||
1. **Task 1**: 配置 JaCoCo 代码覆盖率工具
|
||
2. **Task 2**: 创建测试基础配置类
|
||
3. **Task 3-14**: 为所有 Service 编写单元测试
|
||
4. **Task 15**: 运行所有单元测试并生成覆盖率报告
|
||
5. **Task 16**: 配置 Woodpecker CI/CD 流水线
|
||
6. **Task 17**: 添加静态代码分析
|
||
|
||
### Phase 2: 功能完善（3-4周）
|
||
|
||
1. **Task 18**: 完成 SysUserHandler 函数式迁移
|
||
2. **Task 19**: 完成其他 Handler 的函数式迁移
|
||
3. **Task 20**: 实现前端用户管理页面
|
||
4. **Task 21**: 实现其他前端管理页面
|
||
5. **Task 22**: 完善 API 文档
|
||
|
||
### Phase 3: 效能优化（2-3周）
|
||
|
||
1. **Task 23**: 性能测试
|
||
2. **Task 24**: 数据库查询优化
|
||
3. **Task 25**: 缓存策略优化
|
||
4. **Task 26**: 添加监控和告警
|
||
5. **Task 27**: 安全扫描
|
||
6. **Task 28**: 编写架构设计文档
|
||
7. **Task 29**: 编写部署文档
|
||
|
||
## 📊 检查点
|
||
|
||
在每个 Phase 完成后，创建检查点：
|
||
|
||
### Phase 1 完成检查点
|
||
```bash
|
||
# 运行所有测试
|
||
cd novalon-manage-api/manage-sys
|
||
mvn clean verify
|
||
|
||
# 检查覆盖率
|
||
open target/site/jacoco/index.html
|
||
|
||
# 确认覆盖率 >= 80%
|
||
```
|
||
|
||
### Phase 2 完成检查点
|
||
```bash
|
||
# 测试后端 API
|
||
curl http://localhost:8080/api/users
|
||
|
||
# 测试前端页面
|
||
cd novalon-manage-web
|
||
npm run dev
|
||
|
||
# 访问 http://localhost:5173
|
||
```
|
||
|
||
### Phase 3 完成检查点
|
||
```bash
|
||
# 运行性能测试
|
||
k6 run novalon-manage-api/manage-sys/src/test/k6/performance-test.js
|
||
|
||
# 检查监控指标
|
||
curl http://localhost:8080/actuator/prometheus
|
||
|
||
# 访问 Grafana Dashboard
|
||
open http://localhost:3000
|
||
```
|
||
|
||
## 🎯 成功标准
|
||
|
||
### Phase 1 成功标准
|
||
- ✅ 单元测试覆盖率 >= 80%
|
||
- ✅ 所有测试通过
|
||
- ✅ CI/CD 流水线正常运行
|
||
- ✅ 静态代码分析无严重问题
|
||
|
||
### Phase 2 成功标准
|
||
- ✅ 所有 Handler 迁移到函数式风格
|
||
- ✅ 所有前端页面功能完整
|
||
- ✅ API 文档完善
|
||
|
||
### Phase 3 成功标准
|
||
- ✅ 性能测试通过（P95 < 500ms）
|
||
- ✅ 数据库查询优化完成
|
||
- ✅ 缓存策略生效
|
||
- ✅ 监控告警系统运行正常
|
||
- ✅ 安全扫描无高危漏洞
|
||
- ✅ 文档完善
|
||
|
||
## 🛠️ 常用命令
|
||
|
||
### Git 操作
|
||
```bash
|
||
# 查看当前分支
|
||
git branch
|
||
|
||
# 查看更改
|
||
git status
|
||
|
||
# 提交更改
|
||
git add .
|
||
git commit -m "message"
|
||
|
||
# 推送到远程
|
||
git push origin feature/system-quality-improvement
|
||
```
|
||
|
||
### Maven 操作
|
||
```bash
|
||
# 编译
|
||
cd novalon-manage-api
|
||
mvn clean compile
|
||
|
||
# 测试
|
||
mvn test
|
||
|
||
# 打包
|
||
mvn clean package
|
||
|
||
# 验证（包含测试和覆盖率）
|
||
mvn verify
|
||
```
|
||
|
||
### 前端操作
|
||
```bash
|
||
# 安装依赖
|
||
cd novalon-manage-web
|
||
npm install
|
||
|
||
# 开发服务器
|
||
npm run dev
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 测试
|
||
npm run test
|
||
```
|
||
|
||
### Docker 操作
|
||
```bash
|
||
# 构建镜像
|
||
docker-compose build
|
||
|
||
# 启动服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
```
|
||
|
||
## 📝 提交规范
|
||
|
||
### Commit Message 格式
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### Type 类型
|
||
- `feat`: 新功能
|
||
- `fix`: 修复 bug
|
||
- `refactor`: 重构
|
||
- `test`: 测试
|
||
- `docs`: 文档
|
||
- `perf`: 性能优化
|
||
- `ci`: CI/CD
|
||
- `chore`: 构建/工具
|
||
|
||
### 示例
|
||
```
|
||
test: add unit tests for DictionaryService
|
||
|
||
- Add testFindAll method
|
||
- Add testFindById method
|
||
- Add testSave method
|
||
- Add testUpdate method
|
||
- Add testDeleteById method
|
||
|
||
Closes #123
|
||
```
|
||
|
||
## 🔧 故障排查
|
||
|
||
### 问题：Maven 编译失败
|
||
```bash
|
||
# 清理并重新编译
|
||
mvn clean install -U
|
||
```
|
||
|
||
### 问题：测试失败
|
||
```bash
|
||
# 查看详细错误信息
|
||
mvn test -X
|
||
|
||
# 运行特定测试
|
||
mvn test -Dtest=ClassName
|
||
```
|
||
|
||
### 问题：Docker 容器启动失败
|
||
```bash
|
||
# 查看容器日志
|
||
docker-compose logs <service-name>
|
||
|
||
# 重新构建镜像
|
||
docker-compose build --no-cache <service-name>
|
||
```
|
||
|
||
### 问题：前端构建失败
|
||
```bash
|
||
# 清理缓存
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
|
||
# 重新构建
|
||
npm run build
|
||
```
|
||
|
||
## 📚 参考文档
|
||
|
||
- [系统质量提升计划](docs/plans/2026-03-12-system-quality-improvement.md)
|
||
- [基础设施重构 Phase 2](docs/plans/2026-03-12-infrastructure-refactoring-phase2.md)
|
||
- [E2E 测试报告](docs/reports/E2E_TEST_REPORT.md)
|
||
- [API 文档](http://localhost:8080/swagger-ui.html)
|
||
|
||
## 🎓 最佳实践
|
||
|
||
1. **TDD 原则**：先写测试，再写实现
|
||
2. **小步提交**：每个 Task 完成后立即提交
|
||
3. **频繁验证**：每个 Phase 完成后运行完整测试
|
||
4. **文档同步**：代码变更时同步更新文档
|
||
5. **代码审查**：重要变更前进行代码审查
|
||
|
||
## 🚦 下一步
|
||
|
||
1. 打开新的 IDE 会话
|
||
2. 设置工作目录为 `/Users/zhangxiang/Codes/Novalon/novalon-manage-system-quality`
|
||
3. 调用 `@executing-plans` 技能
|
||
4. 开始执行 Phase 1 的任务
|
||
|
||
祝您执行顺利！🎉
|