199 lines
6.3 KiB
Markdown
199 lines
6.3 KiB
Markdown
# 蚊子系统 (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 实战经验补充（智能体执行）
|
||
|
||
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。
|
||
- 若业务要求覆盖，先确认分支保护权限再执行推送。
|