Ghost in the Machine - RustChain Bounty #2314

🔮 古老物品 AI 附身/控制体验平台

📋 项目概述

Ghost in the Machine 是一个创新的体验平台，让用户能够通过 AI 技术"附身"到古老/稀有物品中，体验物品的历史背景和独特人格。

核心功能

• ✅ 用户认证系统 - JWT Token 认证，安全注册/登录
• ✅ 物品管理 - 古老/稀有物品的 CRUD 操作
• ✅ AI 人格系统 - 每个物品拥有独特的 AI 人格设定
• ✅ 体验预订 - 预约 AI 附身体验时段
• ✅ 体验流程 - 预订→确认→激活→完成全流程
• ✅ 评价系统 - 用户对体验进行评分和评论
• ✅ 缓存优化 - Redis 缓存提升查询性能
• ✅ 健康检查 - 完整的服务监控端点

物品分类

• 古代文物 (Ancient Artifacts)
• 中世纪遗物 (Medieval Relics)
• 维多利亚时代 (Victorian Era)
• 东方古物 (Eastern Antiques)
• 神秘物品 (Mysterious Objects)
• 科技遗物 (Vintage Technology)
• 艺术珍品 (Rare Art)
• 宗教圣物 (Religious Relics)
• 皇室珍宝 (Royal Treasures)
• 民间传说 (Folklore Items)

🚀 快速开始

1. 环境准备

# 克隆项目
cd rustchain-ghost-machine

# 复制环境变量文件
cp .env.example .env

# 编辑 .env 文件，设置安全密钥
nano .env

2. 启动服务

# 一键启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

3. 验证部署

# 健康检查
curl http://localhost:8080/health

# 获取统计数据
curl http://localhost:8080/api/stats

# 列出所有物品
curl http://localhost:8080/api/artifacts

4. 运行测试

# 运行 API 测试脚本
./test-api.sh

📁 项目结构

rustchain-ghost-machine/
├── app/
│   └── app.py              # Flask 主应用 (600+ 行)
├── init-db/
│   └── 001-schema.sql      # 数据库初始化脚本
├── nginx/
│   ├── nginx.conf          # Nginx 主配置
│   └── conf.d/
│       └── ghost.conf      # Ghost API 配置
├── docker-compose.yml      # Docker 服务编排
├── Dockerfile              # API 容器镜像
├── requirements.txt        # Python 依赖
├── .env.example           # 环境变量模板
├── test-api.sh            # API 测试脚本
└── README.md              # 本文档

🔌 API 接口

认证接口

方法	路径	描述
POST	/api/auth/register	用户注册
POST	/api/auth/login	用户登录
GET	/api/users/me	获取当前用户信息 (需认证)

物品接口

方法	路径	描述
GET	/api/artifacts	获取物品列表
GET	/api/artifacts/:id	获取单个物品详情
POST	/api/artifacts	创建新物品 (需认证)

体验接口

方法	路径	描述
POST	/api/artifacts/:id/experience	预订体验 (需认证)
GET	/api/experiences	获取用户体验记录 (需认证)
POST	/api/experiences/:id/start	开始体验 (需认证)
POST	/api/experiences/:id/complete	完成体验 (需认证)

评价接口

方法	路径	描述
POST	/api/experiences/:id/review	创建评价 (需认证)

系统接口

方法	路径	描述
GET	/health	健康检查
GET	/api/stats	平台统计数据

📝 使用示例

注册新用户

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ghost_explorer",
    "email": "explorer@example.com",
    "password": "secure_password_123"
  }'

登录获取 Token

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ghost_hunter",
    "password": "test_password_123"
  }'

获取物品列表

curl http://localhost:8080/api/artifacts

按分类筛选物品

curl "http://localhost:8080/api/artifacts?category=神秘物品"

获取物品详情

curl http://localhost:8080/api/artifacts/1

预订体验

