**SUBJECT:** **企业级加密货币图标系统（Crypto Icon System）详细设计与实现指令**

**背景 (Context):**

你将为我们的企业级SaaS应用构建一个高性能、类型安全且完全符合设计规范的加密货币图标系统。此系统不仅需要展示单个货币图标，还需优雅地处理交易对的堆叠图标样式。该模块必须严格遵守项目 `vue3-typescript-stye.md` 中定义的所有架构原则、编码规范和技术选型。

**核心指令 (Core Directive):**

请根据以下详细设计，实现一个完整的、可复用的、生产级的加密货币图标系统。该系统主要由一个核心的组合式函数（Composable）用于数据管理，以及一个UI组件用于渲染构成。

-----

### **1. 体系结构与设计哲学 (Architecture & Philosophy)**

此图标系统旨在将图标数据管理与UI渲染完全分离，以实现最大程度的内聚和可复用性。

  * **数据层 (Data Layer):** 通过一个**组合式函数 `useCrypto.ts`** 进行管理。该函数在应用启动时加载并索引一次静态图标数据，提供高效、响应式的查询接口供任何组件使用。数据是静态的，在构建时生成，确保了运行时的高性能和零API依赖。
  * **表现层 (Presentation Layer):** 一个**单一职责组件 `CryptoIcon.vue`** 负责根据传入的标识符（单个货币或交易对）从数据层获取SVG数据并完成渲染。该组件将完全兼容Vuetify的尺寸、响应式和主题系统。

-----

### **2. 数据管理模块 (`composables/useCrypto.ts`)**

这是系统的核心逻辑，负责图标数据的加载、索引和查询。

