ZZZeroUID

https://github.com/zzzure/zzzerouid
Admin
一个支持多个聊天平台（QQ、微信、Telegram等）和机器人框架的绝区零游戏插件，提供UID绑定、角色攻略、抽卡记录、面板查询等功能。
Tokens:8,729
Snippets:31
Trust Score:6.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Query Character Guides

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Handles character guide image requests by selecting between different providers based on plugin configuration.

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.models import Event
from gsuid_core.utils.image.convert import convert_img

sv_zzz_guide = SV("绝区零攻略")

@sv_zzz_guide.on_prefix("角色攻略")
@sv_zzz_guide.on_suffix("攻略")
async def send_role_guide_pic(bot: Bot, ev: Event):
    """查询角色攻略图"""
    name = alias_to_char_name(ev.text.strip())

    # 获取攻略提供方配置
    guide_provider = ZZZ_CONFIG.get_config("ZZZGuideProvide").data

    if guide_provider == "猫冬":
        path = CAT_GUIDE_PATH / f"{name}.jpg"
    else:  # 听雨惊花
        path1 = FLOWER_GUIDE_PATH / f"{name}.jpg"
        path2 = FLOWER_GUIDE_PATH / f"{name}.png"
        path = path1 if path1.exists() else path2

    if path.exists():
        img = await convert_img(path)
        await bot.send(img)
    else:
        await bot.send("[绝区零] 该角色攻略不存在")
```

--------------------------------

### Get New Gacha Log Function

Source: https://context7.com/zzzure/zzzerouid/llms.txt

This asynchronous Python function fetches new gacha logs from the game's API using an AuthKey. It iterates through different gacha types and pages, handling potential errors and merging new data with existing logs. Requires `asyncio` and `zzz_api`.

```python
async def get_new_gachalog(uid: str, full_data: Dict, is_force: bool):
    """从米游社 API 获取抽卡记录"""
    for gacha_name, gacha_types in gacha_type_meta_data.items():
        for gacha_type in gacha_types:
            # 获取 AuthKey
            authkey_data = await zzz_api.get_authkey_by_cookie(
                uid, "nap_cn", zzz_api._get_region(uid)
            )
            authkey = authkey_data["authkey"]

            end_id = "0"
            for page in range(1, 999):
                data = await zzz_api.get_zzz_gacha_log_by_authkey(
                    uid, authkey, gacha_type,
                    gacha_type[0], page, end_id
                )
                await asyncio.sleep(0.9)  # 避免请求过快

                if isinstance(data, int) or not data["list"]:
                    break

                end_id = data["list"][-1]["id"]
                # 合并新数据到历史记录
                if gacha_name not in full_data:
                    full_data[gacha_name] = []
                full_data[gacha_name].extend(data["list"])

    return full_data
```

--------------------------------

### Configure Plugin Settings

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Defines and loads plugin configuration options using the GsConfig system.

```python
from gsuid_core.utils.plugins_config.gs_config import StringConfig
from gsuid_core.utils.plugins_config.models import (
    GsStrConfig, GsBoolConfig, GsListStrConfig
)

# 配置项定义
CONFIG_DEFAULT = {
    # 命令前缀
    "ZZZPrefix": GsStrConfig(
        "插件命令前缀", "用于设置ZZZeroUID前缀", "zzz"
    ),

    # 签到时间设置（时、分）
    "SignTime": GsListStrConfig(
        "每晚签到时间设置", "时/分", ["0", "59"]
    ),

    # 定时签到开关
    "SchedSignin": GsBoolConfig(
        "定时签到", "每晚自动签到", True
    ),

    # 体力推送开关
    "SchedEnergyPush": GsBoolConfig(
        "定时检查体力", "每半小时检查一次", True
    ),

    # 攻略提供方
    "ZZZGuideProvide": GsStrConfig(
        "角色攻略图提供方", "攻略来源",
        "猫冬", options=["猫冬", "听雨惊花"]
    ),

    # 面板数据源顺序
    "RefreshDataList": GsListStrConfig(
        "刷新面板顺序", "前一个失败自动使用后一个",
        ["ENKA", "MINIGG", "MYS"],
        options=["MINIGG", "ENKA", "MYS"]
    ),
}

# 加载配置
ZZZ_CONFIG = StringConfig("ZZZeroUID", CONFIG_PATH, CONFIG_DEFAULT)

