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

<Meta title='@dxtmisha/vi/scripts/Classes/DesignStructure - Động cơ phân giải dữ liệu thành phần'/>

# Lớp DesignStructure

Lớp `DesignStructure` là bộ phân giải dữ liệu nền tảng cho các thành phần của hệ thống thiết kế. Nó điều phối việc đọc, lưu trữ (caching) và xử lý dữ liệu thành phần có cấu trúc, bao gồm các thuộc tính, phân cấp lớp CSS và các token kiểu dáng. Nó đóng vai trò là một lớp trừu tượng giữa các tệp cấu hình thô và các động cơ chuyển đổi mẫu.

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

- **Truy cập dữ liệu thống nhất** — Cung cấp API tập trung để truy xuất tất cả siêu dữ liệu liên quan đến một thành phần cụ thể.
- **Bộ nhớ đệm thông minh** — Sử dụng `PropertiesCache` để tránh các thao tác hệ thống tệp dư thừa và tăng tốc độ xử lý nhiều thành phần.
- **Ánh xạ lớp con (Subclass Mapping)** — Phân giải các phân cấp lớp CSS phức tạp cho các cấu trúc thành phần đệ quy.
- **Phơi bày Token kiểu dáng** — Trích xuất và định dạng các token thiết kế thành một định dạng sẵn sàng cho việc tạo SCSS.
- **Điều phối quy ước đặt tên** — Tiêu chuẩn hóa việc đặt tên thành phần, thiết kế và tệp trong toàn bộ quá trình xây dựng.

## Khởi tạo

Để khởi tạo một bộ phân giải cấu trúc, hãy cung cấp mã định danh của thành phần. Lớp sẽ tự động liên kết nó với cấu hình thiết kế của dự án hiện tại.

**Tham số:**
- `component?: string` — Mã định danh cho thành phần (ví dụ: `'button'`, `'list'`). Mặc định là `'component'`.

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

const structure = new DesignStructure('button')
const properties = structure.get()
```

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

### Thu thập dữ liệu

- `get(): DesignStructureList` — Truy xuất danh sách đầy đủ các thuộc tính và siêu dữ liệu của thành phần, có sử dụng bộ nhớ đệm.
- `getClasses(): DesignStructureClassesList` — Phân giải phân cấp các lớp CSS cho thành phần.
- `getStyles(): string[]` — Trả về các token kiểu dáng đã được định dạng được lấy từ cấu trúc của thành phần.

### Đặt tên & Định danh

- `getDesign(): string` — Trả về mã định danh hệ thống thiết kế hiện tại (ví dụ: `'misha'`).
- `getDesignFirst(): string` — Trả về mã định danh thiết kế được định dạng với chữ cái đầu viết hoa.
- `getComponentName(): string` — Trả về tên thành phần thô.
- `getComponentNameFirst(): string` — Trả về tên thành phần với chữ cái đầu viết hoa.
- `getFullComponentName(): string` — Kết hợp tên thiết kế và tên thành phần (ví dụ: `'MishaButton'`).
- `getFileName(): string` — Trả về tên tệp tiêu chuẩn cho triển khai của thành phần.
- `getPathName(): string` — Trả về mã định danh duy nhất cho các khóa bộ nhớ đệm và đường dẫn hệ thống.

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

### Quy trình phân giải (The Resolution Pipeline)

Khi dữ liệu được yêu cầu (ví dụ: thông qua `get()` hoặc `getClasses()`), lớp sẽ kích hoạt một quy trình phân giải theo mô-đun:
1. **Xác thực bộ nhớ đệm**: Đầu tiên, nó kiểm tra xem dữ liệu đã xử lý đã tồn tại trong `PropertiesCache` dưới một khóa được tạo bởi `getPathName()` hay chưa.
2. **Ủy quyền mô-đun**: Nếu dữ liệu thiếu trong bộ nhớ đệm, nó sẽ ủy quyền công việc nặng nề cho các lớp "Read" chuyên biệt:
    - **DesignStructureRead**: Xử lý việc trích xuất các thuộc tính và giá trị.
    - **DesignStructureClasses**: Quản lý việc xây dựng các cây lớp (class trees).
    - **DesignStructureStyles**: Xử lý các token thành các chuỗi kiểu dáng.
3. **Lưu trữ lâu dài**: Dữ liệu đã phân giải được lưu ngược trở lại vào bộ nhớ đệm để nâng cao hiệu suất cho các lần gọi tiếp theo trong cùng một chu kỳ xây dựng.

### Tích hợp với các động cơ mẫu

`DesignStructure` cung cấp "Nguồn sự thật" cho các lớp như `DesignReplace`. Bằng cách tiêu chuẩn hóa cách phân giải tên và đường dẫn, nó đảm bảo rằng mọi tệp được tạo (Vue, TS, SCSS) đều sử dụng các mã định danh nhất quán và duy trì các tham chiếu đường dẫn tương đối chính xác trong không gian làm việc.
