195 lines
11 KiB
Markdown
195 lines
11 KiB
Markdown
# Техническое задание: Система учёта оборудования и материальных средств
|
||
|
||
## 🎯 Тип проекта
|
||
Учётная система с веб-интерфейсом для одного администратора и нескольких пользователей с доступом по ссылке.
|
||
|
||
## 🧱 Стек (жёстко)
|
||
- **Бэкенд:** Node.js (CommonJS) + `node:http` без зависимостей
|
||
- **Хранение:** `data.json` (файл в корне проекта)
|
||
- **Фронтенд:** Статичный `index.html` + `style.css` + `script.js` (ванильный JS)
|
||
- **Дизайн:** Дизайн-система KT AI из папки `design-system/` (классы и токены)
|
||
- **Запуск:** Команда `run` (порт `process.env.PORT || 3000`)
|
||
|
||
---
|
||
|
||
## 📋 Модель данных
|
||
|
||
Файл `data.json` содержит две сущности:
|
||
|
||
```js
|
||
{
|
||
"items": [
|
||
{
|
||
"id": 1725700000000,
|
||
"name": "Наименование оборудования",
|
||
"type": "тип (инструмент/оргтехника/СИЗ/транспорт/склад)",
|
||
"serialNumber": "Серийный номер",
|
||
"inventoryNumber": "Инвентарный номер",
|
||
"location": "Местоположение",
|
||
"responsible": "Ответственный сотрудник",
|
||
"status": "в эксплуатации / на складе / в ремонте / списано",
|
||
"lastCheckDate": "2025-09-01",
|
||
"nextCheckDate": "2026-09-01",
|
||
"checkIntervalMonths": 12,
|
||
"note": "Комментарий",
|
||
"createdAt": "2025-01-15",
|
||
"updatedAt": "2025-09-07"
|
||
}
|
||
],
|
||
"log": [
|
||
{
|
||
"id": 1725700000000,
|
||
"timestamp": "2025-09-07T10:30:00.000Z",
|
||
"action": "создана / изменена / удалена / проверка пройдена",
|
||
"itemId": 1725700000000,
|
||
"itemName": "Наименование",
|
||
"user": "Имя пользователя (если есть авторизация)",
|
||
"changes": { "field": "старое значение → новое значение" }
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🖥 Обязательные экраны
|
||
|
||
### 1. Главная — Таблица всех записей
|
||
- Отображение всех записей в виде таблицы
|
||
- Колонки: Название, Тип, Инвентарный номер, Ответственный, Местоположение, Статус, Дата следующей проверки
|
||
- Сортировка по колонкам (кликом по заголовку)
|
||
- Пагинация (по 20-50 записей на странице)
|
||
|
||
### 2. Поиск и фильтры
|
||
- Строка поиска по подстроке (фильтрует по всем текстовым полям)
|
||
- Фильтр по статусу (кнопки-чипсы: все / в эксплуатации / на складе / в ремонте / списано)
|
||
- Фильтр по типу оборудования
|
||
- **Фильтр «Требуют проверки»** — показывает записи, где `nextCheckDate` ближе чем 30 дней (или настраиваемый порог)
|
||
|
||
### 3. Форма добавления/редактирования
|
||
- Модальное окно или отдельная страница
|
||
- Поля: все обязательные из модели данных (name, type, serialNumber, inventoryNumber, location, responsible, status, lastCheckDate, nextCheckDate, checkIntervalMonths, note)
|
||
- Автоподстановка `nextCheckDate` при вводе `lastCheckDate` + `checkIntervalMonths`
|
||
- Кнопки: Сохранить / Отмена
|
||
|
||
### 4. Счётчики сверху
|
||
- Всего записей
|
||
- По каждому статусу (в эксплуатации / на складе / в ремонте / списано)
|
||
- **Требуют проверки в ближайшие 30 дней** (выделено цветом)
|
||
|
||
### 5. Журнал изменений (log)
|
||
- Отдельная вкладка или модальное окно
|
||
- Таблица: Дата/время, Действие, Запись, Кто изменил, Что изменилось
|
||
- Фильтр по дате и действию
|
||
|
||
### 6. Выгрузка в Excel
|
||
- Кнопка «Выгрузить в Excel» на главной
|
||
- Генерация CSV с BOM (кириллица корректно открывается в Excel)
|
||
- Выгрузка всех записей или отфильтрованных
|
||
|
||
---
|
||
|
||
## 🔔 Алерты (уведомления о проверках)
|
||
|
||
### Вариант 1 — Внутри системы (обязательно)
|
||
- Блок «Требуют внимания» на главной странице
|
||
- Красным выделены записи, где `nextCheckDate` < сегодня (просрочено)
|
||
- Оранжевым — где `nextCheckDate` в ближайшие 30 дней
|
||
- Счётчик просроченных проверок в шапке
|
||
|
||
### Вариант 2 — Telegram-бот (опционально, если пользователь попросит)
|
||
- Отдельный бот на grammY (long-polling)
|
||
- Ежедневная рассылка администратору списка оборудования с приближающейся проверкой
|
||
- Команда `/check` — показать список требующих проверки
|
||
- Команда `/add` — быстрое добавление записи через бота
|
||
|
||
---
|
||
|
||
## 🎨 Дизайн
|
||
|
||
- Использовать классы и токены из `design-system/` (KT AI)
|
||
- Тёмная или светлая тема — по умолчанию светлая, переключатель в шапке
|
||
- Таблица с закреплённой шапкой
|
||
- Адаптивная вёрстка (корректно на мобильных)
|
||
- Статусы цветом: в эксплуатации (зелёный), на складе (синий), в ремонте (оранжевый), списано (серый)
|
||
|
||
---
|
||
|
||
## 📂 Структура файлов
|
||
|
||
```
|
||
project/
|
||
├── package.json # { "name": "uchet", "private": true, "type": "commonjs", "scripts": { "start": "node server.js" } }
|
||
├── server.js # Сервер на node:http + CRUD API + раздача статики
|
||
├── index.html # Главный экран (таблица + фильтры + счётчики)
|
||
├── style.css # Стили + подключение design-system/
|
||
├── script.js # Логика фронтенда (fetch к API, рендер таблицы, фильтры)
|
||
├── data.json # Хранилище данных (не коммитить в git)
|
||
├── .gitignore # data.json, node_modules/, .vibe42-run.log, .vibe42-run.pid
|
||
└── design-system/ # Дизайн-система KT AI (из корня воркспейса)
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠 API (server.js)
|
||
|
||
| Метод | Путь | Описание |
|
||
|-------|------|----------|
|
||
| GET | `/api/items` | Список всех записей |
|
||
| GET | `/api/items/:id` | Одна запись по ID |
|
||
| POST | `/api/items` | Создать запись |
|
||
| PUT | `/api/items/:id` | Обновить запись |
|
||
| DELETE | `/api/items/:id` | Удалить запись (с записью в log) |
|
||
| GET | `/api/log` | Журнал изменений |
|
||
| GET | `/api/stats` | Счётчики (всего, по статусам, требуют проверки) |
|
||
|
||
---
|
||
|
||
## ✅ Чек-лист сдачи
|
||
|
||
- [ ] `node --check server.js` и `node --check script.js` без ошибок
|
||
- [ ] Пути fetch в `script.js` совпадают с роутами в `server.js`
|
||
- [ ] Все поля формы есть в модели данных и на бэкенде
|
||
- [ ] Фильтр «Требуют проверки» работает (сравнение дат)
|
||
- [ ] Удаление с подтверждением `confirm()` и записью в `log`
|
||
- [ ] Выгрузка в CSV с BOM (`\uFEFF` в начале)
|
||
- [ ] Счётчики сверху обновляются при изменении данных
|
||
- [ ] `run` запускается без ошибок в логе
|
||
- [ ] Предпросмотр показывает актуальную вёрстку
|
||
|
||
---
|
||
|
||
## ❓ Вопросы для пользователя (задать перед сборкой)
|
||
|
||
1. **Какое оборудование учитываем?** (инструменты, оргтехника, СИЗ, транспорт, склад — от этого зависят типы и доп. поля)
|
||
|
||
2. **Нужны ли дополнительные поля?** (например: стоимость, дата покупки, поставщик, гарантия, фото оборудования)
|
||
|
||
3. **Кто такие «пользователи»?** (просто люди с ссылкой — все могут редактировать, или нужны уровни доступа: только просмотр / только добавление / полное редактирование)
|
||
|
||
4. **Алерты: только внутри системы или ещё и в Telegram?** (Telegram требует токен бота от @BotFather)
|
||
|
||
5. **Нужен ли экспорт в других форматах?** (PDF, печать этикеток со штрих-кодами)
|
||
|
||
6. **Есть ли уже список оборудования для импорта?** (Excel/CSV файл — можно загрузить сразу)
|
||
|
||
---
|
||
|
||
## 🚀 Запуск
|
||
|
||
1. Создать файлы по структуре выше
|
||
2. `run` — команда поднимет сервер на порту `process.env.PORT || 3000`
|
||
3. Ссылка из вывода `run` (с `?t=...`) — рабочая ссылка для администратора
|
||
4. `.gitignore`: `data.json`, `node_modules/`, `.vibe42-run.log`, `.vibe42-run.pid`
|
||
5. После первого запуска: `git add -A && git commit -m "v1" && git push origin HEAD:main`
|
||
|
||
---
|
||
|
||
## 📎 Примечания
|
||
|
||
- Даты хранить в формате `YYYY-MM-DD`, показывать как `ДД.ММ.ГГГГ`
|
||
- `checkIntervalMonths` — интервал проверки в месяцах (автоподсчёт следующей даты)
|
||
- При изменении `lastCheckDate` или `checkIntervalMonths` — пересчитывать `nextCheckDate`
|
||
- Все изменения писать в `log` с указанием кто и что изменил
|
||
- CSV для выгрузки: разделитель `;`, BOM `\uFEFF` для кириллицы, кавычки для полей с запятыми
|