fakabot/PROJECT_STRUCTURE.md

# 📁 项目结构说明

## 核心文件

### 主程序
- `bot.py` (37KB) - 主程序入口，Flask服务器，支付回调处理
- `user_flow.py` (58KB) - 用户交互流程，订单创建，支付处理
- `admin_panel.py` (103KB) - 管理员面板，商品管理，订单管理

### 支付模块
- `payments.py` (6.7KB) - 支付统一接口
- `payments_lemzf_official.py` (11KB) - 柠檬支付官方对接

### 缓存和限流
- `redis_cache.py` (7.6KB) - Redis缓存模块
- `rate_limiter.py` (6.3KB) - 频率限制模块

### 工具模块
- `utils.py` (15KB) - 工具函数，数据库操作
- `screenshot_utils.py` (12KB) - 支付页面截图

### 配置文件
- `config.json` (1.8KB) - 主配置文件（需自行配置）
- `requirements.txt` (176B) - Python依赖
- `Dockerfile` (832B) - Docker镜像构建
- `docker-compose.yml` (735B) - Docker编排配置

### 文档
- `README.md` - 项目说明
- `CHANGELOG.md` - 更新日志
- `DEPLOY.md` - 部署文档
- `.gitignore` - Git忽略文件

---

## 目录结构

```
fakabot/
├── 📄 核心代码
│   ├── bot.py                          # 主程序（Flask + Telegram Bot）
│   ├── user_flow.py                    # 用户流程处理
│   ├── admin_panel.py                  # 管理员面板
│   ├── payments.py                     # 支付处理
│   ├── payments_lemzf_official.py      # 柠檬支付
│   ├── redis_cache.py                  # Redis缓存
│   ├── rate_limiter.py                 # 频率限制
│   ├── utils.py                        # 工具函数
│   └── screenshot_utils.py             # 截图工具
│
├── ⚙️ 配置文件
│   ├── config.json                     # 主配置（需配置）
│   ├── requirements.txt                # Python依赖
│   ├── Dockerfile                      # Docker镜像
│   └── docker-compose.yml              # Docker编排
│
├── 📚 文档
│   ├── README.md                       # 项目说明
│   ├── CHANGELOG.md                    # 更新日志
│   ├── DEPLOY.md                       # 部署文档
│   ├── PROJECT_STRUCTURE.md            # 项目结构（本文件）
│   └── .gitignore                      # Git忽略
│
└── 💾 数据目录（运行时生成）
    └── data/
        └── fakabot.db                  # SQLite数据库
```

---

## 代码模块说明

### bot.py - 主程序
**功能**：
- Flask Web服务器
- Telegram Bot初始化
- 支付回调处理（柠檬支付/TOKEN188）
- 订单超时管理
- 健康检查接口

**关键函数**：
- `pay_callback()` - 支付回调处理
- `handle_token188_callback()` - TOKEN188回调
- `job_cancel_expired()` - 订单超时取消
- `_mark_paid_and_deliver()` - 标记已支付并发货

---

### user_flow.py - 用户流程
**功能**：
- 用户命令处理（/start, /shop等）
- 商品列表展示
- 支付方式选择
- 订单创建和预加载
- 支付链接生成
- 订单查询

**关键函数**：
- `cb_pay()` - 支付方式选择
- `_preload_payment_order()` - 预加载订单
- `_create_payment_order()` - 创建支付订单
- `cb_payment_announcement_ack()` - 支付公告确认
- `cb_order_list()` - 订单列表

---

### admin_panel.py - 管理员面板
**功能**：
- 商品管理（增删改查）
- 订单管理
- 用户管理
- 统计数据
- 系统设置

**关键功能**：
- 商品上下架
- 订单状态修改
- 数据统计
- 配置管理

---

### payments.py - 支付处理
**功能**：
- 支付统一接口
- 支付网关对接
- 签名生成和验证

---

### redis_cache.py - Redis缓存
**功能**：
- Redis连接管理
- 缓存读写
- 自动过期
- 降级处理

**缓存类型**：
- 商品信息（5分钟）
- 配置信息（10分钟）
- 用户会话（1小时）

---

### rate_limiter.py - 频率限制
**功能**：
- 用户操作限流
- IP限流
- 自动重置
- 降级处理

**限制规则**：
- 用户命令：20次/分钟
- 创建订单：5次/5分钟
- 查询订单：10次/分钟
- IP回调：100次/分钟

---

### utils.py - 工具函数
**功能**：
- 数据库操作
- 消息发送
- 键盘生成
- 设置管理

---

### screenshot_utils.py - 截图工具
**功能**：
- 支付页面截图
- 二维码生成
- Selenium自动化

---

## 数据库表结构

### products - 商品表
- id, name, price, cover_url, full_description, status

### orders - 订单表
- id, user_id, product_id, amount, payment_method, status, out_trade_no, create_time

### card_keys - 卡密表
- id, product_id, card_key, status

### settings - 设置表
- key, value

### last_msgs - 最后消息表
- chat_id, message_id

### usdt_transactions - USDT交易表
- id, out_trade_no, transaction_id, from_address, amount, create_time

---

## 配置说明

### config.json
```json
{
  "BOT_TOKEN": "Telegram Bot Token",
  "ADMIN_ID": 管理员用户ID,
  "DOMAIN": "域名",
  "USE_WEBHOOK": true/false,
  "WEBHOOK_PATH": "/tg/webhook",
  "ORDER_TIMEOUT_SECONDS": 3600,
  "SHOW_QR": false,
  "STRICT_CALLBACK_SIGN_VERIFY": true,
  "ENABLE_PAYMENT_SCREENSHOT": true,
  "PAYMENTS": {
    "alipay": {...},
    "wxpay": {...},
    "usdt_lemon": {...},
    "usdt_token188": {...}
  }
}
```

---

## 环境变量

### Docker环境变量
- `TZ` - 时区（Asia/Shanghai）
- `REDIS_HOST` - Redis主机（redis）
- `REDIS_PORT` - Redis端口（6379）
- `DATA_DIR` - 数据目录（/app/data）

---

## 端口说明

- `58001` - Flask Web服务器（支付回调）
- `58002` - 备用端口
- `6379` - Redis（容器内部）

---

## 文件大小统计

| 文件 | 大小 | 说明 |
|------|------|------|
| admin_panel.py | 103KB | 管理员面板 |
| bot.py | 37KB | 主程序 |
| user_flow.py | 58KB | 用户流程 |
| utils.py | 15KB | 工具函数 |
| screenshot_utils.py | 12KB | 截图工具 |
| payments_lemzf_official.py | 11KB | 柠檬支付 |
| redis_cache.py | 7.6KB | Redis缓存 |
| rate_limiter.py | 6.3KB | 频率限制 |
| payments.py | 6.7KB | 支付处理 |

**总代码量**: ~256KB

---

## 依赖说明

### Python依赖
- python-telegram-bot[job-queue,webhooks]==20.6
- Flask==3.0.3
- requests==2.31.0
- qrcode==7.4.2
- Pillow==10.2.0
- waitress==2.1.2
- selenium==4.15.0
- webdriver-manager==4.0.1
- redis==5.0.1

### 系统依赖
- Python 3.11
- Redis 7
- Chromium（用于截图）

---

## 开发建议

### 代码规范
- 使用Python 3.11+
- 遵循PEP 8规范
- 添加类型注解
- 编写文档字符串

### 测试
- 单元测试
- 集成测试
- 支付回调测试

### 部署
- 使用Docker部署
- 配置反向代理（Nginx）
- 启用HTTPS
- 定期备份数据库

---

**项目整理完成！** ✨