FLUXXWAVVEE/cyber-scam-detection-backend-deploy

# 网络诈骗检测与防范平台 - 后端基础 这是**网络诈骗检测与防范平台**的后端基础层，使用 **FastAPI** 实现，具备结构化日志、类型安全、输入验证以及清晰的接口边界，为未来的 AI 和持久化组件做好准备。 ## 1. 当前阶段范围 本阶段构建**核心后端基础和 API 层**。它不执行实际的诈骗检测、OCR、数据库存储或用户认证。所有计划内但尚未实现的功能都会返回明确的未配置状态码和标准 JSON 错误。不捏造任何虚假的智能或伪造数据库记录。 ### 已实现的功能： - **FastAPI 核心应用**：干净利落的启动/生命周期处理程序、集中式的 Pydantic 设置加载以及版本化路由。 - **API 路由**：规范化路由前缀 `/api/v1` 以及临时的 `/api` 兼容性包装器（带有弃用 Warning 标头）。 - **请求验证**：独立的端点用于验证文本主体长度（`analyses/text`）以及文件大小/MIME/魔数约束（`analyses/screenshot`）。 - **可观测性**：通过 `X-Request-ID` 实现的唯一 UUID 请求追踪，该 ID 会在日志上下文、响应标头和错误主体中进行传递。结构化 JSON 日志排除了私有 PII 数据。 - **安全的图片上传**：通过验证魔数（PNG、JPEG、WebP）来验证图片类型，并使用上下文管理临时文件，在 `finally` 代码块中自动删除。 - **标准化错误系统**：自定义异常映射器返回统一的 payload 结构：`{error: {code, message, request_id, details}}`。 - **系统诊断**：真实客观的 `/health` 和 `/ready` 探针，准确告知缺少哪些 AI/数据库组件。 - **无 Mock 单元测试**：在自包含环境中运行 24 个单元测试，验证验证规则、CORS 规则、文件结构和编排器边界。 ### 延迟实现的功能： - **EasyOCR 文本提取**：抽象于 `OCRServiceInterface` 之后。 - **spaCy NLP 分词器**：抽象于 `NLPServiceInterface` 之后。 - **Scikit-learn 逻辑回归模型**：抽象于 `MLDetectionServiceInterface` 之后。 - **VirusTotal 和 WHOIS 信誉检查**：抽象于 `ThreatIntelligenceServiceInterface` 之后。 - **PostgreSQL 数据库存储**：抽象于 `InMemoryAnalysisRepository` 之后（仅供开发使用的临时内存缓存）。 - **会话认证 / 用户资料管理**：返回 `AUTH_NOT_IMPLEMENTED`。 - **反馈持久化**：返回 `PERSISTENCE_NOT_IMPLEMENTED`。 ## 2. 项目文件结构 ``` backend/ ├── app/ │ ├── __init__.py │ ├── main.py - Application instantiation, middlewares, CORS, and exception mappings │ ├── core/ │ │ ├── config.py - Pydantic settings manager Loading env variables │ │ ├── logging.py - Structured JSON logging formatter with PII redactions │ │ ├── exceptions.py - Application exceptions catalog │ │ ├── error_codes.py - Stable machine-readable error codes constants │ │ └── security.py - Core sanitizers and URL checkers │ ├── api/ │ │ ├── router.py - Router aggregator for canonical v1 and compatibility endpoints │ │ └── v1/ │ │ ├── health.py - Liveness and readiness endpoints │ │ ├── analyses.py - Separate text and screenshot submission handlers │ │ ├── auth.py - Register/login stub endpoints (501 Not Implemented) │ │ ├── feedback.py - User feedback stub endpoints (501 Not Implemented) │ │ ├── users.py - User profile stub endpoints (501 Not Implemented) │ │ └── admin.py - Admin dashboard stub endpoints (501 Not Implemented) │ ├── schemas/ │ │ ├── common.py - Enums for InputTypes, AnalysisStatus, and ComponentStatusState │ │ ├── error.py - Standard error schema models │ │ ├── analysis.py - Analysis request models and report response models │ │ ├── auth.py - Login/register request models │ │ ├── feedback.py - Feedback submission schemas │ │ └── user.py - User details response models │ ├── services/ │ │ ├── orchestrator.py - Coordinates the pipeline evaluation │ │ ├── in_memory_repository.py - Thread-safe cache caching transient scan sessions │ │ ├── interfaces/ - Abstract class definitions for OCR, NLP, ML, Threat, Risk │ │ └── unavailable/ - Concrete stubs returning unimplemented status codes │ ├── middleware/ │ │ ├── request_id.py - Intercepts X-Request-ID headers or generates trace UUIDs │ │ ├── request_logging.py - Logs HTTP method, path, status, and duration latency │ │ └── security_headers.py - Browser security headers (nosniff, clickjacking prevention) │ ├── utils/ │ │ ├── file_validation.py - Verifies MIME headers, size bounds, and magic bytes │ │ └── temp_files.py - Managed temporary file context managers │ └── dependencies/ │ └── services.py - Dependency injections for pipelines ├── tests/ - Test suite │ ├── conftest.py │ ├── test_health.py │ ├── test_analysis_validation.py │ ├── test_upload_validation.py │ ├── test_errors.py │ ├── test_request_id.py │ ├── test_cors.py │ └── test_orchestrator_contract.py ├── .env.example - Template for environment properties ├── .gitignore ├── requirements.txt - Package dependencies list ├── pyproject.toml - Pytest configuration settings └── README.md - Documentation walkthrough ``` ## 3. 安装与本地运行设置 ### Windows 开发设置 (PowerShell / VS Code) 1. **创建虚拟环境**： python -m venv .venv 2. **激活环境**： .venv\Scripts\Activate.ps1 3. **安装依赖项**： pip install -r requirements.txt 4. **设置环境变量**： 在根目录下创建 `.env` 文件（基于 `.env.example`）： Copy-Item .env.example .env 5. **启动本地开发服务器**： uvicorn app.main:app --reload --port 8000 - API 服务器：`http://localhost:8000` - 交互式 OpenAPI Swagger 文档：`http://localhost:8000/docs` - 就绪健康检查：`http://localhost:8000/api/v1/ready` 6. **运行自动化单元测试**： pytest -v ## 4. 安全与隐私控制 - **魔数签名检查**：图片上传会检查魔数，以阻止伪装的二进制文件。 - **自动资源清理**：截图临时文件在请求执行完成后会自动删除（使用 `try/finally` 上下文包装器）。 - **PII 泄露保护**：日志会脱敏映射到密码、token、内容主体和卡号条目的值。 - **可追溯性**：服务器生成的唯一请求 ID 会被注入到日志和标头响应中，以实现清晰的调试。 - **安全的点击劫持防护**：点击劫持防护标头会自动应用于非文档端点。 ## 5. 未来 AI 和数据库集成点 - **PostgreSQL 持久化**：将 `app/dependencies/services.py` 中的 `InMemoryAnalysisRepository` 替换为使用 SQLAlchemy 模型的真实数据库驱动。 - **EasyOCR 钩子**：更新 `dependencies/services.py` 中的 `ocr_service`，实例化一个符合 `OCRServiceInterface` 的模型执行类。 - **spaCy / Scikit-learn 推理**：使用匹配的服务接口，将您的 ML/NLP 向量化分类器模型注入到编排器 pipeline 中。

标签：Apex, AV绕过, FastAPI, OCR, Syscall, Web开发, 后端框架, 机器学习, 测试用例, 网络防骗, 逆向工具