Mahakbajpai/servicesync

# ServiceSync — 实时服务预订 API 与 Dashboard ServiceSync 是一个精简的全栈服务预订平台，包含 Node.js/Express 后端 API、使用 Tailwind CSS 设计的 React dashboard 前端，以及用于记录预订状态变更的不可篡改的 Solidity 智能合约审计追踪。 ## 🌐 在线部署 - **前端 Dashboard (Vercel)**：`https://servicesync-delta.vercel.app` - **后端 API 网关 (Render)**：`https://servicesync-backend-kin4.onrender.com` ## 🚀 快速入门指南 按照以下步骤在本地机器上运行区块链网络、后端服务器和前端 dashboard。 ### 前置条件 请确保已安装以下内容： - **Node.js**（推荐 v18 或更高版本） - **MongoDB**（在本地端口 `27017` 运行，或使用 MongoDB Atlas URI） ### 第一步：安装依赖 在项目根目录下运行： ``` npm run install:all ``` *此脚本会自动为根目录 monorepo、backend、frontend 和 blockchain 项目安装相关包依赖。* ### 第二步：启动区块链节点 打开一个终端窗口并运行： ``` # 启动本地 Hardhat Ethereum 节点 npm run blockchain ``` *该节点运行在 `http://127.0.0.1:8545`（Chain ID：`1337`）。你将看到一系列账户和私钥。* ### 第三步：部署智能合约 打开一个新的终端窗口并部署 Solidity 审计合约： ``` # 部署合约并记录地址 npm run deploy:contract ``` **示例输出：** ``` BookingAudit contract successfully deployed! Address: 0x5FbDB2315678afecb367f032d93F642f64180aa3 ``` *注意：如果部署地址与 `0x5FbDB2315678afecb367f032d93F642f64180aa3` 不同，请复制该地址并更新 `backend/.env` 中的 `CONTRACT_ADDRESS` 值。* ### 第四步：同时运行后端与前端 在新的终端窗口中，同时启动 Express 和 Vite 开发服务器： ``` npm run dev ``` - **后端 API**：运行于 [http://localhost:5000](http://localhost:5000) - **前端 Dashboard**：运行于 [http://localhost:3000](http://localhost:3000) *或者，你可以使用单个命令同时运行这三个进程（区块链 + 后端 + 前端）：`npm run dev:full`。* ## 📁 仓库目录结构 ``` servicesync/ ├── backend/ │ ├── config/ # Database connection setup │ ├── middleware/ # JWT parsing and role guard middleware │ ├── models/ # Mongoose schemas (User, Service, Booking, Review) │ ├── routes/ # REST API routers │ ├── services/ # Ethers.js blockchain connection module │ ├── .env # Local development variables (CORS, JWT, RPC) │ ├── .env.example # Env configuration template │ ├── package.json # Backend dependencies │ └── server.js # Server bootstrapper & configuration ├── blockchain/ │ ├── contracts/ # Solidity smart contracts │ │ └── BookingAudit.sol │ ├── scripts/ # Contract deployment scripts │ │ └── deploy.js │ ├── hardhat.config.js # Hardhat development setup │ └── package.json # Blockchain dependencies ├── frontend/ │ ├── src/ │ │ ├── components/ # Reusable React components (Navbar, etc.) │ │ ├── context/ # AuthContext for session management │ │ ├── pages/ # LandingPage, AuthPages, Dashboards │ │ ├── services/ # Axios API helper config │ │ ├── App.jsx # Layout structure & routes │ │ ├── index.css # Tailwind directives │ │ └── main.jsx # Bootstrap entry │ ├── tailwind.config.js # Styling setups │ └── package.json # Frontend dependencies ├── ServiceSync_Postman_Collection.json # Imports-ready API requests collection ├── package.json # Monorepo configuration ├── verify.js # Diagnostic sanity compilation checks └── README.md # Setup and documentation manual ``` ## ⚙️ 环境变量 (`backend/.env`) 在 `backend/` 文件夹中创建 `.env` 文件（会自动创建默认文件）： - `PORT`：服务器运行的端口（默认为 `5000`）。 - `MONGO_URI`：连接到你的 MongoDB 实例的连接字符串。 - `JWT_SECRET`：Token 签名密钥。 - `RPC_URL`：与 Ethereum 通信的 JSON-RPC endpoint（默认为 `http://127.0.0.1:8545`）。 - `CONTRACT_ADDRESS`：已部署的 `BookingAudit` 合约地址。 - `ACTOR_PRIVATE_KEY`：后端用于签署交易的 Hardhat 账户私钥（使用默认的第一个账户）。 ## 🔌 API 文档 所有 API 响应均返回一致的 JSON 封装结构： ``` { "success": true, "data": { ... }, "message": "Information status text" } ``` ### 1. Authentication Endpoints - **`POST /api/auth/register`**：注册新账号。 - Body：`{ "name": "...", "email": "...", "password": "...", "role": "Customer" | "Provider" }` - **`POST /api/auth/login`**：进行身份验证并获取 JWT token。 - Body：`{ "email": "...", "password": "..." }` ### 2. Service Listings Endpoints - **`POST /api/services`**：创建新的服务列表（*仅限 Provider*）。 - Headers：`Authorization: Bearer ` - Body：`{ "title": "...", "category": "...", "price": 40, "coordinates": [lng, lat], "description": "..." }` - **`GET /api/services`**：获取分页的服务列表，支持可选过滤器和地理空间排序。 - Query Params： - `page`（默认：1） - `limit`（默认：10） - `category`（可选：按类别过滤） - `longitude` & `latitude`（可选：根据坐标将服务按距离远近排序！） - **`GET /api/services/:id`**：获取完整的服务详情。 - **`PUT /api/services/:id`**：更新列表（*仅限服务所有者*）。 - **`DELETE /api/services/:id`**：删除列表（*仅限服务所有者*）。 ### 3. Bookings Endpoints - **`POST /api/bookings`**：预订服务（*仅限 Customer*）。 - Headers：`Authorization: Bearer ` - Body：`{ "serviceId": "..." }` - *业务规则：Provider 不能预订自己的服务。* - **`PATCH /api/bookings/:id/status`**：更新预订状态（*仅限服务所有者*）。 - Headers：`Authorization: Bearer ` - Body：`{ "status": "confirmed" | "completed" }` - *强制状态流程：pending ➔ confirmed ➔ completed。日志更新事件会直接记录在链上。* - **`POST /api/bookings/:id/rate`**：评价已完成的预订（*仅限该预订的 Customer*）。 - Body：`{ "rating": 1-5, "comment": "..." }` - **`GET /api/bookings/:id/audit`**：获取该预订的区块链审计追踪。 - *从智能合约获取不可篡改的账本状态历史记录。* ### 4. Ratings Profile Endpoint - **`GET /api/providers/:id/profile`**：公开 endpoint，用于汇总 Provider 的平均评分和评论列表。 ## 🔒 区块链审计追踪详情 账本通过智能合约（`blockchain/contracts/BookingAudit.sol`）记录状态更新： - **合约类型**：Solidity `BookingAudit` - **功能**： - `recordStatusChange(string bookingId, string oldStatus, string newStatus, address actor)`：记录状态转换、时间戳和操作者地址。 - `getAuditLogs(string bookingId)`：返回该预订的完整状态操作数组。 - **优雅降级**：如果本地区块链节点未运行，后端将处理该错误，把事件写入模拟的 mock 账本中，并在 API 响应中包含 `"mode": "mock"` 键，从而确保应用流程绝不中断。

标签：GNU通用公共许可证, MERN, MITM代理, Node.js, React, Syscalls, 区块链, 智能合约, 服务预订平台, 自定义脚本