# 读取配置示例
sign_time = ZZZ_CONFIG.get_config("SignTime").data  # ["0", "59"]
is_auto_sign = ZZZ_CONFIG.get_config("SchedSignin").data  # True
guide_source = ZZZ_CONFIG.get_config("ZZZGuideProvide").data  # "猫冬"
```

--------------------------------

### MiHoYo API Core

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Core API class for interacting with the MiHoYo server to fetch Zenless Zone Zero game data.

```APIDOC
## GET /api/zzz/index_info

### Description
Fetches basic player information, including character lists, buddy lists, and statistics.

### Method
GET

### Endpoint
/api/zzz/index_info

### Parameters
#### Query Parameters
- **uid** (string) - Required - The player's UID.

### Response
#### Success Response (200)
- **data** (object) - Contains player statistics, avatar list, and buddy list.
  - **stats** (object) - Player statistics.
  - **avatar_list** (array) - List of player's characters.
  - **buddy_list** (array) - List of player's buddies.

#### Response Example
```json
{
  "data": {
    "stats": {
      "active_days": 100,
      "avatar_num": 10,
      "buddy_num": 5
    },
    "avatar_list": [
      { "id": 1, "name": "Character 1" },
      { "id": 2, "name": "Character 2" }
    ],
    "buddy_list": [
      { "id": 101, "name": "Buddy 1" }
    ]
  }
}
```

## GET /api/zzz/note_info

### Description
Fetches real-time note information, such as stamina, daily task progress, etc.

### Method
GET

### Endpoint
/api/zzz/note_info

### Parameters
#### Query Parameters
- **uid** (string) - Required - The player's UID.

### Response
#### Success Response (200)
- **data** (object) - Contains real-time note information.

#### Response Example
```json
{
  "data": {
    "stamina": 150,
    "daily_tasks_completed": 3,
    "bounty_quests_completed": 5
  }
}
```

## GET /api/zzz/avatar_info

### Description
Fetches detailed panel information for specified characters, including equipment, weapons, attributes, and skills.

### Method
GET

### Endpoint
/api/zzz/avatar_info

### Parameters
#### Query Parameters
- **uid** (string) - Required - The player's UID.
- **id_list** (array of integers) - Required - A list of character IDs to fetch details for.

### Response
#### Success Response (200)
- **data** (object) - Contains a list of detailed character information.
  - **avatar_list** (array) - List of detailed character information.

#### Response Example
```json
{
  "data": {
    "avatar_list": [
      { "id": 1, "name": "Character 1", "level": 80, "hp": 10000, "attack": 2000, "skills": [...] },
      { "id": 2, "name": "Character 2", "level": 70, "hp": 9000, "attack": 1800, "skills": [...] }
    ]
  }
}
```

## GET /api/zzz/challenge_info

### Description
Fetches data for the "Trial of the Elements" (Abyss), with an option to retrieve data from the previous period.

### Method
GET

### Endpoint
/api/zzz/challenge_info

### Parameters
#### Query Parameters
- **uid** (string) - Required - The player's UID.
- **schedule_type** (integer) - Optional - 1 for current period, 2 for previous period. Defaults to 1.

### Response
#### Success Response (200)
- **data** (object) - Contains the "Trial of the Elements" data.

#### Response Example
```json
{
  "data": {
    "current_floor": 12,
    "max_floor": 12,
    "stars": 36
  }
}
```
```

--------------------------------

### Bind UID Command for ZZZeroUID

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Handles binding a Zenless Zone Zero UID to a user account. Requires the UID to be provided after the command. Supports inserting, switching, and deleting UID bindings.

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.models import Event
from gsuid_core.utils.database.models import GsBind

sv_user_info = SV("zzz用户信息")

# 绑定 UID 命令处理
@sv_user_info.on_command(("绑定uid", "绑定UID", "绑定"), block=True)
async def bind_uid(bot: Bot, ev: Event):
    qid = ev.user_id
    uid = ev.text.strip()

    if not uid:
        return await bot.send("[绝区零] 你需要在命令后面加入你绝区零的UID！")

    # 插入绑定记录到数据库
    data = await GsBind.insert_uid(
        qid, ev.bot_id, uid, ev.group_id,
        game_name="zzz"
    )

    # 根据返回状态发送对应消息
    messages = {
        0: f"✅[绝区零]绑定uid[{uid}]成功!",
        -1: f"❎[绝区零]uid[{uid}]的位数不正确!",
        -2: f"❎[绝区零]uid[{uid}]已经绑定过了!",
        -3: "❎[绝区零]你输入了错误的格式!",
    }
    return await bot.send(messages.get(data, "未知错误"))

# 切换 UID 命令
@sv_user_info.on_command(("切换uid", "切换UID", "切换"), block=True)
async def switch_uid(bot: Bot, ev: Event):
    qid = ev.user_id
    uid = ev.text.strip()

    data = await GsBind.switch_uid_by_game(qid, ev.bot_id, uid, "zzz")
    # 返回 0 表示切换成功

# 删除 UID 命令
@sv_user_info.on_command(("删除uid", "解绑uid", "删除"), block=True)
async def delete_uid(bot: Bot, ev: Event):
    qid = ev.user_id
    uid = ev.text.strip()

    data = await GsBind.delete_uid(qid, ev.bot_id, uid, "zzz")
    # 返回 0 表示删除成功
```

