niuniu/wenzi

Fork 0

Files

Your Name e5b0f65156

CI / build_test_package (push) Has been cancelled

Details

CI / auto_merge (push) Has been cancelled

Details

docs: update agent rules and add latest e2e reports

2026-03-23 19:32:24 +08:00

6.3 KiB

Raw Blame History

蚊子系统 (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`	部署指南

开发命令

后端

# 构建与测试
mvn -B -DskipTests=false clean verify

# 运行（开发）
mvn spring-boot:run

# 运行测试
mvn test

# 生成覆盖率报告
mvn test jacoco:report

前端

# 安装依赖
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. 技能调用

/zcf:workflow <任务描述>     # 结构化开发工作流
/simplify                   # 代码审查与优化
/testing                     # 测试策略
/backend                     # 后端开发规范
/frontend                   # 前端开发规范

经验总结

PRD设计经验

需求评分: 先评估需求完整性，低于7分需补充信息
方案选择: 提供多种方案对比，明确推荐理由
任务分解: 将PRD功能清单对应到开发任务，便于跟踪
评审迭代: 产品专家+技术专家双重评审

UI/UX设计经验

设计系统: 建立完整的设计令牌（色彩、字体、间距）
组件化: Atomic Design方法论
权限驱动: 按钮级、路由级、数据级权限UI控制

开发实施经验

分阶段实施: 基础框架 → 权限核心 → 审批流 → 业务模块
任务追踪: 136个开发任务与PRD功能点一一对应
测试策略: 单元测试 → 集成测试 → E2E测试

注意事项

使用Serena工具进行代码搜索和编辑时，需要指定relative_path参数
项目使用JaCoCo进行测试覆盖率分析
管理后台使用Vue 3 + TypeScript + Element Plus
API使用X-API-Key进行认证

2026-03 实战经验补充（智能体执行）

迁移策略要前置统一
- PostgreSQL 作为唯一目标方言。
- 历史迁移脚本仅在未发布环境允许改写，发布后必须增量修复迁移。
测试环境漂移是主要假失败来源
- 严格迁移测试依赖容器运行时与临时目录配置，需固定到 CI 命令而不是口头约定。
- 对 “Skipped” 项要有脚本化断言（如 assert-migration-not-skipped.sh）。
仓库污染必须脚本化治理
- 通过 clean-artifacts.sh 做 dry-run 门禁，避免根目录与前端目录被测试产物污染。
- 构建产物优先归档后清理，降低误删风险。
日志管理需要“归档 + 索引”双机制
- archive-logs.sh 负责搬迁历史日志，update-log-archive-index.sh 负责检索索引。
- 持续运行任务会自动再生日志，清理前需识别后台进程状态。
发布阶段必须尊重远端保护策略
- main 受保护时不可强推覆盖，优先走任务分支 + PR。
- 若业务要求覆盖，先确认分支保护权限再执行推送。

6.3 KiB Raw Blame History Unescape Escape