2026-03-04 21:51:50 +08:00
|
|
|
|
# 蚊子系统 (mosquito)
|
|
|
|
|
|
|
|
|
|
|
|
> 活动传播、邀请奖励与运营分析平台
|
|
|
|
|
|
|
|
|
|
|
|
## 项目概述
|
|
|
|
|
|
|
|
|
|
|
|
蚊子系统是一个Spring Boot 3 + Vue 3的活动传播、邀请奖励与运营分析平台。系统包含管理后台（H5）和用户端（H5），支持活动管理、用户管理、奖励发放、风险管理等功能。
|
|
|
|
|
|
|
|
|
|
|
|
## 技术栈
|
|
|
|
|
|
|
|
|
|
|
|
### 后端
|
|
|
|
|
|
- **框架**: Spring Boot 3 (Java 17)
|
|
|
|
|
|
- **数据库**: MySQL 8.0 + Flyway
|
|
|
|
|
|
- **缓存**: Redis Cluster
|
|
|
|
|
|
- **测试**: JUnit 5 + Mockito + JaCoCo
|
|
|
|
|
|
|
|
|
|
|
|
### 前端
|
|
|
|
|
|
- **框架**: Vue 3 + TypeScript
|
|
|
|
|
|
- **UI库**: Element Plus
|
|
|
|
|
|
- **状态管理**: Pinia
|
|
|
|
|
|
- **构建**: Vite
|
|
|
|
|
|
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
蚊子/
|
|
|
|
|
|
├── backend/ # Spring Boot后端
|
|
|
|
|
|
│ └── src/main/java/com/mosquito/
|
|
|
|
|
|
│ ├── project/ # 核心业务代码
|
|
|
|
|
|
│ │ ├── controller/ # REST控制器
|
|
|
|
|
|
│ │ ├── service/ # 业务逻辑
|
|
|
|
|
|
│ │ ├── mapper/ # 数据访问
|
|
|
|
|
|
│ │ ├── domain/ # 领域模型
|
|
|
|
|
|
│ │ ├── dto/ # 数据传输对象
|
|
|
|
|
|
│ │ └── config/ # 配置类
|
|
|
|
|
|
│ └── MosquitoprojectApplication.java
|
|
|
|
|
|
│
|
|
|
|
|
|
├── frontend/
|
|
|
|
|
|
│ ├── admin/ # 管理后台Vue项目
|
|
|
|
|
|
│ └── h5/ # 用户端H5项目
|
|
|
|
|
|
│
|
|
|
|
|
|
├── docs/ # 项目文档
|
|
|
|
|
|
│ ├── prd/ # PRD文档（含开发任务追踪）
|
|
|
|
|
|
│ ├── api.md # API文档
|
|
|
|
|
|
│ ├── architecture.md # 架构文档
|
|
|
|
|
|
│ └── *.md # 其他文档
|
|
|
|
|
|
│
|
|
|
|
|
|
└── .claude/
|
|
|
|
|
|
└── plan/ # 执行计划
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 核心文档
|
|
|
|
|
|
|
|
|
|
|
|
| 文档 | 说明 |
|
|
|
|
|
|
|------|------|
|
|
|
|
|
|
| `docs/prd/管理后台PRD-v1.0.md` | 管理后台PRD（角色、权限、审批流程） |
|
|
|
|
|
|
| `docs/prd/开发任务追踪.md` | 开发任务分解与追踪（136个任务） |
|
|
|
|
|
|
| `docs/api.md` | API接口文档 |
|
|
|
|
|
|
| `docs/DEPLOYMENT_GUIDE.md` | 部署指南 |
|
|
|
|
|
|
|
|
|
|
|
|
## 开发命令
|
|
|
|
|
|
|
|
|
|
|
|
### 后端
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 构建与测试
|
|
|
|
|
|
mvn -B -DskipTests=false clean verify
|
|
|
|
|
|
|
|
|
|
|
|
# 运行（开发）
|
|
|
|
|
|
mvn spring-boot:run
|
|
|
|
|
|
|
|
|
|
|
|
# 运行测试
|
|
|
|
|
|
mvn test
|
|
|
|
|
|
|
|
|
|
|
|
# 生成覆盖率报告
|
|
|
|
|
|
mvn test jacoco:report
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 前端
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 安装依赖
|
|
|
|
|
|
cd frontend/admin && npm install
|
|
|
|
|
|
|
|
|
|
|
|
# 开发模式
|
|
|
|
|
|
npm run dev
|
|
|
|
|
|
|
|
|
|
|
|
# 构建
|
|
|
|
|
|
npm run build
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 开发规范
|
|
|
|
|
|
|
|
|
|
|
|
### 代码风格
|
|
|
|
|
|
- 遵循Spring Boot最佳实践
|
|
|
|
|
|
- 使用阿里Java开发规约
|
|
|
|
|
|
- 前端使用ESLint + Prettier
|
|
|
|
|
|
|
|
|
|
|
|
### 测试要求
|
|
|
|
|
|
- 单元测试覆盖率目标: 70%分支覆盖率
|
|
|
|
|
|
- 核心业务必须有完整测试
|
|
|
|
|
|
- 新功能必须包含测试用例
|
|
|
|
|
|
|
|
|
|
|
|
### Git提交规范
|
|
|
|
|
|
- 使用Conventional Commits格式
|
|
|
|
|
|
- 提交信息: `type(scope): message`
|
|
|
|
|
|
- 类型: feat, fix, docs, test, chore
|
|
|
|
|
|
|
|
|
|
|
|
## 权限系统（生产级PRD）
|
|
|
|
|
|
|
|
|
|
|
|
### 角色体系 (15个角色)
|
|
|
|
|
|
- **系统层**: 超级管理员、系统管理员
|
|
|
|
|
|
- **管理层**: 运营总监、运营经理、市场总监、市场经理、财务经理、风控经理、客服主管
|
|
|
|
|
|
- **执行层**: 运营专员、市场专员、财务专员、风控专员、客服专员
|
|
|
|
|
|
- **审计层**: 审计员
|
|
|
|
|
|
|
|
|
|
|
|
### 权限体系 (225个权限点)
|
|
|
|
|
|
- **模块**: 仪表盘、活动管理、用户管理、奖励管理、风险管理、审批中心、审计日志、通知管理、系统配置、权限管理
|
|
|
|
|
|
- **权限粒度**: 模块.资源.操作.数据范围
|
|
|
|
|
|
|
|
|
|
|
|
### 数据权限 (3级)
|
|
|
|
|
|
- 全部 (ALL): 超级管理员、审计员
|
|
|
|
|
|
- 部门 (DEPARTMENT): 总监、经理级别
|
|
|
|
|
|
- 个人 (OWN): 专员级别
|
|
|
|
|
|
|
|
|
|
|
|
### 审批流程 (13个场景)
|
|
|
|
|
|
- 活动创建/编辑/删除审批
|
|
|
|
|
|
- 奖励发放审批（大额奖励多级审批）
|
|
|
|
|
|
- 用户冻结/解冻审批
|
|
|
|
|
|
- 敏感数据导出审批
|
|
|
|
|
|
- 风控规则审批
|
|
|
|
|
|
- 系统配置审批
|
|
|
|
|
|
|
|
|
|
|
|
## 常用工作流
|
|
|
|
|
|
|
|
|
|
|
|
### 1. PRD设计工作流 (zcf:workflow)
|
|
|
|
|
|
```
|
|
|
|
|
|
研究 → 构思 → 计划 → 执行 → 优化 → 评审
|
|
|
|
|
|
```
|
|
|
|
|
|
- 需求评分（0-10分）
|
|
|
|
|
|
- 方案对比分析
|
|
|
|
|
|
- 详细执行计划
|
|
|
|
|
|
- 代码实现与优化
|
|
|
|
|
|
- 质量评审
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 技能调用
|
|
|
|
|
|
```bash
|
|
|
|
|
|
/zcf:workflow <任务描述> # 结构化开发工作流
|
|
|
|
|
|
/simplify # 代码审查与优化
|
|
|
|
|
|
/testing # 测试策略
|
|
|
|
|
|
/backend # 后端开发规范
|
|
|
|
|
|
/frontend # 前端开发规范
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 经验总结
|
|
|
|
|
|
|
|
|
|
|
|
### PRD设计经验
|
|
|
|
|
|
1. **需求评分**: 先评估需求完整性，低于7分需补充信息
|
|
|
|
|
|
2. **方案选择**: 提供多种方案对比，明确推荐理由
|
|
|
|
|
|
3. **任务分解**: 将PRD功能清单对应到开发任务，便于跟踪
|
|
|
|
|
|
4. **评审迭代**: 产品专家+技术专家双重评审
|
|
|
|
|
|
|
|
|
|
|
|
### UI/UX设计经验
|
|
|
|
|
|
1. **设计系统**: 建立完整的设计令牌（色彩、字体、间距）
|
|
|
|
|
|
2. **组件化**: Atomic Design方法论
|
|
|
|
|
|
3. **权限驱动**: 按钮级、路由级、数据级权限UI控制
|
|
|
|
|
|
|
|
|
|
|
|
### 开发实施经验
|
|
|
|
|
|
1. **分阶段实施**: 基础框架 → 权限核心 → 审批流 → 业务模块
|
|
|
|
|
|
2. **任务追踪**: 136个开发任务与PRD功能点一一对应
|
|
|
|
|
|
3. **测试策略**: 单元测试 → 集成测试 → E2E测试
|
|
|
|
|
|
|
|
|
|
|
|
## 注意事项
|
|
|
|
|
|
|
|
|
|
|
|
- 使用Serena工具进行代码搜索和编辑时，需要指定relative_path参数
|
|
|
|
|
|
- 项目使用JaCoCo进行测试覆盖率分析
|
|
|
|
|
|
- 管理后台使用Vue 3 + TypeScript + Element Plus
|
|
|
|
|
|
- API使用X-API-Key进行认证
|
2026-03-23 19:32:24 +08:00
|
|
|
|
|
|
|
|
|
|
## 2026-03 实战经验补充（智能体执行）
|
|
|
|
|
|
|
|
|
|
|
|
1. **迁移策略要前置统一**
|
|
|
|
|
|
- PostgreSQL 作为唯一目标方言。
|
|
|
|
|
|
- 历史迁移脚本仅在未发布环境允许改写，发布后必须增量修复迁移。
|
|
|
|
|
|
|
|
|
|
|
|
2. **测试环境漂移是主要假失败来源**
|
|
|
|
|
|
- 严格迁移测试依赖容器运行时与临时目录配置，需固定到 CI 命令而不是口头约定。
|
|
|
|
|
|
- 对 “Skipped” 项要有脚本化断言（如 `assert-migration-not-skipped.sh`）。
|
|
|
|
|
|
|
|
|
|
|
|
3. **仓库污染必须脚本化治理**
|
|
|
|
|
|
- 通过 `clean-artifacts.sh` 做 dry-run 门禁，避免根目录与前端目录被测试产物污染。
|
|
|
|
|
|
- 构建产物优先归档后清理，降低误删风险。
|
|
|
|
|
|
|
|
|
|
|
|
4. **日志管理需要“归档 + 索引”双机制**
|
|
|
|
|
|
- `archive-logs.sh` 负责搬迁历史日志，`update-log-archive-index.sh` 负责检索索引。
|
|
|
|
|
|
- 持续运行任务会自动再生日志，清理前需识别后台进程状态。
|
|
|
|
|
|
|
|
|
|
|
|
5. **发布阶段必须尊重远端保护策略**
|
|
|
|
|
|
- `main` 受保护时不可强推覆盖，优先走任务分支 + PR。
|
|
|
|
|
|
- 若业务要求覆盖，先确认分支保护权限再执行推送。
|
