init: 项目初始提交 - NeoZQYY Monorepo 完整代码

packages/shared/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "neozqyy-shared"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "python-dateutil>=2.8.0",
+    "tzdata>=2023.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/neozqyy_shared"]

packages/shared/src/neozqyy_shared/__init__.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""NeoZQYY 共享包 — 跨项目复用的工具代码。
+
+提供：
+- enums: 字段枚举定义（支付状态、订单状态、会员状态、助教状态等）
+- money: 金额精度工具（CNY，Decimal + ROUND_HALF_UP，scale=2）
+- datetime_utils: 时区转换、日期范围计算
+"""
+
+from neozqyy_shared.enums import (
+    PaymentStatus,
+    OrderStatus,
+    MemberStatus,
+    AssistantStatus,
+    DataSource,
+    TaskCategory,
+)
+from neozqyy_shared.money import round_cny, to_cny, CNY_SCALE
+from neozqyy_shared.datetime_utils import (
+    SHANGHAI_TZ,
+    now_shanghai,
+    date_range,
+)
+
+__all__ = [
+    # enums
+    "PaymentStatus",
+    "OrderStatus",
+    "MemberStatus",
+    "AssistantStatus",
+    "DataSource",
+    "TaskCategory",
+    # money
+    "round_cny",
+    "to_cny",
+    "CNY_SCALE",
+    # datetime_utils
+    "SHANGHAI_TZ",
+    "now_shanghai",
+    "date_range",
+]

packages/shared/src/neozqyy_shared/datetime_utils.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""时区转换与日期范围工具。
+
+默认时区：Asia/Shanghai（UTC+8），与业务数据库 timestamptz 对齐。
+"""
+from datetime import datetime, date, timedelta
+from dateutil import tz
+
+SHANGHAI_TZ = tz.gettz("Asia/Shanghai")
+
+
+def now_shanghai() -> datetime:
+    """获取上海时区当前时间。"""
+    return datetime.now(SHANGHAI_TZ)
+
+
+def date_range(start: date, end: date) -> list[date]:
+    """生成日期范围列表（含首尾）。
+
+    start > end 时返回空列表。
+    """
+    if start > end:
+        return []
+    days = (end - start).days + 1
+    return [start + timedelta(days=i) for i in range(days)]

packages/shared/src/neozqyy_shared/enums.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""字段枚举定义 — 从 ETL models/ 提取的通用枚举。
+
+所有枚举继承 (str, Enum)，值为小写英文标识符，
+便于与数据库字段、API 响应直接比较。
+"""
+from enum import Enum
+
+
+class PaymentStatus(str, Enum):
+    """支付状态"""
+    PENDING = "pending"          # 待支付
+    PAID = "paid"                # 已支付
+    REFUNDED = "refunded"        # 已退款
+    PARTIALLY_REFUNDED = "partially_refunded"  # 部分退款
+    CANCELLED = "cancelled"      # 已取消
+
+
+class OrderStatus(str, Enum):
+    """订单状态"""
+    PENDING = "pending"          # 待处理
+    CONFIRMED = "confirmed"      # 已确认
+    IN_PROGRESS = "in_progress"  # 进行中
+    COMPLETED = "completed"      # 已完成
+    CANCELLED = "cancelled"      # 已取消
+    REFUNDED = "refunded"        # 已退款
+
+
+class MemberStatus(str, Enum):
+    """会员状态"""
+    ACTIVE = "active"            # 活跃
+    INACTIVE = "inactive"        # 不活跃
+    SUSPENDED = "suspended"      # 已冻结
+    EXPIRED = "expired"          # 已过期
+
+
+class AssistantStatus(str, Enum):
+    """助教状态"""
+    ACTIVE = "active"            # 在职
+    ON_LEAVE = "on_leave"        # 请假
+    RESIGNED = "resigned"        # 已离职
+
+
+class DataSource(str, Enum):
+    """数据源模式（与 ETL orchestration 保持一致）"""
+    ONLINE = "online"            # 在线抓取
+    OFFLINE = "offline"          # 本地回放
+    HYBRID = "hybrid"            # 抓取 + 入库
+
+
+class TaskCategory(str, Enum):
+    """ETL 任务分类"""
+    ODS = "ODS"
+    DWD = "DWD"
+    DWS = "DWS"
+    SCHEMA = "Schema"
+    QUALITY = "Quality"
+    OTHER = "Other"

packages/shared/src/neozqyy_shared/money.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""金额精度工具 — 人民币（CNY）统一使用 Decimal + ROUND_HALF_UP。
+
+业务约定：所有金额字段保留 2 位小数（分），与数据库 numeric(*, 2) 对齐。
+"""
+from decimal import Decimal, ROUND_HALF_UP
+
+CNY_SCALE = 2
+_QUANT = Decimal("0." + "0" * CNY_SCALE)
+
+
+def round_cny(amount: Decimal) -> Decimal:
+    """人民币金额四舍五入到分。"""
+    return amount.quantize(_QUANT, rounding=ROUND_HALF_UP)
+
+
+def to_cny(value) -> Decimal:
+    """将任意数值转为 Decimal 并四舍五入到分。
+
+    接受 int / float / str / Decimal；
+    不可解析时抛出 decimal.InvalidOperation。
+    """
+    return round_cny(Decimal(str(value)))