667 lines
20 KiB
Markdown
667 lines
20 KiB
Markdown
# GVS-DSDK API 使用手册
|
||
|
||
> 版本：1.0.0 | 更新日期：2026-06-13
|
||
|
||
## 目录
|
||
|
||
- [1. 概述](#1-概述)
|
||
- [2. 快速开始](#2-快速开始)
|
||
- [3. 包结构](#3-包结构)
|
||
- [4. 用户管理 (UserManager)](#4-用户管理-usermanager)
|
||
- [5. 角色管理 (RoleManager)](#5-角色管理-rolemanager)
|
||
- [6. 商铺管理 (ShopManager)](#6-商铺管理-shopmanager)
|
||
- [7. 职务管理 (PositionManager)](#7-职务管理-positionmanager)
|
||
- [8. 权限验证 (PermissionVerifier)](#8-权限验证-permissionverifier)
|
||
- [9. ELT 认证](#9-elt-认证)
|
||
- [10. 分佣引擎 (CommissionEngine)](#10-分佣引擎-commissionengine)
|
||
- [11. 支付网关 (PaymentManager)](#11-支付网关-paymentmanager)
|
||
- [12. MSYNC 服务间通信](#12-msync-服务间通信)
|
||
- [13. FluentQuery ORM 查询](#13-fluentquery-orm-查询)
|
||
- [14. 数据库路由与建表](#14-数据库路由与建表)
|
||
- [15. 数据模型一览](#15-数据模型一览)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
GVS-DSDK 是 GVS 分布式服务 SDK，提供：
|
||
|
||
- **SAAS 用户管理**：用户、角色、权限、商铺、职务的完整 CRUD 和关联管理
|
||
- **ELT 认证**：Cookie → EphemeralToken → User 的无状态认证体系
|
||
- **分佣引擎**：5 种分账策略 + 预结算 + 邀请链分佣
|
||
- **支付网关**：微信/支付宝/银行卡三渠道适配 + 统一编排
|
||
- **MSYNC 通信**：服务注册/发现/OGM/分布式事务
|
||
- **FluentQuery**：SQLAlchemy 风格的 ORM 查询层
|
||
|
||
全程 PascalCase 命名，从数据库到前端无中间转换层。
|
||
|
||
---
|
||
|
||
## 2. 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
pip install -e /path/to/gvsdsdk
|
||
```
|
||
|
||
### settings.py 配置
|
||
|
||
```python
|
||
INSTALLED_APPS = [
|
||
...
|
||
'gvsdsdk',
|
||
]
|
||
|
||
# 方式一：子服务器连接 SAAS 主库（只读）
|
||
DATABASES = {
|
||
'default': { ... }, # 本地数据库
|
||
'saas': { # SAAS 主库
|
||
'ENGINE': 'django.db.backends.mysql',
|
||
'NAME': 'Users',
|
||
'USER': 'root',
|
||
'PASSWORD': '***',
|
||
'HOST': 'saas-db.gvsds.com',
|
||
'PORT': '3306',
|
||
},
|
||
}
|
||
DATABASE_ROUTERS = ['gvsdsdk.db_router.SAASDatabaseRouter']
|
||
GVSDSDK_SAAS_READ_ONLY = True # 默认 True
|
||
|
||
# 方式二：同源数据库（可读写）
|
||
DATABASES = {
|
||
'default': {
|
||
'ENGINE': 'django.db.backends.mysql',
|
||
'NAME': 'mydb',
|
||
...
|
||
},
|
||
}
|
||
DATABASE_ROUTERS = []
|
||
GVSDSDK_MANAGE_TABLES = True # 允许 Django 管理表
|
||
```
|
||
|
||
### 建表
|
||
|
||
```bash
|
||
# 方式一：Django migrate（需 GVSDSDK_MANAGE_TABLES=True）
|
||
python manage.py makemigrations gvsdsdk
|
||
python manage.py migrate
|
||
|
||
# 方式二：gvsdsdk_init 命令（无需 GVSDSDK_MANAGE_TABLES）
|
||
python manage.py gvsdsdk_init --db default
|
||
python manage.py gvsdsdk_init --db default --dry-run # 仅打印 SQL
|
||
python manage.py gvsdsdk_init --db default --modules auth,commission,payment
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 包结构
|
||
|
||
```
|
||
gvsdsdk/
|
||
├── __init__.py # 统一入口（惰性加载 90+ 符号）
|
||
├── models.py # SAAS 核心数据模型（17 张表）
|
||
├── model_base.py # QModel 元类 + FluentQuery 注入
|
||
├── model_utils.py # UUIDObj
|
||
├── fluent.py # FluentQuery ORM 查询层
|
||
├── db_router.py # SAASDatabaseRouter
|
||
├── apps.py # Django AppConfig
|
||
├── management/
|
||
│ └── commands/
|
||
│ └── gvsdsdk_init.py # 建表命令
|
||
│
|
||
├── auth/ # ELT 用户认证模块
|
||
│ ├── elt_auth.py # ELT 认证后端
|
||
│ ├── cookie.py # Cookie 管理
|
||
│ ├── crypto.py # 密码哈希 + AES-256-GCM
|
||
│ ├── middleware.py # ELTAuthMiddleware + CurrentRoleMiddleware
|
||
│ ├── permissions.py # RBAC/ABAC 权限
|
||
│ └── managers.py # UserManager + RoleManager + ShopManager + PositionManager
|
||
│
|
||
├── msync/ # MSYNC 服务间通信
|
||
│ ├── auth.py # 服务认证签名
|
||
│ ├── registry.py # 服务注册中心
|
||
│ ├── ogm.py # 全局对象映射
|
||
│ ├── Transaction.py # 分布式事务
|
||
│ ├── LocalTx.py # 本地事务
|
||
│ └── client.py # 服务客户端
|
||
│
|
||
├── commission/ # 分佣引擎
|
||
│ ├── models.py # 6 张数据模型
|
||
│ ├── manager.py # CommissionEngine 编排器
|
||
│ └── strategies/
|
||
│ └── engine.py # 5 种策略 + 工厂
|
||
│
|
||
└── payment/ # 支付网关
|
||
├── models.py # 2 张数据模型
|
||
├── manager.py # PaymentManager 编排器
|
||
└── gateways/
|
||
├── base.py # 抽象网关 + 数据类
|
||
├── registry.py # GatewayRegistry + payment_registry
|
||
├── wechat.py # 微信支付适配器
|
||
├── alipay.py # 支付宝适配器
|
||
└── bank.py # 银行卡适配器
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 用户管理 (UserManager)
|
||
|
||
```python
|
||
from gvsdsdk.models import User
|
||
|
||
# 创建用户
|
||
user = User.objects.create_user(username='alice', password='xxx', email='a@b.com')
|
||
user = User.objects.create_superuser(username='admin', password='xxx')
|
||
|
||
# 密码
|
||
user.SetPassword('new_pass') # bcrypt 哈希
|
||
user.CheckPassword('input') # 验证密码
|
||
|
||
# 查询
|
||
user = User.objects.get(UserName='alice')
|
||
users = User.objects.filter(UserAccountLicense=1)
|
||
|
||
# 属性
|
||
user.IsActive # UserAccountLicense == 1
|
||
user.IsOnJob # UserPositionStatus == 0
|
||
user.UUIDStr # UUID 字符串
|
||
user.HasPermission('menu:admin') # 检查权限
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 角色管理 (RoleManager)
|
||
|
||
```python
|
||
from gvsdsdk.auth.managers import RoleManager
|
||
|
||
# 创建角色
|
||
role = RoleManager.CreateRole(name='管理员', company_uuid=company_uuid)
|
||
|
||
# 分配/移除角色
|
||
RoleManager.AssignRole(user_uuid=user.UserUUID, role_uuid=role.RoleUUID)
|
||
RoleManager.RemoveRole(user_uuid=user.UserUUID, role_uuid=role.RoleUUID)
|
||
|
||
# 查询角色
|
||
roles = RoleManager.GetRolesForUser(user_uuid=user.UserUUID)
|
||
users = RoleManager.GetUsersForRole(role_uuid=role.RoleUUID)
|
||
|
||
# 分配/移除权限
|
||
RoleManager.AssignPermission(role_uuid=role.RoleUUID, perm_code='menu:admin', perm_name='菜单管理')
|
||
RoleManager.RemovePermission(role_uuid=role.RoleUUID, perm_code='menu:admin')
|
||
|
||
# 查询权限
|
||
perms = RoleManager.GetPermissionsForRole(role_uuid=role.RoleUUID)
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 商铺管理 (ShopManager)
|
||
|
||
```python
|
||
from gvsdsdk.auth.managers import ShopManager
|
||
|
||
# 创建商铺
|
||
shop = ShopManager.CreateShop(
|
||
name='旗舰店',
|
||
company_uuid=company_uuid,
|
||
code='SHOP-001',
|
||
shop_type=1,
|
||
ShopAddress='北京市朝阳区xxx',
|
||
ShopContact='张三',
|
||
ShopPhone='13800138000',
|
||
ShopDesc='公司旗舰门店',
|
||
)
|
||
|
||
# 角色关联商铺
|
||
ShopManager.AssignRole(role_uuid=role.RoleUUID, shop_uuid=shop.ShopUUID, is_main_shop=True)
|
||
ShopManager.RemoveRole(role_uuid=role.RoleUUID, shop_uuid=shop.ShopUUID)
|
||
|
||
# 查询
|
||
shops = ShopManager.GetShopsForRole(role_uuid=role.RoleUUID) # 角色的所有商铺
|
||
roles = ShopManager.GetRolesForShop(shop_uuid=shop.ShopUUID) # 商铺的所有角色
|
||
main_shop = ShopManager.GetMainShopForRole(role_uuid=role.RoleUUID) # 角色的主商铺
|
||
company_shops = ShopManager.GetShopsForCompany(company_uuid=company_uuid) # 公司的所有商铺
|
||
|
||
# 模型方法
|
||
shop.GetRoles() # 商铺关联的所有角色
|
||
```
|
||
|
||
### 商铺模型字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| ShopUUID | BINARY(16) PK | 商铺 UUID |
|
||
| CompanyUUID | BINARY(16) | 所属公司 UUID |
|
||
| ShopName | VARCHAR(128) | 商铺名称 |
|
||
| ShopCode | VARCHAR(64) | 商铺编码 |
|
||
| ShopType | SMALLINT | 商铺类型 |
|
||
| ShopStatus | SMALLINT | 状态（1=启用） |
|
||
| ShopAddress | VARCHAR(512) | 地址 |
|
||
| ShopContact | VARCHAR(128) | 联系人 |
|
||
| ShopPhone | VARCHAR(32) | 联系电话 |
|
||
| ShopDesc | VARCHAR(512) | 描述 |
|
||
| CreateTime | DATETIME | 创建时间 |
|
||
| UpdateTime | DATETIME | 更新时间 |
|
||
|
||
### 角色商铺关联表 (RoleShop)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| RoleShopUUID | BINARY(16) PK | 关联 UUID |
|
||
| RoleUUID | BINARY(16) | 角色 UUID |
|
||
| ShopUUID | BINARY(16) | 商铺 UUID |
|
||
| IsMainShop | SMALLINT | 是否主商铺（0/1） |
|
||
| CreateTime | DATETIME | 创建时间 |
|
||
|
||
---
|
||
|
||
## 7. 职务管理 (PositionManager)
|
||
|
||
```python
|
||
from gvsdsdk.auth.managers import PositionManager
|
||
|
||
# 创建职务
|
||
position = PositionManager.CreatePosition(
|
||
name='总经理',
|
||
company_uuid=company_uuid,
|
||
code='POS-CEO',
|
||
level=10,
|
||
PositionDesc='公司最高管理职务',
|
||
)
|
||
|
||
# 角色关联职务
|
||
PositionManager.AssignRole(role_uuid=role.RoleUUID, position_uuid=position.PositionUUID, is_main_position=True)
|
||
PositionManager.RemoveRole(role_uuid=role.RoleUUID, position_uuid=position.PositionUUID)
|
||
|
||
# 查询
|
||
positions = PositionManager.GetPositionsForRole(role_uuid=role.RoleUUID) # 角色的所有职务
|
||
roles = PositionManager.GetRolesForPosition(position_uuid=position.PositionUUID) # 职务的所有角色
|
||
main_pos = PositionManager.GetMainPositionForRole(role_uuid=role.RoleUUID) # 角色的主职务
|
||
company_positions = PositionManager.GetPositionsForCompany(company_uuid=company_uuid) # 公司的所有职务
|
||
|
||
# 模型方法
|
||
position.GetRoles() # 职务关联的所有角色
|
||
```
|
||
|
||
### 职务模型字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| PositionUUID | BINARY(16) PK | 职务 UUID |
|
||
| CompanyUUID | BINARY(16) | 所属公司 UUID |
|
||
| PositionName | VARCHAR(128) | 职务名称 |
|
||
| PositionCode | VARCHAR(64) | 职务编码 |
|
||
| PositionLevel | SMALLINT | 职务级别 |
|
||
| PositionStatus | SMALLINT | 状态（1=启用） |
|
||
| PositionDesc | VARCHAR(512) | 描述 |
|
||
| CreateTime | DATETIME | 创建时间 |
|
||
| UpdateTime | DATETIME | 更新时间 |
|
||
|
||
### 角色职务关联表 (RolePosition)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| RolePositionUUID | BINARY(16) PK | 关联 UUID |
|
||
| RoleUUID | BINARY(16) | 角色 UUID |
|
||
| PositionUUID | BINARY(16) | 职务 UUID |
|
||
| IsMainPosition | SMALLINT | 是否主职务（0/1） |
|
||
| CreateTime | DATETIME | 创建时间 |
|
||
|
||
---
|
||
|
||
## 8. 权限验证 (PermissionVerifier)
|
||
|
||
```python
|
||
from gvsdsdk.auth.permissions import PermissionVerifier, IsAdminUser, CompanyScopedMixin
|
||
|
||
# 手动验证
|
||
if PermissionVerifier(perm_level=1, perm_attrs=['menu:admin'], user=request.user, request=request):
|
||
pass
|
||
|
||
# DRF 权限类
|
||
class MyViewSet(viewsets.ModelViewSet):
|
||
permission_classes = [IsAuthenticated, IsAdminUser]
|
||
|
||
# 公司范围自动过滤
|
||
class MyCompanyViewSet(CompanyScopedMixin, viewsets.ModelViewSet):
|
||
company_field = 'CompanyUUID' # 自动按当前角色公司过滤
|
||
```
|
||
|
||
---
|
||
|
||
## 9. ELT 认证
|
||
|
||
### 认证流程
|
||
|
||
```
|
||
浏览器 Cookie (ELT_TOKEN) → ELTAuthentication → EphemeralToken → User
|
||
```
|
||
|
||
### 中间件
|
||
|
||
```python
|
||
# settings.py MIDDLEWARE
|
||
'gvsdsdk.auth.middleware.ELTAuthMiddleware', # 解析 ELT Cookie
|
||
'gvsdsdk.auth.middleware.CurrentRoleMiddleware', # 注入 request.current_role
|
||
|
||
# 视图中使用
|
||
request.user # gvsdsdk.models.User 实例
|
||
request.current_role # gvsdsdk.models.Role 实例（或 None）
|
||
request.current_company_uuid # 当前角色所属公司 UUID（或 None）
|
||
```
|
||
|
||
### Cookie 管理
|
||
|
||
```python
|
||
from gvsdsdk.auth.cookie import SetELTCookie, DeleteELTCookie, ELT_COOKIE_NAME
|
||
|
||
# 登录成功后设置 Cookie
|
||
SetELTCookie(response, token_value)
|
||
|
||
# 登出时删除 Cookie
|
||
DeleteELTCookie(response)
|
||
```
|
||
|
||
### 加密工具
|
||
|
||
```python
|
||
from gvsdsdk.auth.crypto import HashPassword, VerifyPassword, SymmetricEncrypt, SymmetricDecrypt
|
||
|
||
# 密码
|
||
hashed = HashPassword('plaintext')
|
||
is_valid = VerifyPassword('plaintext', hashed)
|
||
|
||
# AES-256-GCM 对称加密
|
||
encrypted = SymmetricEncrypt('sensitive data', key)
|
||
decrypted = SymmetricDecrypt(encrypted, key)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 分佣引擎 (CommissionEngine)
|
||
|
||
```python
|
||
from gvsdsdk.commission import CommissionEngine, CommissionError
|
||
|
||
engine = CommissionEngine()
|
||
|
||
# 配置规则
|
||
engine.ConfigureRule(
|
||
event_type='order_complete',
|
||
participant_rules=[
|
||
{'Type': 'percentage', 'Rate': 0.10, 'ParticipantID': 'platform'},
|
||
{'Type': 'fixed', 'Amount': 50.00, 'ParticipantID': 'agent'},
|
||
{'Type': 'remainder', 'ParticipantID': 'merchant'},
|
||
],
|
||
)
|
||
|
||
# 触发分佣
|
||
engine.Dispatch(
|
||
event_type='order_complete',
|
||
event_key='ORDER-12345',
|
||
total_amount=1000.00,
|
||
tenant_uuid=tenant_uuid,
|
||
)
|
||
|
||
# 邀请链分佣
|
||
engine.BuildInviteChainCommission(
|
||
event_type='member_purchase',
|
||
event_key='MEMBER-67890',
|
||
total_amount=500.00,
|
||
invite_chain=[user_uuid_1, user_uuid_2, user_uuid_3],
|
||
tenant_uuid=tenant_uuid,
|
||
)
|
||
|
||
# 预结算
|
||
engine.PreSettle(event_key='ORDER-12345', participant_id='agent', amount=50.00)
|
||
engine.ConfirmPreSettlement(presettlement_uuid=uuid)
|
||
engine.RejectPreSettlement(presettlement_uuid=uuid)
|
||
|
||
# 查询
|
||
records = engine.QueryRecords(participant_id='agent')
|
||
total = engine.TotalByParticipant(participant_id='agent')
|
||
```
|
||
|
||
### 策略类型
|
||
|
||
| 策略 | Type | 说明 |
|
||
|------|------|------|
|
||
| PercentageStrategy | `percentage` | 比例分账，支持保底/封顶 |
|
||
| FixedStrategy | `fixed` | 固定金额 |
|
||
| TieredStrategy | `tiered` | 阶梯分账 |
|
||
| RemainderStrategy | `remainder` | 剩余归平台 |
|
||
| WithdrawalFeeStrategy | `withdrawal_fee` | 提现手续费 |
|
||
|
||
---
|
||
|
||
## 11. 支付网关 (PaymentManager)
|
||
|
||
```python
|
||
from gvsdsdk.payment import PaymentManager, PaymentError
|
||
|
||
manager = PaymentManager()
|
||
|
||
# 配置网关
|
||
manager.ConfigureGateway(
|
||
tenant_uuid=tenant_uuid,
|
||
platform='wechat',
|
||
app_id='wx1234567890',
|
||
merchant_id='1234567890',
|
||
api_key='***',
|
||
)
|
||
|
||
# 发起支付
|
||
response = manager.Pay(
|
||
tenant_uuid=tenant_uuid,
|
||
platform='wechat',
|
||
out_trade_no='ORDER-12345',
|
||
total_amount=100.00,
|
||
subject='商品名称',
|
||
pay_method='JSAPI',
|
||
openid='user_openid',
|
||
)
|
||
|
||
# 查询订单
|
||
result = manager.Query(tenant_uuid=tenant_uuid, out_trade_no='ORDER-12345')
|
||
|
||
# 退款
|
||
result = manager.Refund(
|
||
tenant_uuid=tenant_uuid,
|
||
out_trade_no='ORDER-12345',
|
||
refund_amount=50.00,
|
||
refund_reason='用户申请退款',
|
||
)
|
||
|
||
# 企业转账
|
||
result = manager.Transfer(
|
||
tenant_uuid=tenant_uuid,
|
||
platform='wechat',
|
||
out_trade_no='TRANSFER-001',
|
||
amount=100.00,
|
||
transfer_type='balance',
|
||
openid='user_openid',
|
||
)
|
||
|
||
# 处理回调
|
||
result = manager.HandleNotify(platform='wechat', raw_body=request.body)
|
||
|
||
# 列出可用渠道
|
||
channels = manager.ListChannels()
|
||
```
|
||
|
||
### 支付渠道
|
||
|
||
| 渠道 | Platform | 支付方式 | 转账 |
|
||
|------|----------|---------|------|
|
||
| 微信支付 | `wechat` | JSAPI/Native/H5/小程序 | 支持 |
|
||
| 支付宝 | `alipay` | APP/H5/Native | 支持 |
|
||
| 银行卡 | `bank` | APP/H5/Native | 仅 bank 类型 |
|
||
|
||
---
|
||
|
||
## 12. MSYNC 服务间通信
|
||
|
||
```python
|
||
from gvsdsdk.msync import ServiceRegistry, OGMManager, TransactionManager, ServiceClient
|
||
from gvsdsdk.msync.auth import SignPayload, BuildAuthPayload
|
||
|
||
# 服务注册
|
||
registry = ServiceRegistry()
|
||
registry.Register(
|
||
service_name='my-service',
|
||
domain='https://my-service.gvsds.com',
|
||
secret='***',
|
||
scope=['ogm:read', 'ogm:write'],
|
||
)
|
||
|
||
# OGM 全局对象映射
|
||
ogm = OGMManager()
|
||
mapping_id = ogm.CreateMapping(local_type='User', local_id=user_id)
|
||
remote_obj = ogm.GetRemote(mapping_id)
|
||
|
||
# 分布式事务
|
||
tx_mgr = TransactionManager()
|
||
tx = tx_mgr.Begin(participants=['service-a', 'service-b'])
|
||
tx_mgr.ExecuteStep(tx, 'service-a', 'create_order', {'item': 'xxx'})
|
||
tx_mgr.ExecuteStep(tx, 'service-b', 'deduct_stock', {'item': 'xxx'})
|
||
tx_mgr.Commit(tx)
|
||
|
||
# 服务客户端
|
||
client = ServiceClient(service_name='target-service')
|
||
response = client.Call('/api/resource', method='GET')
|
||
```
|
||
|
||
---
|
||
|
||
## 13. FluentQuery ORM 查询
|
||
|
||
```python
|
||
from gvsdsdk.models import User, Role, Shop, Position
|
||
|
||
# 通过 .query 属性使用 FluentQuery
|
||
users = User.query.filter(User.UserAccountLicense == 1).all()
|
||
admins = User.query.filter(User.IsSuperuser == True).all()
|
||
|
||
# 运算符重载
|
||
young = User.query.filter(User.UserAccountLicense != 0).all()
|
||
|
||
# 排序和分页
|
||
users = User.query.filter(User.IsActive == True).order_by(User.UserCreateTime).limit(10)
|
||
|
||
# Django ORM 原生查询（始终可用）
|
||
users = User.objects.filter(UserAccountLicense=1)
|
||
users = User.objects.filter(UserName__contains='admin')
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 数据库路由与建表
|
||
|
||
### SAASDatabaseRouter
|
||
|
||
```python
|
||
# settings.py — 子服务器连接 SAAS 主库
|
||
DATABASE_ROUTERS = ['gvsdsdk.db_router.SAASDatabaseRouter']
|
||
|
||
# 可选配置
|
||
GVSDSDK_SAAS_DB_ALIAS = 'saas' # SAAS 数据库别名，默认 'saas'
|
||
GVSDSDK_SAAS_READ_ONLY = True # 子服务器只读，默认 True
|
||
```
|
||
|
||
### gvsdsdk_init 建表命令
|
||
|
||
```bash
|
||
# 完整建表
|
||
python manage.py gvsdsdk_init --db default
|
||
|
||
# 仅打印 SQL
|
||
python manage.py gvsdsdk_init --db default --dry-run
|
||
|
||
# 按模块建表
|
||
python manage.py gvsdsdk_init --db default --modules auth
|
||
python manage.py gvsdsdk_init --db default --modules auth,commission,payment
|
||
```
|
||
|
||
### GVSDSDK_MANAGE_TABLES
|
||
|
||
```python
|
||
# settings.py — 同源数据库，允许 Django 管理表
|
||
GVSDSDK_MANAGE_TABLES = True
|
||
|
||
# 然后执行
|
||
# python manage.py makemigrations gvsdsdk
|
||
# python manage.py migrate
|
||
```
|
||
|
||
---
|
||
|
||
## 15. 数据模型一览
|
||
|
||
### SAAS 核心模型 (gvsdsdk.models)
|
||
|
||
| 模型 | 表名 | 说明 |
|
||
|------|------|------|
|
||
| User | User | 用户表 |
|
||
| Role | Role | 角色表 |
|
||
| Permission | Permission | 权限表 |
|
||
| UserRole | UserRole | 用户-角色多对多 |
|
||
| RoleDept | RoleDept | 角色-部门多对多 |
|
||
| Shop | Shop | 商铺表 |
|
||
| RoleShop | RoleShop | 角色-商铺多对多 |
|
||
| Position | Position | 职务表 |
|
||
| RolePosition | RolePosition | 角色-职务多对多 |
|
||
| EphemeralToken | EphemeralToken | ELT 令牌表 |
|
||
| User2FA | User2FA | 双因素认证表 |
|
||
| UserPending2FA | UserPending2FA | 2FA 待验证表 |
|
||
| UserAvatar | UserAvatar | 用户头像表 |
|
||
| UserLoginLog | UserLoginLog | 登录日志表 |
|
||
| AccountActivation | AccountActivation | 账户激活码表 |
|
||
| UserABAC | UserABAC | 用户 ABAC 表 |
|
||
| Password | Password | 密码表 |
|
||
|
||
### 分佣模型 (gvsdsdk.commission.models)
|
||
|
||
| 模型 | 表名 | 说明 |
|
||
|------|------|------|
|
||
| CommissionEvent | CommissionEvent | 分佣事件表 |
|
||
| RateTable | CommissionRateTable | 费率表 |
|
||
| RateEntry | CommissionRateEntry | 费率条目表 |
|
||
| CommissionRule | CommissionRule | 分佣规则表 |
|
||
| CommissionRecord | CommissionRecord | 分佣记录表 |
|
||
| PreSettlement | CommissionPreSettlement | 预结算表 |
|
||
|
||
### 支付模型 (gvsdsdk.payment.models)
|
||
|
||
| 模型 | 表名 | 说明 |
|
||
|------|------|------|
|
||
| PaymentGatewayConfig | PaymentGatewayConfig | 支付网关配置表 |
|
||
| PaymentTransaction | PaymentTransaction | 支付交易流水表 |
|
||
|
||
---
|
||
|
||
## 导入速查表
|
||
|
||
| 用途 | 导入路径 | 顶层快捷 |
|
||
|------|---------|---------|
|
||
| 用户模型 | `from gvsdsdk.models import User` | `from gvsdsdk import User` |
|
||
| 角色管理 | `from gvsdsdk.auth.managers import RoleManager` | `from gvsdsdk import RoleManager` |
|
||
| 商铺管理 | `from gvsdsdk.auth.managers import ShopManager` | `from gvsdsdk import ShopManager` |
|
||
| 职务管理 | `from gvsdsdk.auth.managers import PositionManager` | `from gvsdsdk import PositionManager` |
|
||
| 权限验证 | `from gvsdsdk.auth.permissions import PermissionVerifier` | `from gvsdsdk import PermissionVerifier` |
|
||
| ELT 认证 | `from gvsdsdk.auth.elt_auth import ELTAuthentication` | `from gvsdsdk import ELTAuthentication` |
|
||
| Cookie | `from gvsdsdk.auth.cookie import SetELTCookie` | `from gvsdsdk import SetELTCookie` |
|
||
| 加密 | `from gvsdsdk.auth.crypto import SymmetricEncrypt` | `from gvsdsdk import SymmetricEncrypt` |
|
||
| 中间件 | `from gvsdsdk.auth.middleware import ELTAuthMiddleware` | `from gvsdsdk import ELTAuthMiddleware` |
|
||
| 分佣引擎 | `from gvsdsdk.commission import CommissionEngine` | `from gvsdsdk import CommissionEngine` |
|
||
| 支付网关 | `from gvsdsdk.payment import PaymentManager` | `from gvsdsdk import PaymentManager` |
|
||
| 微信支付 | `from gvsdsdk.payment.gateways.wechat import WechatPaymentGateway` | `from gvsdsdk import WechatPaymentGateway` |
|
||
| MSYNC 认证 | `from gvsdsdk.msync.auth import SignPayload` | `from gvsdsdk import SignPayload` |
|
||
| 服务注册 | `from gvsdsdk.msync import ServiceRegistry` | `from gvsdsdk import ServiceRegistry` |
|
||
| OGM | `from gvsdsdk.msync import OGMManager` | `from gvsdsdk import OGMManager` |
|
||
| 事务 | `from gvsdsdk.msync import TransactionManager` | `from gvsdsdk import TransactionManager` |
|
||
| 数据库路由 | `from gvsdsdk.db_router import SAASDatabaseRouter` | — |
|
||
| UUID 工具 | `from gvsdsdk.model_utils import UUIDObj` | `from gvsdsdk import UUIDObj` |
|
||
| QModel | `from gvsdsdk.model_base import QModel` | `from gvsdsdk import QModel` |
|