v4.1.9: Начальная производственная версия
- Полный backend на Hono + TypeScript - SQLite база данных с 38 записями - 3 пользователя: admin, aknaproff, kasutaja - Модальное окно reportModal (4 шага) - Docker конфигурация для Synology ARM - Все миграции (0001-0017) - Frontend: vanilla HTML/JS (original.html)
This commit is contained in:
Deploy Bot
36
docs/CHECKLIST.md
Executable file
36
docs/CHECKLIST.md
Executable file
@@ -0,0 +1,36 @@
|
||||
# Чек-лист восстановления Aknaproff (v3.20.8)
|
||||
|
||||
## Версионирование прогресса
|
||||
- **v0.0.0** – старт восстановления, подготовительные работы.
|
||||
- **v0.1.0** – завершён чекпоинт CP0 (окружение, git, базовый README).
|
||||
- **v0.2.0** – завершён чекпоинт CP1 (инфраструктура и фронтенд-сборка).
|
||||
- **v0.3.0** – завершён чекпоинт CP2 (миграции и seed).
|
||||
- **v0.4.0** – завершён чекпоинт CP3 (аутентификация и middleware).
|
||||
- **v0.5.0** – завершён чекпоинт CP4 (CRUD заявок и аудит).
|
||||
- **v0.6.0** – завершён чекпоинт CP5 (статусы, флаги, проблемы).
|
||||
- **v0.7.0** – завершён чекпоинт CP6 (отчёты).
|
||||
- **v0.8.0** – завершён чекпоинт CP7 (профиль пользователя).
|
||||
- **v0.9.0** – завершён чекпоинт CP8 (логирование, валидация, ошибки).
|
||||
- **v1.0.0** – завершён чекпоинт CP9 (финальное тестирование, документация, готовность к деплою).
|
||||
|
||||
> Текущая версия: **v1.0.0** (обновить после завершения каждого чекпоинта).
|
||||
|
||||
## Детальный чек-лист
|
||||
|
||||
| Чекпоинт | Статус | Требуемые действия | Артефакты / Проверки |
|
||||
|----------|--------|--------------------|----------------------|
|
||||
| **CP0** | ☑ | Завершить настройку окружения, `git init`, обновить README skeleton. | `git status` чистый, README с базовой информацией. |
|
||||
| **CP1** | ☑ | Настроить Wrangler/Vite, убедиться, что фронтенд выдаётся через Hono и билдится. | `npm run build` успешен, `/` отдаёт HTML, статика подключена. |
|
||||
| **CP2** | ☑ | Реализовать миграции `0002-0017`, обновить `seed.sql`. | `npm run db:migrate:local`, `npm run db:seed` успешны, схема соответствует ТЗ. |
|
||||
| **CP3** | ☑ | Реализовать `POST /api/auth/login`, middleware auth/optionalAuth, токены. | Успешный логин `admin/demo123`, заголовок `X-Refreshed-Token` при optional auth. |
|
||||
| **CP4** | ☑ | CRUD `production_records` + audit log. | Создание/обновление/удаление из UI работают, записи логируются. |
|
||||
| **CP5** | ☑ | Все PATCH: статусы, материалы, проблемы, оплата, заметки. | UI-иконки меняют состояния, блокировки работают, данные сохраняются. |
|
||||
| **CP6** | ☑ | Отчёты Master/Accountant. | UI формирует отчёты, сравнение с seed-данными, CSV/print без ошибок. |
|
||||
| **CP7** | ☑ | Профиль пользователя (смена пароля/имени). | Смена пароля работает, повторный логин с новым паролем успешен. |
|
||||
| **CP8** | ☑ | Централизованная валидация и логирование ошибок. | `audit_log` фиксирует все операции, ошибки возвращают корректные коды, фронт выводит сообщения. |
|
||||
| **CP9** | ☑ | Финальное тестирование, обновление README, подготовка к деплою. | Чеклист пройден, README обновлён, `npm run deploy` (dry-run) успешен. |
|
||||
|
||||
## Дополнительные шаги контроля
|
||||
- После каждого чекпоинта: коммит с тегом `cpX-complete` и обновление текущей версии в этом файле.
|
||||
- Вести журнал заметок (при необходимости) в `docs/NOTES.md` (создавать по требованию).
|
||||
- Перед деплоем: убедиться в наличии `.dev.vars` и секретов, перечисленных в README.
|
||||
137
docs/TECH_SPEC.md
Executable file
137
docs/TECH_SPEC.md
Executable file
@@ -0,0 +1,137 @@
|
||||
# Техническое задание на восстановление бэкенда Aknaproff (v3.20.8)
|
||||
|
||||
## 1. Цель и контекст
|
||||
- **Цель:** восстановить серверную часть системы Aknaproff до состояния версии **v3.20.8**.
|
||||
- **Фронтенд:** использовать без изменений предоставленный HTML/JS/CSS (директория `public/`).
|
||||
- **Базовые принципы:** неизменность UI, совместимость API, повторение бизнес-логики и данных, документирование и миграции.
|
||||
|
||||
## 2. Архитектура и инфраструктура
|
||||
| Компонент | Требование |
|
||||
|------------------|-----------|
|
||||
| Платформа | Cloudflare Pages + Workers (edge runtime). |
|
||||
| Backend-фреймворк| Hono (TypeScript). |
|
||||
| База данных | Cloudflare D1 (SQLite). |
|
||||
| Хранение статик | `public/` (Cloudflare Pages). |
|
||||
| Аутентификация | Токены (base64 JSON + `exp`, HMAC/`crypto.subtle`). |
|
||||
| Логирование | Таблица `audit_log` + централизованный сервис логирования. |
|
||||
| Миграции | `migrations/0001_initial.sql` … `0017_*.sql` (на базе истории). |
|
||||
| Seed-данные | `seed.sql`, пользователи `admin/demo123`, `aknaproff/demo123`. |
|
||||
|
||||
### 2.1 Среда разработки
|
||||
- Node.js ≥ 18, npm ≥ 9.
|
||||
- Wrangler ≥ 4.4 (`package.json`).
|
||||
- Команды npm:
|
||||
- `npm run dev` – разработка.
|
||||
- `npm run build` – сборка.
|
||||
- `npm run deploy` – деплой.
|
||||
- `npm run db:migrate:*` – миграции (local/prod).
|
||||
- `npm run db:seed` – заполнение данных.
|
||||
|
||||
## 3. Структура базы данных (итог v3.20.8)
|
||||
### 3.1 `users`
|
||||
- `id` INTEGER PK AUTOINCREMENT
|
||||
- `username` TEXT UNIQUE NOT NULL
|
||||
- `password_hash` TEXT NOT NULL (bcrypt)
|
||||
- `role` TEXT NOT NULL (`admin`, `public`)
|
||||
- `active` INTEGER DEFAULT 1
|
||||
- `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
- `updated_at` DATETIME
|
||||
|
||||
### 3.2 `production_records`
|
||||
- Основные поля: `client_name`, `type`, `offer_number`, `work_number`, `quantity`, `color`, `notes`, `installer`, `price`, `year`, `month`, `deleted`, `created_at`, `updated_at`.
|
||||
- Статусы (DATE): `material_date`, `material2_date`, `package_date`, `worksheets_date`, `cutting_date`, `glazing_date`, `ready_date`, `issued_date`.
|
||||
- Флаги (INTEGER): `material_confirmed`, `material2_confirmed`, `worksheets_confirmed`, `worksheets_error`, `cutting_error`, `glazing_error`, `ready_error`, `issued_error`, `problem_flag`, `price_paid`, `arve_checked`, `arve_makstud` (DATE), `problems_date` (DATE).
|
||||
- Текст: `problems` (TEXT).
|
||||
|
||||
### 3.3 `status_checkboxes`
|
||||
- `record_id` FK → `production_records(id)` (ON DELETE CASCADE).
|
||||
- Связанные чекбоксы и комментарии (материалы, резка, стекло и т.д.).
|
||||
|
||||
### 3.4 `audit_log`
|
||||
- `id` INTEGER PK AUTOINCREMENT
|
||||
- `record_id` INTEGER NULL
|
||||
- `user_id` INTEGER NULL
|
||||
- `action` TEXT (create/update/delete/login/etc.)
|
||||
- `field` TEXT NULL
|
||||
- `old_value` TEXT NULL
|
||||
- `new_value` TEXT NULL
|
||||
- `meta` TEXT NULL (JSON)
|
||||
- `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
|
||||
### 3.5 Миграции
|
||||
- Реализовать непрерывную цепь 0001–0017 (включительно), отражающую историю изменений до v3.20.8.
|
||||
- Каждая миграция повторяет изменения версии (добавление колонок, индексов, триггеров, пересоздание таблиц).
|
||||
|
||||
## 4. Аутентификация и авторизация
|
||||
- `POST /api/auth/login`: проверка `username`/`password`, возврат `{ token, user }`.
|
||||
- Токен: base64 JSON (`{ sub, role, exp }`) + подпись HMAC.
|
||||
- `Authorization: Bearer <token>`.
|
||||
- Middleware:
|
||||
- `authMiddleware` – обязательная авторизация.
|
||||
- `optionalAuthMiddleware` – допускает отсутствие токена, но обновляет `X-Refreshed-Token` при валидности.
|
||||
- Роли: `admin` – полный доступ, `public` – ограниченный (нет создания/удаления/редактирования цен).
|
||||
|
||||
## 5. API (обязательные эндпоинты)
|
||||
| Метод | Путь | Описание |
|
||||
|-------|------|----------|
|
||||
| POST | `/api/auth/login` | Авторизация, выдача токена, логирование успешного/неуспешного входа. |
|
||||
| GET | `/api/years` | Список лет с данными, optional auth. |
|
||||
| GET | `/api/records` | Получение заявок (фильтры `month`, `year`, поиск). |
|
||||
| POST | `/api/records` | Создание новой заявки (только admin). |
|
||||
| PUT | `/api/records/:id` | Обновление заявки, логирование изменений. |
|
||||
| DELETE | `/api/records/:id` | Soft delete (`deleted=1`). |
|
||||
| PATCH | `/api/records/:id/status` | Унифицированное обновление статуса (`field`, `value`). |
|
||||
| PATCH | `/api/records/:id/material-confirmed` | Тоггл подтверждения материала (MAT-1). |
|
||||
| PATCH | `/api/records/:id/material2-confirmed` | Тоггл подтверждения материалов (MAT-2), требует MAT-1. |
|
||||
| PATCH | `/api/records/:id/worksheets-cycle` | Цикл `worksheets` (3 этапа). |
|
||||
| PATCH | `/api/records/:id/notes` | Обновление заметок. |
|
||||
| PATCH | `/api/records/:id/problems` | Управление проблемами, блокировка `VAL/VÄL`. |
|
||||
| PATCH | `/api/records/:id/price-paid` | Управление оплатой (`price_paid`, `arve_makstud`). |
|
||||
| PATCH | `/api/users/profile` | Смена пароля/имени текущего пользователя. |
|
||||
| GET | `/api/reports/master` | Отчёт мастера (агрегация по месяцам). |
|
||||
| GET | `/api/reports/accountant` | Отчёт бухгалтера (детализация по периодам). |
|
||||
|
||||
### 5.1 Требования к ответам
|
||||
- Формат JSON + кодировка UTF-8.
|
||||
- Валидация входных данных → 422 с описанием ошибок.
|
||||
- Доступ без токена → 401/403.
|
||||
- 404 для несуществующих идентификаторов.
|
||||
|
||||
## 6. Бизнес-логика
|
||||
1. **Даты статусов** – формат `YYYY-MM-DD`, клик → текущая дата, повтор → очистка.
|
||||
2. **Материалы:** `material2_date` допускается только при наличии `material_date` или подтверждения материала.
|
||||
3. **Ошибки:** при `*_error = 1` соответствующая дата очищается, требуется комментарий в `problems`.
|
||||
4. **Проблемы:** `problem_flag = 1` блокирует `ready_date` и `issued_date`.
|
||||
5. **Оплата:** `price_paid = 1` устанавливает `arve_makstud = CURRENT_DATE`; при сбросе – `NULL`.
|
||||
6. **Soft delete:** записи помечаются `deleted = 1`, но сохраняются для отчётов.
|
||||
7. **Аудит:** все изменения записываются в `audit_log` с указанием пользователя, действия и полей.
|
||||
8. **Сортировка по умолчанию:** `ORDER BY id DESC` (новые заказы сверху).
|
||||
|
||||
## 7. Отчёты
|
||||
### 7.1 Master report (`GET /api/reports/master`)
|
||||
- Вход: `year` (обязательный).
|
||||
- Выход: массив месяцев с полями `month`, `total_windows`, `total_price`, `workdays`, `average_per_day`.
|
||||
- Агрегация включительно по незакрытым (но ненапряжённым) записям.
|
||||
|
||||
### 7.2 Accountant report (`GET /api/reports/accountant`)
|
||||
- Вход: `year`, `month`.
|
||||
- Выход: список записей с `client_name`, `offer_number`, `work_number`, `quantity`, `price`, `arve_checked`, `arve_makstud`.
|
||||
- Используется для выгрузки CSV/печати.
|
||||
|
||||
## 8. Нефункциональные требования
|
||||
- Обработка ошибок с назначенными кодами.
|
||||
- Перформанс: ≤ 30 мс CPU на запрос (в рамках Cloudflare Workers).
|
||||
- Минимальная защита от brute force (rate limit логина).
|
||||
- Совместимость с существующим фронтендом (никаких изменений в HTML/JS/CSS).
|
||||
|
||||
## 9. Артефакты проекта
|
||||
- Каталоги: `src/`, `public/`, `migrations/`, `docs/`.
|
||||
- Документация: `README.md`, `docs/TECH_SPEC.md`, `docs/CHECKLIST.md`.
|
||||
- Автотесты / коллекции для ручного тестирования API.
|
||||
|
||||
## 10. Критерии приёмки
|
||||
1. Все сценарии UI выполняются без ошибок (создание, фильтрация, статусы, отчёты, профиль).
|
||||
2. `audit_log` содержит записи обо всех изменениях (включая логин/логаут).
|
||||
3. Данные seed корректно отображаются и используются в отчётах.
|
||||
4. README содержит инструкцию по запуску, миграции, деплой.
|
||||
5. Успешный `npm run deploy` (или dry-run) с использованием Wrangler.
|
||||
Reference in New Issue
Block a user