Metadata-Version: 2.1
Name: seven-cloudapp-frame
Version: 1.2.158
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 框架说明

> 本文档整合了 README.md、rule.md 和 config.md 的内容，提供完整的框架使用指南

---

## 目录

- [1. 项目概述](#1-项目概述)
- [2. 技术栈与依赖](#2-技术栈与依赖)
- [3. 项目架构](#3-项目架构)
- [4. 目录结构](#4-目录结构)
- [5. 安装与初始化](#5-安装与初始化)
- [6. 配置管理](#6-配置管理)
- [7. Handler 处理器](#7-handler-处理器)
- [8. 数据模型](#8-数据模型)
- [9. 业务逻辑层](#9-业务逻辑层)
- [10. 核心功能规范](#10-核心功能规范)
- [11. 第三方接口](#11-第三方接口)
- [12. 缓存系统](#12-缓存系统)
- [13. 排队系统](#13-排队系统)
- [14. ActionHelper 执行助手](#14-actionhelper-执行助手)
- [15. 心跳监控](#15-心跳监控)
- [16. 开发规范](#16-开发规范)
- [17. 项目运行方式](#17-项目运行方式)
- [18. 部署说明](#18-部署说明)

---

## 1. 项目概述

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

### 1.1 主要功能

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

### 1.2 包信息

| 属性 | 值 |
|------|-----|
| 包名 | `seven-cloudapp_frame` |
| 版本 | `1.2.138` |
| Python 要求 | `~=3.8` (即 >=3.8, <4.0) |

---

## 2. 技术栈与依赖

### 2.1 技术栈

| 类别 | 技术 | 版本要求 |
|------|------|----------|
| 开发语言 | 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 |

### 2.2 核心依赖

```
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. 项目架构

### 3.1 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        客户端层                              │
│         微信小程序 / 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             # 商品相关接口
│   │   ├── order.py             # 订单相关接口
│   │   ├── pay.py               # 支付相关接口
│   │   ├── stat.py              # 统计相关接口
│   │   ├── task.py              # 任务相关接口
│   │   ├── theme.py             # 主题皮肤接口
│   │   └── user.py              # 用户相关接口
│   ├── server/                  # 管理端接口（B端）
│   │   ├── act_s.py             # 活动管理
│   │   ├── app_s.py             # 应用管理
│   │   ├── goods_s.py           # 商品管理
│   │   ├── order_s.py           # 订单管理
│   │   ├── prize_s.py           # 奖品管理
│   │   ├── task_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/               # 自定义工具类
│       ├── alipay_helper.py     # 支付宝工具
│       ├── content_censor_helper.py # 内容审核
│       ├── cryptography_helper.py # 加密解密
│       ├── email_helper.py      # 邮件工具
│       ├── excel_helper.py      # Excel处理
│       ├── file_helper.py       # 文件处理
│       ├── queue_up_helper.py   # 排队系统
│       ├── redis_helper.py      # Redis工具
│       ├── safe_helper.py       # 安全工具
│       ├── seven_helper.py      # 七维通用工具
│       ├── sms_helper.py        # 短信工具
│       ├── tiktok_helper.py     # 抖音工具
│       ├── wechat_helper.py     # 微信工具
│       └── locales/             # 国际化
│           ├── translation_helper.py # 翻译工具
│           └── zh_EN.json       # 英文翻译文件
├── models/                      # 数据模型层
│   ├── db_models/               # 数据库表模型
│   │   ├── act/                 # 活动相关表
│   │   ├── asset/               # 资产相关表
│   │   ├── cms/                 # CMS内容表
│   │   ├── pay/                 # 支付相关表
│   │   ├── prize/               # 奖品订单表
│   │   ├── stat/                # 统计报表表
│   │   ├── task/                # 任务相关表
│   │   └── user/                # 用户相关表
│   ├── console_models/          # 控制台业务模型
│   │   ├── asset_console_model.py   # 资产控制台
│   │   ├── erp_console_model.py     # ERP控制台
│   │   ├── stat_console_model.py    # 统计控制台
│   │   ├── task_console_model.py    # 任务控制台
│   │   └── timing_work_model.py     # 定时作业
│   ├── cache_model.py           # 缓存模型基类
│   ├── enum.py                  # 枚举定义
│   ├── frame_base_model.py      # 框架业务基类
│   └── *_base_model.py          # 各业务基类
├── locales/                     # 国际化翻译文件
└── route.py                     # 路由注册
```

---

## 5. 安装与初始化

### 5.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 .
```

### 5.2 Handler初始化必须导入

```python
from seven_cloudapp_frame.libs.common.frame_tornado import *
from seven_framework.web_tornado.monitor import MonitorHandler
```

### 5.3 路由注册（自动）

```python
from seven_cloudapp_frame.route import seven_cloudapp_frame_route

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

### 5.4 作业服务初始化

```python
from seven_cloudapp_frame.libs.common.frame_console import *
```

---

## 6. 配置管理

### 6.1 配置系统概述

框架使用两套配置系统：
1. **框架基础配置** (`seven_framework.config`) - 通过 `config.get_value()` 读取
2. **项目共享配置** (`share_config`) - 通过 `share_config.get_value()` 读取

**配置读取优先级**：
`share_config.get_value()` 内部会先调用 `config.get_value()`，如果 `config` 中没有该配置项，才会从 `share_config` 中读取。建议统一使用 `share_config.get_value()` 来读取配置。

### 6.2 配置加载方式

#### 本地配置文件

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

#### Nacos配置中心

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

### 6.3 基础应用配置

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `app_id` | string | - | 应用标识，小程序唯一ID |
| `app_key` | string | - | 应用Key（淘宝/京东平台） |
| `app_secret` | string | - | 应用密钥 |
| `project_name` | string | "" | 项目名称，用于Redis key隔离 |
| `plat_type` | int | 1 | 平台类型：1-淘宝 2-微信 3-京东 4-Web |
| `client_template_id` | string/list | - | 客户端模板ID |
| `is_app_relation` | bool | False | 是否开启应用关联（仅对淘宝平台生效） |
| `is_saas` | bool | False | 是否SaaS模式，主要用于微信小程序 |

### 6.4 加密安全配置

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `encrypt_key` | string | "r8C1JpyAXxrFV26V" | AES加密密钥 |
| `client_encrypt_type` | int | 0 | 客户端加密类型：0-无 1-AES |
| `server_encrypt_type` | int | 0 | 服务端加密类型：0-无 1-AES |
| `encrypt_limit_time` | int | 10 | 加密请求超时时间（秒） |

> **重要**：正式环境必须设置 `client_encrypt_type=1` 开启加密

### 6.5 安全控制配置 (safe_config)

| 子配置Key | 类型 | 默认值 | 说明 |
|-----------|------|--------|------|
| `is_check_referer` | bool | False | 是否检查Referer(用于微信小程序) |
| `is_current_control` | bool | False | 是否开启流量控制 |
| `current_limit_count` | int | 100000 | 每分钟请求限制次数（全局） |
| `current_limit_user_count` | int | 500 | 用户每分钟请求限制次数 |
| `flow_limit_api_count` | int | 1000 | API流量每秒限制次数 |
| `is_authenticat_app_id` | bool | True | 是否校验app_id一致性 |
| `sensitive_encrypt_key` | string | - | 敏感数据加密密钥 |

### 6.6 数据库配置

#### 基础数据库配置

| 配置Key | 类型 | 说明 |
|---------|------|------|
| `db_cloudapp` | dict | 主数据库配置 |
| `sub_table_config` | dict | 分表配置 |

#### 业务模块数据库配置

| 配置Key | 说明 | 使用模块 |
|---------|------|----------|
| `db_asset` / `redis_asset` | 资产数据库/Redis | asset_log_model等 |
| `db_order` / `redis_order` | 订单数据库/Redis | prize_order_model等 |
| `db_task` / `redis_task` | 任务数据库/Redis | task_info_model等 |
| `db_stat` / `redis_stat` | 统计数据库/Redis | stat_log_model等 |
| `db_user` / `redis_user` | 用户数据库/Redis | user_info_model等 |
| `db_cms` / `redis_cms` | CMS数据库/Redis | cms_info_model等 |

**配置示例**：

```json
{
    "db_asset": {
        "host": "127.0.0.1",
        "port": 3306,
        "user": "root",
        "password": "password",
        "db": "cloudapp_asset",
        "charset": "utf8mb4"
    },
    "redis_asset": {
        "host": "127.0.0.1",
        "port": 6379,
        "password": "",
        "db": 3,
        "is_cluster": false
    }
}
```

### 6.7 Redis配置

| 配置Key | 类型 | 说明 |
|---------|------|------|
| `redis` | dict | 基础Redis配置 |
| `redis_safe` | dict | 安全控制Redis配置 |
| `redis_queueup` | dict | 排队系统Redis配置 |
| `redis_cache` | dict | 缓存专用Redis配置 |
| `platform_redis` | dict | 中台Redis配置 |

### 6.8 缓存配置

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `is_redis_cache` | bool | True | 是否启用Redis缓存 |
| `cache_limit_size` | int | 512 | 缓存值大小限制（KB） |
| `log_redis_cache` | bool | True | 是否记录Redis缓存日志 |
| `dependency_cache_expire` | int | 86400 | 依赖键缓存过期时间（秒） |
| `is_cache_empty` | bool | False | 是否缓存空值 |
| `cache_expire` | int | 0 | 全局缓存过期时间（秒） |

### 6.9 支付配置

#### 微信支付配置 (wechat_pay)

| 配置Key | 说明 |
|---------|------|
| `app_id` | 微信小程序AppID |
| `mch_id` | 商户号 |
| `api_key` | API密钥 |
| `serial_no` | 证书序列号 |
| `certificate_url` | 证书URL |
| `private_key_url` | 私钥URL |
| `pay_notify_url` | 支付回调URL |
| `public_key_id` | 公钥ID(v3支付) |
| `public_key_url` | 公钥URL/秘钥(v3支付) |

#### 抖音支付配置 (tiktok_pay)

| 配置Key | 说明 |
|---------|------|
| `app_id` | 抖音小程序AppID |
| `merchant_id` | 商户号 |
| `salt` | 加密盐值 |
| `token` | 接口调用token |
| `pay_notify_url` | 支付回调URL |

### 6.10 其他配置

#### 对象存储配置

| 配置Key | 说明 |
|---------|------|
| `oss_config` | 阿里云OSS配置 |
| `cos_config` | 腾讯云COS配置 |
| `bos_config` | 百度云BOS配置 |

#### 内容审核配置

| 配置Key | 说明 |
|---------|------|
| `censor_bos_config` | 百度云内容审核配置 |
| `censor_cos_config` | 腾讯云内容审核配置 |

#### 排队系统配置

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `queue_is_log` | bool | False | 是否记录排队日志 |
| `queue_confirm_time` | int | 8 | 排队确认时间（秒） |
| `queue_operate_time` | int | 300 | 排队操作时间（秒） |
| `queue_up_query_gear` | list | - | 排队查询档位配置 |

#### 国际化翻译配置 (translate_config)

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `locales_dir` | string | - | 翻译文件目录路径 |
| `default_locale` | string | zh_CN | 默认语言环境 |

#### 用户系统配置 (user_config)

| 子配置Key | 类型 | 默认值 | 说明 |
|-----------|------|--------|------|
| `user_system_ver` | int | 1 | 用户系统版本：1-基础版 2-增强版，性能更高，用于高并发项目 |

#### HTTP响应配置 (reponse_config)

| 子配置Key | 类型 | 默认值 | 说明 |
|-----------|------|--------|------|
| `return_log_id` | bool | false | 请求标识，便于排查问题，联调的时候前端告知，直接在日志系统通过log_id查询，测试环境默认开启，生产环境默认关闭。 |

#### 日志与调试配置

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `log_plain` | bool | True | 是否记录明文日志 |
| `default_error_message` | string | "系统异常" | 默认错误提示 |
| `allow_origin_list` | list | - | 允许跨域来源列表，用于后台项目调用 | 

### 6.11 完整配置文件示例

```json
{
    "project_name": "my_cloudapp",
    "app_id": "wx1234567890abcdef",
    "app_secret": "your_app_secret",
    "plat_type": 2,

    "safe_config": {
        "is_current_control": true,
        "current_limit_count": 100000,
        "is_authenticat_app_id": true,
        "sensitive_encrypt_key": "your_key"
    },

    "redis": {
        "host": "127.0.0.1",
        "port": 6379,
        "password": "",
        "db": 0
    },

    "db_cloudapp": {
        "host": "127.0.0.1",
        "port": 3306,
        "user": "root",
        "password": "password",
        "db": "cloudapp",
        "charset": "utf8mb4"
    },

    "wechat_pay": {
        "app_id": "wx1234567890abcdef",
        "mch_id": "1234567890",
        "api_key": "your_api_key",
        "pay_notify_url": "https://your-domain.com/pay/notify"
    },

    "client_encrypt_type": 1,
    "log_plain": true
}
```

---

## 7. Handler 处理器

### 7.1 Handler 继承体系

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

### 7.2 核心 Handler 基类

#### ClientBaseHandler

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

#### FrameBaseHandler

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

### 7.3 路由命名规范

| 接口类型 | URL 前缀 | 示例 |
|----------|----------|------|
| 小程序端 (C端) | `/client/` | `/client/login` |
| 后台管理 (B端) | `/server/` | `/server/user_list` |

### 7.4 过滤器 (Filter)

#### filter_base.py

提供请求过滤装饰器：

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

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

---

## 8. 数据模型

### 8.1 模型继承体系

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

### 8.2 CacheModel 缓存模型

- **功能**: MySQL数据自动同步到Redis缓存
- **特性**:
  - 查询结果自动缓存
  - 更新操作自动清除缓存
  - 支持依赖缓存（dependency_cache）
  - 支持空值缓存（is_cache_empty）

### 8.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 | 资产业务逻辑 |

### 8.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)
```

### 8.5 常用查询方法

```python
# 查询单条（带缓存）
model.get_cache_entity(where="id=%s", params=[1])
model.get_cache_entity_by_id(primary_key_id=1)

# 查询列表（带缓存）
model.get_cache_list(where="status=%s", params=[1])

# 分页查询（带缓存）
model.get_cache_page_list(
    field="*", 
    page_index=0, 
    page_size=20,
    page_count_mode='next'  # C端必须用next模式
)

# 查询数量（带缓存）
model.get_cache_total(where="status=%s", params=[1])
```

**分页模式**：
- C端接口：`page_count_mode='next'`（游标分页）
- B端接口：可使用 `page_count_mode='total'`（总数分页）

### 8.6 数据库查询优化

#### 参数类型一致（重要）

- 参数的数据类型必须和数据库一致
- 数据库字段为整数，查询参数必须加 `int()`
- 数据库字段为字符串，查询参数必须加 `str()`
- 否则容易导致索引失效

#### 索引使用规范

- 避免在索引字段上使用函数（如 `DATE(create_date)`）
- 避免前导模糊查询（如 `LIKE '%keyword'`）
- IN 子句元素数量不宜过多（建议不超过50个）

### 8.7 读写分离

**使用场景**：数据及时性要求不高的场景，如后台查询、导出类接口

**使用方法**：

```python
# is_auto = True 开启读库
read_model = MyModel(is_auto=True)
```

**连接串配置**：

```json
{
    "db": "数据库名",
    "host": "主库ip地址",
    "port": "端口",
    "user": "账号",
    "passwd": "密码",
    "charset": "utf8",
    "auto_host": "读库或自动读写代理ip地址"
}
```

---

## 9. 业务逻辑层

### 9.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 | 定时作业基类 |

### 9.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"
        """
```

### 9.3 定时作业基类

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

---

## 10. 核心功能规范

### 10.1 代码规范

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

### 10.2 注释规范

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

### 10.3 请求参数规范

#### Post请求规范

- Content-Type 必须为 `application/json`
- 参数需序列化为 JSON 字符串

#### 参数校验装饰器

```python
@filter_check_params("参数名1,参数名2,参数名3")
def post_async(self):
    pass
```

#### 列表查询条数限制

```python
page_size = self.get_param_int(
    "page_size", 
    default=20, 
    range_list=[1,200],  # 必须在1-200之间
    is_positive=True
)
```

#### 参数获取方法

**字符串参数**：
```python
param = self.get_param(
    param_name='param_1',
    default='',
    strip=True,
    max_length=100
)
```

**整数参数**：
```python
param = self.get_param_int(
    param_name='param_1',
    default=0,
    contain_list=[1,2,3],
    range_list=[1,10],
    is_positive=True
)
```

**金额参数（Decimal）**：
```python
param = self.get_param_decimal('param_1', default=0)
```

**日期时间参数**：
```python
param = self.get_param_datetime(
    'param_1',
    fmt='%Y-%m-%d %H:%M:%S'
)
```

### 10.4 数据安全规范

#### 接口加解密架构

```
客户端请求                                    服务端处理
    │                                              │
    ▼                                              ▼
┌──────────┐                               ┌──────────────┐
│ 明文数据  │                               │ 接收加密数据  │
└────┬─────┘                               └──────┬───────┘
     │                                            │
     ▼                                            ▼
┌──────────┐                               ┌──────────────┐
│ AES加密   │─────── 网络传输(加密数据) ─────▶│ AES解密       │
│ (CBC模式)│                               │ (CBC模式)     │
└────┬─────┘                               └──────┬───────┘
     │                                            │
     ▼                                            ▼
┌──────────┐                               ┌──────────────┐
│ Base64   │                               │ 明文数据      │
│ 编码     │                               │ (业务处理)    │
└──────────┘                               └──────┬───────┘
                                                  │
                                                  ▼
                                           ┌──────────────┐
                                           │ 响应数据加密  │
                                           │ AES+Base64   │
                                           └──────┬───────┘
                                                  │
                                                  ▼
                                           ┌──────────────┐
                                           │ 返回加密响应  │
                                           └──────────────┘
```

#### 加密规范

- **加密方式**: AES-128-CBC、无填充、UTF-8、输出 Base64
- **正式环境**: 必须开启加密模式，`client_encrypt_type`为客户端加密类型 0-无，1-aes加密
- **敏感字段**: 必须使用框架提供的加密功能，使用 `FrameBaseModel` 的 `sensitive_encrypt` 和 `sensitive_decrypt` 方法

#### 加密流程说明

1. **请求加密**: 客户端使用 AES-128-CBC 算法加密请求数据，输出 Base64 格式
2. **数据传输**: 网络传输的是加密后的 Base64 字符串，确保数据安全
3. **服务端解密**: 服务端接收到数据后，使用相同密钥进行 AES 解密
4. **业务处理**: 服务端处理明文数据
5. **响应加密**: 服务端将响应数据加密后返回给客户端
6. **客户端解密**: 客户端解密响应数据，获取明文结果

#### 敏感字段加密示例

```python
# 加密
encrypted = model.sensitive_encrypt("敏感数据")
# 解密
decrypted = model.sensitive_decrypt(encrypted)
```

### 10.5 限流规范

#### 限流配置

```json
{
    "safe_config": {
        "is_current_control": true,
        "current_limit_count": 100000,
        "flow_limit_api_count": 1000,
        "current_limit_user_count": 500
    }
}
```

#### Handler装饰器使用

```python
@filter_check_current_limit()  # 应用级限流
@filter_check_flow_limit()     # 接口级限流
def post_async(self):
    pass
```

### 10.6 用户系统规范

#### 核心概念

- `user_id` 与 `open_id` 一一对应，跨活动不变
- `user_id` 对应 `user_account_tb` 表的主键 `id`

#### 必须使用框架提供的Handler

- `LoginHandler` - 用户登录
- `UpdateUserInfoHandler` - 更新用户信息

#### 高并发登录配置（V2）

```python
{"user_config": {"user_system_ver": 2}}
```

### 10.7 资产系统规范

#### 资产核心特性

- 每条数据都有资产检验码
- 正式环境禁止直接修改数据库
- 测试环境可配置 `is_check_asset` 关闭校验

#### 资产更新示例

```python
from seven_cloudapp_frame.models.asset_base_model import *

asset_base_model = AssetBaseModel(context=self)
invoke_result_data = asset_base_model.update_user_asset(
    app_id=app_id,
    user_id=user_id,
    asset_type=int(asset_object["asset_type"]),
    asset_value=int(asset_object["asset_value"]),
    source_type=3,
    log_title="手动配置",
    handler_name=self.__class__.__name__,
    request_code=self.request_code,
)
if invoke_result_data.success == False:
    return self.response_json_error(
        invoke_result_data.error_code, 
        invoke_result_data.error_message
    )
```

### 10.8 任务系统规范

- **必须使用**: `get_client_task_list_v2` 接口（新标准）
- 支持自动领取和手动领取两种模式

### 10.9 核心功能 - 业务执行事件

#### business_process_executing 功能

- 自动校验活动信息、模块信息、用户信息
- 支持同一用户连续请求限制
- 支持流量削峰
- 支持分布式锁

#### 使用场景

抽奖、兑换、领取奖励等核心操作，安全系数要求高的场景

#### 代码示例

```python
try:
    frame_base_model = FrameBaseModel(context=self)
    invoke_result_data = frame_base_model.business_process_executing(
        self, app_id, act_id, module_id, user_id,
        login_token, self.__class__.__name__,
        request_code=self.request_code,
        check_new_user=False,
        check_user_nick=True,
        acquire_lock_name="",
        request_limit_num=0,
        execute_lock_expire=90
    )
    if invoke_result_data.success == False:
        return invoke_result_data

    # 执行业务逻辑...
finally:
    frame_base_model.business_process_executed()
```

### 10.10 作业规范

#### 必须导入

```python
from seven_cloudapp_frame.libs.common.frame_console import *
```

#### 核心作业必须使用心跳检测

```python
heart_beat_monitor("具体作业名")
threading.Thread(target=heart_beat_check).start()
```

#### 代码必须包裹try except

```python
try:
    time.sleep(0.1)  # 必须至少0.1秒休眠
    # 作业代码
except Exception as e:
    print(f"作业异常: {e}")
    # 发送报警通知、记录日志
```

### 10.11 条件拼接

```python
from seven_cloudapp_frame.models.seven_model import ConditionWhere

# 查询条件
condition_where_query = ConditionWhere()
condition_where_query.add_condition("status", 1)
condition_where_query.add_condition_in("id", true, [1, 2, 3])
act_info_model.get_dict(
    condition_where_query.to_string(), 
    params=condition_where_query.params
)

# 更新条件
condition_where_update = ConditionWhere()
condition_where_update.add_condition("status", 1)
condition_where_update.add_condition("modify_time", SevenHelper.get_now_datetime())
act_info_model.update_table(
    condition_where_update.to_string(','), 
    where='id=%s', 
    params=[1]
)
```

---

## 11. 第三方接口

### 11.1 原则

尽量使用封装好的类，避免直接调用三方接口

### 11.2 淘宝/天猫接口

```python
from seven_cloudapp_frame.models.top_base_model import TopBaseModel

class MyTopModel(TopBaseModel):
    pass
```

### 11.3 抖店接口

```python
from seven_cloudapp_frame.models.third.shakeshop_base_model import ShakeShopBaseModel

class MyShakeModel(ShakeShopBaseModel):
    pass
```

### 11.4 京东接口

```python
from seven_cloudapp_frame.models.third.jd_base_model import JdBaseModel

class MyJdModel(JdBaseModel):
    pass
```

### 11.5 微信小程序接口

```python
from seven_cloudapp_frame.libs.customize.wechat_helper import WeChatHelper

WeChatHelper.get_web_authorize_url(redirect_uri)
WeChatHelper.decrypt_data(encrypted_data, session_key, iv)
WeChatHelper.get_qrcode(access_token, scene, page)
```

### 11.6 微信支付接口

```python
from seven_cloudapp_frame.libs.customize.wechat_helper import WeChatPayV3Request

pay_request = WeChatPayV3Request(app_id, mchid, private_key, serial_no)
pay_request.create_order(body, out_trade_no, total_fee, notify_url, openid)
```

### 11.7 抖音支付接口

```python
from seven_cloudapp_frame.libs.customize.tiktok_helper import TikTokPayRequest

pay_request = TikTokPayRequest(app_id, salt, token)
pay_request.create_order(out_order_no, total_amount, subject, body, notify_url)
```

### 11.8 支付宝接口

```python
from seven_cloudapp_frame.libs.customize.alipay_helper import AliPayRequest

pay_request = AliPayRequest(app_id, private_key, public_key)
pay_request.create_order(out_trade_no, total_amount, subject, notify_url)
```

### 11.9 文件存储

#### 阿里云 OSS

```python
from seven_cloudapp_frame.libs.customize.file_helper import OSSHelper

oss = OSSHelper(access_key, secret_key, bucket, endpoint)
oss.upload_file(file_path, object_name)
```

#### 腾讯云 COS

```python
from seven_cloudapp_frame.libs.customize.file_helper import COSHelper

cos = COSHelper(secret_id, secret_key, region, bucket)
cos.upload_file(file_path, object_name)
```

#### 百度云 BOS

```python
from seven_cloudapp_frame.libs.customize.file_helper import BOSHelper

bos = BOSHelper(access_key, secret_key, endpoint, bucket)
bos.upload_file(file_path, object_name)
```

### 11.10 短信服务

| 厂商 | 类名 |
|------|------|
| 百度智能云 | `BceSmsHelper` |
| 阿里云 | `AliSmsHelper` |
| 腾讯云 | `TencentSmsHelper` |

```python
from seven_cloudapp_frame.libs.customize.sms_helper import AliSmsHelper

sms = AliSmsHelper(access_key, secret_key, sign_name)
sms.send_sms(phone, template_code, params)
```

### 11.11 内容审核

| 厂商 | 类名 |
|------|------|
| 百度云 | `BOSCensorHelper` |
| 腾讯云 | `COSCensorHelper` |

```python
censor = BOSCensorHelper(access_key, secret_key)
result = censor.image_censor(img_list=["url1", "url2"])
result = censor.text_censor(text="待审核文本")
```

---

## 12. 缓存系统

### 12.1 缓存架构

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

### 12.2 缓存前缀

前缀：`data_cache`

### 12.3 缓存键结构

```
# 依赖键
data_cache[:cache_sub_table]:dependency_[dependency_key]

# 缓存键
data_cache[:cache_sub_table]:[md5(dependency_key+cache_key)]
```

### 12.4 缓存值结构

```json
{
  "dep_ver": "依赖键版本号",
  "data": "缓存数据",
  "savetime": "保存时间"
}
```

### 12.5 缓存使用建议

- 批量删除依赖键，减少 Redis 请求
- 数据大的表禁止用默认依赖键
- 大表自定义依赖键提高缓存使用率
- 数据及时性要求不高的场景使用缓存

### 12.6 缓存清理方法

```python
# 删除缓存依赖键
model.delete_dependency_key(dependency_key="my_key")

# 批量删除缓存依赖键
model.delete_dependency_keys(dependency_keys=["key1", "key2"])

# 根据前缀删除
model.delete_dependency_keys_by_pattern(pattern="my_pattern")
```

### 12.7 注意事项

- 依赖键缓存时间默认24小时，普通缓存默认30分钟
- 查询结果是None和0不会被缓存，除非配置文件设置`is_cache_empty=True`
- 支持Redis集群模式
- 支持缓存预热，批量将数据预加载到缓存
- 缓存键使用MD5加密，确保唯一性
- 支持延迟删除和重试机制，提高缓存操作的可靠性

---

## 13. 排队系统

### 13.1 排队系统架构

```
用户请求加入排队
        │
        ▼
┌───────────────┐
│  检查队列状态  │
└───────────────┘
        │
   ┌────┴────┐
   ▼         ▼
┌──────┐  ┌──────┐
│可加入 │  │已满  │
└──┬───┘  └──┬───┘
   │         │
   ▼         ▼
┌──────┐  ┌──────┐
│加入队列│  │返回排队│
│       │  │人数过多│
└──┬───┘  └──────┘
   │
   ▼
┌───────────────┐
│  等待排队排到  │
└───────────────┘
        │
        ▼
┌───────────────┐
│  执行业务操作  │
└───────────────┘
        │
   ┌────┴────┐
   ▼         ▼
┌──────┐  ┌──────┐
│完成  │  │退出  │
└──────┘  └──────┘
```

### 13.2 核心功能

- **加入排队**: 用户加入指定队列等待
- **排队查询**: 查询当前排队位置和预计等待时间
- **排队排到**: 当轮到用户时，通知用户进行业务操作
- **退出排队**: 用户主动退出或超时自动退出
- **批量管理**: 支持批量查询、批量踢出过期用户

### 13.3 配置说明

| 配置Key | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `queue_is_log` | bool | False | 是否记录排队日志 |
| `queue_confirm_time` | int | 8 | 排队确认时间（秒） |
| `queue_operate_time` | int | 300 | 排队操作时间（秒） |
| `queue_operate_total_time` | int | 0 | 排队总操作时间 |
| `queue_up_query_gear` | list | - | 排队查询档位配置 |

**queue_up_query_gear 配置示例**:

```json
{
  "queue_up_query_gear": [
    {"start": 1, "end": 3, "rate": 2},
    {"start": 3, "end": 6, "rate": 3},
    {"start": 7, "end": 100, "rate": 5}
  ]
}
```

### 13.4 使用示例

```python
from seven_cloudapp_frame.libs.customize.queue_up_helper import QueueUpHelper

# 查询用户排队情况
result = QueueUpHelper.query(app_id, queue_name, user_id)

# 查询用户排队数量
num = QueueUpHelper.get_user_queue_num(app_id, user_id)

# 查询用户正在办理中的队列
result = QueueUpHelper.get_process_user_queue(app_id, user_id)

# 退出排队
result = QueueUpHelper.pop(app_id, queue_name, user_id)

# 指定用户退出参与的队列
QueueUpHelper.pop_by_user_id(app_id, user_id, progress_status=1)

# 批量查询用户排队情况(只包含已排队)
result = QueueUpHelper.muti_user_query(app_id, user_id)

# 批量查询用户排队情况(包含已排队和未排队)
result = QueueUpHelper.muti_queue_query(app_id, queue_name_list, user_id)

# 查询指定队列的所有用户信息
result = QueueUpHelper.query_list(app_id, queue_name, user_id, limit=10)

# 批量踢掉过期用户
QueueUpHelper.muti_expire_user_pop(app_id)

# 更新可操作时间
QueueUpHelper.update_time(app_id, queue_name, user_id, operate_time=300)
```

### 13.5 注意事项

- 排队系统基于Redis实现，默认走redis,如果要切可以配置redis_queueup
- 每个队列有最大人数限制，超过限制将无法加入
- 排队排到后需要在规定时间内确认，否则自动退出
- 支持多档位查询频率控制，减少服务器压力

---

## 14. ActionHelper 执行助手

ActionHelper 提供了方法执行的异常重试机制，支持无限循环执行和限制次数执行两种模式。

### 14.1 架构说明

```
┌─────────────────────────────────────────────────────────┐
│                    ActionHelper                         │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ run_action   │  │ run_func     │  │ api_func     │  │
│  │ _while       │  │ _while       │  │              │  │
│  │ (无限循环)    │  │ (无限循环)    │  │ (API专用)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│  ┌──────────────┐  ┌──────────────┐                     │
│  │ run_action   │  │ run_func     │                     │
│  │ (限制次数)    │  │ (限制次数)    │                     │
│  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
              ┌──────────────────────┐
              │   异常重试机制        │
              │  - 可配置重试次数     │
              │  - 可配置间隔时间     │
              │  - 支持日志记录       │
              │  - 批量方法执行       │
              └──────────────────────┘
```

### 14.2 方法说明

| 方法名 | 返回值 | 执行模式 | 适用场景 |
|--------|--------|----------|----------|
| `run_action_while` | None | 无限循环 | 后台任务、守护进程 |
| `run_func_while` | 结果数据 | 无限循环 | 需要返回值的循环任务 |
| `run_action` | bool | 限制次数 | 普通操作重试 |
| `run_func` | 结果数据 | 限制次数 | 需要返回值的普通操作 |
| `api_func` | InvokeResultData/bool | 限制次数 | 外部API调用 |

### 14.3 通用参数说明

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `action`/`func` | callable/list | 必填 | 要执行的方法或方法列表 |
| `sleep_time` | float | 0.5 | 异常后的等待时间（秒） |
| `retry_run_count` | int | 10 | 最大重试次数（限制次数模式） |
| `is_log` | bool | False | 是否记录错误日志 |
| `error_count_log` | int | 10/100 | 每多少次错误记录一次日志 |
| `title` | str | "" | 错误日志标题 |

### 14.4 基础使用示例

#### 单个方法执行

```python
from seven_cloudapp_frame.libs.customize.action_helper import ActionHelper

# 限制次数执行（最多重试10次）
result = ActionHelper.run_func(
    func=lambda: user_model.get_by_id(user_id),
    sleep_time=0.5,
    retry_run_count=10,
    is_log=True,
    title="获取用户信息"
)
```

#### 批量方法执行

```python
# 批量执行多个方法（事务场景）
results = ActionHelper.run_func(
    func=[
        lambda: order_model.add_entity(order),
        lambda: inventory_model.decrease(goods_id, quantity),
        lambda: log_model.add_operation_log("下单", user_id)
    ],
    sleep_time=0.5,
    retry_run_count=5,
    title="订单创建"
)
```

#### 无限循环执行

```python
# 无限循环执行（直到成功）
ActionHelper.run_action_while(
    action=lambda: message_queue.process_pending_messages(),
    sleep_time=1.0,
    is_log=True,
    error_count_log=100,
    title="消息处理"
)
```

### 14.5 API调用专用

`api_func` 专门用于调用外部API，支持对 `InvokeResultData` 和 `bool` 类型的结果进行智能判断：

```python
from seven_cloudapp_frame.libs.customize.action_helper import ActionHelper

# 调用外部API（自动处理InvokeResultData）
def query_member_point():
    return third_party_api.create_order(order_data)

result = ActionHelper.api_func(
    func=query_member_point,
    sleep_time=1,
    retry_run_count=3,
    is_log=True,
    title="创建第三方订单",
    retry_messages=["NETWORK_ERROR", "TIMEOUT"]  # 仅对这些错误码重试
)

# 返回 InvokeResultData 对象
if result.success:
    print(f"订单创建成功: {result.data}")
else:
    print(f"订单创建失败: {result.error_code}")
```

**api_func 特性：**
- 自动识别 `InvokeResultData` 类型的返回结果
- 根据 `success` 字段判断是否成功
- 支持配置 `retry_messages` 指定可重试的错误码
- 对于不可重试的错误会立即返回，避免无效重试

### 14.6 注意事项

1. **方法参数**: 使用 `lambda` 或 `functools.partial` 包装带参数的方法
2. **异常处理**: 所有方法内部异常都会被捕获并触发重试
3. **日志记录**: 建议生产环境开启 `is_log`，便于排查问题
4. **重试次数**: 根据业务场景合理设置，避免无限重试导致资源浪费
5. **API专用**: 调用外部接口优先使用 `api_func`，支持更智能的错误处理

---

## 15. 心跳监控

心跳监控用于实时监控定时作业的运行状态，及时发现作业异常停止的情况。

### 15.1 架构说明

```
┌─────────────────────────────────────────────────────────────┐
│                      心跳监控系统                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────┐      Redis      ┌─────────────┐          │
│   │  作业进程A   │ ───────────────→│  心跳记录   │          │
│   │ (定时上报)   │   heart_beat    │  Key-Value  │          │
│   └─────────────┘   _monitor()    └──────┬──────┘          │
│                                           │                 │
│   ┌─────────────┐                         │                 │
│   │  作业进程B   │ ────────────────────────┤                 │
│   │ (定时上报)   │   heart_beat_monitor()  │                 │
│   └─────────────┘                         │                 │
│                                           │                 │
│   ┌─────────────┐      Redis      ┌───────▼───────┐        │
│   │  检测进程    │ ←───────────────│ heart_beat    │        │
│   │ (独立运行)   │   scan/读取     │ _check()      │        │
│   │             │                 │ 每分钟检测    │        │
│   │ 异常告警    │ ───────────────→│ 超时预警      │        │
│   │ (日志/微信)  │                 │               │        │
│   └─────────────┘                 └───────────────┘        │
│                                                             │
│   Key格式: heart_beat_monitor:{work_name}                   │
│   Value: {"process_date": "时间", "check_time": 分钟, "data": {}} │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 15.2 核心方法

| 方法名 | 作用 | 调用位置 | 说明 |
|--------|------|----------|------|
| `heart_beat_monitor` | 上报心跳 | 作业循环体内 | 定期上报作业运行状态 |
| `heart_beat_delete` | 删除心跳 | 作业结束/退出时 | 清理心跳记录，避免误报 |
| `heart_beat_check` | 检测心跳 | 独立检测进程 | 监控所有作业心跳状态 |

### 15.3 方法详解

#### heart_beat_monitor - 心跳上报

```python
from seven_cloudapp_frame.libs.common.frame_console import heart_beat_monitor

# 在作业循环中定期调用
heart_beat_monitor(
    work_name="order_sync_job",      # 作业名称（唯一标识）
    interval_time=30,                 # 上报间隔（秒），默认30
    data={"count": 100, "status": "running"},  # 附加数据
    check_time=5,                     # 预警阈值（分钟），默认60
    redis_config_dict=None            # 自定义Redis配置
)
```

**参数说明：**

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `work_name` | str | 必填 | 作业唯一名称 |
| `interval_time` | int | 30 | 上报间隔（秒），控制写入Redis频率 |
| `data` | dict | {} | 附加数据，可记录作业状态信息 |
| `check_time` | int | 60 | 预警阈值（分钟），超过此时间未上报则告警 |
| `redis_config_dict` | dict | None | 自定义Redis配置 |

**上报机制：**
- 本地缓存控制：使用 `work_process_date_dict` 控制实际写入频率
- 默认30秒写入一次Redis，避免频繁写入
- 数据保存30天（30 * 24 * 3600秒）

#### heart_beat_delete - 删除心跳

```python
from seven_cloudapp_frame.libs.common.frame_console import heart_beat_delete

# 作业正常结束时调用
heart_beat_delete(
    work_name="order_sync_job",      # 作业名称
    redis_config_dict=None            # 自定义Redis配置
)
```

**使用场景：**
- 作业正常退出时清理心跳记录
- 避免已停止的作业触发误报
- 同时清理本地缓存和Redis记录

#### heart_beat_check - 心跳检测

```python
from seven_cloudapp_frame.libs.common.frame_console import heart_beat_check
import threading

# 在独立线程中启动检测
threading.Thread(
    target=heart_beat_check,
    kwargs={
        "redis_config_dict": None,     # 自定义Redis配置
        "wx_send_key": "xxxxx"          # 企业微信群机器人key
    },
    daemon=True
).start()
```

**检测机制：**
- 每分钟扫描一次所有心跳记录
- 对比 `process_date` 和当前时间
- 超过 `check_time` 分钟未上报则触发告警
- 支持日志告警和企业微信告警

**告警方式：**
- `wx_send_key` 为空：仅记录错误日志
- `wx_send_key` 有值：发送企业微信消息

### 15.4 配置说明

在 `share_config.json` 中配置：

```json
{
  "heart_beat_name": "prod",           // 命名空间，用于区分环境
  "is_heart_beat_monitor": true        // 是否开启心跳监控，默认true
}
```

**命名空间作用：**
- 不同环境（prod/dev/test）使用不同前缀
- Key格式变为：`heart_beat_monitor:{heart_beat_name}:{work_name}`
- 避免不同环境的心跳记录冲突

### 15.5 完整使用示例

#### 作业代码示例

```python
from seven_cloudapp_frame.libs.common.frame_console import heart_beat_monitor, heart_beat_delete

def my_background_job():
    work_name = "data_sync_job"
    try:
        while True:
            try:
                # 执行业务逻辑
                process_data()

                # 上报心跳（每30秒实际写入一次）
                heart_beat_monitor(
                    work_name=work_name,
                    interval_time=30,
                    data={"last_sync": TimeHelper.get_now_format_time()},
                    check_time=5  # 5分钟未上报则告警
                )

                time.sleep(0.1)  # 必须包含

            except Exception as ex:
                logger_error.error(f"作业异常:{ex}")
                time.sleep(5)

    finally:
        # 作业退出时清理心跳
        heart_beat_delete(work_name)
```

#### 检测进程示例

```python
from seven_cloudapp_frame.libs.common.frame_console import heart_beat_check
import threading

# 启动心跳检测（通常在服务启动时执行）
def start_heart_beat_monitor():
    threading.Thread(
        target=heart_beat_check,
        kwargs={
            "wx_send_key": "693axxx6-7xxx-4xxx-8xxx-xxxxxxxxxxxx"  # 企业微信key
        },
        daemon=True
    ).start()

# 在服务启动时调用
start_heart_beat_monitor()
```

### 15.6 注意事项

1. **必须调用 delete**: 作业正常退出时必须调用 `heart_beat_delete`，否则会产生误报
2. **独立检测进程**: `heart_beat_check` 需要在独立线程/进程中运行
3. **合理设置阈值**: `check_time` 根据作业执行频率设置，避免过于敏感或迟钝
4. **命名空间隔离**: 多环境部署时务必配置 `heart_beat_name`
5. **上报频率控制**: `interval_time` 控制本地缓存，实际写入频率由框架控制
6. **异常处理**: 作业内部异常不应影响心跳上报，需单独捕获

---

## 16. 开发规范

### 16.1 模型开发规范

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

### 16.2 国际化规范

- 错误消息使用 `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.3 红线规范（必须遵守）

1. ✅ Handler必须继承 `ClientBaseHandler` 或 `FrameBaseHandler`
2. ✅ 请求参数必须使用 `get_param*` 方法获取
3. ✅ 列表查询必须限制 `page_size` 在 1-200 之间
4. ✅ 核心操作必须使用 `business_process_executing`
5. ✅ 数据库查询参数类型必须与字段类型一致
6. ✅ 作业代码必须包裹 try except
7. ✅ 作业必须包含 `time.sleep(0.1)`
8. ✅ 正式环境必须开启加密
9. ✅ 敏感字段必须使用框架加密方法
10. ✅ 资产操作必须使用 `AssetBaseModel`

---

## 17. 项目运行方式

### 17.1 启动服务

```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)
```

### 17.2 启动控制台任务

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

erp_console = ErpConsoleModel()

# 启动订单推送和物流拉取
erp_console.console_erp(
    mod_count=10,
    process_type=2,
    pull_time_range="09:00-22:00",
    push_time_range="09:00-22:00"
)
```

### 17.3 启动定时作业

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

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

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

---

## 18. 部署说明

### 18.1 环境要求

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

### 18.2 数据库配置

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

### 18.3 缓存配置

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

### 18.4 配置中心

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

### 18.5 语言翻译

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

### 18.6 监控与日志

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

---


## 附录：常用模块引用速查

| 功能 | 引用路径 |
|------|----------|
| Handler 基类 | `seven_cloudapp_frame.handlers.frame_base.FrameBaseHandler` |
| 客户端 Handler | `seven_cloudapp_frame.handlers.frame_base.ClientBaseHandler` |
| 模型基类 | `seven_cloudapp_frame.models.frame_base_model.FrameBaseModel` |
| 缓存模型 | `seven_cloudapp_frame.models.cache_model.CacheModel` |
| 全局配置 | `seven_cloudapp_frame.libs.common.share_config` |
| 核心帮助类 | `seven_cloudapp_frame.libs.customize.seven_helper.SevenHelper` |
| Redis 帮助类 | `seven_cloudapp_frame.libs.customize.redis_helper.RedisHelper` |
| 枚举定义 | `seven_cloudapp_frame.models.enum` |
| 条件拼接 | `seven_cloudapp_frame.models.seven_model.ConditionWhere` |
| 文件存储 (OSS) | `seven_cloudapp_frame.libs.customize.file_helper.OSSHelper` |
| 文件存储 (COS) | `seven_cloudapp_frame.libs.customize.file_helper.COSHelper` |
| 文件存储 (BOS) | `seven_cloudapp_frame.libs.customize.file_helper.BOSHelper` |
| 短信 (百度) | `seven_cloudapp_frame.libs.customize.sms_helper.BceSmsHelper` |
| 短信 (阿里) | `seven_cloudapp_frame.libs.customize.sms_helper.AliSmsHelper` |
| 短信 (腾讯) | `seven_cloudapp_frame.libs.customize.sms_helper.TencentSmsHelper` |
| 内容审核 (百度) | `seven_cloudapp_frame.libs.customize.content_censor_helper.BOSCensorHelper` |
| 内容审核 (腾讯) | `seven_cloudapp_frame.libs.customize.content_censor_helper.COSCensorHelper` |
| 物流查询 | `seven_cloudapp_frame.libs.customize.logistics_helper.AliLogisticsHelper` |
| 邮件服务 | `seven_cloudapp_frame.libs.customize.email_helper.EmailHelper` |
| 加密帮助类 | `seven_cloudapp_frame.libs.customize.cryptography_helper.CryptographyHelper` |
| 计数器 | `seven_cloudapp_frame.libs.customize.counter_helper.CounterHelper` |
| Excel 操作 | `seven_cloudapp_frame.libs.customize.excel_helper.ExcelExHelper` |
| 排队系统 | `seven_cloudapp_frame.libs.customize.queue_up_helper.QueueUpHelper` |

---

## 版本信息

- **当前版本**: 1.2.138
- **作者**: 267


