sophhub 0.4.45 → 0.4.47

package/skills/sophnet-invoice-assistant/src/scripts/risk_rules.py

@@ -0,0 +1,95 @@
+"""Risk classification rules for the invoice assistant skeleton."""
+
+from __future__ import annotations
+
+KEYWORD_LAST = "\u4e0a\u6b21"
+KEYWORD_RECENT = "\u6700\u8fd1"
+KEYWORD_LATEST = "\u6700\u65b0"
+
+TEMPLATE_FIELD_NAMES = (
+    "buyerType",
+    "title",
+    "taxNo",
+    "addressPhone",
+    "bankAccount",
+    "invoiceType",
+)
+
+
+def _normalize_text(value):
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _selected_trans_nos(request):
+    return [item.strip() for item in str(request.recharge_trans_nos or "").split(",") if item.strip()]
+
+
+def _requests_latest_template(request):
+    text = request.user_request or ""
+    return bool(
+        request.use_latest_template
+        or KEYWORD_LAST in text
+        or KEYWORD_RECENT in text
+        or KEYWORD_LATEST in text
+    )
+
+
+def _same_template(left, right):
+    if not left or not right:
+        return False
+    left_id = left.get("id")
+    right_id = right.get("id")
+    if left_id is not None and right_id is not None:
+        return str(left_id) == str(right_id)
+    return _normalize_text(left.get("templateName")) == _normalize_text(right.get("templateName"))
+
+
+def _payload_matches_template(payload, template):
+    if not payload or not template:
+        return False
+    for field_name in TEMPLATE_FIELD_NAMES:
+        if _normalize_text(payload.get(field_name)) != _normalize_text(template.get(field_name)):
+            return False
+    return True
+
+
+def classify_submit_risk(request, payload=None, template=None, latest_template=None, selected_records=None):
+    selected_records = selected_records or []
+    values = _selected_trans_nos(request)
+
+    if request.save_as_template:
+        return {
+            "level": "high",
+            "reason": "save_as_template_requires_confirmation",
+        }
+    if len(values) != 1 or len(selected_records) != 1:
+        return {
+            "level": "high",
+            "reason": "single_recharge_record_required",
+        }
+    if not _requests_latest_template(request):
+        return {
+            "level": "high",
+            "reason": "latest_template_reuse_not_requested",
+        }
+    if not template or not latest_template:
+        return {
+            "level": "high",
+            "reason": "latest_template_not_available",
+        }
+    if not _same_template(template, latest_template):
+        return {
+            "level": "high",
+            "reason": "selected_template_is_not_latest",
+        }
+    if not _payload_matches_template(payload, template):
+        return {
+            "level": "high",
+            "reason": "invoice_fields_changed_from_template",
+        }
+    return {
+        "level": "low",
+        "reason": "latest_template_with_single_record_and_matching_fields",
+    }

package/skills/sophnet-invoice-assistant/src/scripts/status_flow.py

@@ -0,0 +1,69 @@
+"""Invoice application status query skeleton."""
+
+from __future__ import annotations
+
+from invoice_client import InvoiceClientError
+from output import build_result, failure
+
+
+def _build_status_message(application):
+    status = application.get("status")
+    application_no = application.get("applicationNo")
+    if status == "ISSUED":
+        return "Invoice application {0} has been issued and is ready for download.".format(application_no)
+    if status == "REJECTED":
+        return "Invoice application {0} was rejected. Check the reject reason before retrying.".format(application_no)
+    return "Invoice application {0} is still being processed.".format(application_no)
+
+
+def run_status(request, auth_context, client):
+    if not auth_context.is_authenticated:
+        return failure(
+            action=request.action,
+            error_code="AUTH_CONTEXT_MISSING",
+            error_message="Current Sophnet auth context is missing. Please log in again.",
+        )
+
+    try:
+        org = client.get_current_personal_org(request.org_id)
+        params = {"pageNum": 1, "pageSize": 10}
+        if request.application_no:
+            params["applicationNo"] = request.application_no
+        page = client.list_invoice_applications(org.get("id"), params=params)
+    except InvoiceClientError as exc:
+        return failure(
+            action=request.action,
+            error_code=exc.code,
+            error_message=exc.message,
+        )
+
+    items = []
+    if isinstance(page, dict):
+        items = page.get("list") or []
+    if not items:
+        return failure(
+            action=request.action,
+            error_code="NO_APPLICATION_FOUND",
+            error_message="No invoice application was found under the current personal org.",
+            extra={"ORG_ID": str(org.get("id"))},
+        )
+
+    application = items[0]
+    return build_result(
+        status="succeeded",
+        action=request.action,
+        message=_build_status_message(application),
+        extra={
+            "ORG_ID": str(org.get("id")),
+            "ORG_NAME": org.get("name") or "",
+            "APPLICATION_NO": application.get("applicationNo") or "",
+            "APPLICATION_STATUS": application.get("status") or "",
+            "TITLE": application.get("title") or "",
+            "AMOUNT": str(application.get("amount") or ""),
+            "HAS_INVOICE_FILE": str(bool(application.get("hasInvoiceFile"))).lower(),
+            "APPLIED_AT": application.get("appliedAt") or "",
+            "ISSUED_AT": application.get("issuedAt") or "",
+            "REJECT_REASON": application.get("rejectReason") or "",
+            "RESULT_COUNT": str(len(items)),
+        },
+    )

