ava-data-models 0.2.0

AVACloud 业务领域公共 Pydantic v2 数据模型包

ava-data-models

AVACloud 业务领域公共 Pydantic v2 数据模型包。

项目定位

ava-data-models 是 AVACloud 生态下的公共业务对象模型层，仅存放：

• Pydantic v2 业务对象数据模型
• 业务对象公共基类

不包含业务枚举、查询条件、分页、批量操作、通用请求/响应包装，也不包含任何业务查询、校验逻辑、持久化或外部服务调用，作为各智能体项目的公共依赖被引用。

技术栈

• Python >= 3.10
• Pydantic v2
• pydantic-settings
• typing-extensions

安装

# 作为依赖安装（发布到 PyPI 后）
pip install ava-data-models

# 本地开发安装
pip install -e ".[dev]"

目录结构

ava-data-models/
├── pyproject.toml
├── README.md
├── scripts/
│   ├── generate_from_dts.py    # 从 ibas index.d.ts 自动生成模型
│   └── generate_inits.py       # 生成业务模块 __init__.py
├── src/
│   └── ava_data_models/
│       ├── __init__.py         # 根包导出：公共业务对象基类
│       ├── common/             # 公共基础
│       │   └── base.py         # BusinessObject / Document / DocumentLine / MasterData / ...
│       ├── accounting/
│       ├── apparelindustry/
│       ├── approvalprocess/
│       ├── budget/
│       ├── businesspartner/
│       ├── cargos/
│       ├── channels/
│       ├── dealer/
│       ├── documents/
│       ├── equipment/
│       ├── groupfinancemanagement/
│       ├── humanresources/
│       ├── importexport/
│       ├── initialfantasy/
│       ├── integration/
│       ├── invoice/
│       ├── manufacturing/
│       ├── manufacturingcost/
│       ├── manufacturingoutsourcing/
│       ├── manufacturingscheduling/
│       ├── marketingpromotion/
│       ├── masterdata/
│       ├── materials/
│       ├── membercenter/
│       ├── message/
│       ├── product/
│       ├── projectsystem/
│       ├── purchase/
│       ├── qualitycontrol/
│       ├── receiptpayment/
│       ├── reimbursement/
│       ├── reportanalysis/
│       ├── sales/
│       ├── salesopportunity/
│       ├── servicecenter/
│       ├── shopping/
│       ├── store/
│       ├── supplier/
│       ├── taxation/
│       ├── thirdpartyapp/
│       └── ...                 # 每个业务模块独立分包
└── tests/
    └── test_common.py

命名规范

• 类名：大驼峰（CamelCase），例如 SalesOrder、PurchaseRequestItem。
• 属性名：下划线命名（snake_case），例如 doc_entry、customer_code。
• 通过 Field(..., alias="camelCase") 保留原始 ibas API 字段名，支持直接反序列化来自 ibas 的 camelCase JSON。

业务对象基类层次

模型基类与 ibas 业务对象体系对齐：

BusinessObject
├── MasterData          # 对应 ibas.IBOMasterData
├── MasterDataLine      # 对应 ibas.IBOMasterDataLine
├── Document            # 对应 ibas.IBODocument
├── DocumentLine        # 对应 ibas.IBODocumentLine
├── Simple              # 对应 ibas.IBOSimple
└── SimpleLine          # 对应 ibas.IBOSimpleLine

• BusinessObject 携带 source_system / fetched_at 跨系统溯源元信息。
• 生成器仅对直接继承上述 ibas.IBO* 接口的类生成模型。
• 集合壳类（如 ISalesOrderItems）不再保留，字段统一用 list[T] 表示。

使用示例

1. 导入公共基础模型

from ava_data_models import BusinessObject, Document

2. 导入业务模块模型

from ava_data_models.sales import SalesOrder, SalesOrderItem
from ava_data_models.purchase import PurchaseOrder, PurchaseRequest
from ava_data_models.materials import Material, Warehouse
from ava_data_models.manufacturing import ProductionOrder

3. 直接解析 ibas API 返回的 camelCase JSON

import json
from ava_data_models.sales import SalesOrder

payload = {
    "docEntry": 10001,
    "docNum": "SO-2024-0001",
    "customerCode": "C001",
    "customerName": "示例客户",
    "documentTotal": 1250.00,
    "salesOrderItems": [
        {"itemCode": "P001", "quantity": 10.0, "price": 125.0},
    ],
}

order = SalesOrder.model_validate(payload)
print(order.doc_entry)       # 10001
print(order.customer_code)   # C001
print(order.document_total)  # 1250.0
print(len(order.sales_order_items))  # 1

4. 序列化为 snake_case 或 camelCase

# 默认输出 snake_case
order.model_dump()

# 输出 camelCase（使用 alias）
order.model_dump(by_alias=True)

# JSON 字符串
order.model_dump_json(by_alias=True)

模型生成脚本

本项目提供 scripts/generate_from_dts.py，可基于本地 ibas-typescript/test/apps/{module}/index.d.ts 中的 bo 命名空间自动生成对应业务模块的 Pydantic 模型。

生成范围

仅对 bo 命名空间中直接继承 ibas.IBO* 业务对象接口的类生成模型：

ibas 接口	Python 基类
ibas.IBusinessObject	BusinessObject
ibas.IBODocument	Document
ibas.IBODocumentLine	DocumentLine
ibas.IBOMasterData	MasterData
ibas.IBOMasterDataLine	MasterDataLine
ibas.IBOSimple	Simple
ibas.IBOSimpleLine	SimpleLine

集合壳类（如 ISalesOrderItems）不生成独立模型，相关字段统一用 list[T] 表示。

前提

• 本地存在 ibas TypeScript 测试应用目录，默认路径： /Users/Niuren.Zhu/Codes/ColorCoding/ibas-typescript/test/apps
• 可通过环境变量覆盖： export IBAS_TEST_APPS=/path/to/ibas-typescript/test/apps

生成全部模块

python scripts/generate_from_dts.py
python scripts/generate_inits.py

生成单个模块

# 修改 generate_from_dts.py 中的 MODULES 列表，仅保留目标模块后执行
python scripts/generate_from_dts.py
python scripts/generate_inits.py

生成后注意事项

• 生成器为尽力解析，复杂的泛型、方法、跨模块引用会降级为 Any。
• 集合类（如 ISalesOrderItems）会启发式转换为 list[SalesOrderItem]。
• 生成后建议人工复核关键字段类型与注释，必要时手工补充或修正。

开发

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 代码格式化（可选）
black src tests
ruff check src tests --fix

发布到 PyPI

# 1. 安装构建与上传工具
pip install build twine

# 2. 清理历史构建产物
rm -rf dist/ build/ *.egg-info

# 3. 构建源码分发包与 Wheel
python -m build

# 4. 先上传到 TestPyPI 验证（可选）
python -m twine upload --repository testpypi dist/*

# 5. 上传到正式 PyPI
python -m twine upload dist/*

上传前请确认：

• pyproject.toml 中的 version 已更新。
• 已配置 PyPI API token（~/.pypirc 或通过 twine login）。

贡献与维护

• 新增业务模块：在 src/ava_data_models/ 下新增分包，参照现有模块结构编写 models.py 与 __init__.py。
• 修改公共模型：优先在 common/ 中定义，并在 common/__init__.py 与根包 __init__.py 中导出。
• 保持只存放业务对象模型，不引入枚举、查询条件、分页、批量操作、业务逻辑、数据库查询或外部 HTTP 调用。

许可证

Apache License 2.0