fred-admin 1.0.0__py3-none-any.whl

fred_admin/common/Route.py

@@ -0,0 +1,390 @@
+# coding: utf-8
+"""
+ * @Author：cyg
+ * @Package：Route
+ * @Project：Default (Template) Project
+ * @name：Route
+ * @Date：2025/6/1 11:25
+ * @Filename：Route
+"""
+
+import os
+import re
+
+from flask import send_from_directory, render_template, abort, Response
+from jinja2 import ChoiceLoader, FileSystemLoader
+
+from fred_admin.common.RuntimeHook import get_modules_dir
+
+
+# 常见的 Service Worker 文件名模式（支持多框架）
+SW_FILE_PATTERNS = ['sw.js', 'service-worker.js', 'sw.min.js', 'worker.js', 'serviceWorker.js']
+
+
+def _find_service_worker_files(templates_dir):
+    """
+    查找 templates 目录下的所有 Service Worker 文件
+    
+    支持：Vue (Vite PWA)、React (Workbox)、Angular、Next.js 等
+    """
+    sw_files = []
+    if not os.path.isdir(templates_dir):
+        return sw_files
+    
+    # 1. 检查常见 SW 文件名
+    for sw_name in SW_FILE_PATTERNS:
+        sw_path = os.path.join(templates_dir, sw_name)
+        if os.path.isfile(sw_path):
+            sw_files.append(sw_path)
+    
+    # 2. 扫描所有 JS 文件，查找包含 NavigationRoute 的文件
+    for root, dirs, files in os.walk(templates_dir):
+        for file in files:
+            if file.endswith('.js'):
+                file_path = os.path.join(root, file)
+                if file_path not in sw_files:
+                    try:
+                        with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                            content = f.read()
+                        if 'NavigationRoute' in content:
+                            sw_files.append(file_path)
+                    except Exception:
+                        continue
+    
+    return sw_files
+
+
+def _fix_pwa_sw_file(sw_file_path, swagger_paths):
+    """
+    修复 PWA Service Worker 文件，在 NavigationRoute 中添加 denylist
+    
+    支持多种框架和 Workbox 版本：
+    - Vite PWA (Vue)
+    - Workbox (React, Angular, Next.js)
+    - 自定义 Service Worker
+    """
+    if not os.path.isfile(sw_file_path):
+        return False
+    
+    try:
+        with open(sw_file_path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+        
+        # 检查是否包含 NavigationRoute
+        if 'NavigationRoute' not in content:
+            return False
+        
+        # 检查是否已修复过
+        if 'denylist:[' in content and '/docs' in content:
+            return False
+        
+        # 构建 denylist 正则表达式字符串
+        denylist_items = [f"/^\\/{p.lstrip('/')}/" for p in swagger_paths if p]
+        if not denylist_items:
+            return False
+        denylist_str = ','.join(denylist_items)
+        
+        new_content = content
+        
+        # 模式1: new X.NavigationRoute(X.createHandlerBoundToURL("index.html"))
+        # 匹配 Workbox 各种写法：s., e., workbox., etc.
+        pattern1 = r'(new\s+[a-zA-Z_][a-zA-Z0-9_]*\.NavigationRoute\s*\([a-zA-Z_][a-zA-Z0-9_]*\.createHandlerBoundToURL\s*\(["\']index\.html["\']\)\s*\))'
+        replacement1 = f'new s.NavigationRoute(s.createHandlerBoundToURL("index.html"),{{denylist:[{denylist_str}]}})'
+        new_content = re.sub(pattern1, replacement1, new_content)
+        
+        # 模式2: new NavigationRoute(createHandlerBoundToURL("index.html"))
+        pattern2 = r'(new\s+NavigationRoute\s*\([a-zA-Z_][a-zA-Z0-9_]*\.createHandlerBoundToURL\s*\(["\']index\.html["\']\)\s*\))'
+        replacement2 = f'new NavigationRoute(s.createHandlerBoundToURL("index.html"),{{denylist:[{denylist_str}]}})'
+        new_content = re.sub(pattern2, replacement2, new_content)
+        
+        # 模式3: registerRoute(new NavigationRoute(handler, { ... }))
+        # 已有配置的情况，添加 denylist 到现有配置中
+        if new_content == content and 'NavigationRoute' in content:
+            # 查找 NavigationRoute 中已有的配置对象，添加 denylist
+            # 匹配: NavigationRoute(..., { ... }) 的情况
+            pattern3 = r'(NavigationRoute\s*\([^)]+,\s*\{)([^}]*)(\}))'
+            def add_denylist(match):
+                existing = match.group(2).strip()
+                if 'denylist' not in existing:
+                    if existing:
+                        return f"{match.group(1)}{existing},denylist:[{denylist_str}]{match.group(3)}"
+                    else:
+                        return f"{match.group(1)}denylist:[{denylist_str}]{match.group(3)}"
+                return match.group(0)
+            new_content = re.sub(pattern3, add_denylist, new_content)
+        
+        
+        if new_content != content:
+            with open(sw_file_path, 'w', encoding='utf-8') as f:
+                f.write(new_content)
+            return True
+        return False
+    except Exception:
+        return False
+
+
+def _inject_sw_update_script(index_file_path):
+    """
+    在 index.html 中注入 Service Worker 强制更新脚本
+    
+    通用于所有前端框架：Vue、React、Angular、Next.js 等
+    """
+    if not os.path.isfile(index_file_path):
+        return False
+    
+    try:
+        with open(index_file_path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+        
+        # 检查是否已注入过
+        if 'fred-pwa-swagger-fix' in content:
+            return False
+        
+        # 通用的 Service Worker 更新脚本
+        sw_update_script = '''<script id="fred-pwa-swagger-fix">(function(){if('serviceWorker'in navigator){navigator.serviceWorker.getRegistration().then(function(reg){if(reg){reg.update();if(reg.installing)reg.installing.postMessage({type:'SKIP_WAITING'});if(reg.waiting)reg.waiting.postMessage({type:'SKIP_WAITING'});}});navigator.serviceWorker.addEventListener('controllerchange',function(){location.reload();});}})();</script>'''
+        
+        # 在 </head> 前插入（优先）
+        if '</head>' in content:
+            new_content = content.replace('</head>', sw_update_script + '</head>', 1)
+        # 或在 </body> 前
+        elif '</body>' in content:
+            new_content = content.replace('</body>', sw_update_script + '</body>', 1)
+        # 或在文件末尾
+        else:
+            new_content = content + sw_update_script
+        
+        if new_content != content:
+            with open(index_file_path, 'w', encoding='utf-8') as f:
+                f.write(new_content)
+            return True
+        return False
+    except Exception:
+        return False
+
+
+def _auto_fix_pwa_swagger_conflict(app, modules_dir):
+    """
+    自动修复所有模块的 PWA Service Worker 与 Swagger 的冲突
+    
+    支持任意前端框架：Vue、React、Angular、Next.js、Svelte 等
+    框架会在应用启动时自动扫描并修复 Service Worker 文件。
+    
+    仅当 ENABLE_SWAGGER = True 时才执行注入，否则跳过。
+    """
+    # 未启用 Swagger 时，不做任何处理
+    if not app.config.get('ENABLE_SWAGGER', False):
+        return
+    
+    # 获取需要排除的路径
+    swagger_path = app.config.get('OPENAPI_SWAGGER_UI_PATH', '/docs') or '/docs'
+    swagger_paths = [swagger_path.strip('/'), 'doc', 'openapi.json', 'openapi']
+    swagger_paths = list(set([p.strip('/') for p in swagger_paths if p.strip('/')]))
+    
+    # 如果没有有效的排除路径，跳过
+    if not swagger_paths:
+        return
+    
+    fixed_modules = []
+    
+    # 遍历所有模块
+    if modules_dir and os.path.isdir(modules_dir):
+        for module_name in os.listdir(modules_dir):
+            module_path = os.path.join(modules_dir, module_name)
+            if not os.path.isdir(module_path):
+                continue
+            
+            templates_dir = os.path.join(module_path, 'templates')
+            if not os.path.isdir(templates_dir):
+                continue
+            
+            module_fixed = False
+            
+            # 1. 查找并修复所有 Service Worker 文件
+            sw_files = _find_service_worker_files(templates_dir)
+            for sw_file in sw_files:
+                if _fix_pwa_sw_file(sw_file, swagger_paths):
+                    module_fixed = True
+            
+            # 2. 修复 index.html（注入 SW 更新脚本）
+            index_file = os.path.join(templates_dir, 'index.html')
+            if _inject_sw_update_script(index_file):
+                module_fixed = True
+            
+            if module_fixed:
+                fixed_modules.append(module_name)
+    
+    if fixed_modules:
+        app.logger.info(f"PWA Service Worker 已自动配置 denylist 排除 Swagger 路径，影响模块: {', '.join(fixed_modules)}")
+
+
+class Route:
+
+    def _delegate_swagger_ui_if_needed(self, path):
+        """
+        首页 SPA 通配 /<path:path> 可能与 /docs 竞争匹配顺序。
+        一旦本视图收到 OPENAPI_SWAGGER_UI_PATH 下的路径，直接交给 swagger_ui.show，
+        避免返回后台 index.html 后出现 /docs#/login。
+        """
+        if not self.app.config.get('ENABLE_SWAGGER', False):
+            return None
+        raw = (self.app.config.get('OPENAPI_SWAGGER_UI_PATH') or '').strip()
+        if not raw:
+            return None
+        segment = raw.strip('/')
+        if not segment:
+            return None
+        if not (
+            path == segment
+            or path == segment + '/'
+            or path.startswith(segment + '/')
+        ):
+            return None
+        show = self.app.view_functions.get('swagger_ui.show')
+        if not show:
+            return None
+        if path == segment or path == segment + '/':
+            return show()
+        rest = path[len(segment) :].lstrip('/')
+        return show(rest or None)
+    
+    @staticmethod
+    def _get_project_root():
+        """
+        获取项目根目录（使用当前工作目录）
+        
+        :return: 项目根目录路径
+        """
+        return os.getcwd()
+    
+    def __init__(self, app):
+        self.app = app
+    
+    def set_routes(self):
+        # 0. 自动修复 PWA Service Worker 与 Swagger 的冲突
+        modules_dir = get_modules_dir()
+        _auto_fix_pwa_swagger_conflict(self.app, modules_dir)
+        
+        # 1. 自动注册 ROUTE_CONFIG 中的文件服务路由
+        route_config = self.app.config.get('ROUTE_CONFIG', {})
+        for route_prefix, folder in route_config.items():
+            if not route_prefix or not folder:
+                continue
+            endpoint_name = f"path_route_{route_prefix}"
+            
+            def make_handler(folder_path):
+                def handler(path):
+                    folder_dir = os.path.join(self._get_project_root(), folder_path)
+                    return send_from_directory(folder_dir, path)
+                return handler
+            
+            self.app.add_url_rule(
+                f'/{route_prefix}/<path:path>',
+                endpoint=endpoint_name,
+                view_func=make_handler(folder)
+            )
+
+        # 2. 蓝图路由配置
+        sys_blueprints = ['api-docs', 'swagger_ui']
+        i = 0
+        project_root = self._get_project_root()
+        modules_dir = get_modules_dir()  # 获取模块目录
+        jinja_loader_arr = [self.app.jinja_loader]
+        home_modules = self.app.config.get('HOME_MODULES', None)
+        for blueprint_name in self.app.blueprints:
+            if blueprint_name in sys_blueprints:
+                continue
+            
+            # 支持 modules/*/templates 目录结构（前端打包目录放在模块根目录下）
+            if modules_dir:
+                module_templates = os.path.join(modules_dir, blueprint_name, 'templates')
+                if os.path.isdir(module_templates):
+                    jinja_loader_arr.append(FileSystemLoader(module_templates))
+                    web_path = module_templates
+                    index_path = os.path.join(web_path, 'index.html')
+                else:
+                    jinja_loader_arr.append(FileSystemLoader(f'{blueprint_name}/templates'))
+                    web_path = os.path.join(project_root, f'{blueprint_name}/templates/{blueprint_name}')
+                    index_path = os.path.join(web_path, 'index.html')
+            else:
+                jinja_loader_arr.append(FileSystemLoader(f'{blueprint_name}/templates'))
+                web_path = os.path.join(project_root, f'{blueprint_name}/templates/{blueprint_name}')
+                index_path = os.path.join(web_path, 'index.html')
+            is_home = False
+            if not os.path.exists(web_path) or not os.path.exists(index_path):
+                continue
+            if not home_modules and i == 0:
+                is_home = True
+            elif home_modules == blueprint_name:
+                is_home = True
+            if is_home:
+                self.register_static_route(blueprint_name, is_home)
+            self.register_static_route(blueprint_name, False)
+            i += 1
+        self.app.jinja_loader = ChoiceLoader(jinja_loader_arr)
+
+    def register_static_route(self, blueprint_name, is_home):
+        assets_path_pre = "/" if is_home else f"/{blueprint_name}"
+        modules_dir = get_modules_dir()  # 获取模块目录
+        
+        # 获取模块的 templates 目录
+        if modules_dir:
+            module_templates_dir = os.path.join(modules_dir, blueprint_name, 'templates')
+        else:
+            module_templates_dir = os.path.join(self._get_project_root(), f'{blueprint_name}/templates/{blueprint_name}')
+
+        # 动态生成唯一 endpoint 名称
+        if is_home:
+            index_endpoint = f"{blueprint_name}_home_index"
+        else:
+            index_endpoint = f"{blueprint_name}_index"
+        
+        # 保存当前模块的 templates 目录（闭包捕获）
+        _templates_dir = module_templates_dir
+
+        @self.app.route(f"{assets_path_pre}", endpoint=f"{index_endpoint}_root")
+        def module_index_root():
+            # 直接发送模块自己的 index.html
+            return send_from_directory(_templates_dir, 'index.html')
+
+        # 统一处理所有路径请求（包括静态资源文件和 SPA 页面路由）
+        @self.app.route(f"{assets_path_pre}/<path:path>", endpoint=index_endpoint)
+        def module_index_path(path):
+            project_root = self._get_project_root()
+            
+            # 1. 优先处理 ROUTE_CONFIG 映射（支持如 /admin/upload/xxx 映射到实际 upload 目录）
+            route_config = self.app.config.get('ROUTE_CONFIG', {})
+            for route_prefix, folder in route_config.items():
+                if path.startswith(f"{route_prefix}/"):
+                    relative_path = path[len(route_prefix)+1:]
+                    folder_dir = os.path.normpath(os.path.join(project_root, folder))
+                    if os.path.isfile(os.path.join(folder_dir, relative_path)):
+                        return send_from_directory(folder_dir, relative_path)
+
+            # 2. 自动探测资源文件逻辑
+            # 搜索优先级：1. modules/*/templates (前端打包目录)  2. 项目根目录
+            search_dirs = []
+            if modules_dir:
+                # 支持 modules/*/templates 目录结构
+                module_templates = os.path.join(modules_dir, blueprint_name, 'templates')
+                if os.path.isdir(module_templates):
+                    search_dirs.append(module_templates)
+            search_dirs.append(os.path.join(project_root, f'{blueprint_name}/templates/{blueprint_name}'))
+            search_dirs.append(project_root)
+            
+            for base_dir in search_dirs:
+                file_path = os.path.normpath(os.path.join(base_dir, path))
+                if os.path.isfile(file_path):
+                    return send_from_directory(os.path.dirname(file_path), os.path.basename(file_path))
+
+            delegated = self._delegate_swagger_ui_if_needed(path)
+            if delegated is not None:
+                return delegated
+
+            # 3. SPA 路由支持：如果请求没有文件后缀，或者明确请求 index.html
+            file_ext = os.path.splitext(path)[1]
+            if not file_ext or path == 'index.html' or path.endswith('/'):
+                # 直接发送模块自己的 index.html
+                return send_from_directory(_templates_dir, 'index.html')
+            
+            # 4. 如果有后缀但文件确实不存在，返回 404
+            abort(404)

fred_admin/common/RuntimeHook.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+"""
+运行时钩子：在 create_app 前自动发现项目根并应用 path + iter_modules patch，
+使 Blueprint 能从 modules 目录正确加载，项目 run.py 无需手写 patch。
+支持 src/modules 和 modules 两种目录结构，优先使用配置的 MODULES_DIR。
+"""
+import os
+import pkgutil
+import sys
+from pathlib import Path
+
+_HOOK_APPLIED = False
+_MODULES_DIR = None  # 存储发现的模块目录
+
+
+def get_modules_dir():
+    """获取模块目录路径"""
+    return str(_MODULES_DIR) if _MODULES_DIR else None
+
+def _find_modules_dir(root: Path):
+    """查找模块目录，优先级：src/modules > modules"""
+    src_modules = root / "src" / "modules"
+    if src_modules.is_dir():
+        return src_modules
+    modules = root / "modules"
+    if modules.is_dir():
+        return modules
+    return None
+
+
+def _find_project_root():
+    """从 cwd 向上查找包含 run.py 或 config/ 且含模块目录的项目根。"""
+    current = Path.cwd().resolve()
+    for _ in range(10):
+        if (current / "run.py").exists() or (current / "setup.py").exists():
+            if _find_modules_dir(current):
+                return current
+        # 支持 config/ 或 common/config/ 目录结构
+        has_config = (current / "config").is_dir() or (current / "common" / "config").is_dir()
+        if has_config and _find_modules_dir(current):
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    return None
+
+
+def apply_project_hook():
+    """
+    若当前工作目录在弗雷德项目下（存在 modules 目录），则：
+    - 将项目根与 modules 目录加入 sys.path
+    - 将每个模块的 backend 目录加入 sys.path（支持 modules/*/backend 结构）
+    - patch pkgutil.iter_modules，使 Blueprints 从 modules 目录发现模块
+    幂等，仅执行一次。
+    """
+    global _HOOK_APPLIED, _MODULES_DIR
+    if _HOOK_APPLIED:
+        return
+    root = _find_project_root()
+    if root is None:
+        return
+    modules_dir = _find_modules_dir(root)
+    if modules_dir is None:
+        return
+    _MODULES_DIR = modules_dir
+    root_str = str(root)
+    modules_dir_str = str(modules_dir)
+    
+    # 收集所有需要添加的路径，然后按正确的优先级插入
+    # 优先级：项目根目录 > modules目录 > backend目录
+    paths_to_add = []
+    
+    # 添加每个模块的 backend 目录（最低优先级）
+    for item in modules_dir.iterdir():
+        if item.is_dir() and not item.name.startswith('_'):
+            backend_dir = item / "backend"
+            if backend_dir.is_dir():
+                backend_dir_str = str(backend_dir)
+                paths_to_add.append(backend_dir_str)
+    
+    # modules目录（中等优先级）
+    paths_to_add.append(modules_dir_str)
+    
+    # 项目根目录（最高优先级）
+    paths_to_add.append(root_str)
+    
+    # 先从 sys.path 中移除这些路径（如果存在），然后按正确顺序重新插入
+    for p in paths_to_add:
+        if p in sys.path:
+            sys.path.remove(p)
+    
+    # 按相反顺序插入，使最高优先级的排在最前面
+    for p in paths_to_add:
+        sys.path.insert(0, p)
+    
+    _orig_iter_modules = pkgutil.iter_modules
+
+    def _patched_iter_modules(path=None, prefix=""):
+        if path is not None and len(path) == 1:
+            p = path[0]
+            if p == "" or p == ".":
+                path = [modules_dir_str]
+            elif not os.path.isabs(p) and not os.path.exists(p):
+                alt = os.path.join(modules_dir_str, p)
+                if os.path.isdir(alt):
+                    path = [alt]
+        return _orig_iter_modules(path, prefix)
+
+    pkgutil.iter_modules = _patched_iter_modules
+    _HOOK_APPLIED = True