"""快递鸟文档资源模型"""

from typing import Dict, List, Optional, Any
from pydantic import BaseModel

# 基本物流状态码及描述
BASIC_STATE_DESCRIPTIONS = {
    0: "暂无轨迹信息",
    1: "已揽收",
    2: "在途中",
    3: "已签收",
    4: "问题件",
    5: "转寄",
    6: "清关"
}

# 快递公司编码映射
SHIPPER_CODES = {
    # 常用快递公司
    "ZTO": "中通快递",
    "STO": "申通快递", 
    "YTO": "圆通速递",
    "YD": "韵达速递",
    "SF": "顺丰速运",
    "YZPY": "邮政快递包裹",
    "EMS": "EMS",
    "JD": "京东快递",
    "JDKY": "京东快运",
    "UC": "优速快递",
    "DBL": "德邦快递",
    "JTSD": "极兔速递",
    "CNSD": "菜鸟速递",
    "CNCY": "菜鸟橙运",
    "DNWL": "丹鸟物流",
    "HTKY": "百世快递",
    "BTWL": "百世快运",
    "HTKYKY": "百世快运（下单）",
    "ZJS": "宅急送",
    "ANE": "安能快递",
    "ANEKY": "安能快运",
    "DBLKY": "德邦快运",
    "CNDJWL": "菜鸟大件物流",
    "BAISHIGUOJI": "百世国际",
    "BAISHIYP": "百世云配",
    "KYSY": "跨越速运",
    "LB": "龙邦快递",
    "FASTGO": "速派快递",
    "GTKY": "高铁快运",
    "GTSD": "高铁速递",
    "HGLL": "黑狗冷链",
    "HHLL": "黑狗冷链",
    "MB": "民邦快递",
    "MHKD": "民航快递",
    
    # 国际快递
    "TNT": "TNT快递",
    "UPS": "UPS快递",
    "FEDEX": "FedEx联邦快递",
    "DHL": "DHL快递",
    "ARAMEX": "Aramex",
    "DPEX": "DPEX国际快递",
    "CA": "加拿大邮政",
    "AUSTRIAPOST": "奥地利邮政",
    "BLSYZ": "比利时邮政",
    "AOMENYZ": "澳门邮政",
    "ANTILLESPOST": "荷属安的列斯荷兰邮政",
    "CJKOREAEXPRESS": "大韩通运",
    "CARGOLUX": "卢森堡航空",
    "HKPOST": "香港邮政",
    "KOREAPOSTKR": "韩国邮政韩文",
    "GJYZBG": "国际邮政包裹",
    "LEOPARD": "云豹国际货运",
    "LIANBANGKUAIDIEN": "联邦快递-英文",
    "LUNDAO": "论道国际物流",
    "MAPLEEXPRESS": "今枫国际快运",
    "MEIXI": "美西快递",
    
    # 其他快递公司
    "HOAU": "天地华宇",
    "HHWL": "华翰物流",
    "XFEX": "信丰物流",
    "YDKY": "韵达快运",
    "ZTOZY": "中通智运",
    "ZTOCC": "中通冷链",
    "AMAZON": "亚马逊物流",
    "PJ": "品骏快递",
    "SUBIDA": "速必达物流",
    "SDEZ": "速递e站",
    "AJ": "安捷快递",
    "AX": "安迅物流",
    "AYUS": "安邮美国",
    "ADD": "澳多多",
    "AYCA": "澳邮专线",
    "AXD": "安鲜达",
    "ANMIN56": "安敏物流",
    "ANNTO": "安得物流",
    "AUODEXPRESS": "澳德物流",
    "A4PX": "转运四方",
    "A2U": "A2U速递",
    "AAE": "AAE全球专递",
    "ALWL": "安鹿物流",
    "BDT": "八达通",
    "BETWL": "百腾物流",
    "BNTWL": "奔腾物流",
    "BFAY": "八方安运",
    "BAOTONGKD": "宝通快递",
    "BJY": "8+1物流",
    "CITY100": "城市100",
    "CEVA": "CEVA物流",
    "CJKD": "城际快递",
    "CTWL": "长通物流",
    "CNPEX": "CNPEX中邮快递",
    "COE": "COE东方快递",
    "CFWL": "春风物流",
    "CHTWL": "广东诚通物流",
    "CXHY": "传喜物流",
    "CLP": "科力普",
    "DSWL": "D速物流",
    "DLG": "到了港",
    "DTWL": "大田物流",
    "DDOTBASE": "叮当同城",
    "DDWL": "多道物流",
    "ETK": "E特快",
    "FKD": "飞康达",
    "FYP": "丰云配",
    "FYKD": "凡宇货的",
    "FCWL": "丰程物流",
    "FEIKUAIDA": "飞快达",
    "FENGHUANGKUAIDI": "凤凰快递",
    "FENGTIANEXPRESS": "奉天物流",
    "FOURPXUS": "四方格",
    "FSEXP": "全速快递",
    "FUJISUYUN": "富吉速运",
    "FX": "法翔速运",
    "FBKD": "飞豹快递",
    "FANQIU": "泛球物流",
    "FBOX": "丰巢",
    "FRGYL": "复融供应链",
    "FT": "丰通快运",
    "GD": "冠达",
    "GDEMS": "广东邮政",
    "GSD": "共速达",
    "GDKJK56": "快捷快物流",
    "GDQWWL": "全网物流",
    "GDRZ58": "容智快运",
    "GOEX": "时安达速递",
    "GSWTKD": "万通快递",
    "GT": "冠泰",
    "GUANGDONGTONGLU": "广东通路",
    "GUANGDONGYONGBANG": "永邦快递",
    "GUEXP": "全联速运",
    "GUOERYUE": "天天快物流",
    "GZANJCWL": "广州安能聚创物流",
    "GZXINGCHENG": "贵州星程快递",
    "GTONG": "广通",
    "GAI": "迦递快递",
    "GKSD": "港快速递",
    "GDYDS": "广东易代收",
    "SHHJ": "弘家物流",
    "HLWL": "恒路物流",
    "HOTSCM": "鸿桥供应链",
    "HPTEX": "海派通物流公司",
    "hq568": "华强物流",
    "HXLWL": "华夏龙物流",
    "HDKD": "汇达快递",
    "HF": "汇丰物流",
    "HTWL": "鸿泰物流",
    "HQKY": "华企快运",
    "HXWL": "华兴物流",
    "HFHW": "合肥汇文",
    "HLONGWL": "辉隆物流",
    "HLD": "宏利德物流",
    "HAIHONGWANGSONG": "海红网送",
    "HANGYU": "航宇快递",
    "HAOXIANGWULIU": "豪翔物流",
    "HAPPYLINK": "开心快递",
    "HDWL": "宏递快运",
    "HEIMAO56": "黑猫速运",
    "HEXINEXPRESS": "合心速递",
    "HGY56": "环国运物流",
    "HHAIR56": "华瀚快递",
    "HIGHSINCE": "海欣斯快递",
    "HITAOE": "Hi淘易快递",
    "HJS": "猴急送物流",
    "HKEEX": "飞豹速递",
    "HLKYTJ": "互联快运",
    "HLPGYL": "共联配",
    "HLTOP": "海联快递",
    "HNSSD56": "顺时达物流",
    "CP74025905": "华鼎物流",
    "HNZQWL": "中强物流",
    "HOMECOURIER": "如家国际快递",
    "HOMEXPRESS": "居家通",
    "HONDURAS": "洪都拉斯",
    "HONGJIE": "宏捷国际物流",
    "HONGPINWULIU": "宏品物流",
    "HSGTSD": "海硕高铁速递",
    "HSLL": "户尚冷链物流",
    "HTKD": "恒通快递",
    "HUANDONGLG": "环东物流",
    "HUAXIAHUOYUN": "华夏货运",
    "HUIF56": "汇峰物流",
    "HUILIN56": "汇霖大货网",
    "HUOLALAWULIU": "货拉拉物流",
    "HUTONGWULIU": "户通物流",
    "HYESHIP": "鸿远物流",
    "HYK": "上海昊宏国际货物",
    "HYYTES": "恒宇运通",
    "HQKD": "华企快递",
    "HRWL": "韩润物流",
    "HYH": "货运皇物流",
    "HLYSD": "好来运快递",
    "HJWL": "皇家物流",
    "HISENSE": "海信物流",
    "HSSY": "汇森速运",
    "HTB56": "徽托邦物流",
    "IBUY8": "爱拜物流",
    "IEX": "泛太优达",
    "IGCAEXPRESS": "无限速递",
    "JAD": "捷安达",
    "JGSD": "京广速递",
    "JIUYE": "九曳供应链",
    "JXD": "急先达",
    "JYKD": "晋越快递",
    "JCEX": "佳成国际",
    "JCSUDA": "嘉诚速达",
    "JDPPLUS": "急递",
    "JETSTAREXP": "捷仕",
    "JIACHENEXPRESS": "佳辰国际速递",
    "JIAJIATONG56": "佳家通货运",
    "JIAJIAWL": "加佳物流",
    "JIAJIKUAIDI": "佳吉快递",
    "JIAXIANWULIU_HEZUO": "嘉贤物流",
    "JIEBORNE": "捷邦物流",
    "JIGUANG": "极光转运",
    "JINAN": "金岸物流",
    "JINCHENGWULIU": "锦程物流",
    "JINDUAN": "近端",
    "JSWL": "景顺物流",
    "JINTONGKD": "劲通快递",
    "JISU": "冀速物流",
    "JIUJIUWL": "久久物流",
    "JJX888": "佳捷翔物流",
    "JSDKY": "极速达",
    "JPKD": "绝配国际速递",
    "JRHYWL": "金润荷役物流",
    "JSEXPRESS": "骏绅物流",
    "JSSDT56": "时达通",
    "JUDING": "聚鼎物流",
    "JUMSTC": "聚盟共建",
    "JUNFENGGUOJI": "骏丰国际速递",
    "JUWU": "聚物物流",
    "JTKD": "捷特快递",
    "JYSY": "精英速运",
    "JYM": "加运美",
    "JGWL": "景光物流",
    "JYWL": "佳怡物流",
    "JDWL": "金大物流",
    "KFW": "快服务",
    "KSDWL": "快速递物流",
    "KAOLAEXPRESS": "考拉国际速递",
    "KEJIE": "科捷物流",
    "KERRYTJ": "嘉里大荣物流",
    "KEYPON": "启邦国际物流",
    "KZWL": "科紫物流",
    "KHFD": "快航飞递",
    "KOALAEXP": "考拉速递",
    "KRTAO": "淘韩国际快递",
    "KUAIYOUDA": "四川快优达速递",
    "KXDA": "凯信达",
    "KBSY": "快8速运",
    "LANJUNSUYUN": "岚骏速运",
    "LHKD": "蓝弧快递",
    "LAHUOEX": "拉火速运",
    "LANBIAOKUAIDI": "蓝镖快递",
    "CPSLDWL": "蓝桥TMS-顺达物流",
    "LBBK": "立白宝凯物流",
    "LDZY168": "两点之间",
    "LEDAOWULIU": "楽道物流",
    "LEDII": "乐递供应链",
    "LETSEML": "美联快递",
    "LHEXPRESSUS": "联合速递",
    "LHKDS": "联合快递",
    "LIJISONG": "成都立即送",
    "LINGSONG": "领送送",
    "LITTLEBEARBEAR": "小熊物流",
    "LNET": "新易泰",
    "LONGBANWULIU": "龙邦速递",
    "LONGCPS": "加拿大龙行速运",
    "LONGVAST": "长风物流",
    "LSEXPRESS": "6LS EXPRESS",
    "LTEXP": "乐天速递",
    "LTPARCEL": "联通快递",
    "LUBEN": "陆本速递",
    "LYT": "联运通物流",
    "LJS": "立即送",
    "LHT": "联昊通速递",
    "MK": "美快",
    "MDM": "门对门快递",
    "MEITAI": "美泰物流",
    "MOSUDA": "魔速达",
    "MEKW": "密尔克卫",
    "MRDY": "迈隆递运",
    "MIAOWU": "喵物配送",
    "MLWL": "明亮物流",
    "NFCM": "南方传媒物流",
    "NEBUEX": "星云速递",
    "NEWL": "尼尔物流",
    "NEZHA": "速尔哪吒",
    "NHACEH": "云链航空",
    "NT56": "南天物流",
    "NNTENGDA": "腾达速递",
    "NUOER": "诺尔国际物流",
    "NUOYAAO": "偌亚奥国际快递",
    "NZZTO": "新西兰中通",
    "NEDA": "能达速递",
    "ONTRAC": "ONTRAC",
    "PADTF": "平安达腾飞快递",
    "PANEX": "泛捷快递",
    "PJ": "品骏快递",
    "PARCELCHINA": "诚一物流",
    "PARCELFORCECN": "英国邮政大包EMS",
    "PZHJST": "急顺通",
    "PCWL56": "普畅物流",
    "PDSTOW": "全球速递",
    "PEEX": "派尔快递",
    "PEISIHUOYUNKUAIDI": "配思货运",
    "PENGCHENG": "鹏程快递",
    "PINXINKUAIDI": "品信快递",
    "PMT0704BE": "龙行天下",
    "POSTELBE": "PostElbe",
    "POSTNLCHINA": "荷兰邮政-中国件",
    "PCA": "PCA Express",
    "QCKD": "全晨快递",
    "QRT": "全日通快递",
    "QUICK": "快客快递",
    "QXT": "全信通",
    "QBEXPRESS": "秦邦快运",
    "QHXYKD": "雪域快递",
    "QHXYYG": "雪域易购",
    "QIANLI": "千里速递",
    "QINLING": "秦岭智能速运",
    "QQYZ": "全球邮政",
    "QUANJITONG": "全际通",
    "QUANSUTONG": "全速通",
    "QUANTWL": "全通快运",
    "QYZY": "七曜中邮",
    "RFD": "如风达",
    "RONGHUI": "融辉物流",
    "RQ": "荣庆物流",
    "RRS": "日日顺物流",
    "RLWL": "日昱物流",
    "RENRENEX": "人人转运",
    "RHT": "睿和泰速运",
    "RJTCSD": "锐界同城",
    "RRSKX": "日日顺快线",
    "RRSZHWL": "日日顺智慧物联",
    "RFEX": "瑞丰速递",
    "SAD": "赛澳递",
    "SNWL": "苏宁物流",
    "SAWL": "圣安物流",
    "SDWL": "上大物流",
    "SFWL": "盛丰物流",
    "SCCS": "SCCS",
    "SYWL": "顺衍物流",
    "ST": "速通物流",
    "STWL": "速腾物流",
    "SUBIDA": "速必达物流",
    "SDEZ": "速递e站",
    "SDL": "速道物流",
    "SCZPDS": "速呈宅配",
    "SHWL": "盛辉物流",
    "SJWL": "穗佳物流",
    "STSD": "三态速递",
    "SANZHI": "三志物流",
    "SXHMJ": "山西红马甲",
    "SYKD": "世运快递",
    "STKD": "盛通快递",
    "SJ": "郑州速捷",
    "SAIAODIMMB": "赛澳递for买卖宝",
    "SANHUWULIU": "叁虎物流",
    "SCIC": "中加国际快递",
    "SCXINGCHENG": "四川星程快递",
    "SCYTQ": "药淘齐物流",
    "SDSD": "速达速递",
    "SHANGCHENG": "尚橙物流",
    "SHANGHAIKUAITONG": "上海快通",
    "SHANXIJIANHUA": "山西建华",
    "SHAOKE": "捎客物流",
    "SHBWCH": "杰响物流",
    "SHJSD": "闪货极速达",
    "SHLDHY": "上海林道货运",
    "SHPOST": "同城快寄",
    "SHUNFENGHK": "顺丰-繁体",
    "SHUNFENGLENGYUN": "顺丰冷链",
    "SHUNJIEDA": "顺捷达",
    "SHUNJIEFENGDA": "顺捷丰达",
    "SHUNSHID": "顺士达速运",
    "SIGNEDEXPRESS": "签收快递",
    "SINOAIRINEX": "中外运空运",
    "SINOEX": "中外运速递-中文",
    "SIXROAD": "易普递",
    "SJA56": "四季安物流",
    "SPEEDA": "行必达",
    "SPEEDOEX": "申必达",
    "SSD": "速速达",
    "STAREX": "星速递",
    "STARYVR": "星运快递",
    "STOEXPRESS": "美国申通",
    "STONEWZEALAND": "申通新西兰",
    "STZD56": "智德物流",
    "SUBAOEX": "速豹",
    "SUCMJ": "特急便物流",
    "SUFENGKUAIDI": "速风快递",
    "SUPINEXPRESS": "速品快递",
    "SURPOST": "苏里南",
    "SWCH": "瑞士邮政",
    "SWEDENPOST": "瑞典邮政",
    "SXEXPRESS": "三象速递",
    "SXHONGMAJIA": "红马甲物流",
    "SYJHE": "沈阳佳惠尔",
    "SZDPEX": "深圳DPEX",
    "SZSHIHUATONG56": "世华通物流",
    "SZYOUZHENG": "深圳邮政",
    "SX": "顺心捷达",
    "SQWL": "商桥物流",
    "SYJWDX": "佳旺达物流",
    "TAIWANYZ": "台湾邮政",
    "CP30903602": "腾林物流",
    "HNTLWL": "泰联物流",
    "TSSTO": "唐山申通",
    "TJS": "特急送",
    "TYWL": "通用物流",
    "TAIJIN": "泰进物流",
    "TBZS": "特宝专送",
    "TIANXIANG": "天翔快递",
    "TIMEDG": "万家通快递",
    "TJKJWL": "泰实货运",
    "TJLYZ56": "老扬州物流",
    "TNJEX": "明通国际快递",
    "TONGDAXING": "通达兴物流",
    "TU": "运联科技",
    "TZKY": "铁中快运",
    "TDHY": "华宇物流",
    "TXWL": "天玺物流",
    "TJDGJWL": "泰捷达物流",
    "JTE": "捷特快递",
    "ULUCKEX": "优联吉运",
    "UTAOSCM": "UTAO 优到",
    "UAPEX": "全一快递",
    "WJK": "万家康",
    "WJWL": "万家物流",
    "WM": "中粮我买网",
    "WXWL": "万象物流",
    "WTP": "微特派",
    "WANJIATONG": "宁夏万家通",
    "WDM": "万达美",
    "WHEREXPESS": "威盛快递",
    "WLFAST": "凡仕特物流",
    "WOWVIP": "沃埃家",
    "WUYUANSUDI": "伍圆速递",
    "WYKJT": "51跨境通",
    "WTWL": "温通物流",
    "WHXBWL": "武汉晓毕物流",
    "XCWL": "迅驰物流",
    "XFEX": "信丰物流",
    "XYT": "希优特",
    "XIAOMIWULIU": "小米物流",
    "XJ": "新杰物流",
    "XINMENGCHENG": "鑫梦成",
    "XDSHIPPING": "国晶物流",
    "XIANGLONGYUNTONG": "祥龙运通物流",
    "XIANGTENG": "翔腾物流",
    "XLKD": "喜来快递",
    "XUNXUAN": "迅选物流",
    "XYB2B": "行云物流",
    "XYD666": "鑫远东速运",
    "XYJ": "西邮寄",
    "XIAOBI": "晓毕物流",
    "YJYY": "云集医药冷链",
    "YC56": "永昌物流",
    "YDWL": "宇达物流",
    "YAD": "源安达快递",
    "YCWL": "远成物流",
    "YCSY": "远成快运",
    "YDH": "义达国际物流",
    "YKD": "药康达快递",
    "YFHEX": "原飞航物流",
    "YFSD": "亚风快递",
    "YTKD": "运通快递",
    "YXKD": "亿翔快递",
    "YUNDX": "运东西网",
    "YMDD": "壹米滴答",
    "YZTSY": "一站通速运",
    "YFSUYUN": "驭丰速运",
    "YSDF": "余氏东风",
    "YF": "耀飞快递",
    "YDKY": "韵达快运",
    "YL": "云路",
    "YFEX": "越丰物流",
    "YJSD": "顺捷丰达/银捷速递",
    "YMWL": "英脉物流",
    "YTFH": "一统飞鸿",
    "YAMAXUNWULIU": "亚马逊中国",
    "YATFAI": "一辉物流",
    "YDFEXPRESS": "易达丰国际速递",
    "YIHANGMALL": "易航物流",
    "YINGCHAO": "英超物流",
    "YIQISONG": "一起送",
    "YIZHENGDASUYUN": "一正达速运",
    "YJHGO": "武汉优进汇",
    "YKOUAN": "洋口岸",
    "YNZTSY": "黑猫同城送",
    "YONGBANGWULIU": "永邦国际物流",
    "YOUCWL": "邮畅快运",
    "YOULAI": "邮来速递",
    "YPSD": "壹品速递",
    "YUANDUN": "远盾物流",
    "YUANTONGKUAIYUN": "圆通快运",
    "YUANZHIJIECHENG": "元智捷诚",
    "YUJTONG": "宇捷通",
    "YUNDAEXUS": "美国云达",
    "YUNFENG56": "韵丰物流",
    "YUNTONG": "运通速运",
    "YYBSY": "邮驿帮速运",
    "YYEXP": "西安运逸快递",
    "YYSDCN": "鹰运",
    "YTOGJ": "圆通国际",
    "CP35202654": "宇鑫物流",
    "YZGN": "包裹/平邮/挂号信",
    "YLFWL": "一路发物流",
    "YJWL": "云聚物流",
    "ZYE": "众邮快递",
    "ZJS": "宅急送",
    "ZTKY": "中铁快运",
    "ZY_AZY": "澳转运",
    "ZY_BDA": "八达网",
    "ZY_BYECO": "贝易购",
    "ZY_CTM": "赤兔马转运",
    "ZY_CUL": "CUL中美速递",
    "ZY_ETD": "ETD",
    "ZY_FCKD": "风驰快递",
    "ZY_FLSD": "风雷速递",
    "ZY_HCYD": "皓晨优递",
    "ZY_HDB": "海带宝",
    "ZY_HFMZ": "汇丰美中速递",
    "ZY_HJSD": "豪杰速递",
    "ZY_HMKD": "华美快递",
    "ZY_HTAO": "360hitao转运",
    "ZY_HTCUN": "海淘村",
    "ZY_HTKE": "365海淘客",
    "ZY_HTONG": "华通快运",
    "ZY_HXKD": "海星桥快递",
    "ZY_HXSY": "华兴速运",
    "ZY_IHERB": "LogisticsY",
    "ZY_LPZ": "领跑者快递",
    "ZY_LZWL": "量子物流",
    "ZY_MBZY": "明邦转运",
    "ZY_MZ": "168 美中快递",
    "ZY_OEJ": "欧e捷",
    "ZY_OZF": "欧洲疯",
    "ZY_OZGO": "欧洲GO",
    "ZY_QMT": "全美通",
    "ZDEPOST": "直德邮",
    "ZENZEN": "三三国际物流",
    "ZHAOJIN": "招金精炼",
    "ZHENGYIKUAIDI": "鑫正一快递",
    "ZHONGHONGWL": "中宏物流",
    "ZHONGHUANUS": "中环转运",
    "ZHONGXINDA": "忠信达",
    "ZHPEX": "众派速递",
    "ZJCY56": "创运物流",
    "ZJGJ56": "振捷国际货运",
    "ZJSTKY": "苏通快运",
    "ZLINK": "三真驿道",
    "ZLXDJWL": "中粮鲜到家物流",
    "ZTOZY": "中通智运",
    "ZRTL": "中融泰隆",
    "ZSKY": "准实快运",
    "ZSMHWL": "明辉物流",
    "ZTCCE": "中途速递",
    "ZTSY": "纵通速运",
    "ZY_AG": "爱购转运",
    "ZY_AUSE": "澳世速递",
    "ZY_BM": "斑马物流",
    "ZY_BT": "百通物流",
    "ZY_CM": "策马速递",
    "ZY_ESONG": "宜送转运",
    "ZY_FD": "飞碟快递",
    "ZY_FG": "飞鸽快递",
    "ZY_FX": "风行快递",
    "ZY_HC": "皓晨快递",
    "ZY_JA": "君安快递",
    "ZY_JD": "骏达快递",
    "ZY_JH": "久禾快运",
    "ZY_JHT": "金海淘",
    "ZY_LX": "龙象快递",
    "ZY_MST": "美速通",
    "ZY_QQEX": "QQ-EX",
    "ZY_RT": "瑞天快递",
    "ZY_SFZY": "四方转运",
    "ZY_ST": "上腾快递",
    "ZY_TN": "滕牛快递",
    "ZY_TSZ": "唐三藏转运",
    "ZY_TX": "同心快递",
    "ZY_TY": "天翼快递",
    "ZY_XC": "星辰快递",
    "ZY_XF": "先锋快递",
    "ZY_YQ": "云骑快递",
    "ZY_YTUSA": "运淘美国",
    "ZY100": "中远快运",
    "ZYZOOM": "增速海淘",
    "ZZJH": "郑州建华",
    "ZY_SCS": "SCS国际物流",
    "ZY_SOHO": "SOHO苏豪国际",
    "ZY_SONIC": "Sonic-Ex速递",
    "ZY_TCM": "通诚美中快递",
    "ZY_TPAK": "TrakPak",
    "ZY_TTHT": "天天海淘",
    "ZY_TZKD": "天泽快递",
    "ZY_XDKD": "迅达快递",
    "ZY_XDSY": "信达速运",
    "ZY_XGX": "新干线快递",
    "ZY_XJ": "信捷转运",
    "ZY_YGKD": "优购快递",
    "ZY_YJSD": "友家速递(UCS)",
    "ZY_YPW": "云畔网",
    "ZY_YSW": "易送网",
    "ZYQS": "中运全速",
    "ZYWL": "中邮物流",
    "ZHQKD": "汇强快递",
    "ZTE": "众通快递",
    "ZTOKY": "中通快运",
    "ZTOCC": "中通冷链",
    "ZHWL": "中骅物流",
    "ZTWL": "中铁物流",
    "ZHN": "智汇鸟",
    "ZYKY": "中原快运",
    "ZXXFX": "正鑫小飞侠"
}