--------------------------------

### Manage Push Notifications with SQLModel

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Defines the database model for push notifications and registers the administrative interface.

```python
from typing import Optional
from sqlmodel import Field
from gsuid_core.utils.database.base_models import Push
from gsuid_core.webconsole import site
from gsuid_core.webconsole.mount_app import GsAdminModel
from fastapi_amis_admin.amis.components import PageSchema

class ZzzPush(Push, table=True):
    """绝区零推送配置数据模型"""
    __table_args__ = {"extend_existing": True}

    bot_id: str = Field(title="平台")
    zzz_uid: str = Field(default=None, title="绝区零UID")

    # 体力推送配置
    energy_push: Optional[str] = Field(
        title="绝区零体力推送",
        default="off",
        schema_extra={"json_schema_extra": {"hint": "zzz开启体力推送"}}
    )
    energy_value: Optional[int] = Field(
        title="电量阈值", default=180
    )
    energy_is_push: Optional[str] = Field(
        title="电量是否已推送", default="off"
    )

# 注册网页管理后台
@site.register_admin
class ZzzPushAdmin(GsAdminModel):
    pk_name = "id"
    page_schema = PageSchema(
        label="绝区零推送管理",
        icon="fa fa-bullhorn",
    )
    model = ZzzPush
```

--------------------------------

### Real-time Stamina Query for ZZZeroUID

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Queries and displays real-time game status such as stamina, daily quest progress, and bounty missions. Supports scheduled stamina reminders.

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.aps import scheduler
from gsuid_core.models import Event

sv_get_stamina = SV("绝区零查询体力")

@sv_get_stamina.on_fullmatch(("每日", "mr", "便笺", "便签"))
async def send_daily_info_pic(bot: Bot, ev: Event):
    """查询实时便签"""
    uid = await get_uid(bot, ev)
    if not uid:
        return await bot.send("请先绑定UID")

    # 获取便签数据并绘制图片
    await draw_stamina_img(bot, ev)
```

--------------------------------

### 查询临界推演数据

Source: https://context7.com/zzzure/zzzerouid/llms.txt

展示临界推演玩法的挑战记录与成绩，包含对应的战斗数据模型。

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.models import Event

sv_get_void = SV("zzz查询临界推演")

@sv_get_void.on_fullmatch(
    ("临界推演", "临界", "推演"),
    block=True,
)
async def send_void_info(bot: Bot, ev: Event):
    """查询临界推演数据"""
    uid = await get_uid(bot, ev)
    if not uid:
        return await bot.send("请先绑定UID")

    im = await draw_void_img(uid, ev)
    await bot.send(im)

# 临界推演数据模型
class ZZZVoidFrontBattleData:
    main_challenge_record_list: List[MainChallengeRecord]
    boss_challenge_record: BossChallengeRecord
    void_front_battle_abstract_info_brief: VoidFrontBattleAbstractInfoBrief
```

--------------------------------

### Integrate Hakush API

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Provides asynchronous functions to fetch character, weapon, and equipment data from the Hakush API.

