zhjwxt/Dashboard业务逻辑文档.md

Dashboard WebView 业务逻辑文档

概述

Dashboard WebView 是一个为移动端应用提供数据可视化展示的功能模块，通过WebView组件在客户端中嵌入HTML页面，展示不同角色的统计数据和图表。

系统架构

技术栈

• 后端: ThinkPHP 框架
• 前端: HTML5 + CSS3 + JavaScript
• 图表库: ECharts 5.4.0
• 渲染方式: ThinkPHP view() 模板渲染
• 数据传输: JWT Token + HTTP GET 参数

文件结构

niucloud/app/api/
├── controller/Dashboard.php          # 控制器（业务逻辑）
└── view/dashboard/                   # 视图模板目录
    ├── main.html                     # 主页面模板
    ├── error.html                    # 错误页面模板
    └── layouts/
        └── base.html                 # 基础布局模板

业务流程

1. 页面访问流程

客户端 → API请求 → Token验证 → 角色识别 → 页面类型判断 → 数据获取 → 模板渲染 → HTML输出

2. 请求参数说明

参数名	类型	必填	说明	示例值
type	string	否	页面类型	my_data / dept_data / campus_data
token	string	是	用户认证Token	JWT格式
platform	string	否	平台标识	web / app / miniprogram

3. 页面类型定义

• my_data: 我的数据 - 显示个人业绩统计
• dept_data: 部门数据 - 显示所属部门统计
• campus_data: 校区数据 - 显示整个校区统计

数据统计业务逻辑

1. 我的数据 (my_data)

适用角色: 市场人员(school_departments.id=1的部门=school_sys_role.dept_id的角色) 数据维度:

• 本月录入资源数量
• 当天录入资源数量
• 获得绩效金额
• 其他奖金

图表展示:

• 月度录入资源数量趋势图（折线图）
• 客户来源分布图（饼图）

算法逻辑:

2. 部门数据 (dept_data)

适用角色: 部门主管及以上 权限控制: 只能查看本部门数据 数据维度:

• 部门总业绩
• 团队人数
• 人均业绩
• 部门排名

图表展示:

• 团队成员业绩排行榜（柱状图）
• 部门月度趋势对比（折线图）

算法逻辑:

// 基于用户所属部门统计部门数据
function getDeptData($userInfo) {
    $deptId = $userInfo['department_id'];
    
    // 部门总业绩：部门内所有员工的本月业绩总和
    $deptPerformance = Contract::whereIn('staff_id', function($query) use ($deptId) {
        $query->select('id')->from('staff')->where('department_id', $deptId);
    })->where('status', 'signed')
      ->whereMonth('sign_time', date('m'))
      ->sum('amount');
    
    // 团队人数：部门内员工总数
    $teamCount = Staff::where('department_id', $deptId)
        ->where('status', 'active')
        ->count();
    
    // 人均业绩：部门总业绩 / 团队人数
    $avgPerformance = $teamCount > 0 ? $deptPerformance / $teamCount : 0;
    
    // 部门排名：按业绩排序获取当前部门排名
    $deptRanking = $this->calculateDeptRanking($deptId);
}

3. 校区数据 (campus_data)

适用角色: 校区管理员、校长级别 权限控制: 只能查看所属校区数据 数据维度:

• 校区总业绩
• 部门数量
• 员工总数
• 客户总数

图表展示:

• 各部门业绩对比（柱状图）
• 校区业绩趋势图（折线图）

算法逻辑:

// 基于用户所属校区统计校区数据
function getCampusData($userInfo) {
    $campusId = $userInfo['campus_id'];
    
    // 校区总业绩：校区内所有员工的本月业绩总和
    $campusPerformance = Contract::whereIn('staff_id', function($query) use ($campusId) {
        $query->select('id')->from('staff')->where('campus_id', $campusId);
    })->where('status', 'signed')
      ->whereMonth('sign_time', date('m'))
      ->sum('amount');
    
    // 部门数量：校区内部门总数
    $deptCount = Department::where('campus_id', $campusId)
        ->where('status', 'active')
        ->count();
    
    // 员工总数：校区内所有员工数量
    $staffCount = Staff::where('campus_id', $campusId)
        ->where('status', 'active')
        ->count();
    
    // 客户总数：校区内所有客户数量
    $customerCount = Customer::whereIn('staff_id', function($query) use ($campusId) {
        $query->select('id')->from('staff')->where('campus_id', $campusId);
    })->count();
}

权限控制逻辑

1. Token验证

