Monad Mate

Monad Mate=====================项目概述Monad Mate 是一个面向线下即时结伴的 Web3 应用。用户在商场或超市发布短时活动意图，系统在相同场地、相近时间和相同场景下推荐匹配对象。双方确认后通过 MON承诺金建立履约约束；完成线下核验后退还押金，并可铸造不可转让的履约凭证。项目处于开发/演示阶段。生产环境必须替换默认密钥、数据库凭据及链上管理私钥，且应在启用真实押金或身份核验前完成安全审计。主要功能* 即时同场匹配：按 venue_key、活动场景和可用时间窗筛选，再结合偏好、履约 信用、习惯、时间重叠和安全信号进行可解释排序。* 线下活动流程：发布邀约、匹配与私信、双方确认、承诺金托管、GPS / BLE / QR 签到与活动结果记录。* 安全与信誉：双向屏蔽、举报与审核、验证等级、安全偏好硬过滤、履约信用和 信誉衰减。* 钱包与链上能力：支持托管式邮箱/手机号登录和 EIP-191 外部钱包登录；接入 Monad 测试网托管、事件日志及灵魂绑定履约凭证。* AI 辅助：本地或 AINative 模型服务用于匹配文案、内容审核与偏好向量；未配置 外部服务时，部分能力会降级运行。主要技术栈前端：Next.js 14、React 18、TypeScript、Tailwind CSS、Framer Motion后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、Alembic、Uvicorn数据与异步：PostgreSQL 16、Redis 7、Celery区块链：Solidity、Foundry、Monad Testnet（Chain ID 10143）、web3.py扩展服务：ZeroDB、AINative / Ollama / Xinference、Hedera HCS、Coinbase x402部署：Docker / Docker Compose目录说明app/ Next.js 用户端，默认开发端口 3001backend/ FastAPI API、数据模型、业务服务和 Celery 任务landing/ Next.js 落地页 / PWA，默认开发端口 3000contracts/ Monad 智能合约与 Foundry 测试packages/ 可独立复用的 stake、reputation、x402 Python 包docs/ API、部署与分发文档scripts/ 演示数据等辅助脚本安装与运行一、Docker Compose（推荐）前置条件：Docker Desktop 与 Docker Compose。在项目根目录执行： cd backend Test-Path .env docker compose up --buildCompose 读取 backend/.env。请仅在本地修改该文件，不要提交私钥、API Key 或生产数据库密码。生产环境必须使用强随机 SECRET_KEY，并按需配置 MONAD_*、AINATIVE_API_KEY、ZERODB_* 等变量。启动后访问： API 文档：http://localhost:9998/api/docs 落地页：http://localhost:9999停止服务： docker compose downCompose 会启动 API、PostgreSQL、Redis、后台调度服务、落地页和用户端容器。用户端容器仅在 Compose 网络内暴露；需要本地访问时请单独启动前端。二、本地开发前置条件：Python 3.12+、Node.js 20+、PostgreSQL、Redis；完整后台任务还需要Celery。后端： cd backend python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt uvicorn app.main:app --reload --port 9999API 文档：http://localhost:9999/docs后台任务（另开终端，激活虚拟环境后执行）： cd backend celery -A app.tasks.celery_app worker --loglevel=info celery -A app.tasks.celery_app beat --loglevel=info用户端： cd app npm ci npm run dev落地页（另开终端）： cd landing npm ci npm run dev用户端默认地址：http://localhost:3001落地页默认地址：http://localhost:3000演示数据与测试后端启动后，在项目根目录执行： python scripts/demo_seed.py --base-url http://localhost:9999演示脚本会创建示例用户、房间、匹配、消息、核验和举报数据。项目没有固定公开演示账号；本地开发环境的验证码会由登录接口返回，生产环境不会返回。后端测试： cd backend pytest tests/ -v合约测试（需安装 Foundry）： cd contracts forge test环境变量与链上部署常用环境变量：DATABASE_URL PostgreSQL 连接地址REDIS_URL Redis / Celery 连接地址SECRET_KEY JWT 与托管钱包派生密钥；生产环境必须更换MONAD_RPC_URL、MONAD_CHAIN_ID Monad RPC 与网络 IDMONAD_ESCROW_ADDRESS 已部署的托管合约地址MONAD_EVENT_LOG_ADDRESS 已部署的事件日志合约地址MONAD_CREDENTIAL_SBT_ADDRESS 已部署的履约凭证合约地址MONAD_PRIVATE_KEY / MONAD_KEYSTORE_PATH 后端链上管理账户，仅保存于安全环境AINATIVE_API_KEY、ZERODB_* 可选 AI / 向量服务配置部署 Monad 测试网合约： cd contracts forge install foundry-rs/forge-std export MONAD_RPC_URL=https://testnet-rpc.monad.xyz export MONAD_DEPLOYER_KEY=0x... bash scripts/deploy_testnet.sh部署脚本会输出托管、事件日志和履约凭证合约地址。将地址填入后端环境变量并重启API 后生效。