umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
235 lines (234 loc) • 10.1 kB
TypeScript
import { IModelRules } from './interface';
import { IModelState, Model } from './db/Model';
import { IDbResult, AppContext } from '../core';
import { TKey } from './db';
/**
* Тип для мета-данных
*/
export type TMetaType = Record<string, unknown> | string | null | undefined;
/**
* Тип для возвращаемых данных
*/
export type TDataType = string | Record<string, unknown> | null | undefined;
/**
* Интерфейс для внутреннего состояния модели пользовательских данных.
* Определяет структуру данных для хранения информации о пользователях в базе данных.
*/
export interface IUserDataModelState extends IModelState {
/**
* Идентификатор пользователя.
* Уникальный идентификатор пользователя в конкретной платформе.
* @example "123456789" для Telegram, "user_123456" для VK
*/
userId: string | number | null;
/**
* Метаданные пользователя в JSON.
* Содержит дополнительную информацию о пользователе, такую как статистика использования,
* настройки, временные метки и т.д.
* @example { "lastVisit": "2024-03-20T12:00:00Z", "usageCount": 42 }
*/
meta: TMetaType;
/**
* Пользовательские данные в JSON.
* Содержит основное состояние пользователя, например, прогресс в игре,
* сохраненные настройки, историю действий и т.д.
* @example { "progress": 75, "settings": { "notifications": true } }
*/
data: string | Record<string, unknown> | null;
/**
* Тип платформы.
* Определяет, на какой платформе зарегистрирован пользователь.
*/
platform: string;
}
/**
* Модель для работы с пользовательскими данными.
* Предоставляет единый интерфейс для работы с данными пользователей во всех поддерживаемых платформах.
*
* Основные возможности:
* - Сохранение состояния пользователя между сессиями
* - Хранение метаданных (например, статистика использования)
* - Поддержка как файлового хранилища, так и БД
* - Автоматическая сериализация/десериализация данных
*
* @example
* Сохранение прогресса пользователя:
* ```ts
* class GameController extends BotController {
* public async action(intentName: string): Promise<void> {
* // Загрузка данных пользователя
* const userData = new UsersData(this.appContext);
* userData.userId = this.userId;
*
* // Если есть сохраненные данные - загружаем их
* if (await userData.getOne()) {
* const progress = userData.data.progress || 0;
* this.text = `Ваш текущий прогресс: ${progress}%`;
* } else {
* // Создаем новые данные
* userData.data = { progress: 0 };
* userData.meta = { firstVisit: new Date() };
* await userData.save();
* this.text = 'Добро пожаловать в игру!';
* }
* }
* }
* ```
*
* @example
* Работа с разными платформами:
* ```ts
* const userData = new UsersData(appContext);
*
* // Для Алисы
* userData.platform = T_ALISA;
*
* // Для Telegram
* userData.platform = T_TELEGRAM;
* ```
*/
export declare class UsersData extends Model<IUserDataModelState> {
/**
* Название таблицы для хранения данных пользователей.
* @readonly
*/
static readonly TABLE_NAME = "UsersData";
/**
* Создает экземпляр модели пользовательских данных.
* Предоставляет унифицированный интерфейс для хранения данных пользователя.
*
* @example
* ```ts
* const userData = new UsersData(appContext);
* userData.userId = 'user123';
* userData.type = UsersData.T_TELEGRAM;
* ```
*/
constructor(appContext: AppContext);
protected getId(): TKey;
/**
* Уникальный идентификатор пользователя.
* Может быть строкой или числом в зависимости от платформы.
* @example "123456789" для Telegram, 123456789 для VK
*/
get userId(): string | number | null | undefined;
/**
* Устанавливает уникальный идентификатор пользователя.
* @param userId
*/
set userId(userId: string | number | null);
/**
* Метаданные пользователя.
* Может содержать любые дополнительные данные о пользователе, такие как:
* - Статистика использования
* - Временные метки
* - Настройки пользователя
* - Дополнительная информация
* @remarks При сохранении в БД автоматически преобразуется в JSON строку
*/
get meta(): TMetaType;
/**
* Устанавливает метаданные пользователя.
* @param meta
*/
set meta(meta: TMetaType);
/**
* Основные данные пользователя.
* Содержит основное состояние пользователя, например:
* - Прогресс в игре
* - Сохраненные настройки
* - История действий
* - Другие пользовательские данные
* @remarks При сохранении в БД автоматически преобразуется в JSON строку
*/
get data(): TDataType;
/**
* Устанавливает основные данные пользователя.
* @param data
*/
set data(data: TDataType);
/**
* Тип платформы пользователя.
* Определяет платформу, с которой работает пользователь.
*/
set platform(platform: string);
/**
* Тип платформы пользователя.
* Определяет платформу, с которой работает пользователь.
*/
get platform(): string;
/**
* Возвращает название таблицы/файла для хранения данных.
*
* @return {string} Название таблицы для хранения данных пользователей
*/
tableName(): string;
/**
* Определяет правила валидации полей модели.
*
* @return {IModelRules[]} Массив правил валидации
*/
rules(): IModelRules[];
/**
* Возвращает описания атрибутов модели.
* Используется для отображения понятных названий полей.
*
* @return {IUserDataModelState} Описания атрибутов
*/
attributeLabels(): IUserDataModelState;
/**
* Ищет одну запись в хранилище по текущим параметрам.
*
* @return {Promise<boolean>} true, если запись найдена
*
* @example
* ```ts
* const userData = new UsersData(appContext);
* userData.userId = 'user123';
* if (await userData.getOne()) {
* console.log('Пользователь найден:', userData.data);
* } else {
* console.log('Пользователь не найден');
* }
* ```
*/
getOne(): Promise<boolean>;
private safeStringify;
/**
* Валидирует значения перед сохранением.
* Преобразует объекты meta и data в JSON при сохранении в БД.
*
* @throws {Error} Если данные не прошли валидацию
*
* @example
* ```ts
* userData.meta = { lastVisit: new Date() };
* userData.data = { progress: 75 };
* userData.validate(); // meta и data будут преобразованы в JSON
* ```
*/
validate(): void;
/**
* Инициализирует модель данными.
* Преобразует JSON строки meta и data в объекты при загрузке из БД.
*
* @param data - Данные для инициализации
* @remarks
* - При парсинге data, ошибки игнорируются для обеспечения обратной совместимости
* - Парсинг происходит только если включено сохранение в БД (appContext.isSaveDb === true)
*
* @example
* ```ts
* const userData = new UsersData(appContext);
* userData.init({
* userId: 'user123',
* meta: '{"lastVisit":"2024-03-20T12:00:00Z"}',
* data: '{"progress":75}',
* platform: T_TELEGRAM
* });
* console.log(userData.meta.lastVisit); // Date object
* console.log(userData.data.progress); // 75
* ```
*/
init(data: IDbResult[] | IDbResult | null): void;
}