```python
from httpx import AsyncClient
from typing import Dict, Optional, Union

HAKUSH_BASE = "https://static.nanoka.cc/zzz/2.8.2+14745356"
HAKUSH_API = f"{HAKUSH_BASE}/zh"

# API 端点
ZZZ_CHARACTER = HAKUSH_API + "/character/{}.json"
ZZZ_WEAPON = HAKUSH_API + "/weapon/{}.json"
ZZZ_ALL_CHAR = f"{HAKUSH_BASE}/character.json"
ZZZ_ALL_WEAPON = f"{HAKUSH_BASE}/weapon.json"
ZZZ_ALL_EQUIP = f"{HAKUSH_BASE}/equipment.json"

async def get_hakush_char_data(id: Union[int, str]) -> Optional[CharacterData]:
    """获取角色详细数据"""
    data = await _hakush_request(ZZZ_CHARACTER.format(id))
    if isinstance(data, Dict):
        return data
    return None

async def get_hakush_all_char_data() -> Optional[Dict[str, CharacterDatabase]]:
    """获取所有角色基础数据"""
    data = await _hakush_request(ZZZ_ALL_CHAR)
    return data if isinstance(data, Dict) else None

async def get_hakush_weapon_data(id: Union[int, str]) -> Optional[WeaponData]:
    """获取武器详细数据"""
    data = await _hakush_request(ZZZ_WEAPON.format(id))
    return data if isinstance(data, Dict) else None

async def get_hakush_all_equipment() -> Optional[Dict[str, EquipData]]:
    """获取所有驱动盘数据"""
    data = await _hakush_request(ZZZ_ALL_EQUIP)
    return data if isinstance(data, Dict) else None

async def _hakush_request(url: str) -> Optional[Dict]:
    """发送 HTTP 请求"""
    async with AsyncClient(timeout=None) as client:
        req = await client.get(
            url,
            headers={"User-Agent": "ZZZeroUID/2.7.0"}
        )
        return req.json()
```

--------------------------------

### 配置米游社自动签到

Source: https://context7.com/zzzure/zzzerouid/llms.txt

支持手动签到及定时自动签到任务，包含管理员权限配置与任务调度逻辑。

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.aps import scheduler
from gsuid_core.models import Event
from gsuid_core.subscribe import gs_subscribe
from gsuid_core.utils.sign.sign import sign_in

sv_zzz_sign = SV("绝区零米游社签到")
sv_zzz_sign_config = SV("绝区零米游社签到配置", pm=1)  # pm=1 表示需要管理员权限

@sv_zzz_sign.on_fullmatch("签到")
async def get_sign_func(bot: Bot, ev: Event):
    """手动签到"""
    uid = await GsBind.get_uid_by_game(ev.user_id, ev.bot_id, "zzz")
    if uid is None:
        return await bot.send("请先绑定UID")

    result = await sign_in(uid, "zzz")
    await bot.send(result)

@sv_zzz_sign_config.on_fullmatch("全部重签")
async def recheck(bot: Bot, ev: Event):
    """管理员命令：为所有用户重新签到"""
    await bot.send("🚩 [绝区零] [全部重签] 已开始执行!")
    await zzz_sign_at_night(True)
    await bot.send("🚩 [绝区零] [全部重签] 执行完成!")

# 定时签到任务（默认每天 00:59 执行）
SIGN_TIME = ZZZ_CONFIG.get_config("SignTime").data  # ["0", "59"]

@scheduler.scheduled_job("cron", hour=SIGN_TIME[0], minute=SIGN_TIME[1])
async def zzz_sign_at_night(force: bool = False):
    """定时自动签到"""
    if ZZZ_CONFIG.get_config("SchedSignin").data or force:
        datas = await gs_subscribe.get_subscribe("[绝区零] 自动签到")
        priv_result, group_result = await gs_subscribe.muti_task(
            datas, sign_in_task, "uid"
        )
        # 推送签到结果...
```

--------------------------------

### Real-time Stamina Query

Source: https://context7.com/zzzure/zzzerouid/llms.txt

API for querying real-time stamina and daily task status, with support for scheduled stamina reminders.

```APIDOC
## GET /api/zzz/stamina

### Description
Queries the real-time stamina and daily task progress. Can be used to trigger stamina reminders.

### Method
GET

### Endpoint
/api/zzz/stamina

### Parameters
#### Query Parameters
- **uid** (string) - Required - The player's UID.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the status of the stamina query or reminder.
- **image_url** (string) - URL to an image displaying the stamina and task status.

