Metadata-Version: 2.1
Name: seven-cloudapp-frame
Version: 1.2.138
Summary: seven cloudapp frame
Home-page: http://gitlab.tdtech.gao7.com/TaoBaoCloud/seven_cloudapp_frame.git
Author: seven
Author-email: tech@gao7.com
License: MIT
Platform: UNKNOWN
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: ~=3.4
Description-Content-Type: text/markdown
Requires-Dist: seven-framework (>=1.2.3)
Requires-Dist: seven-top (>=1.0.28)
Requires-Dist: asq (==1.3)
Requires-Dist: emoji (==1.6.1)
Requires-Dist: xmltodict (==0.12.0)
Requires-Dist: requests (==2.32.3)
Requires-Dist: requests-pkcs12 (==1.25)
Requires-Dist: mmh3 (==3.0.0)
Requires-Dist: bce-python-sdk (==0.8.61)

# seven_cloudapp_frame

## 目录

- [1. 项目概述](#1-项目概述)
- [2. 技术栈](#2-技术栈)
- [3. 项目架构](#3-项目架构)
- [4. 目录结构](#4-目录结构)
- [5. 核心业务流程图](#5-核心业务流程图)
- [6. 核心模块说明](#6-核心模块说明)
- [7. 路由系统](#7-路由系统)
- [8. Handler 处理器](#8-handler-处理器)
- [9. 数据模型](#9-数据模型)
- [10. 业务逻辑层](#10-业务逻辑层)
- [11. 缓存系统](#11-缓存系统)
- [12. 依赖关系](#12-依赖关系)
- [13. 配置管理](#13-配置管理)
- [14. 项目运行方式](#14-项目运行方式)
- [15. 开发规范](#15-开发规范)
- [16. 部署说明](#16-部署说明)

---

## 1. 项目概述

天志互联 Python 云应用框架库，提供活动管理、任务系统、用户服务、订单支付、资产管理等电商营销类业务的基础能力框架。

### 主要功能

- **活动管理**：活动创建、奖品配置、价格档位、主题皮肤管理
- **任务系统**：任务配置、任务进度追踪、任务奖励发放
- **用户服务**：用户登录、会员管理、黑名单、收货地址、用户资产
- **订单支付**：订单创建、支付回调、退款处理、物流同步
- **资产管理**：资产发放、资产流水、库存管理、资产预警
- **统计报表**：用户行为日志、活动数据报表、排队系统统计
- **内容管理**：CMS 内容配置、广告位管理、文章发布
- **第三方对接**：淘宝 API、微信支付、支付宝、抖音、京东

---

## 2. 技术栈

| 类别 | 技术 | 版本要求 |
|------|------|----------|
| 开发语言 | Python | ~=3.8 |
| Web 框架 | Tornado | 内置支持 |
| 关系型数据库 | MySQL | 5.7 / 8.0 |
| 缓存 | Redis | 4.0+ |
| 配置中心 | Nacos | 可选 |
| 基础框架 | seven-framework | >=1.2.3 |
| 淘宝 API | seven-top | >=1.0.28 |

### 核心依赖

```
seven-framework>=1.2.3
seven-top>=1.0.28
asq==1.3
emoji==1.6.1
xmltodict==0.12.0
requests==2.32.3
mmh3==3.0.0
bce-python-sdk==0.8.61
```

---

## 3. 项目架构

```
┌─────────────────────────────────────────────────────────────┐
│                        客户端层                              │
│         微信小程序 / H5 / 淘宝小程序 / 抖音 / Web             │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      Handler 层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ client/      │  │ server/      │  │ filter_base.py  │   │
│  │ C端接口      │  │ 管理端接口   │  │ 请求过滤        │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      业务逻辑层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ *_base_model │  │ console_models│  │ seven_model.py  │   │
│  │ 业务基类     │  │ 控制台模型   │  │ 基础实体        │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                       数据访问层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ db_models/   │  │ CacheModel   │  │ FrameDbModel    │   │
│  │ 数据库模型   │  │ 缓存模型     │  │ 数据库基类      │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                       基础设施层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ MySQL        │  │ Redis        │  │ Nacos           │   │
│  │ 主从支持     │  │ 缓存/队列    │  │ 配置中心        │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## 4. 目录结构

```
seven_cloudapp_frame/
├── handlers/                    # 请求处理层
│   ├── client/                  # C端接口（用户端）
│   │   ├── act.py               # 活动相关接口
│   │   ├── app.py               # 应用相关接口
│   │   ├── goods.py             # 商品相关接口
│   │   ├── ip_c.py              # IP相关接口
│   │   ├── order.py             # 订单相关接口
│   │   ├── pay.py               # 支付相关接口
│   │   ├── stat.py              # 统计相关接口
│   │   ├── task.py              # 任务相关接口
│   │   ├── theme.py             # 主题皮肤接口
│   │   └── user.py              # 用户相关接口
│   ├── server/                  # 管理端接口（B端）
│   │   ├── act_s.py             # 活动管理
│   │   ├── app_s.py             # 应用管理
│   │   ├── base_s.py            # 基础管理
│   │   ├── cms_s.py             # CMS管理
│   │   ├── goods_s.py           # 商品管理
│   │   ├── ip_s.py              # IP管理
│   │   ├── launch_s.py          # 投放管理
│   │   ├── module_s.py          # 模块管理
│   │   ├── order_s.py           # 订单管理
│   │   ├── price_s.py           # 价格管理
│   │   ├── prize_s.py           # 奖品管理
│   │   ├── report_s.py          # 报表管理
│   │   ├── task_s.py            # 任务管理
│   │   ├── theme_s.py           # 主题管理
│   │   └── user_s.py            # 用户管理
│   ├── core.py                  # 核心路由注册
│   ├── filter_base.py           # 请求过滤器基类
│   └── frame_base.py            # Handler基类
├── libs/                        # 工具库
│   ├── common/                  # 通用组件
│   │   ├── frame_console.py     # 控制台框架
│   │   ├── frame_db.py          # 数据库操作封装
│   │   ├── frame_helper.py      # 框架辅助工具
│   │   ├── frame_tornado.py     # Tornado框架封装
│   │   └── share_config.py      # 全局配置管理
│   └── customize/               # 自定义工具类
│       ├── action_helper.py     # 行为辅助
│       ├── alipay_helper.py     # 支付宝工具
│       ├── bloomfilter_helper.py # 布隆过滤器
│       ├── content_censor_helper.py # 内容审核
│       ├── counter_helper.py    # 计数器工具
│       ├── cryptography_helper.py # 加密解密
│       ├── email_helper.py      # 邮件工具
│       ├── excel_helper.py      # Excel处理
│       ├── file_helper.py       # 文件处理
│       ├── logistics_helper.py  # 物流工具
│       ├── oss2_helper.py       # 阿里云OSS
│       ├── queue_up_helper.py   # 排队系统
│       ├── redis_helper.py      # Redis工具
│       ├── safe_helper.py       # 安全工具
│       ├── seven_helper.py      # 七维通用工具
│       ├── sms_helper.py        # 短信工具
│       ├── tiktok_helper.py     # 抖音工具
│       ├── time_helper.py       # 时间工具
│       ├── wechat_helper.py     # 微信工具
│       └── locales/             # 国际化
│           ├── translation_helper.py # 翻译工具
│           └── zh_EN.json       # 英文翻译文件
├── models/                      # 数据模型层
│   ├── db_models/               # 数据库表模型
│   │   ├── act/                 # 活动相关表
│   │   ├── app/                 # 应用相关表
│   │   ├── asset/               # 资产相关表
│   │   ├── base/                # 基础数据表
│   │   ├── browse/              # 浏览记录表
│   │   ├── cms/                 # CMS内容表
│   │   ├── collect/             # 收藏记录表
│   │   ├── counter/             # 计数器表
│   │   ├── dict/                # 字典表
│   │   ├── erp/                 # ERP关系表
│   │   ├── friend/              # 友情链接表
│   │   ├── function/            # 功能配置表
│   │   ├── invite/              # 邀请记录表
│   │   ├── ip/                  # IP信息表
│   │   ├── launch/              # 投放计划表
│   │   ├── marketing/           # 营销活动表
│   │   ├── middler/             # 中间商表
│   │   ├── operation/           # 操作日志表
│   │   ├── pay/                 # 支付相关表
│   │   ├── price/               # 价格档位表
│   │   ├── prize/               # 奖品订单表
│   │   ├── product/             # 产品表
│   │   ├── queueup/             # 排队记录表
│   │   ├── refund/              # 退款订单表
│   │   ├── saas/                # SaaS配置表
│   │   ├── skin/                # 皮肤表
│   │   ├── special/             # 专题表
│   │   ├── stat/                # 统计报表表
│   │   ├── store/               # 店铺资产表
│   │   ├── tao/                 # 淘宝相关表
│   │   ├── task/                # 任务相关表
│   │   ├── theme/               # 主题表
│   │   ├── third/               # 第三方订单表
│   │   ├── user/                # 用户相关表
│   │   └── version/             # 版本表
│   ├── console_models/          # 控制台业务模型
│   │   ├── asset_console_model.py   # 资产控制台
│   │   ├── erp_console_model.py     # ERP控制台
│   │   ├── launch_console_model.py  # 投放控制台
│   │   ├── stat_console_model.py    # 统计控制台
│   │   ├── task_console_model.py    # 任务控制台
│   │   ├── timing_work_model.py     # 定时作业
│   │   └── token_console_model.py   # Token控制台
│   ├── act_base_model.py        # 活动业务基类
│   ├── app_base_model.py        # 应用业务基类
│   ├── asset_base_model.py      # 资产业务基类
│   ├── cache_model.py           # 缓存模型基类
│   ├── cms_base_model.py        # CMS业务基类
│   ├── enum.py                  # 枚举定义
│   ├── frame_base_model.py      # 框架业务基类
│   ├── goods_base_model.py      # 商品业务基类
│   ├── ip_base_model.py         # IP业务基类
│   ├── launch_base_model.py     # 投放业务基类
│   ├── module_base_model.py     # 模块业务基类
│   ├── mp_base_model.py         # 小程序业务基类
│   ├── operate_base_model.py    # 操作业务基类
│   ├── order_base_model.py      # 订单业务基类
│   ├── prize_base_model.py      # 奖品业务基类
│   ├── push_base_model.py       # 推送业务基类
│   ├── seven_model.py           # 基础实体模型
│   ├── stat_base_model.py       # 统计业务基类
│   ├── task_base_model.py       # 任务业务基类
│   ├── theme_base_model.py      # 主题业务基类
│   ├── top_base_model.py        # 淘宝业务基类
│   └── user_base_model.py       # 用户业务基类
├── locales/                     # 国际化翻译文件
├── __init__.py
└── route.py                     # 路由注册
```

---

## 5. 核心业务流程图

### 5.1 活动参与流程

```
用户进入小程序
    │
    ▼
获取活动信息 (act_info)
    │
    ▼
校验参与条件 (会员/关注/黑名单)
    │
    ▼
执行任务 (task) ──► 获取任务奖励
    │                    │
    ▼                    ▼
参与抽奖/排队 ──► 发放奖品 (prize)
    │                    │
    ▼                    ▼
创建订单 (order) ◄── 确认中奖
    │
    ▼
支付回调 (pay) ──► 更新订单状态
    │
    ▼
物流同步 (erp) ──► 同步物流信息
```

### 5.2 订单推送与物流回写流程

```
定时任务启动
    │
    ├──► process_order_push (推送订单)
    │      │
    │      ▼
    │   查询待同步订单 (sync_status=0/3)
    │      │
    │      ▼
    │   调用遁甲API创建订单
    │      │
    │      ▼
    │   更新订单同步状态
    │
    └──► process_order_pull (拉取物流)
           │
           ▼
        查询已发货订单
           │
           ▼
        调用遁甲API获取物流
           │
           ▼
        更新物流信息到订单
```

---

## 6. 核心模块说明

### 6.1 活动模块 (act)

| 文件 | 说明 |
|------|------|
| act_info_model.py | 活动基本信息 |
| act_module_model.py | 活动模块配置 |
| act_prize_model.py | 活动奖品配置 |
| act_type_model.py | 活动类型定义 |
| act_base_model.py | 活动业务逻辑 |

### 6.2 用户模块 (user)

| 文件 | 说明 |
|------|------|
| user_info_model.py | 用户基本信息 |
| user_account_model.py | 用户账号信息 |
| user_address_model.py | 用户收货地址 |
| user_asset_model.py | 用户资产信息 |
| user_black_model.py | 用户黑名单 |
| user_base_model.py | 用户业务逻辑 |

### 6.3 订单模块 (order/prize)

| 文件 | 说明 |
|------|------|
| prize_order_model.py | 奖品订单表 |
| prize_roster_model.py | 中奖名单表 |
| pay_order_model.py | 支付订单表 |
| order_base_model.py | 订单业务逻辑 |

### 6.4 任务模块 (task)

| 文件 | 说明 |
|------|------|
| task_info_model.py | 任务配置信息 |
| task_log_model.py | 任务执行日志 |
| task_count_model.py | 任务计数统计 |
| task_gear_count_model.py | 任务档位统计 |
| task_base_model.py | 任务业务逻辑 |

### 6.5 资产模块 (asset)

| 文件 | 说明 |
|------|------|
| asset_log_model.py | 资产流水记录 |
| asset_inventory_model.py | 资产库存 |
| asset_only_model.py | 唯一资产 |
| asset_warn_notice_model.py | 资产预警 |
| asset_base_model.py | 资产业务逻辑 |

---

## 7. 路由系统

### 7.1 路由注册方式

框架提供自动路由注册机制，业务方可通过以下方式引入框架路由：

```python
from seven_cloudapp_frame.route import seven_cloudapp_frame_route

handlers = []
handlers.extend(seven_cloudapp_frame_route())
```

### 7.2 路由列表

#### C端接口 (client)

| 路由 | Handler | 说明 |
|------|---------|------|
| /client/login | LoginHandler | 小程序登录 |
| /client/act_info | ActInfoHandler | 获取活动信息 |
| /client/user_asset | GetUserAssetHandler | 获取用户资产 |
| /client/user_address_list | UserAddressListHandler | 收货地址列表 |
| /client/save_user_address | SaveUserAddressHandler | 保存收货地址 |
| /client/theme_info | ThemeInfoHandler | 主题信息 |
| /client/act_prize_list | ActPrizeListHandler | 活动奖品列表 |
| /client/create_wechat_qrcode | CreateWeChatQrCodeHandler | 获取微信小程序码 |

#### 管理端接口 (server)

| 路由 | Handler | 说明 |
|------|---------|------|
| /server/act_list | ActListHandler | 活动列表 |
| /server/save_act | SaveActHandler | 保存活动 |
| /server/user_list | UserListHandler | 用户列表 |
| /server/order_list | OrderListHandler | 订单列表 |
| /server/prize_list | PrizeListHandler | 奖品列表 |
| /server/stat_report | StatReportHandler | 统计报表 |

---

## 8. Handler 处理器

### 8.1 Handler 继承体系

```
BaseApiHandler (seven-framework)
    │
    └── FrameBaseApiHandler (frame_base.py)
            │
            ├── ClientBaseHandler (client/*.py)
            │       └── 用户端接口Handler（大部分接口）
            │
            └── FrameBaseHandler (frame_base.py)
                    └── 无需加密/第三方调用接口
```

### 8.2 核心 Handler 基类

#### FrameBaseApiHandler

- **位置**: [handlers/frame_base.py](file:///e:/Project/Gao7Git/seven/seven_cloudapp_frame/seven_cloudapp_frame/handlers/frame_base.py)
- **功能**: 提供通用API处理能力
- **主要方法**:
  - `options_async()`: 处理跨域预检请求
  - `set_default_headers()`: 设置跨域响应头
  - `check_xsrf_cookie()`: 禁用XSRF检查

#### ClientBaseHandler

- **功能**: C端接口基类，server/ 目录下接口也继承此类
- **特性**: 
  - 自动获取 app_id、act_id、user_id
  - 支持用户登录态校验
  - 支持接口签名验证

#### FrameBaseHandler

- **功能**: 无需加密或给第三方调用的接口基类
- **特性**:
  - 不自动获取用户信息
  - 不强制签名验证
  - 适用于开放接口或回调接口

### 8.3 过滤器 (Filter)

#### filter_base.py

提供请求过滤装饰器：

```python
@filter_check_sign(sign_key="your_key", expired_seconds=300)
def post_async(self):
    # 自动验证请求签名
    pass
```

| 装饰器 | 功能 |
|--------|------|
| filter_check_sign | HTTP请求签名验证 |

---

## 9. 数据模型

### 9.1 模型继承体系

```
FrameDbModel (seven-framework)
    │
    └── CacheModel (cache_model.py)
            │
            └── ActInfoModel (db_models/act/*.py)
            └── UserInfoModel (db_models/user/*.py)
            └── PrizeOrderModel (db_models/prize/*.py)
            └── ...
```

### 9.2 CacheModel 缓存模型

- **位置**: [models/cache_model.py](file:///e:/Project/Gao7Git/seven/seven_cloudapp_frame/seven_cloudapp_frame/models/cache_model.py)
- **功能**: MySQL数据自动同步到Redis缓存
- **特性**:
  - 查询结果自动缓存
  - 更新操作自动清除缓存
  - 支持依赖缓存（dependency_cache）
  - 支持空值缓存（is_cache_empty）

### 9.3 业务基类模型

| 基类 | 文件 | 功能 |
|------|------|------|
| FrameBaseModel | frame_base_model.py | 框架通用业务逻辑 |
| ActBaseModel | act_base_model.py | 活动业务逻辑 |
| UserBaseModel | user_base_model.py | 用户业务逻辑 |
| OrderBaseModel | order_base_model.py | 订单业务逻辑 |
| PrizeBaseModel | prize_base_model.py | 奖品业务逻辑 |
| TaskBaseModel | task_base_model.py | 任务业务逻辑 |
| AssetBaseModel | asset_base_model.py | 资产业务逻辑 |

### 9.4 分表支持

以下表支持分表模式：

- `stat_log_tb` - 统计日志
- `stat_report_tb` - 统计报表
- `asset_log_tb` - 资产流水
- `user_asset_tb` - 用户资产
- `task_count_tb` - 任务计数
- `user_info_tb` - 用户信息
- `prize_order_tb` - 奖品订单
- `prize_roster_tb` - 中奖名单

使用方式：

```python
prize_order_model = PrizeOrderModel().set_sub_table(app_id)
```

---

## 10. 业务逻辑层

### 10.1 控制台模型 (Console Models)

控制台模型用于处理定时任务和后台业务逻辑：

| 模型 | 文件 | 功能 |
|------|------|------|
| ErpConsoleModel | erp_console_model.py | ERP订单推送与物流拉取 |
| TaskConsoleModel | task_console_model.py | 任务定时处理 |
| AssetConsoleModel | asset_console_model.py | 资产定时发放 |
| StatConsoleModel | stat_console_model.py | 统计数据汇总 |
| LaunchConsoleModel | launch_console_model.py | 投放计划执行 |
| TokenConsoleModel | token_console_model.py | Token刷新管理 |
| TimingWork | timing_work_model.py | 定时作业基类 |

### 10.2 ERP 控制台示例

```python
class ErpConsoleModel:
    def console_erp(self, mod_count=1, process_type=1, 
                    pull_time_range="", push_time_range=""):
        """
        启动订单推送和物流拉取任务
        :param mod_count: 队列数（分片数）
        :param process_type: 1-Redis模式 2-API模式
        :param pull_time_range: 拉取时间段，如 "09:00-22:00"
        :param push_time_range: 推送时间段，如 "09:00-22:00"
        """
```

### 10.3 定时作业基类

```python
class TimingWork:
    """定时作业基类"""
    def execute(self):
        """执行业务逻辑，子类重写此方法"""
        pass
```

---

## 11. 缓存系统

### 11.1 缓存架构

```
业务查询
    │
    ▼
┌─────────────┐
│  查询Redis  │────命中────► 直接返回
└─────────────┘
    │ 未命中
    ▼
┌─────────────┐
│  查询MySQL  │
└─────────────┘
    │
    ▼
┌─────────────┐
│  写入Redis  │
└─────────────┘
    │
    ▼
  返回结果
```

### 11.2 缓存配置

```json
{
  "redis_cache": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 1
  },
  "is_cache_empty": false
}
```

### 11.3 缓存工具类

| 工具类 | 文件 | 功能 |
|--------|------|------|
| RedisHelper | redis_helper.py | Redis通用操作 |
| CacheModel | cache_model.py | 数据库缓存同步 |
| BloomFilterHelper | bloomfilter_helper.py | 布隆过滤器 |

---

## 12. 依赖关系

### 12.1 外部依赖

```
seven_cloudapp_frame
    │
    ├── seven-framework >= 1.2.3  (基础框架)
    │       ├── Tornado (Web服务)
    │       ├── SQLAlchemy (ORM)
    │       ├── Redis-py (Redis客户端)
    │       └── Nacos-sdk (配置中心)
    │
    ├── seven-top >= 1.0.28  (淘宝API)
    │       └── Top-sdk (淘宝开放平台)
    │
    └── 其他第三方库
            ├── requests (HTTP请求)
            ├── bce-python-sdk (百度智能云)
            └── mmh3 (哈希算法)
```

### 12.2 内部模块依赖

```
handlers/
    ├── 依赖 libs/common/ (配置、数据库)
    ├── 依赖 libs/customize/ (工具类)
    └── 依赖 models/ (业务模型)

models/
    ├── db_models/ 依赖 libs/common/frame_db.py
    ├── console_models/ 依赖 db_models/
    └── *_base_model.py 依赖 frame_base_model.py

libs/
    ├── common/ 为基础层，被所有模块依赖
    └── customize/ 为工具层，按需依赖
```

---

## 13. 配置管理

### 13.1 配置加载方式

1. **本地配置文件**

```python
from seven_cloudapp_frame.libs.common.share_config import init_config
init_config("config_dev.json")
```

2. **Nacos配置中心**

```python
from seven_cloudapp_frame.libs.common.share_config import init_config_from_nacos
init_config_from_nacos(config_file, config_content)
```

3. **远程HTTP配置**

```python
init_config("http://config-server/config.json")
```

### 13.2 配置文件示例

```json
{
  "run_port": "8080",
  "project_name": "cloudapp",
  "db_cloudapp": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "password",
    "database": "cloudapp_db",
    "charset": "utf8mb4"
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 0
  },
  "redis_cache": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 1
  },
  "nacos": {
        "host": "",
        "namespace": "",
        "group": "",
        "data_id": "",
        "username": "",
        "password": ""
  },
  "armor_url": "https://armor.example.com",
  "armor_sign_key": "your_sign_key",
  "safe_config": {
    "sensitive_encrypt_key": "your_encrypt_key"
  },
  "translate_config": {
    "is_translate": false,
    "locales_dir": "/locales",
  },
  "allow_origin_list": ["https://example.com"],
  "test_config": {
    "user_nick": "test_nick",
    "open_id": "test_open_id",
    "source_app_id": "test_app_id",
    "client_ver": "1.0.0",
    "access_token": ""
  }
}
```
---

## 14. 项目运行方式

### 14.1 安装依赖

```bash
pip install seven-cloudapp-frame
```

或本地安装：

```bash
git clone http://gitlab.tdtech.gao7.com/TaoBaoCloud/seven_cloudapp_frame.git
cd seven_cloudapp_frame
pip install -e .
```

### 14.2 启动服务

```python
from seven_cloudapp_frame.route import seven_cloudapp_frame_route
from seven_framework.web_tornado import start_web

handlers = []
handlers.extend(seven_cloudapp_frame_route())

# 启动Tornado服务
start_web(handlers, port=8080)
```

### 14.3 启动控制台任务

```python
from seven_cloudapp_frame.models.console_models.erp_console_model import ErpConsoleModel

erp_console = ErpConsoleModel()

# 启动订单推送和物流拉取
erp_console.console_erp(
    mod_count=10,           # 10个队列分片
    process_type=2,         # API模式
    pull_time_range="09:00-22:00",  # 拉取时间段
    push_time_range="09:00-22:00"   # 推送时间段
)
```

### 14.4 启动定时作业

```python
from seven_cloudapp_frame.models.console_models.timing_work_model import TimingWork

class MyTimingWork(TimingWork):
    def execute(self):
        # 执行业务逻辑
        pass

work = MyTimingWork()
work.execute()
```

---

## 15. 开发规范

### 15.1 代码规范

- 使用 UTF-8 编码
- 遵循 PEP 8 代码风格
- 类名使用驼峰命名法（PascalCase）
- 方法名和变量名使用小写下划线命名法（snake_case）
- 常量使用全大写下划线命名法（UPPER_SNAKE_CASE）

### 15.2 注释规范

```python
def method_name(self, param1, param2):
    """
    :description: 方法描述
    :param param1: 参数1说明
    :param param2: 参数2说明
    :return: 返回值说明
    :last_editors: 最后编辑人
    """
    pass
```

### 15.3 模型开发规范

1. **数据库模型**: 继承 `CacheModel`，使用 `FrameDbModel` 能力
2. **业务模型**: 继承 `FrameBaseModel` 或对应业务基类
3. **Handler**: 继承 `ClientBaseHandler` 或 `FrameBaseHandler`

### 15.4 国际化规范

- 错误消息使用 `translation_helper` 进行翻译
- 翻译文件放置在 `locales/` 目录
- 支持 `zh_CN` 和 `zh_EN` 两种语言
- 翻译文件使用 JSON 格式，以中文为 key

```python
from seven_cloudapp_frame.libs.customize.locales.translation_helper import translation_helper

error_msg = translation_helper.translate("用户不存在")
```

---

## 16. 部署说明

### 16.1 环境要求

| 组件 | 版本 | 说明 |
|------|------|------|
| Python | 3.8+ | 运行环境 |
| MySQL | 5.7 / 8.0 | 主数据库 |
| Redis | 4.0+ | 缓存和队列 |
| Nacos | 可选 | 配置中心 |

### 16.2 数据库配置

- **主库配置**: 默认 `db_cloudapp`
- **主从支持**: 支持读写分离
- **分表支持**: 8张表支持分表模式
- **字符集**: 推荐使用 `utf8mb4`

### 16.3 缓存配置

- **Redis 缓存**: 用于数据缓存，默认 30 分钟过期
- **依赖缓存**: 用于关联数据缓存，默认 24 小时过期
- **缓存失败重试**: 支持缓存失效后的重试机制

### 16.4 配置中心

- **Nacos 配置**: 生产环境推荐使用 Nacos 进行配置管理
- **本地配置**: 开发环境可使用本地 JSON 配置文件
- **远程配置**: 支持通过 HTTP URL 加载配置文件

### 16.5 语言翻译

- 设置 `is_translate` 为 `true` 开启翻译
- 配置 `locales_dir` 指向翻译文件目录
- 支持 `zh_CN` 和 `zh_EN` 两种语言

### 16.6 监控与日志

- 内置心跳监控机制（`heart_beat_monitor`）
- 支持操作日志记录（`operation_log_model`）
- 异常日志自动记录到错误日志文件

---

## 版本信息

- **当前版本**: 1.2.137
- **作者**: Huang
- **邮箱**: tech@gao7.com
- **仓库**: http://gitlab.tdtech.gao7.com/TaoBaoCloud/seven_cloudapp_frame.git
- **许可证**: MIT


