فهرست منبع

fix(#2): 写一下README

Automated by Antigravity AI
robot 1 ماه پیش
والد
کامیت
8d6dff5e73
1فایلهای تغییر یافته به همراه210 افزوده شده و 0 حذف شده
  1. 210 0
      README.md

+ 210 - 0
README.md

@@ -0,0 +1,210 @@
+# Jerry WebApp 2.0 (Backend API & Services)
+
+基于 FastAPI + SQLAlchemy + MySQL/Redis 的现代化异步后端服务系统,主要提供签证预约调度协调(Coordinate)、增值服务任务管理(VAS Task)、订单与多渠道支付、智能 Agent 与大模型工具调用、以及消息通知等能力。
+
+---
+
+## 目录
+
+- [核心功能特性](#核心功能特性)
+- [系统架构与技术栈](#系统架构与技术栈)
+- [目录结构说明](#目录结构说明)
+- [环境配置与准备](#环境配置与准备)
+- [本地运行与部署](#本地运行与部署)
+  - [1. 本地启动 (开发与生产模式)](#1-本地启动-开发与生产模式)
+  - [2. Docker 与 Docker Compose 部署](#2-docker-与-docker-compose-部署)
+- [测试运行规范](#测试运行规范)
+- [API 接口与文档](#api-接口与文档)
+- [消息服务 (Iris Messenger)](#消息服务-iris-messenger)
+
+---
+
+## 核心功能特性
+
+1. **签证预约与调度协同 (Coordinate & Free Config)**
+   - 支持各大签证中心(TLSContact、VFS Global、BLS 等)配置抓取与空位轮询机制;
+   - 具备代理节点声誉与熔断风控评分体系(Proxy Reputation & Circuit Breaker)。
+
+2. **云端插件热升级与分发系统 (Plugins & Node Management)**
+   - 云端插件版本管理、代码上传校验(SHA256)、安全下载分发;
+   - 基于 Redis Pub/Sub 的实时插件版本下发与节点热重载。
+
+3. **订单、账单与多渠道支付 (Orders & Payment)**
+   - 订单全生命周期状态流转与幂等防重保障;
+   - 支持多币种与支付手续费(Processing Fee)自动计算;
+   - 集成 Stripe 与 Creem 支付网关(含生产与沙盒多套密钥环境隔离)及 Webhook 回调验签。
+
+4. **增值服务与工单系统 (VAS Tasks & Tickets)**
+   - 客户工单追踪处理、智能告警与防刷防重流控。
+
+5. **大语言模型与 Agent 引擎 (LLM & Intelligent Agent)**
+   - 兼容 OpenAI 格式 API(默认 DeepSeek),内置多种业务工具集(订单查询、节点控制、账单结算等)及上下文记忆管理。
+
+6. **多渠道通知分发引擎 (Iris Messenger)**
+   - 支持 Email、微信 (WeChat)、WhatsApp、Telegram 等渠道的异步消息轮询与重试发送。
+
+---
+
+## 系统架构与技术栈
+
+- **Web 框架**: [FastAPI](https://fastapi.tiangolo.com/) (Python 3.9+)
+- **ASGI 服务器**: [Uvicorn](https://www.uvicorn.org/) (结合 `uvloop` + `httptools`)
+- **ORM & 数据库**: [SQLAlchemy 2.x](https://www.sqlalchemy.org/) (异步驱动 `asyncmy` / `psycopg2-binary`) + MySQL 8.x
+- **缓存与消息中继**: [Redis](https://redis.io/)
+- **对象存储**: Cloudflare R2 / SeaweedFS
+- **数据校验**: Pydantic v2
+- **测试框架**: pytest + pytest-asyncio
+
+---
+
+## 目录结构说明
+
+```text
+jerry_webapp_2/
+├── app/
+│   ├── api/                      # API 路由层 (公共路由、登录保护路由、管理员路由)
+│   │   └── endpoints/            # 各业务领域控制器 (auth, order, payment, plugin, proxy 等)
+│   ├── core/                     # 核心基础设施 (配置 settings, 数据库 database, 权限 auth, 日志 logger)
+│   ├── models/                   # SQLAlchemy ORM 数据模型
+│   ├── schemas/                  # Pydantic 请求/响应数据模型
+│   ├── services/                 # 核心业务逻辑与服务实现
+│   │   └── agent/                # 智能 Agent 引擎、Memory 与内置 Tools
+│   ├── utils/                    # 公共工具类 (限流 throttler, 优先级队列, 代理辅助, 统一响应等)
+│   ├── visa_free_config_fetchers/# 各签证中心自动化抓取适配器
+│   └── main.py                   # FastAPI 应用主入口及中间件、全局异常处理
+├── docs/                         # 系统详细设计文档 (如 plugin.md 插件管理系统设计)
+├── scripts/                      # 运维与后台脚本 (如 iris.py 消息推送 Worker、数据库迁移脚本)
+├── tests/                        # 单元测试与集成测试套件
+├── starter.py                    # 服务启动入口脚本 (支持 DEV / PROD 环境模式切换)
+├── requirements.txt              # Python 依赖清单
+├── Dockerfile                    # 容器化构建镜像配置
+├── docker-compose.yml            # Docker Compose 编排文件 (API Backend + Iris Messenger)
+└── .env                          # 环境变量配置文件 (模板/本地环境)
+```
+
+---
+
+## 环境配置与准备
+
+在项目根目录创建或修改 `.env` 配置文件(参考 `.env` 模板):
+
+```ini
+# 全局环境配置: DEV (开发测试) | PROD (生产正式)
+ENV=DEV
+
+# 数据库连接 (MySQL 异步驱动)
+DATABASE_URL=mysql+asyncmy://<username>:<password>@<host>:<port>/<dbname>?charset=utf8mb4
+
+# Redis 缓存与 Pub/Sub
+REDIS_URL=redis://:<password>@<host>:<port>/0
+
+# LLM 大模型配置 (兼容 OpenAI 规范)
+LLM_API_KEY=sk-xxxx
+LLM_BASE_URL=https://api.deepseek.com
+LLM_MODEL=deepseek-v4-flash
+
+# 支付网关配置 (按 ENV 自动路由 PROD 或 TEST 密钥)
+STRIPE_PROD_API_KEY=
+STRIPE_PROD_WEBHOOK_SECRET=
+STRIPE_TEST_API_KEY=
+STRIPE_TEST_WEBHOOK_SECRET=
+
+CREEM_PROD_API_KEY=
+CREEM_PROD_WEBHOOK_SECRET=
+CREEM_TEST_API_KEY=
+CREEM_TEST_WEBHOOK_SECRET=
+
+# 消息通知网关配置
+TELEGRAM_API_TOKEN=
+WECHAT_API_TOKEN=
+WHATSAPP_API_BASE_URL=
+WHATSAPP_API_KEY=
+
+# 对象存储配置 (Cloudflare R2)
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET_NAME=
+```
+
+---
+
+## 本地运行与部署
+
+### 1. 本地启动 (开发与生产模式)
+
+#### 安装依赖
+推荐在虚拟环境中执行:
+```bash
+pip install -r requirements.txt
+```
+
+#### 启动服务
+使用项目统一启动器 `starter.py`:
+- **开发模式(默认,热重载 + 开启 Swagger 文档)**:
+  ```bash
+  python starter.py
+  ```
+- **生产模式(多工作进程 + uvloop + 关闭公网 API 文档)**:
+  ```bash
+  # Linux / macOS
+  ENV=PROD WORKERS=4 python starter.py
+
+  # Windows PowerShell
+  $env:ENV="PROD"; $env:WORKERS="4"; python starter.py
+  ```
+
+服务默认监听 `0.0.0.0:8888`。
+
+---
+
+### 2. Docker 与 Docker Compose 部署
+
+通过容器化方式一键编排启动后端 API 和 Iris 消息队列服务:
+
+```bash
+# 构建并启动后台容器
+docker-compose up -d --build
+
+# 查看运行状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f backend
+```
+
+---
+
+## 测试运行规范
+
+为确保根包模块 `app` 正确被解析,在执行单元测试时建议使用 `-m pytest` 或设置 `PYTHONPATH`:
+
+```bash
+# 执行全部单元测试
+python -m pytest
+
+# 执行指定模块测试 (例如插件管理或 RBAC 防护测试)
+python -m pytest tests/test_plugin_api.py
+python -m pytest tests/test_rbac_idor_guards.py
+```
+
+---
+
+## API 接口与文档
+
+在开发环境(`ENV=DEV`)启动后,可通过浏览器访问交互式 API 文档:
+- **Swagger UI**: [http://localhost:8888/docs](http://localhost:8888/docs)
+- **ReDoc UI**: [http://localhost:8888/redoc](http://localhost:8888/redoc)
+- **OpenAPI 规范 JSON**: [http://localhost:8888/openapi.json](http://localhost:8888/openapi.json)
+
+> **注**:在生产环境(`ENV=PROD`)下,出于安全考虑,文档路由将自动关闭。
+
+---
+
+## 消息服务 (Iris Messenger)
+
+独立后台服务负责异步消息发送(邮件、微信、Telegram、WhatsApp),具备指数退避重试和频道并发锁防护:
+```bash
+python scripts/iris.py
+```
+在 Docker 环境中,`docker-compose.yml` 已配置该服务作为独立容器 (`textskin-messenger`) 运行。