#### Response Example
```json
{
  "message": "Stamina and task status updated.",
  "image_url": "http://example.com/stamina_status.png"
}
```
```

--------------------------------

### 查询式舆防卫战数据

Source: https://context7.com/zzzure/zzzerouid/llms.txt

通过指令查询深渊战绩，支持本期/上期及完整数据展示，并定义了相关数据模型。

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.models import Event

sv_get_challenge = SV("zzz查询深渊")

@sv_get_challenge.on_fullmatch(
    ("深渊", "查询深渊", "式舆防卫战",
     "上期深渊", "完整深渊"),
    block=True,
)
async def send_abyss_info(bot: Bot, ev: Event):
    """查询式舆防卫战数据"""
    uid = await get_uid(bot, ev)
    if not uid:
        return await bot.send("请先绑定UID")

    # 判断查询本期还是上期
    schedule_type = 2 if "上期" in ev.command else 1
    # 判断是否显示完整数据
    is_full = "完整" in ev.command

    im = await draw_challenge_img(uid, ev, schedule_type, is_full)
    await bot.send(im)

# 深渊数据模型
class ZZZChallenge:
    schedule_id: int                # 赛季 ID
    begin_time: int                 # 开始时间戳
    end_time: int                   # 结束时间戳
    rating_list: List[Rating]       # 评分列表
    all_floor_detail: List[FloorDetail]  # 所有层详情
    max_layer: int                  # 最高通关层数

class FloorDetail:
    layer_index: int                # 层数索引
    rating: str                     # 评分（S/A/B）
    buffs: List[Buff]               # 增益效果
    node_1: ChallengeNode           # 第一节点
    node_2: ChallengeNode           # 第二节点
    challenge_time: int             # 通关用时
```

--------------------------------

### ZZZeroUID API for MyHoyoverse Interaction

Source: https://context7.com/zzzure/zzzerouid/llms.txt

Encapsulates all methods for communicating with MyHoyoverse servers, supporting both Chinese and international servers. Provides full game data query capabilities.

```python
from typing import Dict, List, Union, Optional
from gsuid_core.utils.api.mys_api import _MysApi

class ZZZApi(_MysApi):
    """绝区零米游社 API 封装类"""

    # 服务器区域映射
    REGION_MAP = {
        "10": "prod_gf_us",    # 美服
        "13": "prod_gf_jp",    # 日服
        "15": "prod_gf_eu",    # 欧服
        "17": "prod_gf_sg",    # 亚服
    }

    def _get_region(self, uid: str) -> str:
        """根据 UID 获取服务器区域"""
        if len(uid) < 10:
            return "prod_gf_cn"  # 国服
        return self.REGION_MAP.get(uid[:2], "prod_gf_jp")

    async def get_zzz_index_info(self, uid: str) -> Union[int, ZZZIndexResp]:
        """获取玩家基础信息（角色列表、邦布列表、统计数据）"""
        data = await self.simple_zzz_req("/index", uid)
        if isinstance(data, Dict):
            return data["data"]  # 包含 stats, avatar_list, buddy_list
        return data

    async def get_zzz_note_info(self, uid: str) -> Union[int, ZZZNoteResp]:
        """获取实时便签（体力、任务进度等）"""
        data = await self.simple_zzz_req("/note", uid)
        if isinstance(data, Dict):
            return data["data"]
        return data

    async def get_zzz_avatar_info(
        self, uid: str, id_list: List[int]
    ) -> Union[int, List[ZZZAvatarInfo]]:
        """获取角色详细面板信息（装备、武器、属性、技能）"""
        # 并发请求多个角色数据
        import asyncio
        tasks = [
            self.simple_zzz_req(
                "/avatar/info", uid,
                params={"id_list[]": str(i), "need_wiki": False}
            )
            for i in id_list
        ]
        results = await asyncio.gather(*tasks)
        return [r["data"]["avatar_list"] for r in results if isinstance(r, Dict)]

    async def get_zzz_challenge_info(
        self, uid: str, schedule_type: int = 1
    ) -> Union[int, ZZZChallenge]:
        """获取式舆防卫战（深渊）数据，schedule_type=2 为上期"""
        data = await self.simple_zzz_req(
            "/challenge", uid,
            params={"schedule_type": schedule_type}
        )
        if isinstance(data, Dict):
            return data["data"]
        return data

# 创建全局 API 实例
zzz_api = ZZZApi()

# 使用示例
async def query_player_data(uid: str):
    # 获取玩家基础信息
    index = await zzz_api.get_zzz_index_info(uid)
    if isinstance(index, int):
        print(f"查询失败，错误码: {index}")
        return

    print(f"活跃天数: {index['stats']['active_days']}")
    print(f"角色数量: {index['stats']['avatar_num']}")
    print(f"邦布数量: {index['stats']['buddy_num']}")

    # 获取角色详情
    char_ids = [avatar['id'] for avatar in index['avatar_list'][:3]]
    details = await zzz_api.get_zzz_avatar_info(uid, char_ids)
```