**2.1. 数据源与生成 (Data Source & Generation)**

  * **数据来源:**
      * **元数据:** 使用python3构建脚本,放置于`ProjectTonyStack/TonyMask/scripts/`中,用于从[TradingView](https://tradingview.com/markets/cryptocurrencies/prices-all/) 或者从稳定、公开的加密货币API（例如 CoinGecko 或 CoinMarketCap 的免费API）通过手动执行，获取前1000名加密货币的图标数据。
      * **SVG图标:** 不要使用开源库 **`cryptocurrency-icons`**。该库的内容过时,无法满足需求,请设计爬虫脚本爬取svg图标数据。
  * **数据静态化:**
      * 该脚本将整合后的元数据和SVG内容生成一个静态的 `crypto-data.ts` 文件，存放于 `src/assets/` 目录下。此文件将导出一个类型为 `CryptoCurrencyInfo[]` 的常量数组。这种方式避免了客户端的运行时API请求，极大地提升了性能和稳定性。
      * 对于未在 `cryptocurrency-icons` 库中找到的图标，脚本应自动关联一个预定义的“未知货币”SVG图标。

**2.2. 数据结构定义 (`types/crypto.d.ts`)**

```typescript
// src/types/crypto.d.ts

/**
 * @interface CryptoCurrencyInfo
 * @description 定义了单个加密货币的完整信息结构。
 */
export interface CryptoCurrencyInfo {
  /** 货币的唯一ID (e.g., "bitcoin") */
  id: string;
  /** 货币简称/符号 (e.g., "BTC") */
  symbol: string;
  /** 货币全称 (e.g., "Bitcoin") */
  name: string;
  /** 货币全称的大写形式 (e.g., "BITCOIN") */
  nameUpperCase: string;
  /** 货币的SVG图标原始内容 (作为字符串) */
  svg: string;
  /** 市值排名 */
  marketCapRank: number;
}
```

**2.3. Composable 实现 (`useCrypto.ts`)**

  * **状态管理:**

      * 使用 `shallowRef` 来存储从 `crypto-data.ts` 导入的完整货币列表，因为该数据在应用生命周期内是只读的，无需深度响应。
      * 在首次调用时，一次性构建多个 `Map` 对象用于快速索引，并将其存储在模块作用域的常量中，实现单例模式，避免重复计算。

  * **高效查询机制:**

      * **O(1) 查找:** 创建三个独立的 `Map` 来满足不同的查询需求：
        1.  `symbolMap: Map<string, CryptoCurrencyInfo>` (通过简称查询, e.g., 'BTC')
        2.  `nameMap: Map<string, CryptoCurrencyInfo>` (通过全称小写查询, e.g., 'bitcoin')
        3.  `idMap: Map<string, CryptoCurrencyInfo>` (通过ID查询, e.g., 'bitcoin')
      * **查询函数 `findCryptoInfo`:**
          * 设计一个签名清晰的函数 `const findCryptoInfo = (identifier: string): CryptoCurrencyInfo | undefined => { ... }`。
          * 该函数内部将尝试按以下顺序和逻辑进行高效查找：
            1.  将输入 `identifier` 转换为小写。
            2.  优先在 `symbolMap` 中查找。
            3.  若未找到，则在 `nameMap` 中查找。
            4.  若仍未找到，则在 `idMap` 中查找。
            5.  返回找到的 `CryptoCurrencyInfo` 对象，否则返回 `undefined`。
      * **交易对解析函数 `parseTradingPair`:**
          * 设计一个函数 `const parseTradingPair = (pair: string): { base: CryptoCurrencyInfo | undefined, quote: CryptoCurrencyInfo | undefined } => { ... }`。
          * 该函数负责解析常见的交易对格式（如 `BTCUSDT`, `ETHUSDT`）。它会尝试从已知的稳定币后缀（`USDT`, `USDC`, `BUSD`, `DAI`等）分割基础货币和计价货币，然后分别调用 `findCryptoInfo` 进行查找。

-----

### **3. UI组件 (`components/CryptoIcon.vue`)**

此组件是图标的最终渲染载体。

**3.1. 组件API设计 (Props)**

```typescript
// CryptoIcon.vue
import type { CryptoCurrencyInfo } from '@/types/crypto.d.ts';

interface Props {
  /** 单个货币标识符 (简称、全称或ID)，与`pair`属性互斥 */
  symbol?: string;
  /** 交易对字符串 (e.g., "BTCUSDT")，与`symbol`属性互斥 */
  pair?: string;
  /**
   * 图标尺寸，可以是数字(px)或Vuetify预设的尺寸字符串
   * @default 24
   */
  size?: string | number;
  /**
   * 是否仅显示图标，不显示旁边的名称
   * @default false
   */
  iconOnly?: boolean;
}
```

  * 组件逻辑中必须包含对 `symbol` 和 `pair` 互斥性的校验。

**3.2. 渲染逻辑 (`<template>`)**

  * **根元素:** 使用 `div` 作为容器，并应用 `d-inline-flex align-center` 以确保图标和文字垂直对齐。
  * **图标容器:**
      * **单个图标:** 直接渲染一个 `div`，使用 `v-html` 绑定从 `useCrypto` composable中查找到的SVG字符串。
      * **交易对图标:**
          * 创建一个相对定位的容器 `div` (`position: relative`)。
          * 内部渲染两个绝对定位的 `div`，分别用于基础货币和计价货币。
          * **样式:** 仿照TradingView，基础货币图标（左）尺寸为100%，计价货币图标（右下）尺寸约为60%，通过 `bottom: -10%; right: -10%;` 进行偏移，并设置更高的 `z-index` 和一个小的白色边框（使用Vuetify主题变量 `rgb(var(--v-theme-surface))`）以创建堆叠效果。
  * **健壮性:**
      * 当 `findCryptoInfo` 或 `parseTradingPair` 返回 `undefined` 时，必须优雅地降级，显示预定义的“未知货币”图标。
      * 使用可选链 (`?.`) 和空值合并运算符 (`??`) 安全地访问数据。
  * **名称展示:**
      * 当 `iconOnly` 为 `false` 时，在图标右侧渲染货币全称大写 (`nameUpperCase`)。使用 `v-if` 控制其显示。
      * 使用 `v-text` 绑定名称，并应用Vuetify的排版类 (`text-subtitle-2` 或类似)。

**3.3. 样式与主题 (Styling & Theming)**

  * **严禁硬编码颜色。** SVG内部的 `fill` 或 `stroke` 属性，如果需要跟随主题变化（例如在单色图标版本中），应设置为 `currentColor`。
  * 组件的所有样式必须能完美适配**明亮 (Light)** 和**黑暗 (Dark)** 两种主题。边框、背景等颜色必须使用Vuetify主题变量，如 `border-color: rgb(var(--v-theme-surface));`。

**3.4. 无障碍 (Accessibility - a11y)**

  * 图标的根元素需添加 `role="img"`。
  * 动态绑定 `aria-label` 属性，其内容为货币的全称（例如 `aria-label="Bitcoin"`）或交易对的名称（例如 `aria-label="Bitcoin / Tether"`），为屏幕阅读器用户提供清晰的上下文。

-----

### **4. 项目结构整合 (Directory Structure)**

```
src/
├── assets/
│   └── crypto-data.ts      # (构建时生成) 静态图标数据
├── components/
│   └── CryptoIcon.vue        # UI渲染组件
├── composables/
│   └── useCrypto.ts          # 数据逻辑与查询核心
├── types/
│   └── crypto.d.ts           # TypeScript类型定义
scripts/
└── generate-crypto-data.ts   # 用于在构建时生成数据的Node.js脚本
```

-----

### **5. 最终实现指令 (Actionable Prompt for Implementation)**

现在，请严格遵循以上这份详尽的架构设计方案，完成`CryptoIcon.vue`组件、`useCrypto.ts`组合式函数、`crypto.d.ts`类型定义文件以及`generate-crypto-data.ts`构建脚本的编码工作。确保最终产出的代码是生产级的，完全符合`vue3-typescript-stye.md`中定义的所有规范，特别是在TypeScript强类型、组合式API、Vuetify 3集成、主题适配和代码健壮性方面达到典范水平。