Aknaproff/README.md

# Aknaproff Backend Restoration

This repository contains the Cloudflare Pages/Workers backend implementation required to restore the Aknaproff production tracker service to its historical state (**v3.20.8**) while keeping the provided HTML/JS/CSS frontend unchanged.

## Project Summary
- **Goal:** полностью восстановить API, миграции и бизнес-логику для фронтенда `AKNAPROFF Tootmine`.
- **Текущая внутренняя версия:** `v1.0.0` (см. `docs/CHECKLIST.md`).
- **Технологии:** Hono (TypeScript), Cloudflare Pages + Workers, D1 (SQLite), Wrangler, Vite.
- **Документация:**
  - [Техническое задание](docs/TECH_SPEC.md)
  - [Чек-лист и прогресс](docs/CHECKLIST.md)

## Структура проекта
```
backend/
├── docs/                 # TECH_SPEC.md, CHECKLIST.md и вспомогательные заметки
├── migrations/           # Миграции D1 (0001 …)
├── public/               # Статический фронтенд (HTML, CSS, JS)
├── src/                  # Код Hono (TypeScript)
├── seed.sql              # Начальные данные
├── package.json          # Скрипты npm и зависимости
├── wrangler.toml         # Конфигурация Wrangler (Pages + D1)
└── README.md             # Этот файл
```

## Быстрый старт
```bash
npm install
npm run db:migrate:local
npm run db:seed
npm run dev
```
- Dev-сервер доступен по адресу http://localhost:5173 (Vite) или через Wrangler Pages dev (см. ниже).

## Сборка и предпросмотр
```bash
npm run build           # Сборка статики и worker-кода (dist/)
npm run preview         # Wrangler Pages dev с собранным билдом
```

## Деплой
```bash
npm run deploy          # npm run build && wrangler pages deploy dist
```
> Перед деплоем убедитесь, что настроены Cloudflare credentials (`setup_cloudflare_api_key`) и определён `cloudflare_project_name`.

## Запуск в Docker / Synology
Эти файлы входят в пакет `backend` и готовы к импорту в Docker UI:
- `Dockerfile`
- `docker-compose.yml`
- `.dockerignore`
- `docker-entrypoint.sh`
- `wrangler.toml`

### Как использовать на Synology (через Docker UI без консоли)
1. Скопируйте папку `backend/` (или подготовленный архив) на NAS Synology.
2. В *Container Manager* → **Projects** → **Create** укажите `docker-compose.yml` (можно выбрать напрямую или загрузить `.tar.gz`, содержащий compose-файл).
3. Отредактируйте переменные окружения при необходимости:
   - `PORT` — внешний порт сервиса (по умолчанию 3000).
   - `SEED_DATA` — поставьте `true` только на первом запуске, если хотите автоматически выполнить `seed.sql`.
   - `PERSIST_PATH` — путь хранения локальной базы (по умолчанию `/data`).
   - `WRANGLER_SEND_METRICS` — необязательно, по умолчанию отключено.
4. После старта контейнер выполнит полный цикл автоматически (весь конфиг берёт из `/app/wrangler.toml`, поэтому ошибка
   «Pages does not support custom paths for the Wrangler configuration file» больше не появляется):
   - применит миграции D1 через `wrangler d1 migrations apply --persist-to /data`;
   - один раз (при `SEED_DATA=true`) импортирует `seed.sql` и создаст маркер `/data/.seeded`;
   - запустит `wrangler pages dev dist --local` на порту `PORT`.
5. Интерфейс будет доступен по адресу `http://<IP Synology>:<открытый порт>`.
6. После успешного запуска установите `SEED_DATA=false` и перезапустите проект (чтобы повторное наполнение не выполнялось).

> Том `d1-data` в `docker-compose.yml` монтируется в `/data`, поэтому локальная SQLite-база (D1 local) и маркер `/.seeded` сохраняются между перезапусками.

## Работа с миграциями и данными
```bash
npm run db:migrate:local  # Применить все миграции локально
npm run db:migrate:prod   # Применить миграции в продакшн D1
npm run db:seed           # Заселить тестовые данные (локально)
```

## Тестовые учётные записи
| Пользователь | Пароль | Роль |
|--------------|--------|------|
| `admin`      | `demo123` | Admin |
| `aknaproff`  | `demo123` | Admin |
| `tootmine`   | `demo123` | Пользователь (только просмотр) |

## API Overview
| Method & Path | Описание | Требует токен |
|---------------|----------|---------------|
| `POST /api/auth/login` | Логин, выдача токена | Нет |
| `GET /api/years` | Список годов с данными | Опционально |
| `GET /api/records` | Получение заявок (фильтры `month`, `year`) | Опционально |
| `POST /api/records` | Создание заявки | Admin |
| `PUT /api/records/:id` | Обновление заявки | Admin |
| `DELETE /api/records/:id` | Soft delete заявки | Admin |
| `PATCH /api/records/:id/status` | Тоггл дат (MAT/LÕI/KLA/VAL/VÄL) | Да |
| `PATCH /api/records/:id/material-confirmed` | Подтверждение MAT-1 | Admin |
| `PATCH /api/records/:id/material2-confirmed` | Подтверждение MAT-2 | Admin |
| `PATCH /api/records/:id/worksheets-cycle` | 3-стадийный цикл töölehti | Да |
| `PATCH /api/records/:id/notes` | Заметки + дата | Да |
| `PATCH /api/records/:id/problems` | Проблемы + error flags | Да |
| `PATCH /api/records/:id/price-paid` | Тоггл оплаты/арве | Admin |
| `GET /api/reports/master` | Агрегированные данные по месяцам | Опционально |
| `GET /api/reports/accountant` | Детализированный отчёт (нужны `month`, `year`) | Опционально |
| `PATCH /api/users/profile` | Смена ФИО и пароля | Да |

## Запуск dev-сервера (Wrangler Pages)
```bash
npm run build
fuser -k 3000/tcp 2>/dev/null || true
pm2 start npm --name aknaproff-backend -- run dev:sandbox
# остановить: pm2 delete aknaproff-backend
```
Dev-сервер будет доступен по http://127.0.0.1:3000 (или через выданный URL `GetServiceUrl`). Логи: `pm2 logs aknaproff-backend --nostream`.

## Контроль прогресса
Каждый завершённый чекпоинт фиксируется в `docs/CHECKLIST.md` с обновлением версии (v0.x.0). После CP9 проект готов к финальному деплою.

## Полезные ссылки
- [Cloudflare Wrangler Docs](https://developers.cloudflare.com/workers/wrangler/)
- [Hono Documentation](https://hono.dev)
- [Cloudflare D1](https://developers.cloudflare.com/d1/)