--------------------------------

### 查询危局强袭战数据

Source: https://context7.com/zzzure/zzzerouid/llms.txt

实现Boss挑战玩法记录查询，包含挑战得分、星数及角色使用情况的数据模型。

```python
from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.models import Event

sv_get_mem = SV("zzz查询危局强袭战")

@sv_get_mem.on_fullmatch(
    ("危局强袭战", "强袭战", "上期强袭战"),
    block=True,
)
async def send_mem_info(bot: Bot, ev: Event):
    """查询危局强袭战数据"""
    uid = await get_uid(bot, ev)
    if not uid:
        return await bot.send("请先绑定UID")

    schedule_type = 2 if "上期" in ev.command else 1
    im = await draw_mem_img(uid, ev, schedule_type)
    await bot.send(im)

# 危局强袭战数据模型
class ZZZMEMInfo:
    zone_id: int                    # 区域 ID
    total_star: int                 # 总星数
    total_score: int                # 总分数
    rank_percent: int               # 排名百分比
    list: List[ListItem]            # 挑战记录列表

class ListItem:
    star: int                       # 获得星数
    score: int                      # 得分
    boss: List[Boss]                # Boss 信息
    avatar_list: List[Avatar]       # 使用角色
    buddy: Buddy                    # 使用邦布
```

--------------------------------

### UID Management API

Source: https://context7.com/zzzure/zzzerouid/llms.txt

APIs for managing user UID bindings, including adding, switching, and deleting UIDs.

