hzdyjs/docs/开发文档/移动端动态路由使用指南.md

移动端动态路由使用指南

📋 概述

本指南介绍如何在uni-app中实现动态路由跳转，无需在pages.json中预先配置所有页面路由。

🎯 核心特性

✅ 主要优势

• 无需预配置: 页面无需在pages.json中预先配置
• 动态跳转: 支持运行时动态跳转到任意页面
• 智能处理: 自动处理页面不存在的情况
• 模板生成: 支持动态生成标准页面模板
• 权限控制: 集成权限检查机制

🔧 技术实现

• 路由管理: RouterManager 统一管理路由跳转
• 模板生成: PageGenerator 生成标准页面模板
• 权限集成: 与现有权限系统无缝集成
• 错误处理: 完善的错误处理和用户提示

🚀 快速开始

1. 基本使用

// 在页面中引入路由管理工具
import RouterManager from '@/utils/router';

// 简单跳转
RouterManager.navigateToService('学生信息');

// 带参数跳转
RouterManager.navigateToService('物业报修', {
    params: {
        type: 'urgent',
        category: 'electrical'
    }
});

// 带回调的跳转
RouterManager.navigateToService('场地预约', {
    onSuccess: () => {
        console.log('跳转成功');
    },
    onCreatePage: (serviceName, route) => {
        console.log(`需要创建页面: ${serviceName} -> ${route}`);
    }
});

2. 在首页中使用

<template>
    <ServiceItem
        title="学生信息"
        @click="handleServiceClick"
    >
        <template #icon>
            <u-icon name="account" size="24" />
        </template>
    </ServiceItem>
</template>

<script>
import RouterManager from '@/utils/router';

export default {
    methods: {
        handleServiceClick(service) {
            RouterManager.navigateToService(service.title, {
                onSuccess: () => {
                    console.log(`✅ 成功跳转到服务: ${service.title}`);
                },
                onCreatePage: (serviceName, route) => {
                    console.log(`📝 创建页面: ${serviceName} -> ${route}`);
                }
            });
        }
    }
}
</script>

📁 文件结构

mobile/src/utils/
├── router.js              # 路由管理工具
├── page-generator.js      # 页面模板生成器
└── permission.js          # 权限管理（现有）

mobile/src/pages/
├── index/
│   └── index.vue          # 首页（已更新）
├── student/               # 学工管理页面
├── logistics/             # 后勤管理页面
├── recruitment/           # 招生就业页面
├── hr/                    # 人事管理页面
├── finance/               # 财务管理页面
└── system/                # 系统管理页面

🔧 配置说明

1. 路由映射配置

在 mobile/src/utils/router.js 中配置服务路由映射：

// 服务路由映射配置
const SERVICE_ROUTES = {
    // 学工管理
    'student:info': '/pages/student/info/index',
    'student:dorm': '/pages/student/dorm/index',
    'student:leave': '/pages/student/leave/index',
    // ... 更多路由
};

// 服务名称映射
const SERVICE_NAMES = {
    '学生信息': 'student:info',
    '宿舍管理': 'student:dorm',
    '学生请假': 'student:leave',
    // ... 更多映射
};

2. 权限配置

在 mobile/src/utils/page-generator.js 中配置权限标识：

static getPermissionKey(serviceName) {
    const permissionMap = {
        '学生信息': 'student:info',
        '宿舍管理': 'student:dorm',
        '学生请假': 'student:leave',
        // ... 更多权限配置
    };
    
    return permissionMap[serviceName] || 'system:default';
}

📝 页面模板生成

1. 生成列表页面

import PageGenerator from '@/utils/page-generator';

// 生成学生信息列表页面模板
const listTemplate = PageGenerator.generateListPage('学生信息', '/pages/student/info/index');
console.log(listTemplate);

2. 生成表单页面

// 生成学生信息表单页面模板
const formTemplate = PageGenerator.generateFormPage('学生信息', '/pages/student/info/form');
console.log(formTemplate);

3. 自动创建页面

// 在路由管理工具中集成页面创建功能
RouterManager.navigateToService('学生信息', {
    onCreatePage: async (serviceName, route) => {
        // 生成页面模板
        const listTemplate = PageGenerator.generateListPage(serviceName, route);
        const formTemplate = PageGenerator.generateFormPage(serviceName, route);
        
        // 这里可以调用API创建页面文件
        // 或者保存到本地文件系统
        console.log('生成的列表页面模板:', listTemplate);
        console.log('生成的表单页面模板:', formTemplate);
    }
});

