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

<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesPath - Bộ phân giải Đường dẫn & Môi trường'/>

# Lớp PropertiesPath

Lớp `PropertiesPath` là một tiện ích cốt lõi chịu trách nhiệm chuyển đổi các định danh thiết kế trừu tượng thành các đường dẫn vật lý thực tế trên hệ thống tệp. Nó quản lý việc ánh xạ thư mục cho cả token thiết kế toàn cầu và các ghi đè thành phần cụ thể, đảm bảo việc khám phá đường dẫn đa nền tảng luôn nhất quán. Bằng cách cung cấp các phương thức duyệt kề (traversal) có lưu bộ nhớ đệm (cached) như `to` và `toAll`, nó điều phối chuỗi tải dữ liệu cho các dự án đa chủ đề, đóng vai trò là nguồn thông tin môi trường chính cho engine thuộc tính.

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

- **Ánh xạ Đa thiết kế** — Tự động ánh xạ một mảng tên thiết kế tới các thư mục token và thành phần tương ứng của chúng.
- **Khám phá Gốc đa nền tảng** — Cung cấp `PropertiesFile` để đảm bảo các đường dẫn là tuyệt đối và được phân giải chính xác trên các hệ điều hành khác nhau.
- **Tối ưu hóa Nội bộ (Caching)** — Tích hợp với `PropertiesCache` để giảm thiểu việc truy cập hệ thống tệp dư thừa trong các quy trình chuyển đổi token phức tạp.
- **Phát hiện Chế độ Constructor** — Xác định và xử lý thiết kế đặc biệt `_constructor`, đóng vai trò là cơ sở chung cho tất cả các chủ đề.
- **Duyệt dữ liệu linh hoạt** — Cung cấp các lệnh gọi lại (callbacks) cấp cao để xử lý các tệp thiết kế mà không để lộ các chi tiết thô của hệ thống tệp.

## Khởi tạo

Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesPath(designs)`.

**Tham số:**
- `designs: string[]` — một danh sách các tên thiết kế tương ứng với tên thư mục trong cấu trúc dự án.

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

// 1. Xác định các thiết kế cần quản lý
const activeDesigns = ['basic', 'constructor', 'premium']

// 2. Tạo thực thể bộ phân giải đường dẫn
const pathResolver = new PropertiesPath(activeDesigns)

// 3. Phân giải đường dẫn cho một thiết kế cụ thể
const basicPaths = pathResolver.getPath('basic')
```

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

- `isConstructor(): boolean` — kiểm tra xem môi trường hiện tại có bao gồm thiết kế constructor cơ sở hay không.
- `getDesigns(): string[]` — trả về danh sách tên thiết kế được đăng ký trong thực thể.
- `getPath(name): PropertiesPathItem` — truy xuất các đường dẫn cụ thể (toàn cầu và thành phần) cho một thiết kế nhất định.
- `getPaths(): PropertiesPathList` — trả về bản đăng ký đầy đủ của các ánh xạ từ thiết kế đến đường dẫn.
- `to(name, design, callback): T` — thực thi một lệnh gọi lại chuyển đổi có lưu bộ nhớ đệm cho một thiết kế cụ thể.
- `toAll(name, callback): T` — điều phối một quá trình chuyển đổi toàn cầu có lưu bộ nhớ đệm trên tất cả các thiết kế đã đăng ký.

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

### Luồng Khám phá Môi trường & Lưu bộ nhớ đệm

`PropertiesPath` quản lý việc ánh xạ giữa logic cấp cao và lưu trữ vật lý:
1. **Tổng hợp thư mục**: Khi khởi tạo, lớp chuẩn hóa tên thiết kế thành kiểu kebab-case và sử dụng logic `getDir` nội bộ để tổng hợp các đường dẫn tuyệt đối đến `UI_DIRS_TOKENS` và `UI_DIRS_COMPONENTS`.
2. **Cô lập Thiết kế**: Lớp phân biệt giữa các chủ đề tiêu chuẩn và `_constructor`. Nếu một thiết kế được đánh dấu là constructor, việc khám phá thư mục tiêu chuẩn sẽ bị bỏ qua để cho phép xử lý lớp cơ sở chuyên biệt.
3. **Chuyển đổi có lưu bộ nhớ đệm**: Khi `to()` hoặc `toAll()` được gọi, lớp không chỉ trả về các đường dẫn — nó còn cố gắng lấy dữ liệu đã xử lý trước đó từ `PropertiesCache`. Nếu xảy ra tình trạng không tìm thấy trong bộ nhớ đệm (cache miss), lệnh gọi lại được cung cấp sẽ được thực thi với các đường dẫn đã phân giải và kết quả mới sẽ được lưu trữ một cách minh bạch.
4. **Tổng hợp Hệ thống phân cấp Thống nhất**: Thông qua `toAll()`, lớp cho phép mẫu "hợp nhất ngược" (merge-up), trong đó các token từ nhiều thiết kế (ví dụ: `constructor` + `basic` + `local-theme`) được tải theo chuỗi và kết hợp thành một cấu trúc phân cấp duy nhất bằng `replaceRecursive`.
