import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/scripts/Classes/DesignWikiStormItem - Bộ phân giải siêu dữ liệu IDE cho thành phần'/>

# Lớp DesignWikiStormItem

Lớp `DesignWikiStormItem` là một bộ phân giải chi tiết (granular resolver) chịu trách nhiệm trích xuất, phân tích và định dạng siêu dữ liệu cho một thành phần UI duy nhất. Nó đóng vai trò là cầu nối giữa tài liệu nội bộ hướng đến Storybook và định dạng `web-types.json`, đảm bảo rằng mọi thuộc tính và mô tả đều được ánh xạ chính xác cho IntelliSense trong IDE.

## Các tính năng chính

- **Ánh xạ Storybook sang WebTypes** — Tự động chuyển đổi các đối tượng `WikiStorybook` thành các định nghĩa thẻ (tags) tương thích với JetBrains.
- **Phân giải Module động** — Tính toán chính xác các đường dẫn module cho các thành phần để hỗ trợ tính năng "Jump to Definition" trong các IDE.
- **Tài liệu theo ngữ cảnh** — Bảo tồn và định dạng các mô tả thành phần, kiểu dữ liệu thuộc tính và các giá trị mặc định.
- **Truy xuất dữ liệu theo chương trình** — Nhập (import) và phân tích các tệp `wikiData.ts` theo chương trình để lấy siêu dữ liệu thực tế của thành phần.
- **Tổng hợp thuộc tính** — Xây dựng danh sách các thuộc tính bằng cách phân giải các kiểu dữ liệu phức tạp thành các chuỗi IDE dễ đọc cho con người.

## Khởi tạo

Khởi tạo bộ phân giải bằng cách cung cấp ngữ cảnh dự án, đường dẫn cấu trúc và siêu dữ liệu thư viện của thành phần.

**Tham số:**
- `project: string` — Tên của dự án (ví dụ: `'@dxtmisha/ui'`).
- `path: string[]` — Các đoạn đường dẫn trong hệ thống tệp dẫn đến thư mục thành phần.
- `data: LibraryData` — Siêu dữ liệu cốt lõi của thành phần (tên, bí danh, thư mục).

```typescript
import { DesignWikiStormItem } from '@dxtmisha/scripts'

const resolver = new DesignWikiStormItem(
  '@dxtmisha/ui',
  ['packages', 'core', 'src', 'components'],
  componentData
)
await resolver.init()
const tagMetadata = resolver.get()
```

## Các phương thức

### Thu thập thông tin

- `get(): WebTypesTagItem | undefined` — Trả về định nghĩa thẻ đã hợp nhất chứa tên, mô tả, nguồn và các thuộc tính.
- `getAttribute(item: WikiStorybookProp): WebTypesAttributeItem` — Chuyển đổi một thuộc tính Storybook duy nhất thành định nghĩa thuộc tính Web-Types.
- `getAttributes(): WebTypesAttributes` — Biên soạn danh sách đầy đủ các thuộc tính cho thành phần.

### Điều khiển

- `init(): Promise<this>` — Khởi tạo bất đồng bộ instance `WikiStorybook` nội bộ bằng cách tải dữ liệu tài liệu của thành phần.

## Các thao tác (Operations)

### Quy trình trích xuất siêu dữ liệu

Khi bộ phân giải được khởi tạo và truy vấn, nó tuân theo một quy trình dữ liệu có cấu trúc:
1. **Tải dữ liệu Wiki (`initWiki`)**: Nó phân giải đường dẫn tệp đến `wikiData.ts` của thành phần và thực hiện import động để lấy siêu dữ liệu thực tế (props, defaults, design tokens).
2. **Tổng hợp thẻ (`get`)**: Nó xây dựng tên thẻ IDE bằng cách kết hợp bí danh của hệ thống thiết kế với tên thành phần nội bộ.
3. **Ánh xạ nguồn (Source Mapping)**: Nó xác định các thuộc tính `module` và `symbol`, cho phép các IDE liên kết siêu dữ liệu ngược lại mã nguồn thực tế.
4. **Biên soạn thuộc tính (`getAttributes`)**: Nó duyệt qua mọi thuộc tính được định nghĩa trong wiki, phân giải chú thích tài liệu, kiểu dữ liệu TypeScript và giá trị mặc định của nó thành một cấu trúc JSON chuẩn hóa.

### Vai trò trong Động cơ IDE

`DesignWikiStormItem` là "ngựa thồ" (workhorse) của bộ công cụ tạo siêu dữ liệu. Trong khi `DesignWikiStorm` quản lý cấu trúc tệp tổng thể, lớp này xử lý sự phức tạp của việc phân tích từng thành phần riêng lẻ, đảm bảo rằng logic UI chuyên biệt được biểu diễn chính xác dưới định dạng mà các công cụ phát triển có thể hiểu được.