🎨 页面模板特性

1. 列表页面模板

• ✅ 统一头部: 渐变背景 + 标题 + 操作按钮
• ✅ 搜索功能: 关键词搜索 + 重置功能
• ✅ 数据列表: 支持分页 + 加载更多
• ✅ 操作按钮: 编辑 + 删除（权限控制）
• ✅ 响应式设计: 适配不同屏幕尺寸

2. 表单页面模板

• ✅ 表单验证: 完整的输入验证规则
• ✅ 状态管理: 新增/编辑状态自动切换
• ✅ API集成: 自动调用对应的后端接口
• ✅ 用户体验: 加载状态 + 成功提示

🔒 权限控制

1. 按钮级权限

<u-button 
    v-if="hasPermi(['student:info:add'])"
    type="primary" 
    @click="handleAdd"
>
    新增
</u-button>

2. 页面级权限

// 在页面加载时检查权限
onLoad() {
    if (!this.hasPermi(['student:info:list'])) {
        uni.showToast({
            title: '无访问权限',
            icon: 'none'
        });
        uni.navigateBack();
        return;
    }
    this.loadData();
}

🚨 错误处理

1. 页面不存在处理

// 自动检测页面是否存在
RouterManager.navigateToService('学生信息', {
    fail: (error) => {
        // 显示创建页面对话框
        uni.showModal({
            title: '页面不存在',
            content: '学生信息页面尚未创建，是否创建该页面？',
            confirmText: '创建页面',
            cancelText: '取消',
            success: (res) => {
                if (res.confirm) {
                    // 生成页面模板
                    this.createPageTemplate('学生信息', '/pages/student/info/index');
                }
            }
        });
    }
});

2. 网络错误处理

// 在页面模板中自动处理网络错误
async loadData() {
    try {
        const response = await api.get('/student/info/list', { params });
        // 处理成功响应
    } catch (error) {
        console.error('加载数据失败:', error);
        uni.showToast({
            title: '网络错误',
            icon: 'none'
        });
    }
}

📊 使用统计

支持的服务模块

模块	服务数量	状态
学工管理	6个	✅ 已配置
后勤管理	6个	✅ 已配置
招生就业	3个	✅ 已配置
人事管理	3个	✅ 已配置
财务管理	3个	✅ 已配置
系统管理	6个	✅ 已配置

路由映射统计

• 总路由数: 27个
• 已配置: 27个
• 待实现: 0个
• 覆盖率: 100%

🔄 工作流程

1. 用户点击服务卡片

用户点击 → 检查权限 → 查找路由 → 执行跳转

2. 页面不存在处理

跳转失败 → 显示对话框 → 用户确认 → 生成模板 → 创建页面

3. 页面创建流程

生成模板 → 保存文件 → 更新路由 → 重新跳转

🧪 测试验证

1. 功能测试

// 测试路由跳转
RouterManager.navigateToService('学生信息');

// 测试页面存在性检查
const exists = await RouterManager.checkPageExists('/pages/student/info/index');
console.log('页面是否存在:', exists);

// 测试模板生成
const template = PageGenerator.generateListPage('学生信息', '/pages/student/info/index');
console.log('生成的模板长度:', template.length);

2. 权限测试

// 测试权限检查
const hasPermission = hasPermi(['student:info:list']);
console.log('是否有权限:', hasPermission);

📚 最佳实践

1. 路由命名规范

• 使用小写字母和连字符
• 按模块分组组织
• 保持路径简洁明了

2. 权限配置规范

• 使用统一的权限标识格式
• 按功能模块组织权限
• 保持权限粒度适中

3. 页面模板规范

• 使用统一的UI组件
• 保持代码结构一致
• 添加完整的错误处理

🔮 未来扩展

1. 计划功能

• 在线页面编辑器
• 模板市场
• 页面预览功能
• 批量页面生成

2. 技术优化

• 路由缓存机制
• 页面懒加载
• 性能监控
• 错误追踪

---

📞 联系方式

如有问题或建议，请联系开发团队或查看项目仓库的 Issues。

---

📝 维护: 移动端动态路由使用指南
🔄 更新: 2025-01-26
📁 文件: docs/开发文档/移动端动态路由使用指南.md