Faustus-Faber/CORE

# CORE - 社区响应与应急组织 []() []() []() []() ## 目录 - [概述](#overview) - [功能](#features) - [技术栈](#tech-stack) - [项目结构](#project-structure) - [前置条件](#prerequisites) - [安装](#installation) - [配置](#configuration) - [运行应用](#running-the-application) - [演示账户](#demo-accounts) - [功能测试](#testing-features) - [API 端点](#api-endpoints) - [故障排除](#troubleshooting) - [路线图](#roadmap) ## 概述 CORE 使社区能够通过实时事件报告、资源管理、志愿者协调和安全的证据文档来协调应急响应工作。该平台集成了 AI 驱动的可信度评估和欺诈检测，以确保在危机情况下信息的可靠性。 **完整规范：** [软件需求规格说明书](./docs/SRS.md) ## 功能 ### ✅ 模块 0：基础（已完成） - 响应式设计的公共落地页 - 完整的认证系统（注册、登录、登出、密码重置） - 用户资料管理 - 基于角色的访问控制 (RBAC) - 管理员用户管理仪表板 ### ✅ 模块 1，功能 1：紧急报告（已完成） - 多格式事件提交（文本、图片、视频、语音备注） - 通过 Groq 进行 AI 驱动的分析（Whisper + Qwen 模型） - 语音转录和翻译 - 可信度评分、严重性分类、垃圾邮件检测 - 具有高级过滤和排序功能的报告浏览器 - 针对未发布报告的管理员审核工作流 ### ✅ 模块 1，功能 2：资源登记（已完成） - 带有 GPS 坐标的应急资源编目 - 交互式危机地图（Google Maps 集成） - 资源状态跟踪（可用、已预订、已耗尽等） - 所有者管理的资源编辑和停用 ### ✅ 模块 1，功能 3：志愿者审核与欺诈检测（已完成） - 带有公开资料的志愿者名录 - 带有欺诈检测算法的审核系统 - 账户年龄验证 - 审核速度监控 - 基于关键词的欺诈标记 - 评分异常检测 - 针对被标记内容的管理员审核 ### ✅ 模块 1，功能 4：安全文档（已完成） - 私有数字证据文件夹 - 带有 GPS/时间戳元数据的安全文件上传 - 具有可配置过期时间的可共享链接 - 软删除，含 30 天恢复期 - 带有审计追踪的操作备注 ## 技术栈 | 层级 | 技术 | |-------|--------------| | **Frontend** | React 19, TypeScript, Tailwind CSS, Vite, React Router | | **Backend** | Express, TypeScript, Multer | | **Database** | MongoDB (Atlas), Prisma ORM | | **Authentication** | JWT (httpOnly cookies), bcryptjs | | **Maps** | Google Maps API (@react-google-maps/api) | | **AI Services** | Groq API (Whisper, Qwen) | | **Testing** | Vitest, Supertest | ### 核心依赖 **Backend** ``` { "@prisma/client": "^6.5.0", "express": "^4.21.2", "multer": "^2.1.1", "jsonwebtoken": "^9.0.2", "bcryptjs": "^2.4.3", "zod": "^3.24.2" } ``` **Frontend** ``` { "react": "^19.0.0", "react-router-dom": "^7.2.0", "axios": "^1.7.9", "@react-google-maps/api": "^2.20.8", "tailwindcss": "^3.4.17" } ``` ## 项目结构 ``` CORE/ ├── backend/ │ ├── src/ │ │ ├── controllers/ # Request handlers │ │ ├── services/ # Business logic │ │ ├── middleware/ # Auth, upload, error handling │ │ ├── routes/ # API route definitions │ │ ├── utils/ # Validation, helpers │ │ └── server.ts # Entry point │ ├── prisma/ │ │ ├── schema.prisma # Database schema │ │ └── seed.ts # Test data seeder │ ├── uploads/ # Static file storage │ └── package.json ├── frontend/ │ ├── src/ │ │ ├── pages/ # Route components │ │ ├── components/ # Reusable UI components │ │ ├── services/ # API client │ │ ├── context/ # React context (Auth) │ │ ├── types/ # TypeScript types │ │ └── App.tsx # Root component │ └── package.json ├── docs/ │ └── SRS.md # Software Requirements Specification └── README.md ``` ## 前置条件 | 软件 | 版本 | 下载 | |----------|---------|----------| | Node.js | 22+ | [nodejs.org](https://nodejs.org) | | npm | 10+ | 包含在 Node.js 中 | | MongoDB | Atlas 或本地 | [mongodb.com/cloud/atlas](https://mongodb.com/cloud/atlas) | ## 安装 ### 快速开始 ``` # 进入项目目录 cd "D:\CSE471 Project\CORE\Module 1\Merged" # 安装所有依赖 cd backend && npm install cd ../frontend && npm install cd .. # 初始化数据库 cd backend npm run prisma:generate npm run prisma:push npm run seed cd .. ``` ### 详细步骤 1. **克隆或下载**仓库 2. **安装 backend 依赖：** cd backend npm install 3. **安装 frontend 依赖：** cd ../frontend npm install cd .. 4. **生成 Prisma 客户端：** cd backend npm run prisma:generate 5. **同步数据库 schema：** npm run prisma:push 6. **填充测试数据：** npm run seed ## 配置 ### Backend 环境变量 创建 `backend/.env`： ``` # 数据库 DATABASE_URL="mongodb+srv://:@/core?retryWrites=true&w=majority" # 服务器 PORT=5000 CORS_ORIGIN="http://localhost:5173" # 身份验证 JWT_SECRET="generate-a-strong-random-secret-here" # 管理员账户（已填充） ADMIN_EMAIL="admin@core.local" ADMIN_PHONE="+8801700000000" ADMIN_PASSWORD="Admin@12345" ADMIN_NAME="CORE Admin" ADMIN_LOCATION="Dhaka" # Groq AI API GROQ_API_KEY="your-groq-api-key" GROQ_BASE_URL="https://api.groq.com/openai/v1" GROQ_WHISPER_MODEL="whisper-large-v3" GROQ_QWEN_MODEL="qwen/qwen3-32b" AI_REQUEST_TIMEOUT_MS=15000 ``` ### Frontend 环境变量 创建 `frontend/.env`： ``` VITE_API_URL=http://localhost:5000/api VITE_GOOGLE_MAPS_API_KEY=your-google-maps-api-key ``` ## 运行应用 ### 启动开发服务器 **终端 1 - Backend：** ``` cd backend npm run dev ``` Backend 运行于：`http://localhost:5000` **终端 2 - Frontend：** ``` cd frontend npm run dev ``` Frontend 运行于：`http://localhost:5173` ### 停止现有进程 如果端口被占用： ``` $conn5000 = Get-NetTCPConnection -LocalPort 5000 -State Listen -ErrorAction SilentlyContinue if ($conn5000) { Stop-Process -Id $conn5000.OwningProcess -Force } $conn5173 = Get-NetTCPConnection -LocalPort 5173 -State Listen -ErrorAction SilentlyContinue if ($conn5173) { Stop-Process -Id $conn5173.OwningProcess -Force } ``` ### 访问入口 | 服务 | URL | 描述 | |---------|-----|-------------| | Frontend | http://localhost:5173 | 主应用 | | Backend API | http://localhost:5000/api | REST API | | Health Check | http://localhost:5000/api/health | API 状态 | | Static Files | http://localhost:5000/uploads/ | 已上传的媒体文件 | ## 演示账户 运行 `npm run seed` 后，可以使用以下账户： ### 管理员 | 凭证 | 值 | |------------|-------| | Email | `admin@core.local` | | Phone | `+8801700000000` | | Password | `Admin@12345` | | Access | 完整的管理员权限 | ### 标准用户（密码：`User@12345`） | Email | 用途 | |-------|---------| | `alice@core.local` | 受信任的审核者（60 天账户） | | `bob@core.local` | 受信任的审核者（60 天账户） | | `carol@core.local` | 受信任的审核者（60 天账户） | | `frank@core.local` | 欺诈测试（<24 小时账户） | | `grace@core.local` | 活跃的紧急报告者 | ### 志愿者（密码：`Volunteer@12345`） | Email | 状态 | 描述 | |-------|--------|-------------| | `sarah@core.local` | ✅ 良好 | 5★ 评分，好评 | | `mike@core.local` | ⚠️ 已标记 | 平均评分低（1.6★） | | `tom@core.local` | ⚠️ 已标记 | 检测到欺诈关键词 | | `emma@core.local` | ✅ 活跃 | 暂无审核 | ## 功能测试 ### 紧急报告工作流 1. **提交报告：** - 登录：`grace@core.local` / `User@12345` - 导航：报告事件 - 填写：标题、描述、类型、位置 - 可选：附加媒体或语音备注 - 提交 → 重定向到报告浏览器 2. **浏览报告：** - 导航：报告浏览器 (`/reports/explore`) - 筛选：严重性、可信度、时间 - 切换：社区报告 / 我的提交 3. **管理员审核：** - 登录：管理员账户 - 导航：管理员面板 → 审核报告 - 操作：发布或保持审核中 ### 志愿者审核与欺诈检测 | 测试用例 | 步骤 | 预期结果 | |-----------|-------|----------| | 新账户标记 | 以 `frank@core.local` 登录 → 提交审核 | 审核被标记 | | 短文本标记 | 提交文本少于 20 个字符的审核 | 审核被标记 | | 欺诈关键词 | 包含 "scam", "fake", "fraud" | 审核被标记 | | 低评分标记 | 查看 Mike Wilson 资料 | 志愿者被标记 | | 管理员审核 | 管理员面板 → 已标记审核 | 批准/删除选项 | ### 资源管理 1. **添加资源：** - 登录：任意用户 - 导航：资源 → 添加资源 - 填写：名称、类别、数量、位置（地图） - 可选：照片（最多 3 张）、可用时间窗口 - 提交 → 我的资源 2. **交互式地图：** - 导航：地图 - 查看：资源标记 - 点击：带有详情的信息窗口 ## API 端点 ### 认证 | 方法 | 端点 | 描述 | |--------|----------|-------------| | POST | `/api/auth/signup` | 注册新用户 | | POST | `/api/auth/login` | 用户登录 | | POST | `/api/auth/logout` | 用户登出 | | POST | `/api/auth/forgot-password` | 请求密码重置 | | POST | `/api/auth/reset-password` | 使用 token 重置密码 | ### 报告 | 方法 | 端点 | 描述 | |--------|----------|-------------| | POST | `/api/reports` | 提交事件报告 | | GET | `/api/reports` | 列出社区报告 | | GET | `/api/reports/my` | 列出用户提交内容 | | PUT | `/api/reports/:id/status` | 更新报告状态（管理员） | ### 志愿者 | 方法 | 端点 | 描述 | |--------|----------|-------------| | GET | `/api/volunteers` | 列出志愿者 | | GET | `/api/volunteers/:id` | 获取志愿者资料 | | POST | `/api/volunteers/:id/reviews` | 提交审核 | | GET | `/api/volunteers/:id/reviews` | 获取志愿者审核 | ### 资源 | 方法 | 端点 | 描述 | |--------|----------|-------------| | POST | `/api/resources` | 登记资源 | | GET | `/api/resources` | 列出资源 | | GET | `/api/resources/my` | 列出用户资源 | | PUT | `/api/resources/:id` | 更新资源 | | DELETE | `/api/resources/:id` | 删除资源 | ### 文档（安全文件夹） | 方法 | 端点 | 描述 | |--------|----------|-------------| | GET | `/api/docs` | 列出用户文件夹 | | POST | `/api/docs` | 创建文件夹 | | GET | `/api/docs/:id` | 获取文件夹详情 | | POST | `/api/docs/:id/files` | 上传文件 | | POST | `/api/docs/:id/notes` | 添加备注 | | POST | `/api/docs/:id/share` | 生成分享链接 | | DELETE | `/api/docs/:id` | 软删除文件夹 | ### 管理 | 方法 | 端点 | 描述 | |--------|----------|-------------| | GET | `/api/admin/users` | 列出所有用户 | | PUT | `/api/admin/users/:id/role` | 更新用户角色 | | PUT | `/api/admin/users/:id/ban` | 封禁/解封用户 | | GET | `/api/admin/flagged-reviews` | 获取已标记审核 | | GET | `/api/admin/flagged-volunteers` | 获取已标记志愿者 | ## 故障排除 ### 端口冲突 **错误：** 端口 5000 或 5173 已被使用 **解决方案：** ``` # 结束端口 5000 上的进程 $conn = Get-NetTCPConnection -LocalPort 5000 -State Listen -ErrorAction SilentlyContinue if ($conn) { Stop-Process -Id $conn.OwningProcess -Force } # 结束端口 5173 上的进程 $conn = Get-NetTCPConnection -LocalPort 5173 -State Listen -ErrorAction SilentlyContinue if ($conn) { Stop-Process -Id $conn.OwningProcess -Force } ``` ### 文件上传失败 | 问题 | 解决方案 | |-------|----------| | 上传目录缺失 | 确保 `backend/uploads` 存在 | | 文件过大 | 最大限制：20MB（图片/视频），10MB（音频） | | 格式无效 | 支持：JPG, PNG, WEBP, MP4, WEBM | | 图片无法加载 | Backend 必须正在运行（服务 `/uploads/`） | ### 数据库错误 | 问题 | 解决方案 | |-------|----------| | 连接失败 | 验证 `.env` 中的 `DATABASE_URL` | | Schema 不匹配 | 运行 `npm run prisma:generate` 然后 `npm run prisma:push` | | 填充失败 | 删除数据库并重新运行 `npm run seed` | ### Google Maps 问题 | 问题 | 解决方案 | |-------|----------| | 地图空白 | 验证 `VITE_GOOGLE_MAPS_API_KEY` | | API 错误 | 在 Cloud Console 中启用 Maps JavaScript API | | 需要账单 | 向 Google Cloud 项目添加付款方式 | ### 构建错误 ``` # 清除缓存并重新构建 cd backend rm -r node_modules rm package-lock.json npm install cd ../frontend rm -r node_modules rm package-lock.json npm install ``` ## 验证命令 ``` # 后端测试 cd backend && npm test # 后端构建 cd backend && npm run build # 前端构建 cd frontend && npm run build ``` ## 路线图 ### ✅ 已完成（模块 1） - [x] 功能 1：紧急报告 - [x] 功能 2：资源登记 - [x] 功能 3：志愿者审核与欺诈检测 [x] 功能 4：安全文档 ### 📋 模块 2（计划中） - [ ] 具备 AI 重复聚类的实时仪表板 - [ ] 交互式危机地图（增强版） - [ ] 高级志愿者目录搜索 - [ ] 视觉证据库 ### 📋 模块 3（计划中） - [ ] 实时危机更新 - [ ] 资源状态管理 - [ ] 自动化 SMS 调度 (Twilio) - [ ] NGO 总结报告 (PDF) - [ ] 资源预订系统 - [ ] 志愿者游戏化（排行榜、徽章） - [ ] 灾害损害 OCR (Google Vision API) ## 许可证 本项目是 CSE471 课程作业的一部分。保留所有权利。 ## 贡献者 社区响应与应急组织 (CORE) 开发团队

标签：DNS 解析, GNU通用公共许可证, Google Maps, IP 地址批量处理, MongoDB, Node.js, OpenAI, Qwen, RBAC, React, SaaS, Syscalls, Sysdig, Twilio, Whisper, 严重性分类, 事件分析, 人工智能, 信息可信度, 全栈Web平台, 公共安全, 内存规避, 危机响应, 地图集成, 多模态报告, 实时响应, 应急管理, 志愿者协调, 欺诈检测, 灾难恢复, 用户模式Hook绕过, 短信通知, 社区组织, 自动化攻击, 证据记录, 语音转文字, 资源跟踪, 非政府组织