bitrix_task_control/README.md

64 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Система отчётов Google Sheets
Исходник правды — git. Редактор Apps Script только для запуска: следующий `clasp push` затрёт ручные правки.
Сборка даёт IIFE (`const __gas = (...)()`). Меню и `onOpen` Apps Script находит только по объявлениям `function onOpen()` на верхнем уровне файла, поэтому после бандла `tools/build.mjs` дописывает такие обёртки.
## Команды
```bash
npm install
npm test
npm run build -- universal
npm run push -- universal
npm run deploy -- universal
```
`deploy` гоняет тесты, собирает бандл отдела и делает `clasp push` в каждый проект из его `scriptIds`.
Перед первым push: `npx clasp login`.
## Структура
- `src/core` — общее ядро (конфиг, листы, почта, Bitrix, даты, коды задач)
- `src/reports/<id>` — отчёт-плагин: меню, обработчики, свои ключи Config
- `src/departments/<id>/profile.ts` — состав поставки отдела
- `src/departments/<id>/entry.ts` — точка сборки
- `tests` — Vitest, без SpreadsheetApp
- `dist/<id>` — собранный проект для clasp (в git не кладётся)
- `departments.json` — `scriptIds` целевых проектов Apps Script
Лист `Config` и Script Properties по-прежнему runtime-настройки конкретной таблицы. Профиль отдела задаёт **какой код** в неё попадает.
## Как добавить отдел
1. Скопируйте `src/departments/universal/` в `src/departments/<id>/`.
2. В профиле оставьте только нужные плагины. Чтобы подменить логику отчёта, импортируйте свою реализацию с тем же `id` и теми же именами `handlers`.
3. Добавьте `scriptIds` в `departments.json`. Один профиль можно отправить в несколько проектов: перечислите их id в массиве. Поле `scriptId` со строкой по-прежнему означает один проект.
```json
"salesOriginal": {
"scriptIds": ["SCRIPT_ID_TABLE_1", "SCRIPT_ID_TABLE_2"],
"htmlFiles": ["DateRangeDialog.html"]
}
```
4. `npm run deploy -- <id>`.
Уникальный отчёт кладите в `src/reports/<newId>/` и подключайте только в профилях, которым он нужен.
## Как добавить отчёт
1. Папка `src/reports/<id>/` с `index.ts`, где экспортируется `ReportPlugin`.
2. В плагине: `menuTitle`, `menuItems`, `handlers`, при необходимости `requiredConfigKeys` / `requiredScriptProperties`.
3. Чистую логику (строки → строки отчёта) выносите в отдельный файл и покрывайте тестом, как `src/reports/bigSmall/builder.ts`.
4. Подключите плагин в профиле отдела.
Имена глобальных функций из меню текущего эталона (`universal`) не меняйте — на них могут висеть привычка и триггеры.
## Выкат в таблицу
Сборка кладёт в `dist/<id>/` файлы `Code.js`, `appsscript.json`, HTML и `.clasp.json`. Push идёт только из этой папки, а не из корня репозитория. Если в профиле несколько `scriptIds`, один и тот же бандл отправляется в каждый проект по очереди.
Секреты (HMAC, webhook Bitrix) задаются в Script Properties целевого проекта. Что писать на лист `Config` — в [config/README.md](config/README.md).