# trustwill-backend

**Repository Path**: yeannnn/trustwill-backend

## Basic Information

- **Project Name**: trustwill-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TrustWill Backend

基于用户端加密与链上哈希存证的数字资产包裹管理后端。

## 项目定位

平台面向游戏账号交接说明、社交账号资料说明、照片、文档、网盘资料、纪念文件等生活化数字资产。用户在前端本地完成文件加密，后端只保存**密文文件**和**资产包裹元数据**，不保存用户明文内容、不保存私钥、不直接控制第三方平台账号。

区块链部分用于记录资产包裹的哈希、接收人、释放时间和状态，保证内容不可被平台篡改、流程可追溯。

## 技术栈

- Python 3.10+
- FastAPI
- SQLite + SQLAlchemy
- Uvicorn
- python-jose (JWT)
- passlib + bcrypt (密码哈希)

## 快速启动

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 复制环境配置（已配置好，无需修改）
cp .env.example .env

# 3. 启动服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

启动后访问:
- API 服务: http://localhost:8000
- Swagger 文档: http://localhost:8000/docs

## 环境变量

| 变量 | 说明 | 默认值 |
|---|---|---|
| DATABASE_URL | SQLite 数据库路径 | sqlite:///./trustwill.db |
| SECRET_KEY | JWT 签名密钥 | 已自动生成 |
| ALGORITHM | JWT 算法 | HS256 |
| ACCESS_TOKEN_EXPIRE_MINUTES | Token 过期时间 | 60 |
| UPLOAD_DIR | 文件上传目录 | uploads |

## 核心模块

### 1. 认证模块 `/api/auth`
- `POST /register` - 注册
- `POST /login` - 登录（OAuth2 标准表单格式）

### 2. 用户模块 `/api/users`
- `GET /me` - 当前用户信息
- `POST /bind-wallet` - 绑定钱包地址

### 3. 资产包裹模块 `/api/packages`
- `POST /` - 创建包裹
- `GET /sent/{wallet_address}` - 发出的包裹
- `GET /received/{wallet_address}` - 收到的包裹
- `GET /{package_id}` - 包裹详情
- `POST /{package_id}/claim` - 领取包裹
- `POST /{package_id}/cancel` - 取消包裹
- `GET /history/{wallet_address}` - 历史记录

### 4. 文件上传模块 `/api/upload`
- `POST /encrypted-file` - 上传密文文件
- `GET /download/{package_id}` - 下载密文文件

### 5. 模拟链上存证 `/api/mock-chain`
- `POST /create-proof/{package_id}` - 生成模拟存证
- `GET /events/{package_id}` - 查询链上事件

### 6. 通知模块 `/api/notifications`
- `GET /{wallet_address}` - 通知列表
- `POST /{notification_id}/read` - 标记已读

## 前端联调要点

1. **登录接口**返回 OAuth2 标准格式 `{"access_token": "...", "token_type": "bearer"}`，非统一包装格式
2. 后续请求在 Header 中携带 `Authorization: Bearer <token>`
3. 文件上传使用 `multipart/form-data`
4. 文件下载返回二进制流，前端负责解密

## 文档

- [API 接口文档](docs/api.md)
- [前端交接说明](docs/handoff.md)

## 数据库表

- `users` - 用户
- `asset_packages` - 资产包裹
- `package_files` - 密文文件记录
- `notifications` - 通知
- `chain_events` - 链上事件

## 职责边界

### 后端负责
- 用户注册/登录/钱包绑定
- 加密资产包裹 CRUD
- 密文文件存储
- 模拟链上存证
- 通知与状态记录

### 后端不负责
- 智能合约核心逻辑（由合约同学负责）
- 前端加密/解密逻辑
- 保存明文密码、私钥、助记词
- 对接真实社交平台或游戏账号 API