```APIDOC
## POST /api/zzz/bind_uid

### Description
Binds a Zenless Zone Zero UID to the user's account.

### Method
POST

### Endpoint
/api/zzz/bind_uid

### Parameters
#### Request Body
- **uid** (string) - Required - The Zenless Zone Zero UID to bind.

### Request Example
```json
{
  "uid": "123456789"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the success or failure of the binding.

#### Response Example
```json
{
  "message": "✅[绝区零]绑定uid[123456789]成功!"
}
```

## POST /api/zzz/switch_uid

### Description
Switches the active UID for the user.

### Method
POST

### Endpoint
/api/zzz/switch_uid

### Parameters
#### Request Body
- **uid** (string) - Required - The UID to switch to.

### Request Example
```json
{
  "uid": "987654321"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the success or failure of the switch.

#### Response Example
```json
{
  "message": "UID switched successfully."
}
```

## POST /api/zzz/delete_uid

### Description
Deletes a bound UID from the user's account.

### Method
POST

### Endpoint
/api/zzz/delete_uid

### Parameters
#### Request Body
- **uid** (string) - Required - The UID to delete.

### Request Example
```json
{
  "uid": "123456789"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the success or failure of the deletion.

#### Response Example
```json
{
  "message": "UID deleted successfully."
}
```
```

--------------------------------

### ZZZ Note Response Data Model

Source: https://context7.com/zzzure/zzzerouid/llms.txt

A Python data model representing the response structure for ZZZ notes, including energy, vitality, and other game-related status.

```python
class ZZZNoteResp:
    energy: Energy          # 体力值
    vitality: Vitality      # 活力值
    vhs_sale: VhsSale       # 录像店状态
    bounty_commission: BountyCommission  # 悬赏委托
    survey_points: SurveyPoints          # 调查点
    weekly_task: ZZZWeeklyTask           # 每周任务
```

--------------------------------

### Scheduled Job for Energy Check

Source: https://context7.com/zzzure/zzzerouid/llms.txt

This Python function is scheduled to run every 30 minutes to check and push energy reminders. It requires the `scheduler` library and optionally accepts a `force` parameter.

```python
@scheduler.scheduled_job("cron", minute="*/30")
async def zzz_notice_job(force: bool = False):
    """定时检查并推送体力提醒"""
    if is_check_energy or force:
        await get_notice_list()
```

--------------------------------

### Send Character Detail Message

Source: https://context7.com/zzzure/zzzerouid/llms.txt

This function handles user requests to query character details. It retrieves the user's UID and the character name from the event, then calls a function to draw and send an image of the character's details. Requires `gsuid_core` library.

```python
@sv_char_detail.on_prefix(("角色面板", "查询"))
@sv_char_detail.on_suffix("面板")
async def send_char_detail_msg(bot: Bot, ev: Event):
    """查询角色面板"""
    uid = await get_uid(bot, ev)
    char = ev.text.strip()

    if not char or not uid:
        return

    # 绘制角色详情图片
    im = await draw_char_detail_img(uid, ev, char)
    return await bot.send(im)
```

--------------------------------

### ZZZ Avatar Info Data Model

Source: https://context7.com/zzzure/zzzerouid/llms.txt

A Python data model for ZZZ avatar information, detailing character attributes, equipment, skills, and ranks. This model is used to structure character data retrieved from various sources.

```python
class ZZZAvatarInfo:
    id: int                      # 角色 ID
    level: int                   # 等级
    name_mi18n: str             # 角色名称
    element_type: int           # 属性类型
    avatar_profession: int      # 职业类型
    rarity: str                 # 稀有度
    equip: List[Equip]          # 驱动盘装备
    weapon: Weapon              # 武器/音擎
    properties: List[Property]  # 角色属性
    skills: List[Skill]         # 技能列表
    rank: int                   # 影画（命座）数量
    ranks: List[Rank]           # 影画详情
```

--------------------------------

### Save Gacha Logs Function

Source: https://context7.com/zzzure/zzzerouid/llms.txt

This asynchronous Python function saves gacha (gacha) logs for a given UID. It handles loading existing logs, fetching new ones from the game's API, and saving the updated data to a JSON file. Ensure `aiofiles` and `json` libraries are imported.

```python
import json
import asyncio
import aiofiles
from datetime import datetime

# 卡池类型映射
gacha_type_meta_data = {
    "音擎频段": ["3001"],   # 武器池
    "独家频段": ["2001"],   # 限定角色池
    "常驻频段": ["1001"],   # 常驻池
    "邦布频段": ["5001"],   # 邦布池
}

async def save_gachalogs(uid: str, is_force: bool = False) -> str:
    """刷新并保存抽卡记录"""
    path = PLAYER_PATH / str(uid)
    path.mkdir(parents=True, exist_ok=True)

    # 加载历史记录
    gachalogs_path = path / "gacha_logs.json"
    if gachalogs_path.exists():
        async with aiofiles.open(gachalogs_path, "r", encoding="UTF-8") as f:
            gacha_log = json.loads(await f.read())
        gachalogs_history = gacha_log["data"]
    else:
        gachalogs_history = {}

    # 获取新记录
    raw_data = await get_new_gachalog(uid, gachalogs_history, is_force)
    if isinstance(raw_data, int):
        return f"获取失败，错误码: {raw_data}"

    # 保存结果
    result = {
        "uid": uid,
        "data_time": datetime.now().strftime("%Y-%m-%d %H-%M-%S"),
        "normal_gacha_num": len(raw_data.get("常驻频段", [])),
        "char_gacha_num": len(raw_data.get("独家频段", [])),
        "weapon_gacha_num": len(raw_data.get("音擎频段", [])),
        "bangboo_gacha_num": len(raw_data.get("邦布频段", [])),
        "data": raw_data,
    }

    async with aiofiles.open(gachalogs_path, "w", encoding="UTF-8") as f:
        await f.write(json.dumps(result, indent=2, ensure_ascii=False))

    return f"✅UID{uid}数据更新成功！"
```

--------------------------------

### Send Refresh Character Detail Message

Source: https://context7.com/zzzure/zzzerouid/llms.txt

This function handles requests to refresh character panel data. It attempts to fetch data from multiple sources (ENKA, MiniGG, MYS) based on configuration and sends the result. Requires `gsuid_core` library and configuration settings.

```python
@sv_char_detail.on_command(("刷新面板", "强制刷新", "更新面板"))
async def send_refresh_char_detail_msg(bot: Bot, ev: Event):
    """刷新角色面板数据"""
    uid = await get_uid(bot, ev)
    if not uid:
        return await bot.send("请先绑定UID")

    # 按配置顺序尝试不同数据源
    data_list = ZZZ_CONFIG.get_config("RefreshDataList").data
    # 默认顺序: ["ENKA", "MINIGG", "MYS"]

    for source in data_list:
        try:
            im = await refresh_char_by_config(source, uid, ev)
            if isinstance(im, bytes):
                return await bot.send(im)
        except Exception as e:
            continue

    return await bot.send(im)
```
Tokens:
Raw