package/skills/sophnet-invoice-assistant/src/scripts/submit_flow.py

@@ -0,0 +1,472 @@
+"""Submit invoice application flow."""
+
+from __future__ import annotations
+
+from invoice_client import InvoiceClientError
+from output import build_result, failure, need_confirmation
+from risk_rules import classify_submit_risk
+
+
+VALID_BUYER_TYPES = ("INDIVIDUAL", "ENTERPRISE")
+VALID_INVOICE_TYPES = ("NORMAL", "SPECIAL")
+VALID_ISSUING_MODES = ("AGGREGATED", "SEPARATE")
+INVOICE_ELIGIBLE_START_DATE = "2026-06-24"
+
+KEYWORD_ENTERPRISE = "\u4f01\u4e1a"
+KEYWORD_COMPANY = "\u516c\u53f8"
+KEYWORD_SPECIAL_SHORT = "\u4e13\u7968"
+KEYWORD_SPECIAL_LONG = "\u4e13\u7528\u53d1\u7968"
+KEYWORD_NORMAL_SHORT = "\u666e\u7968"
+KEYWORD_NORMAL_LONG = "\u666e\u901a\u53d1\u7968"
+KEYWORD_LAST = "\u4e0a\u6b21"
+KEYWORD_RECENT = "\u6700\u8fd1"
+KEYWORD_LATEST = "\u6700\u65b0"
+KEYWORD_THAT_ONE = "\u90a3\u7b14"
+KEYWORD_AGGREGATED = "\u805a\u5408"
+KEYWORD_SUM = "\u5408\u5e76"
+KEYWORD_TOTAL = "\u6c47\u603b"
+KEYWORD_SINGLE = "\u5206\u5f00"
+KEYWORD_SEPARATE = "\u5355\u72ec"
+KEYWORD_EACH = "\u6bcf\u6761"
+
+
+def _normalize_text(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _normalize_tax_no(value):
+    text = _normalize_text(value)
+    return text.upper() if text else None
+
+
+def _normalize_trans_nos(value):
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple)):
+        raw_values = value
+    else:
+        raw_values = str(value).split(",")
+
+    result = []
+    seen = set()
+    for item in raw_values:
+        current = str(item).strip()
+        if not current or current in seen:
+            continue
+        seen.add(current)
+        result.append(current)
+    return result
+
+
+def _record_created_at(record):
+    value = record.get("createdAt") or record.get("rechargedAt")
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _is_record_eligible(record):
+    created_at = _record_created_at(record)
+    if not created_at:
+        return False
+    return created_at[:10] >= INVOICE_ELIGIBLE_START_DATE
+
+
+def _filter_eligible_records(records):
+    eligible = []
+    ineligible = []
+    for item in records or []:
+        if _is_record_eligible(item):
+            eligible.append(item)
+        else:
+            ineligible.append(item)
+    return eligible, ineligible
+
+
+def _resolve_issuing_mode(request, trans_nos, fallback_mode=None):
+    explicit = _normalize_text(request.issuing_mode)
+    if explicit in VALID_ISSUING_MODES:
+        return explicit, None
+
+    normalized_fallback = _normalize_text(fallback_mode)
+    if normalized_fallback in VALID_ISSUING_MODES and len(trans_nos) > 1:
+        return normalized_fallback, None
+
+    if len(trans_nos) <= 1:
+        return None, None
+
+    text = request.user_request or ""
+    if KEYWORD_AGGREGATED in text or KEYWORD_SUM in text or KEYWORD_TOTAL in text:
+        return "AGGREGATED", None
+    if KEYWORD_SINGLE in text or KEYWORD_SEPARATE in text or KEYWORD_EACH in text:
+        return "SEPARATE", None
+
+    return None, "issuingMode"
+
+
+def _parse_buyer_type(request):
+    if request.buyer_type in VALID_BUYER_TYPES:
+        return request.buyer_type
+    text = request.user_request or ""
+    if KEYWORD_ENTERPRISE in text or KEYWORD_COMPANY in text:
+        return "ENTERPRISE"
+    return "INDIVIDUAL"
+
+
+def _parse_invoice_type(request, buyer_type):
+    if request.invoice_type in VALID_INVOICE_TYPES:
+        return request.invoice_type
+    text = request.user_request or ""
+    if KEYWORD_SPECIAL_SHORT in text or KEYWORD_SPECIAL_LONG in text:
+        return "SPECIAL"
+    if KEYWORD_NORMAL_SHORT in text or KEYWORD_NORMAL_LONG in text:
+        return "NORMAL"
+    if buyer_type == "ENTERPRISE":
+        return "SPECIAL"
+    return "NORMAL"
+
+
+def _get_field_requirements(buyer_type, invoice_type):
+    if buyer_type == "INDIVIDUAL":
+        return {
+            "tax_no": False,
+            "address_phone": False,
+            "bank_account": False,
+            "allow_special": False,
+        }
+    if invoice_type == "NORMAL":
+        return {
+            "tax_no": True,
+            "address_phone": False,
+            "bank_account": False,
+            "allow_special": True,
+        }
+    return {
+        "tax_no": True,
+        "address_phone": True,
+        "bank_account": True,
+        "allow_special": True,
+    }
+
+
+def _sort_templates(templates):
+    def sort_key(item):
+        return item.get("updatedAt") or ""
+
+    return sorted(templates or [], key=sort_key, reverse=True)
+
+
+def _find_latest_template(templates):
+    sorted_items = _sort_templates(templates)
+    return sorted_items[0] if sorted_items else None
+
+
+def _find_template_by_name(templates, template_name):
+    target = _normalize_text(template_name)
+    if not target:
+        return None
+    for item in templates or []:
+        if _normalize_text(item.get("templateName")) == target:
+            return item
+    return None
+
+
+def _resolve_template(request, templates):
+    named = _find_template_by_name(templates, request.template_name)
+    if named is not None:
+        return named
+    text = request.user_request or ""
+    if request.use_latest_template or KEYWORD_LAST in text or KEYWORD_RECENT in text or KEYWORD_LATEST in text:
+        return _find_latest_template(templates)
+    return None
+
+
+def _infer_recharge_records(request, records):
+    explicit = _normalize_trans_nos(request.recharge_trans_nos)
+    if explicit:
+        return explicit, None
+
+    eligible_records, ineligible_records = _filter_eligible_records(records)
+    available = [item for item in eligible_records if item.get("invoiceStatus") == "AVAILABLE"]
+    if not available:
+        if ineligible_records:
+            return [], (
+                "Recharge records before 2026-06-24 are not invoiceable. "
+                "Please choose recharge records on or after 2026-06-24."
+            )
+        return [], "No invoiceable recharge records are currently available."
+
+    if len(available) == 1:
+        return [available[0].get("transNo")], None
+
+    text = request.user_request or ""
+    if KEYWORD_RECENT in text or KEYWORD_THAT_ONE in text or KEYWORD_LATEST in text:
+        return [available[0].get("transNo")], None
+
+    return [], "Multiple invoiceable recharge records are available. Please specify rechargeTransNos."
+
+
+def _select_record_map(records, trans_nos):
+    lookup = {}
+    for item in records or []:
+        trans_no = item.get("transNo")
+        if trans_no:
+            lookup[str(trans_no)] = item
+    return [lookup[item] for item in trans_nos if item in lookup]
+
+
+def _sum_amount(records):
+    total = 0.0
+    for item in records:
+        try:
+            total += float(item.get("changeAmount") or 0)
+        except (TypeError, ValueError):
+            continue
+    return total
+
+
+def _validate_fields(buyer_type, invoice_type, title, tax_no, address_phone, bank_account):
+    requirements = _get_field_requirements(buyer_type, invoice_type)
+    missing = []
+    if not title:
+        missing.append("title")
+    if invoice_type == "SPECIAL" and not requirements["allow_special"]:
+        return ["invoiceType"]
+    if requirements["tax_no"] and not tax_no:
+        missing.append("taxNo")
+    if requirements["address_phone"] and not address_phone:
+        missing.append("addressPhone")
+    if requirements["bank_account"] and not bank_account:
+        missing.append("bankAccount")
+    return missing
+
+
+def _resolve_template_name(request, template):
+    return (
+        _normalize_text(request.template_name)
+        or _normalize_text(template.get("templateName") if template else None)
+        or _normalize_text(request.title)
+    )
+
+
+def _build_payload(request, template, records):
+    buyer_type = _parse_buyer_type(request)
+    invoice_type = _parse_invoice_type(request, buyer_type)
+
+    title = _normalize_text(request.title) or _normalize_text(template.get("title") if template else None)
+    tax_no = _normalize_tax_no(request.tax_no) or _normalize_tax_no(template.get("taxNo") if template else None)
+    address_phone = _normalize_text(request.address_phone) or _normalize_text(template.get("addressPhone") if template else None)
+    bank_account = _normalize_text(request.bank_account) or _normalize_text(template.get("bankAccount") if template else None)
+
+    eligible_records, _ = _filter_eligible_records(records)
+    trans_nos, trans_no_error = _infer_recharge_records(request, eligible_records)
+    if trans_no_error:
+        return None, [trans_no_error], []
+
+    selected_records = _select_record_map(eligible_records, trans_nos)
+    if len(selected_records) != len(trans_nos):
+        return None, [
+            "One or more rechargeTransNos are not invoiceable. "
+            "Recharge records before 2026-06-24 are not supported."
+        ], trans_nos
+
+    issuing_mode, issuing_mode_error = _resolve_issuing_mode(request, trans_nos)
+    if issuing_mode_error:
+        return None, [issuing_mode_error], trans_nos
+
+    missing_fields = _validate_fields(
+        buyer_type,
+        invoice_type,
+        title,
+        tax_no,
+        address_phone,
+        bank_account,
+    )
+    if not trans_nos:
+        missing_fields.append("rechargeTransNos")
+    resolved_template_name = _resolve_template_name(request, template)
+    if not resolved_template_name:
+        missing_fields.append("templateName")
+    if missing_fields:
+        return None, missing_fields, trans_nos
+
+    payload = {
+        "buyerType": buyer_type,
+        "title": title,
+        "invoiceType": invoice_type,
+        "rechargeTransNos": trans_nos,
+    }
+    if tax_no:
+        payload["taxNo"] = tax_no
+    if address_phone:
+        payload["addressPhone"] = address_phone
+    if bank_account:
+        payload["bankAccount"] = bank_account
+    if issuing_mode:
+        payload["issuingMode"] = issuing_mode
+    payload["saveAsTemplate"] = True
+    payload["templateName"] = resolved_template_name
+    return payload, [], trans_nos
+
+
+def _build_confirmation_summary(payload, selected_records, template):
+    source = "latest template" if template else "manual input"
+    return (
+        "Submit invoice with buyerType={buyerType}, title={title}, invoiceType={invoiceType}, "
+        "rechargeTransNos={transNos}, issuingMode={issuingMode}, amount={amount:.2f}, source={source}"
+    ).format(
+        buyerType=payload.get("buyerType"),
+        title=payload.get("title"),
+        invoiceType=payload.get("invoiceType"),
+        transNos=",".join(payload.get("rechargeTransNos") or []),
+        issuingMode=payload.get("issuingMode") or "",
+        amount=_sum_amount(selected_records),
+        source=source,
+    )
+
+
+def _requests_latest_template(request, template, latest_template):
+    text = request.user_request or ""
+    if not template or not latest_template:
+        return False
+    template_id = template.get("id")
+    latest_template_id = latest_template.get("id")
+    same_latest = False
+    if template_id is not None and latest_template_id is not None:
+        same_latest = str(template_id) == str(latest_template_id)
+    elif _normalize_text(template.get("templateName")) and _normalize_text(template.get("templateName")) == _normalize_text(latest_template.get("templateName")):
+        same_latest = True
+    return bool(
+        same_latest and (
+            request.use_latest_template
+            or KEYWORD_LAST in text
+            or KEYWORD_RECENT in text
+            or KEYWORD_LATEST in text
+        )
+    )
+
+
+def run_submit(request, auth_context, client):
+    if not auth_context.is_authenticated:
+        return failure(
+            action=request.action,
+            error_code="AUTH_CONTEXT_MISSING",
+            error_message="Current Sophnet auth context is missing. Please log in again.",
+        )
+
+    try:
+        org = client.get_current_personal_org(request.org_id)
+        templates = client.list_invoice_templates(org.get("id")) or []
+        records_page = client.list_invoiceable_recharge_records(
+            org.get("id"),
+            params={"pageNum": 1, "pageSize": 100, "invoiceableOnly": "true"},
+        )
+        records = records_page.get("list") or [] if isinstance(records_page, dict) else []
+        eligible_records, ineligible_records = _filter_eligible_records(records)
+        latest_template = _find_latest_template(templates)
+        template = _resolve_template(request, templates)
+        payload, missing_fields, trans_nos = _build_payload(request, template, eligible_records)
+        if payload is None:
+            if len(missing_fields) == 1 and "Multiple invoiceable recharge records" in missing_fields[0]:
+                available_records = [item for item in eligible_records if item.get("invoiceStatus") == "AVAILABLE"]
+                return need_confirmation(
+                    action=request.action,
+                    summary="Selectable recharge records: {0}".format(
+                        ", ".join([str(item.get("transNo") or "") for item in available_records[:10]])
+                    ),
+                    message="Please specify rechargeTransNos before submitting the invoice request.",
+                    extra={
+                        "ORG_ID": str(org.get("id")),
+                        "CANDIDATE_RECHARGE_TRANS_NOS": ",".join(
+                            [str(item.get("transNo") or "") for item in available_records[:10]]
+                        ),
+                    },
+                )
+            if "issuingMode" in missing_fields:
+                available_records = [item for item in eligible_records if item.get("invoiceStatus") == "AVAILABLE"]
+                return need_confirmation(
+                    action=request.action,
+                    summary="Selected multiple recharge records. Please choose issuingMode=AGGREGATED or SEPARATE.",
+                    message="When one invoice application contains multiple recharge records, you must choose aggregated or separate invoicing.",
+                    extra={
+                        "ORG_ID": str(org.get("id")),
+                        "CANDIDATE_RECHARGE_TRANS_NOS": ",".join(
+                            [str(item.get("transNo") or "") for item in available_records[:10]]
+                        ),
+                        "AVAILABLE_ISSUING_MODES": ",".join(VALID_ISSUING_MODES),
+                    },
+                )
+            return failure(
+                action=request.action,
+                error_code="MISSING_REQUIRED_FIELDS",
+                error_message="Missing required submit fields: {0}".format(",".join(missing_fields)),
+                extra={
+                    "ORG_ID": str(org.get("id")),
+                    "INELIGIBLE_RECHARGE_RECORD_COUNT": str(len(ineligible_records)),
+                },
+            )
+
+        selected_records = _select_record_map(eligible_records, trans_nos)
+        request.buyer_type = payload.get("buyerType")
+        request.invoice_type = payload.get("invoiceType")
+        request.recharge_trans_nos = ",".join(payload.get("rechargeTransNos") or [])
+        request.issuing_mode = payload.get("issuingMode")
+        request.use_latest_template = _requests_latest_template(
+            request,
+            template,
+            latest_template,
+        )
+        risk = classify_submit_risk(
+            request,
+            payload=payload,
+            template=template,
+            latest_template=latest_template,
+            selected_records=selected_records,
+        )
+        if risk["level"] == "high" and not request.confirm:
+            return need_confirmation(
+                action=request.action,
+                summary=_build_confirmation_summary(payload, selected_records, template),
+                message="Please confirm the invoice details before submission.",
+                extra={
+                    "ORG_ID": str(org.get("id")),
+                    "RISK_LEVEL": risk.get("level") or "",
+                    "RISK_REASON": risk.get("reason") or "",
+                    "BUYER_TYPE": payload.get("buyerType") or "",
+                    "TITLE": payload.get("title") or "",
+                    "INVOICE_TYPE": payload.get("invoiceType") or "",
+                    "RECHARGE_TRANS_NOS": ",".join(payload.get("rechargeTransNos") or []),
+                    "ISSUING_MODE": payload.get("issuingMode") or "",
+                },
+            )
+
+        application = client.create_invoice_application(org.get("id"), payload)
+    except InvoiceClientError as exc:
+        return failure(
+            action=request.action,
+            error_code=exc.code,
+            error_message=exc.message,
+        )
+
+    return build_result(
+        status="succeeded",
+        action=request.action,
+        message="Invoice application was submitted successfully.",
+        extra={
+            "ORG_ID": str(org.get("id")),
+            "ORG_NAME": org.get("name") or "",
+            "RISK_LEVEL": risk.get("level") or "",
+            "RISK_REASON": risk.get("reason") or "",
+            "APPLICATION_NO": application.get("applicationNo") or "",
+            "APPLICATION_STATUS": application.get("status") or "",
+            "TITLE": application.get("title") or "",
+            "AMOUNT": str(application.get("amount") or ""),
+            "ISSUING_MODE": payload.get("issuingMode") or "",
+            "HAS_INVOICE_FILE": str(bool(application.get("hasInvoiceFile"))).lower(),
+            "INELIGIBLE_RECHARGE_RECORD_COUNT": str(len(ineligible_records)),
+            "INVOICE_ELIGIBLE_START_DATE": INVOICE_ELIGIBLE_START_DATE,
+        },
+    )