56 lines
3.4 KiB
Markdown
56 lines
3.4 KiB
Markdown
# Система отчётов 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` в его `scriptId`.
|
||
|
||
Перед первым 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` — `scriptId` целевого Apps Script
|
||
|
||
Лист `Config` и Script Properties по-прежнему runtime-настройки конкретной таблицы. Профиль отдела задаёт **какой код** в неё попадает.
|
||
|
||
## Как добавить отдел
|
||
|
||
1. Скопируйте `src/departments/universal/` в `src/departments/<id>/`.
|
||
2. В профиле оставьте только нужные плагины. Чтобы подменить логику отчёта, импортируйте свою реализацию с тем же `id` и теми же именами `handlers`.
|
||
3. Добавьте `scriptId` в `departments.json`.
|
||
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 идёт только из этой папки, а не из корня репозитория.
|
||
|
||
Секреты (HMAC, webhook Bitrix) задаются в Script Properties целевого проекта. Что писать на лист `Config` — в [config/README.md](config/README.md).
|