# 详细物流状态码及描述
DETAILED_STATE_DESCRIPTIONS = {
    0: "暂无轨迹信息",
    1: "已揽收",
    10: "待揽件",
    2: "在途中",
    201: "到达派件城市",
    202: "派件中",
    211: "已放入快递柜或驿站",
    204: "到达转运中心",
    205: "到达派件网点",
    206: "寄件网点发件",
    3: "已签收",
    301: "正常签收",
    302: "异常后最终签收",
    304: "代收签收",
    311: "快递柜或驿站签收",
    5: "转寄",
    4: "问题件",
    401: "发货无信息",
    402: "超时未签收",
    403: "超时未更新",
    404: "拒收（退件）",
    405: "派件异常",
    406: "退货签收",
    407: "退货未签收",
    412: "快递柜或驿站超时未取",
    413: "单号已拦截",
    414: "破损",
    415: "客户取消发货",
    416: "无法联系",
    417: "配送延迟",
    418: "快件取出",
    419: "重新派送",
    420: "收货地址不详细",
    421: "收件人电话错误",
    422: "错分件",
    423: "超区件",
    6: "清关",
    601: "待清关",
    602: "清关中",
    603: "已清关",
    604: "清关异常"
}


def get_state_description(state: int = None, state_ex: int = None) -> str:
    """获取状态描述
    
    Args:
        state: 基本物流状态码
        state_ex: 详细物流状态码
        
    Returns:
        状态描述文本
    """
    # 如果有详细状态码，优先使用详细状态描述
    if state_ex is not None:
        return DETAILED_STATE_DESCRIPTIONS.get(state_ex, f"未知状态({state_ex})")
    
    # 否则使用基本状态描述
    if state is not None:
        return BASIC_STATE_DESCRIPTIONS.get(state, f"未知状态({state})")
    
    return "未知状态"


