Руководство по внесению кода

Построение бэкенда

Бэкенд этого проекта делится на API и статические ресурсы.

API

• Для работы бэкенда необходимы Web-сервер, PHP и совместимая с MySQL база данных.
  • Рекомендуется использовать: Nginx 1.19, MySQL 5.7, PHP 7.4.

1. Скачайте или клонируйте код на локальный компьютер.
2. Выберите ветку в зависимости от ситуации. Ветка master является официальной версией. Также можно выбрать соответствующую фиксацию по тегу.
3. Импортируйте файл /backend/db_template.sql в базу данных и загрузите все файлы из папки /backend/ на веб-сервер.
4. Введите информацию о базе данных в файле config.php.
5. Измените конфигурацию сервера, чтобы автоматически добавлять HTTP-заголовок Access-Control-Allow-Origin: *.
   • В случае использования Nginx добавьте строку add_header 'Access-Control-Allow-Origin' '*'; в конфигурацию.

Примечание:

Статические ресурсы

• Поскольку требуется разрешение CORS для доступа к бэкенду, может быть невозможно использовать некоторые сервисы хостинга статических ресурсов, такие как Github Pages или Gitee Pages. Рекомендуется создать собственный бэкенд или использовать сервисы Vercel или Netlify.

1. Загрузите или клонируйте код на свой компьютер.
2. Выберите ветку в зависимости от ситуации. Версия master — официальная версия. Также можно выбрать соответствующий коммит по тегу.
3. Загрузите все файлы из папки /static/ на сервер.

Разработка фронтенда

• Необходим браузер с установленным Tampermonkey, а также веб-сервер, который может предоставлять услуги CORS.
  • Можно использовать Violentmonkey, но он не был протестирован.
  • Рекомендуется использовать Visual Studio Code, Firefox Developer Edition 100.0 и Tampermonkey 4.16.

1. Загрузите или клонируйте код на свой компьютер.
2. Выберите ветку в зависимости от ситуации. Версия master — официальная версия. Также можно выбрать соответствующий коммит по тегу.
3. Создайте бэкенд, следуя шагам, описанным в разделе «Построение бэкенда».
4. Внесите изменения в staticURL (статические ресурсы) и backendURL (API) в /TsinghuaCloudRemake.user.js.
5. Откройте /TsinghuaCloudRemake.user.js в браузере и обновите страницу. Установите скрипт в окне Tampermonkey.

Архитектура проекта

Для повышения эффективности разработки и расширения возможностей проекта используется архитектура с разделением на пользовательский скрипт, статический бэкенд и API.

Рабочий процесс

Когда пользователь посещает облачное хранилище университета Цинхуа, Tampermonkey запускает пользовательский скрипт. Скрипт определяет, нужно ли перейти в режим Remake, основываясь на информации текущей страницы. На данный момент режим активируется только на страницах с видео.

После перехода в режим Remake пользовательский скрипт получает статические ресурсы с настроенного статического бэкенда и изменяет текущую страницу на основе этих ресурсов. Затем активирует JavaScript-код в статических ресурсах и завершает выполнение.

JavaScript-код в статических ресурсах инициализирует различные интерактивные интерфейсы и получает необходимую информацию с бэкенда, изменяя текущую страницу.

Пользовательский скрипт

/TsinghuaCloudRemake.user.js, содержит основные настройки, сопоставление типов страниц и функции загрузки ресурсов, но не включает реализацию логики, которая влияет на конкретные страницы.

Эта структура значительно уменьшает размер пользовательского скрипта и позволяет выполнять горячее обновление бэкенда без необходимости частого обновления скрипта пользователем.

Кроме того, в пользовательском скрипте зарезервировано сопоставление для файлов других типов. Это означает, что если в будущем потребуется улучшить обработку других типов файлов, достаточно будет добавить небольшое количество кода и написать новый бэкенд.

Чтобы обеспечить безопасность данных пользователей, пользовательский скрипт не использует UnsafeWindow, а передаёт конфигурационную информацию через элемент <meta>.

Статический бэкенд

Статический бэкенд содержит код для изменения страниц и выполнения логики.

Поскольку статический бэкенд не является частью пользовательского скрипта, JavaScript-код будет работать в режиме native.

API бэкенд

API бэкенд разработан на PHP и включает операции с базой данных и обработку данных.

Принцип разработки API бэкенда заключается в минимизации вычислений для снижения нагрузки на сервер. Кроме того, API бэкенд стремится стать интерфейсом между фронтендом и базой данных.

Компоненты

С версии v1.0.0-beta-2 для лёгкого изменения и разработки были введены компоненты.

Компоненты состоят из файла входа widget.js и других ресурсов, которые загружаются асинхронно.

Файл /static/widgets.json содержит массив с краткой информацией обо всех компонентах. При использовании компонентов необходимо заполнить информацию о них в файле /static/widgets.json, например:

{
    "id": "shao-note",
    "url": "",
    "name": "SHAO Note",
    "description": "A note taking widget based on SHAO-Pastebin",
    "context": [
        "video"
    ],
    "enabled": true
}

Можно загрузить компоненты из внешних адресов, указав URL в ключе url. Если url пуст, скрипт загрузит файл widget.js из папки widgets в каталоге статических ресурсов бэкенда с именем, соответствующим идентификатору компонента.

Во время работы компонента можно просмотреть информацию обо всех компонентах, вызвав глобальную переменную widgetList.