Neo-ZQYY/packages/shared

packages/shared — 跨项目共享包

neozqyy-shared：NeoZQYY Monorepo 的共享工具包，提供业务枚举、金额精度处理、时间工具和其他通用功能。

安装

作为 uv workspace 成员，其他模块通过 pyproject.toml 引用：

[project]
dependencies = ["neozqyy-shared"]

[tool.uv.sources]
neozqyy-shared = { workspace = true }

模块说明

enums.py — 业务枚举

所有枚举继承 (str, Enum)，值为小写英文标识符，可直接与数据库字段和 API 响应比较。

枚举类	说明	值
PaymentStatus	支付状态	pending / paid / refunded / partially_refunded / cancelled
OrderStatus	订单状态	pending / confirmed / in_progress / completed / cancelled / refunded
MemberStatus	会员状态	active / inactive / suspended / expired
AssistantStatus	助教状态	active / on_leave / resigned
DataSource	数据源模式	online / offline / hybrid
TaskCategory	ETL 任务分类	ODS / DWD / DWS / Schema / Quality / Other

用法：

from neozqyy_shared.enums import PaymentStatus, OrderStatus

if row["status"] == PaymentStatus.PAID:
    ...

money.py — 金额精度工具

业务约定：所有金额字段保留 2 位小数（分），与数据库 numeric(*, 2) 对齐。使用 Decimal + ROUND_HALF_UP。

函数	说明
round_cny(amount: Decimal) -> Decimal	人民币金额四舍五入到分
to_cny(value) -> Decimal	将任意数值（int/float/str/Decimal）转为 CNY 精度

用法：

from neozqyy_shared.money import to_cny, round_cny
from decimal import Decimal

price = to_cny(99.999)   # Decimal('100.00')
total = round_cny(Decimal("123.456"))  # Decimal('123.46')

datetime_utils.py — 时间工具

默认时区 Asia/Shanghai（UTC+8），与业务数据库 timestamptz 对齐。支持营业日计算和日期范围生成。

函数	说明
now_shanghai() -> datetime	获取上海时区当前时间
date_range(start, end) -> list[date]	生成日期范围列表（含首尾）
get_business_date(dt, start_hour=8) -> date	根据营业日分割点计算业务日期
format_business_date(dt, start_hour=8) -> str	格式化业务日期为 YYYY-MM-DD

用法：

from neozqyy_shared.datetime_utils import now_shanghai, date_range, get_business_date
from datetime import date, datetime

now = now_shanghai()
dates = date_range(date(2026, 1, 1), date(2026, 1, 7))  # 7 天

# 营业日计算（凌晨 2:00 算前一天，上午 10:00 算当天）
biz_date = get_business_date(datetime(2026, 1, 2, 2, 0))   # 2026-01-01
biz_date = get_business_date(datetime(2026, 1, 2, 10, 0))  # 2026-01-02

依赖

python-dateutil>=2.8.0
tzdata>=2023.0

使用方

• apps/etl/connectors/feiqiu/ — ETL Connector
• apps/backend/ — FastAPI 后端
• apps/mcp-server/ — MCP Server