class StateCodeInfo(BaseModel):
    """物流状态码信息"""
    code: str
    name: str
    description: str


class TrackingDocInfo(BaseModel):
    """轨迹查询文档信息"""
    request_type: str
    batch_support: str
    billing_rule: str
    sort_rule: str
    api_url: str
    supported_companies: str
    special_requirements: List[str]
    request_params: Dict[str, Dict[str, Any]]
    response_params: Dict[str, Dict[str, Any]]


class RecognizeDocInfo(BaseModel):
    """单号识别文档信息"""
    request_type: str
    batch_support: str
    billing_rule: str
    api_url: str
    rules: List[str]
    request_params: Dict[str, Dict[str, Any]]
    response_params: Dict[str, Dict[str, Any]]


class TimelineDocInfo(BaseModel):
    """时效预估文档信息"""
    request_type: str
    batch_support: str
    billing_rule: Dict[str, str]
    api_url: str
    scenarios: List[Dict[str, str]]
    request_params: Dict[str, Dict[str, Any]]
    response_params: Dict[str, Dict[str, Any]]
    delivery_time_calculation: List[str]


class CrossBorderTrackingDocInfo(BaseModel):
    """跨境小包查询文档信息"""
    request_type: str
    batch_support: str
    billing_rule: str
    api_url: str
    supported_companies: str
    special_requirements: List[str]
    request_params: Dict[str, Dict[str, Any]]
    response_params: Dict[str, Dict[str, Any]]


class ServicePointDocInfo(BaseModel):
    """网点查询文档信息"""
    request_type: str
    batch_support: str
    billing_rule: str
    api_url: str
    supported_companies: str
    special_requirements: List[str]
    request_params: Dict[str, Dict[str, Any]]
    response_params: Dict[str, Dict[str, Any]]


class KDNiaoDocResources(BaseModel):
    """快递鸟文档资源集合"""
    tracking: TrackingDocInfo
    recognize: RecognizeDocInfo
    timeline: TimelineDocInfo
    address_parse: TrackingDocInfo
    service_point: ServicePointDocInfo
    state_codes: List[StateCodeInfo]
    state_ex_codes: List[StateCodeInfo]
    cross_border_tracking: CrossBorderTrackingDocInfo
    cross_border_state_codes: List[StateCodeInfo]