bocai-cli-core 0.2.0__py3-none-any.whl

bocai_cli/commands/card.py

@@ -0,0 +1,653 @@
+from __future__ import annotations
+
+import json
+
+from typing import Any
+
+import typer
+
+from bocai_cli.api import ApiFacade
+from bocai_cli.command_utils import command_handler
+from bocai_cli.config import load_config
+from bocai_cli.date_range_validation import validate_date_range, validate_optional_date_order
+from bocai_cli.errors import ConfigValidationError
+from bocai_cli.output import print_json
+
+app = typer.Typer(help="卡相关命令。", invoke_without_command=True)
+
+
+@app.callback()
+def card_root(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=0)
+
+
+def _build_api() -> ApiFacade:
+    config = load_config()
+    return ApiFacade(
+        base_url=config.base_url,
+        token=config.token,
+        timeout_seconds=config.timeout_seconds,
+    )
+
+
+def _parse_transaction_ids(raw_transaction_ids: str) -> list[str]:
+    values = [item.strip() for item in raw_transaction_ids.split(",")]
+    non_empty_values = [item for item in values if item]
+
+    unique_values: list[str] = []
+    seen: set[str] = set()
+    for value in non_empty_values:
+        if value not in seen:
+            seen.add(value)
+            unique_values.append(value)
+
+    if not unique_values:
+        raise ConfigValidationError("--transaction-ids 至少要包含一个有效ID。")
+
+    return unique_values
+
+
+def _parse_int_ids(raw_ids: str, *, option_name: str) -> list[int]:
+    values = [item.strip() for item in raw_ids.split(",") if item.strip()]
+    unique_values: list[int] = []
+    for value in values:
+        try:
+            parsed_id = int(value)
+        except ValueError as exc:
+            raise ConfigValidationError(
+                f"--{option_name} 必须是逗号分隔的正整数。"
+            ) from exc
+        if parsed_id <= 0:
+            raise ConfigValidationError(f"--{option_name} 必须是逗号分隔的正整数。")
+        if parsed_id not in unique_values:
+            unique_values.append(parsed_id)
+    return unique_values
+
+
+def _parse_card_ids(raw_card_ids: str) -> list[int]:
+    return _parse_int_ids(raw_card_ids, option_name="card-ids")
+
+
+def _parse_tag_ids(raw_tag_ids: str) -> list[int]:
+    return _parse_int_ids(raw_tag_ids, option_name="tag-ids")
+
+
+def _validate_allowed_option(
+    value: int,
+    allowed_values: set[int],
+    *,
+    option_name: str,
+    description: str,
+) -> None:
+    if value not in allowed_values:
+        raise ConfigValidationError(f"--{option_name} 只支持 {description}。")
+
+
+def _parse_performance_update_payload(raw_payload: str) -> list[dict[str, Any]]:
+    try:
+        payload = json.loads(raw_payload)
+    except json.JSONDecodeError as exc:
+        raise ConfigValidationError("--payload 必须是合法 JSON。") from exc
+
+    if not isinstance(payload, list):
+        raise ConfigValidationError("--payload 必须是数组。")
+
+    if not payload:
+        raise ConfigValidationError("--payload 至少要包含一条交易记录。")
+
+    for index, item in enumerate(payload, start=1):
+        if not isinstance(item, dict):
+            raise ConfigValidationError(f"--payload 第 {index} 项必须是对象。")
+        if "transactionId" not in item:
+            raise ConfigValidationError(f"--payload 第 {index} 项缺少 transactionId。")
+        if "performance" not in item:
+            raise ConfigValidationError(f"--payload 第 {index} 项缺少 performance。")
+
+    return payload
+
+
+def _parse_performance_new_payload(raw_payload: str) -> dict[str, Any]:
+    try:
+        payload = json.loads(raw_payload)
+    except json.JSONDecodeError as exc:
+        raise ConfigValidationError("--payload 必须是合法 JSON。") from exc
+
+    if not isinstance(payload, dict):
+        raise ConfigValidationError("--payload 必须是对象。")
+
+    if "data" not in payload:
+        raise ConfigValidationError("--payload 缺少 data。")
+
+    data = payload["data"]
+    if not isinstance(data, list):
+        raise ConfigValidationError("--payload.data 必须是数组。")
+
+    if not data:
+        raise ConfigValidationError("--payload.data 至少要包含一条合同记录。")
+
+    required_fields = (
+        "seq",
+        "date",
+        "activateNow",
+        "phone",
+        "name",
+        "cardName",
+        "contractNum",
+        "count",
+        "payAmount",
+        "payMethod",
+        "performanceAmount",
+        "performance",
+        "saleType",
+    )
+    for index, item in enumerate(data, start=1):
+        if not isinstance(item, dict):
+            raise ConfigValidationError(f"--payload.data 第 {index} 项必须是对象。")
+        for field in required_fields:
+            if field not in item:
+                raise ConfigValidationError(f"--payload.data 第 {index} 项缺少 {field}。")
+
+    return payload
+
+
+@app.command("sale-performance", help="获取售卡业绩数据")
+@command_handler
+def sale_performance(
+    start_date: str = typer.Option(
+        ...,
+        "--start-date",
+        help="开始日期，格式 YYYY-MM-DD。",
+    ),
+    end_date: str = typer.Option(
+        ...,
+        "--end-date",
+        help="结束日期，格式 YYYY-MM-DD。",
+    ),
+    page_num: int = typer.Option(
+        ...,
+        "--page-num",
+        min=0,
+        help="页码，必须大于等于 0。",
+    ),
+    page_size: int = typer.Option(
+        ...,
+        "--page-size",
+        min=1,
+        help="每页条数，必须大于等于 1。",
+    ),
+    type_: int = typer.Option(
+        ...,
+        "--type",
+        min=1,
+        max=2,
+        help="卡类型：1会员卡，2培训卡。",
+    ),
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+) -> None:
+    validate_date_range(start_date, end_date)
+
+    api = _build_api()
+    data = api.card.sale_performance(
+        start_date=start_date,
+        end_date=end_date,
+        page_num=page_num,
+        page_size=page_size,
+        type_=type_,
+        center_id=center_id,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+@app.command("sale-performance-clear", help="清除售卡业绩数据")
+@command_handler
+def sale_performance_clear(
+    transaction_ids: str = typer.Option(
+        ...,
+        "--transaction-ids",
+        help="交易ID列表，逗号分隔。",
+    ),
+    phone: str = typer.Option(
+        ...,
+        "--phone",
+        help="不分业绩员工手机号。",
+    ),
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+) -> None:
+    parsed_transaction_ids = _parse_transaction_ids(transaction_ids)
+
+    api = _build_api()
+    data = api.card.performance_clear(
+        transaction_ids=parsed_transaction_ids,
+        phone=phone,
+        center_id=center_id,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+@app.command("sale-performance-update", help="更新售卡业绩数据")
+@command_handler
+def sale_performance_update(
+    payload: str = typer.Option(
+        ...,
+        "--payload",
+        help="业绩更新列表，JSON 数组字符串。[{\\\"transactionId\\\":1, \\\"performance\\\":[{\\\"sellerName\\\":\\\"测试\", \\\"amount\\\":10.0}]}]",
+    ),
+    phone: str = typer.Option(
+        ...,
+        "--phone",
+        help="不分业绩员工手机号。",
+    ),
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+) -> None:
+    parsed_payload = _parse_performance_update_payload(payload)
+
+    api = _build_api()
+    data = api.card.performance_update(
+        phone=phone,
+        transactions=parsed_payload,
+        center_id=center_id,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+@app.command("sale-performance-new", help="录卡合同业绩数据")
+@command_handler
+def sale_performance_new(
+    type_: int = typer.Option(
+        ...,
+        "--type",
+        min=1,
+        max=2,
+        help="卡类型：1会员卡，2培训卡。",
+    ),
+    payload: str = typer.Option(
+        ...,
+        "--payload",
+        help="待录单合同列表，JSON 对象字符串。{\\\"data\":[{\\\"seq\\\":1,\\\"date\\\":\"2026-01-01\\\",\\\"activateNow\\\":true,\\\"phone\\\":\\\"xxx\\\",\\\"name\\\":\\\"xxxx\\\",\\\"cardName\\\":\\\"xxx\\\",\n\\\"contractNum\\\":\\\"xxx\\\",\\\"count\\\":3,\\\"payAmount\\\":1000,\\\"payMethod\\\":\\\"\\\",\n\\\"payAmount2\\\":1000,\\\"payMethod2\\\":\\\"\\\",\\\"performanceAmount\\\":2000,\n\\\"performance\\\":[{\\\"sellerName\\\":\\\"xxx\\\",\\\"amount\\\":2000}],\\\"saleType\\\":\\\"新卡\\\",\\\"remarks\\\":\\\"\\\",\\\"noPerformancePhone\\\":\\\"xxx\\\"}]} ",
+    ),
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+) -> None:
+    parsed_payload = _parse_performance_new_payload(payload)
+
+    api = _build_api()
+    data = api.card.performance_new(
+        type_=type_,
+        payload=parsed_payload,
+        center_id=center_id,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+@command_handler
+def studio_contract_list(
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+    card_type: int = typer.Option(
+        -1,
+        "--card-type",
+        help="卡种类型：-1全部，3期限卡，4次卡，5储值卡。",
+    ),
+    card_ids: str = typer.Option(
+        "",
+        "--card-ids",
+        help="卡种ID，英文逗号分隔，例如 1,2,3。",
+    ),
+    status: int = typer.Option(
+        99,
+        "--status",
+        help="卡状态：-1全部，99有效卡，1已开卡，0未开卡，3已过期，2请假中，8停卡中，4已转让，5已退卡，6已升级，7已转店。",
+    ),
+    remain_start: int | None = typer.Option(
+        None,
+        "--remain-start",
+        min=0,
+        help="剩余开始，可选。",
+    ),
+    remain_end: int | None = typer.Option(
+        None,
+        "--remain-end",
+        min=0,
+        help="剩余结束，可选。",
+    ),
+    sale_type: int = typer.Option(
+        -1,
+        "--sale-type",
+        help="销售类型：-1全部，11新卡，12续卡，13转卡，14升级卡，15退卡，19转店。",
+    ),
+    contract_status: int = typer.Option(
+        -1,
+        "--contract-status",
+        help="合同状态：-1全部，1电子合同，2纸质合同，3无合同，4电子合同(未签署)。",
+    ),
+    seller_id: int = typer.Option(
+        -1,
+        "--seller-id",
+        help="销售人ID，-1表示全部。",
+    ),
+    tag_id: int = typer.Option(
+        -1,
+        "--tag-id",
+        help="会员卡标签ID，-1表示全部。",
+    ),
+    card_create_start_date: str = typer.Option(
+        "",
+        "--card-create-start-date",
+        help="办卡开始日期，格式 YYYY-MM-DD。",
+    ),
+    card_create_end_date: str = typer.Option(
+        "",
+        "--card-create-end-date",
+        help="办卡结束日期，格式 YYYY-MM-DD。",
+    ),
+    card_activate_start_date: str = typer.Option(
+        "",
+        "--card-activate-start-date",
+        help="开卡开始日期，格式 YYYY-MM-DD。",
+    ),
+    card_activate_end_date: str = typer.Option(
+        "",
+        "--card-activate-end-date",
+        help="开卡结束日期，格式 YYYY-MM-DD。",
+    ),
+    card_expire_start_date: str = typer.Option(
+        "",
+        "--card-expire-start-date",
+        help="过期开始日期，格式 YYYY-MM-DD。",
+    ),
+    card_expire_end_date: str = typer.Option(
+        "",
+        "--card-expire-end-date",
+        help="过期结束日期，格式 YYYY-MM-DD。",
+    ),
+    course_start_date: str = typer.Option(
+        "",
+        "--course-start-date",
+        help="最后上课开始日期，格式 YYYY-MM-DD。",
+    ),
+    course_end_date: str = typer.Option(
+        "",
+        "--course-end-date",
+        help="最后上课结束日期，格式 YYYY-MM-DD。",
+    ),
+    page_num: int = typer.Option(
+        ...,
+        "--page-num",
+        min=0,
+        help="页码，从 0 开始。",
+    ),
+    page_size: int = typer.Option(
+        ...,
+        "--page-size",
+        min=1,
+        help="每页数量，必须大于等于 1。",
+    ),
+    type_: int = typer.Option(
+        0,
+        "--type",
+        min=0,
+        max=2,
+        help="合同类型：0全部合同，1会员卡合同，2课程卡合同。",
+    ),
+) -> None:
+    _validate_allowed_option(
+        card_type,
+        {-1, 3, 4, 5},
+        option_name="card-type",
+        description="-1、3、4、5",
+    )
+    _validate_allowed_option(
+        status,
+        {-1, 99, 1, 0, 3, 2, 8, 4, 5, 6, 7},
+        option_name="status",
+        description="-1、0、1、2、3、4、5、6、7、8、99",
+    )
+    _validate_allowed_option(
+        sale_type,
+        {-1, 11, 12, 13, 14, 15, 19},
+        option_name="sale-type",
+        description="-1、11、12、13、14、15、19",
+    )
+    _validate_allowed_option(
+        contract_status,
+        {-1, 1, 2, 3, 4},
+        option_name="contract-status",
+        description="-1、1、2、3、4",
+    )
+    if remain_start is not None and remain_end is not None and remain_start > remain_end:
+        raise ConfigValidationError("--remain-start 不能大于 --remain-end。")
+
+    validate_optional_date_order(
+        card_create_start_date,
+        card_create_end_date,
+        start_option_name="card-create-start-date",
+        end_option_name="card-create-end-date",
+    )
+    validate_optional_date_order(
+        card_activate_start_date,
+        card_activate_end_date,
+        start_option_name="card-activate-start-date",
+        end_option_name="card-activate-end-date",
+    )
+    validate_optional_date_order(
+        card_expire_start_date,
+        card_expire_end_date,
+        start_option_name="card-expire-start-date",
+        end_option_name="card-expire-end-date",
+    )
+    validate_optional_date_order(
+        course_start_date,
+        course_end_date,
+        start_option_name="course-start-date",
+        end_option_name="course-end-date",
+    )
+
+    parsed_card_ids = _parse_card_ids(card_ids)
+    api = _build_api()
+    data = api.card.studio_contract_list(
+        center_id=center_id,
+        page_num=page_num,
+        page_size=page_size,
+        type_=type_,
+        card_type=card_type,
+        card_ids=parsed_card_ids,
+        status=status,
+        remain_start=remain_start,
+        remain_end=remain_end,
+        sale_type=sale_type,
+        contract_status=contract_status,
+        seller_id=seller_id,
+        tag_id=tag_id,
+        card_create_start_date=card_create_start_date,
+        card_create_end_date=card_create_end_date,
+        card_activate_start_date=card_activate_start_date,
+        card_activate_end_date=card_activate_end_date,
+        card_expire_start_date=card_expire_start_date,
+        card_expire_end_date=card_expire_end_date,
+        course_start_date=course_start_date,
+        course_end_date=course_end_date,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+@command_handler
+def contract_detail(
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+    contract_id: str = typer.Option(
+        ...,
+        "--contract-id",
+        help="合同ID。",
+    ),
+) -> None:
+    api = _build_api()
+    data = api.card.contract_detail(center_id=center_id, contract_id=contract_id)
+    print_json({"status": "ok", "data": data})
+
+
+@command_handler
+def studio_sale_performance(
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+    start_date: str = typer.Option(
+        ...,
+        "--start-date",
+        help="开始日期，格式 YYYY-MM-DD。",
+    ),
+    end_date: str = typer.Option(
+        ...,
+        "--end-date",
+        help="结束日期，格式 YYYY-MM-DD。",
+    ),
+    seller_id: int = typer.Option(
+        -1,
+        "--seller-id",
+        help="销售人ID，-1表示全部。",
+    ),
+    type_: int = typer.Option(
+        0,
+        "--type",
+        min=0,
+        max=2,
+        help="业绩类型：0全部业绩，1会员卡业绩，2课程卡业绩。",
+    ),
+    card_ids: str = typer.Option(
+        "",
+        "--card-ids",
+        help="卡种ID，英文逗号分隔，例如 1,2,3。",
+    ),
+    tag_ids: str = typer.Option(
+        "",
+        "--tag-ids",
+        help="会员卡标签ID，英文逗号分隔，例如 1,2,3。",
+    ),
+    page_num: int = typer.Option(
+        0,
+        "--page-num",
+        min=0,
+        help="页码，从 0 开始。",
+    ),
+    page_size: int = typer.Option(
+        20,
+        "--page-size",
+        min=1,
+        help="每页数量，必须大于等于 1。",
+    ),
+) -> None:
+    validate_date_range(start_date, end_date)
+
+    parsed_card_ids = _parse_card_ids(card_ids)
+    parsed_tag_ids = _parse_tag_ids(tag_ids)
+    api = _build_api()
+    data = api.card.studio_sale(
+        center_id=center_id,
+        start_date=start_date,
+        end_date=end_date,
+        type_=type_,
+        seller_id=seller_id,
+        card_ids=parsed_card_ids,
+        tag_ids=parsed_tag_ids,
+        page_num=page_num,
+        page_size=page_size,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+@command_handler
+def studio_private_consume_performance(
+    center_id: str = typer.Option(
+        ...,
+        "--center-id",
+        help="门店ID。",
+    ),
+    start_date: str = typer.Option(
+        ...,
+        "--start-date",
+        help="开始日期，格式 YYYY-MM-DD。",
+    ),
+    end_date: str = typer.Option(
+        ...,
+        "--end-date",
+        help="结束日期，格式 YYYY-MM-DD。",
+    ),
+    trainer_id: int = typer.Option(
+        -1,
+        "--trainer-id",
+        help="教练ID，-1表示全部。",
+    ),
+    teach_mode: int = typer.Option(
+        -1,
+        "--teach-mode",
+        help="售课方式：-1全部，1一对一，2一对多。",
+    ),
+    page_num: int = typer.Option(
+        ...,
+        "--page-num",
+        min=0,
+        help="页码，从 0 开始，必填。",
+    ),
+    page_size: int = typer.Option(
+        ...,
+        "--page-size",
+        min=1,
+        help="每页数量，必须大于等于 1，必填。",
+    ),
+) -> None:
+    validate_date_range(start_date, end_date)
+    _validate_allowed_option(
+        teach_mode,
+        {-1, 1, 2},
+        option_name="teach-mode",
+        description="-1、1、2",
+    )
+
+    api = _build_api()
+    data = api.card.studio_private_consume_performance(
+        center_id=center_id,
+        start_date=start_date,
+        end_date=end_date,
+        trainer_id=trainer_id,
+        teach_mode=teach_mode,
+        page_num=page_num,
+        page_size=page_size,
+    )
+    print_json({"status": "ok", "data": data})
+
+
+studio_app = typer.Typer(help="卡相关命令。", invoke_without_command=True)
+studio_app.callback()(card_root)
+studio_app.command("sale-performance", help="销售业绩报表")(studio_sale_performance)
+studio_app.command("sale-performance-clear", help="清除售卡业绩数据")(sale_performance_clear)
+studio_app.command("sale-performance-update", help="更新售卡业绩数据")(sale_performance_update)
+studio_app.command("sale-performance-new", help="录卡合同业绩数据")(sale_performance_new)
+studio_app.command("contract-list", help="获取合同列表")(studio_contract_list)
+studio_app.command("contract-detail", help="获取合同详情")(contract_detail)
+studio_app.command("private-consume-performance", help="获取私教上课业绩报表")(
+    studio_private_consume_performance
+)