// JWT Token 解析获取用户信息
function verifyToken($token) {
    try {
        $payload = JWT::decode($token, $secretKey);
        return [
            'user_id' => $payload->user_id,
            'user_type' => $payload->user_type,
            'role_type' => $payload->role_type,
            'campus_id' => $payload->campus_id ?? 0,
            'department_id' => $payload->department_id ?? 0
        ];
    } catch (Exception $e) {
        throw new AuthException('Token验证失败');
    }
}

2. 页面访问权限

// 页面类型访问权限控制
function checkPageAccess($pageType, $userInfo) {
    $rolePermissions = [
        'staff' => ['my_data'],                    // 普通员工只能查看个人数据
        'supervisor' => ['my_data', 'dept_data'], // 主管可查看个人和部门数据
        'manager' => ['my_data', 'dept_data', 'campus_data'], // 经理可查看所有类型数据
        'admin' => ['my_data', 'dept_data', 'campus_data']     // 管理员可查看所有类型数据
    ];
    
    $userRole = $this->getUserRole($userInfo['user_id']);
    $allowedPages = $rolePermissions[$userRole] ?? [];
    
    if (!in_array($pageType, $allowedPages)) {
        throw new PermissionException('无权限访问该页面');
    }
}

3. 数据范围控制

// 数据查询范围限制
function applyDataScope($query, $userInfo, $pageType) {
    switch ($pageType) {
        case 'my_data':
            // 只能查看自己的数据
            $query->where('staff_id', $userInfo['user_id']);
            break;
            
        case 'dept_data':
            // 只能查看本部门数据
            $deptStaffIds = Staff::where('department_id', $userInfo['department_id'])
                ->pluck('id')->toArray();
            $query->whereIn('staff_id', $deptStaffIds);
            break;
            
        case 'campus_data':
            // 只能查看本校区数据
            $campusStaffIds = Staff::where('campus_id', $userInfo['campus_id'])
                ->pluck('id')->toArray();
            $query->whereIn('staff_id', $campusStaffIds);
            break;
    }
}

图表配置说明

1. ECharts 配置标准

• 主题色: #29d3b4 (青绿色)
• 背景色: #181A20 (深灰色)
• 字体: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif

2. 图表类型映射

• 折线图: 趋势数据（月度业绩、时间序列）
• 柱状图: 对比数据（成员排行、部门对比）
• 饼图: 占比数据（客户来源分布、业务分布）

3. 响应式设计

• 移动端优化：小于480px时单列布局
• 图表自适应：监听窗口大小变化自动调整

性能优化

1. 缓存策略

// Redis缓存用户统计数据（5分钟有效期）
$cacheKey = "dashboard_data_{$userInfo['user_id']}_{$pageType}";
$cachedData = Redis::get($cacheKey);

if (!$cachedData) {
    $data = $this->calculateRealData($pageType, $userInfo);
    Redis::setex($cacheKey, 300, json_encode($data)); // 5分钟缓存
} else {
    $data = json_decode($cachedData, true);
}

2. 数据库优化

• 为统计查询添加复合索引
• 使用预计算表存储统计结果
• 分页查询避免大数据量

3. 前端优化

• CDN加载ECharts库
• 图片懒加载和压缩
• CSS压缩和合并

扩展规划

1. 角色细分支持

计划支持的角色类型:

• 销售专员: 基础销售数据统计
• 销售主管: 团队管理数据 + 个人数据
• 市场专员: 线索获取和转化数据
• 客服专员: 客户服务相关数据
• 财务专员: 收款和财务相关数据
• 教研专员: 课程和教学数据
• 校长: 全校区综合数据

2. 数据维度扩展

计划新增的统计维度:

• 客户满意度统计
• 课程完成率统计
• 退费率统计
• 续费率统计
• 员工绩效评分
• 市场推广效果统计

3. 图表类型扩展

计划支持的图表类型:

• 雷达图：综合能力评估
• 热力图：时间分布统计
• 仪表盘：目标完成度
• 漏斗图：业务流程转化
• 地图：地域分布统计

数据表设计要求

统计相关表

错误处理

1. 异常类型定义

class DashboardException extends Exception {
    const TOKEN_INVALID = 1001;      // Token无效
    const PERMISSION_DENIED = 1002;  // 权限不足
    const DATA_NOT_FOUND = 1003;     // 数据不存在
    const TEMPLATE_ERROR = 1004;     // 模板渲染错误
}

2. 错误页面展示

• 友好的错误提示界面
• 错误代码和消息展示
• 返回和重试按钮

该文档会根据实际开发需求持续更新和完善