curl -X POST http://localhost:8080/api/artifacts/1/experience \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "start_time": "2026-04-01T10:00:00Z",
    "end_time": "2026-04-01T11:00:00Z"
  }'

创建新物品

curl -X POST http://localhost:8080/api/artifacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "明代青花瓷瓶",
    "description": "精美的明代青花瓷瓶，距今 600 年历史",
    "category": "东方古物",
    "era": "明朝",
    "ai_personality": "优雅、高贵的古代文人语气，喜欢吟诗作对",
    "experience_price": 300.00,
    "deposit_amount": 3000.00,
    "historical_background": "出自景德镇官窑，曾为皇室收藏"
  }'

提交评价

curl -X POST http://localhost:8080/api/experiences/1/review \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "rating": 5,
    "comment": "非常神奇的体验！AI 人格栩栩如生，仿佛真的穿越到了古代！"
  }'

🔒 安全特性

• ✅ 密码 SHA256 哈希存储
• ✅ JWT Token 认证 (30 天有效期)
• ✅ Token 哈希存储 (非明文)
• ✅ SQL 注入防护 (参数化查询)
• ✅ CORS 跨域配置
• ✅ Nginx 速率限制 (10 请求/秒)
• ✅ 安全响应头 (X-Frame-Options, X-Content-Type-Options)
• ✅ 非 root 用户运行容器

📊 数据库设计

核心表

• users - 用户信息
• api_tokens - API 认证令牌
• artifacts - 古老物品 (含 AI 人格设定)
• experiences - 体验订单
• reviews - 评价记录

预置数据

• 10 个物品分类
• 3 个测试用户
• 5 个示例物品 (古埃及占卜镜、中世纪炼金术士坩埚等)

🛠️ 技术栈

组件	技术	版本
后端框架	Flask	3.0.0
数据库	PostgreSQL	16.4
缓存	Redis	7.4
反向代理	Nginx	1.25.4
Python	Python	3.11
认证	PyJWT	2.8.0

🧪 测试

# 运行自动化测试
./test-api.sh

# 手动测试健康检查
curl http://localhost:8080/health

# 测试认证流程
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"ghost_hunter","password":"test_password_123"}'

📈 监控与维护

查看服务状态

docker-compose ps

查看日志

# 所有服务
docker-compose logs -f

# 特定服务
docker-compose logs -f ghost-api
docker-compose logs -f postgres
docker-compose logs -f redis

重启服务

docker-compose restart

停止服务

docker-compose down

清理数据 (谨慎使用)

docker-compose down -v

💰 RustChain 集成

RTC 代币支付

平台支持 RustChain 原生代币 RTC 支付：

• 钱包地址：RTC53fdf727dd301da40ee79cdd7bd740d8c04d2fb4
• 支付确认：链上确认后自动更新订单状态
• 押金退还：体验完成后自动退还

智能合约 (未来)

• 体验合约自动化执行
• 争议仲裁机制
• 信誉系统上链

📋 验收清单

功能	状态
用户注册/登录	✅
JWT 认证系统	✅
物品 CRUD	✅
AI 人格设定	✅
体验预订流程	✅
体验状态管理	✅
评价系统	✅
Redis 缓存	✅
健康检查	✅
Docker 部署	✅
README 文档	✅
环境变量配置	✅
API 测试脚本	✅

🎯 下一步

1. AI 集成 - 接入 LLM 实现真实 AI 对话
2. 语音合成 - 为不同 AI 人格配置独特语音
3. VR/AR 支持 - 沉浸式物品体验
4. 智能合约 - RustChain 链上支付和仲裁
5. 移动端 - React Native 应用
6. 多语言 - i18n 国际化支持

📄 许可证

MIT License - RustChain Bounty Program

👥 联系方式

• GitHub: https://github.com/RustChain-Protocol/RustChain
• Issue: #2314
• 开发者：牛马 🐴

---

代码已完成！PR 准备提交！ 🎉