uvapi 0.10.1
UltraVIEW Platform app backend develop SDK
Requires Python: >=3.13

# UrVerse Core SDK

[![覆盖率](http://bjrdsonar.rigoltech.com/api/project_badges/measure?project=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff&metric=coverage&token=sqb_3e11d87f098df5c1fb290e2da8d2f818dfcf7916)](http://bjrdsonar.rigoltech.com/dashboard?id=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff)
[![警报](http://bjrdsonar.rigoltech.com/api/project_badges/measure?project=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff&metric=alert_status&token=sqb_3e11d87f098df5c1fb290e2da8d2f818dfcf7916)](http://bjrdsonar.rigoltech.com/dashboard?id=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff)
[![可维护性评级](http://bjrdsonar.rigoltech.com/api/project_badges/measure?project=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff&metric=software_quality_maintainability_rating&token=sqb_3e11d87f098df5c1fb290e2da8d2f818dfcf7916)](http://bjrdsonar.rigoltech.com/dashboard?id=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff)
[![可靠性评级](http://bjrdsonar.rigoltech.com/api/project_badges/measure?project=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff&metric=software_quality_reliability_rating&token=sqb_3e11d87f098df5c1fb290e2da8d2f818dfcf7916)](http://bjrdsonar.rigoltech.com/dashboard?id=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff)
[![安全评级](http://bjrdsonar.rigoltech.com/api/project_badges/measure?project=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff&metric=software_quality_security_rating&token=sqb_3e11d87f098df5c1fb290e2da8d2f818dfcf7916)](http://bjrdsonar.rigoltech.com/dashboard?id=UltraVIEW_uvtools_app_sdk_d3fe8dee-49e4-4065-94ff-30f462f14eff)

## 项目简介

这是UrVerse Core SDK的组成部分，展示了如何基于UrVerse平台开发功能应用。UrVerse是一个模块化的测试测量软件平台，采用"轻核心+强应用"的设计理念，支持仪器发现与连接管理、应用管理、低代码开发等功能。

> 📖 **UrVerse平台FRS说明**: 详细的功能需求规格请参考 [飞书云文档](https://rigolportal.feishu.cn/wiki/VxNgwFycNiuCgLkSbQlcw5Hanog)

## 快速开始

### 安装SDK

```bash
pip install uvapi
```

### 最简使用示例

创建一个简单的FastAPI应用只需要几行代码：

```python
# main.py
import uvicorn
from uvapi import UV_APP, UV_APP_CONFIG

# 配置API模块
UV_APP_CONFIG.app_config.apis.append('your_app.apis.api')

# 加载API并启动服务
UV_APP.load_apis()
uvicorn.run(UV_APP.app, host='0.0.0.0', port=9000)
```

### 1. 定义数据模型

```python
# models/sql_models.py
from sqlmodel import SQLModel, Field
from typing import Optional
from datetime import datetime

class User(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(max_length=100, description='用户姓名')
    email: str = Field(max_length=255, unique=True, description='用户邮箱')
    created_at: datetime = Field(default_factory=datetime.now)
```

### 2. 创建API接口

```python
# apis/api.py
from sqlmodel import Session, select
from uvapi import UV_APP
from uvapi.logger import get_logger
from ..models import User, UserCreate, UserRead

# 创建数据库
UV_APP.create_db()

@app.action()
def create_user(user: UserCreate) -> UserRead:
    """创建用户"""
    with Session(UV_APP.db_engine) as session:
        db_user = User.model_validate(user)
        session.add(db_user)
        session.commit()
        session.refresh(db_user)
        return UserRead.model_validate(db_user, from_attributes=True)

@app.action()
def get_users() -> List[UserRead]:
    """获取所有用户"""
    with Session(UV_APP.db_engine) as session:
        users = session.exec(select(User)).all()
        return [UserRead.model_validate(user, from_attributes=True) for user in users]
```

### 3. 定义属性组

```python
from uvapi import UV_APP
from uvapi.framework.attribute import BaseAttrGroup

@UV_APP.register_attributes()
class GroupNameA(BaseAttrGroup):
    attr_name_a: str = 'aaa'
    attr_name_b: int = 10

# 使用自定义组名
@UV_APP.register_attributes('CustomGroupName')
class GroupNameB(BaseAttrGroup):
    temperature: float = 25.0
    humidity: int = 60
```

### 4. 使用属性组

```python
# 获取单例实例
group = GroupNameA()

# 修改属性值，自动触发WebSocket推送
group.attr_name_b += 10
```

### 5. WebSocket连接

前端可以通过以下WebSocket端点连接：

```
ws://localhost:9000/v1/workers/{app_id}/attributes/ws
```

其中 `{app_id}` 是应用的ID。

### 6. 消息格式

当属性发生变更时，会推送以下格式的MessagePack消息：

```python
{
    'type': 'attribute_change',
    'group': 'GroupNameA',           # 属性组名
    'attribute': 'attr_name_b',      # 属性名
    'old_value': 10,                 # 此属性旧值
    'value': 20,                     # 新值
    'timestamp': 1234567890.0
}
```

当app_config.toml中的attributes_auto_push为true时， 会每间隔attributes_push_interval，自动推送如下格式的消息：
```python
{
    'type': 'attribute_snapshot',
    'group': 'GroupNameA',           # 属性组名
    'attributes': {
        'attr_name_a': value_a,
        'attr_name_b': value_b
    },
    'timestamp': 1234567890.0
}
```

### 7. 运行应用

```bash
python main.py
```

访问 `http://localhost:9000/docs` 查看自动生成的API文档。

## CLI 构建打包工具

UrVerse Core SDK 提供了命令行工具 `pyuvtools`，用于构建和打包应用。

### 快速开始

```bash
# 构建应用
pyuvtools build

# 打包为 .uvapp 安装包
pyuvtools uvapp
```

### 文档

- **[CLI 使用指南](docs/CLI_BUILD_USAGE.md)** - 详细的使用说明和配置指南
- **[CLI 概要设计](docs/CLI_DESIGN_SPECIFICATION.md)** - 完整的技术设计文档

## 工程使用说明

> SonarQube服务器地址[sonarqube(http://bjrdsonar.rigoltech.com)](http://bjrdsonar.rigoltech.com)

> Gitlab服务器地址[Gitlab(http://bjrdgit.rigoltech.com)](http://bjrdgit.rigoltech.com)