# 蚊子系统 (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进行认证