Aknaproff/PROJECT_STRUCTURE.md

# AKNAPROFF Tootmine - Структура проекта

**Версия:** v4.0.13 (28.11.2025)

---

## 📁 Структура директорий

```
webapp/
├── src/                        # Backend исходники (Hono + TypeScript)
│   ├── index.tsx              # Главный файл приложения (26 API endpoints)
│   ├── original-html.ts       # Embedded HTML для главной страницы
│   ├── middleware/            # Middleware для аутентификации
│   │   └── auth.ts           # authMiddleware, optionalAuthMiddleware
│   └── utils/                 # Утилиты
│       └── auth.ts           # JWT, password hashing
│
├── public/                     # Статические файлы
│   ├── original.html          # Исходный HTML шаблон
│   ├── test-datepicker.html   # Тестовая страница для date picker
│   └── static/                # Статические ресурсы (доступны как /static/*)
│       ├── app.js             # Главный JavaScript файл (1500+ строк)
│       └── styles.css         # Дополнительные стили
│
├── migrations/                 # D1 Database миграции
│   ├── 0001_initial_schema.sql
│   ├── 0002_add_user_profiles.sql
│   └── meta/
│
├── dist/                       # Build output (создаётся при npm run build)
│   ├── _worker.js             # Скомпилированный Cloudflare Worker
│   └── _routes.json           # Cloudflare routing config
│
├── .wrangler/                  # Wrangler development state
│   └── state/v3/d1/           # Локальная D1 база данных
│
├── node_modules/               # NPM зависимости
│
├── .git/                       # Git repository
│
├── package.json                # NPM конфигурация и скрипты
├── wrangler.jsonc              # Cloudflare Workers конфигурация
├── tsconfig.json               # TypeScript конфигурация
├── vite.config.ts              # Vite build конфигурация
├── ecosystem.config.cjs        # PM2 конфигурация (для development)
├── .gitignore                  # Git ignore файл
├── seed.sql                    # Demo данные для локальной разработки
│
├── README.md                   # Основная документация проекта
├── FULL_DEVELOPMENT_HISTORY.md # Полная история разработки (25KB)
├── VERSION_SUMMARY.md          # Краткая сводка версий (3KB)
└── PROJECT_STRUCTURE.md        # Этот файл
```

---

## 📄 Ключевые файлы

### Backend (src/)

#### src/index.tsx (главный файл)
```typescript
// 665 строк кода
// 26 API endpoints
// Hono framework + Cloudflare Workers
// D1 Database integration

Основные секции:
- Type Bindings (D1Database, Variables)
- CORS middleware
- Static file serving
- Auth routes (login, profile)
- Data routes (CRUD для records)
- Status checkbox routes
- Material confirmed routes
- Main page route
```

#### src/middleware/auth.ts
```typescript
// JWT authentication middleware
// authMiddleware - требует токен
// optionalAuthMiddleware - опциональный токен
```

#### src/utils/auth.ts
```typescript
// JWT token generation
// Password hashing/verification (bcrypt-style)
```

#### src/original-html.ts
```typescript
// Embedded HTML template
// Создаётся из public/original.html
// Содержит полный HTML главной страницы
```

### Frontend (public/)

#### public/original.html
```html
<!-- Главный HTML шаблон -->
<!-- ~700 строк -->
<!-- Tailwind CSS (CDN) -->
<!-- FontAwesome icons -->
<!-- Axios для HTTP запросов -->
```

#### public/static/app.js
```javascript
// Главный JavaScript файл
// ~1500 строк кода

Основные функции:
- loadRecords() - загрузка records из API
- renderRecords() - рендеринг таблицы
- renderCalendarCell() - calendar picker для MAT-1/MAT-2
- renderDateCell() - 3-step toggle для других полей
- toggleDate() - toggle date fields
- toggleMaterialConfirmed() - toggle MAT-1 checkbox
- toggleMaterial2Confirmed() - toggle MAT-2 checkbox
- openModal() - открытие модального окна
- editRecord() - редактирование record
- deleteRecord() - удаление record
- handleLogin() - логин
- initFilters() - инициализация фильтров
```

### Database (migrations/)

#### migrations/0001_initial_schema.sql
```sql
-- production_records table
-- status_checkboxes table
-- users table
-- audit_log table
-- Indexes
```

### Configuration

#### package.json
```json
{
  "scripts": {
    "dev": "vite",
    "dev:sandbox": "wrangler pages dev dist --ip 0.0.0.0 --port 3000",
    "build": "vite build",
    "deploy": "npm run build && wrangler pages deploy dist",
    "db:migrate:local": "wrangler d1 migrations apply webapp-production --local",
    "db:migrate:prod": "wrangler d1 migrations apply webapp-production"
  },
  "dependencies": {
    "hono": "^4.0.0"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "4.20250705.0",
    "@hono/vite-cloudflare-pages": "^0.4.2",
    "vite": "^5.0.0",
    "wrangler": "^3.78.0"
  }
}
```

#### wrangler.jsonc
```jsonc
{
  "name": "webapp",
  "compatibility_date": "2024-01-01",
  "pages_build_output_dir": "./dist",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "webapp-production",
      "database_id": "your-database-id"
    }
  ]
}
```

#### ecosystem.config.cjs (PM2)
```javascript
module.exports = {
  apps: [{
    name: 'webapp',
    script: 'npx',
    args: 'wrangler pages dev dist --ip 0.0.0.0 --port 3000',
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    }
  }]
}
```

---

## 📊 Статистика кода

| Файл | Строки | Тип | Назначение |
|------|--------|-----|------------|
| src/index.tsx | ~665 | TypeScript | Backend API |
| public/static/app.js | ~1500 | JavaScript | Frontend logic |
| public/original.html | ~700 | HTML | UI template |
| src/middleware/auth.ts | ~50 | TypeScript | Authentication |
| src/utils/auth.ts | ~80 | TypeScript | JWT & passwords |
| migrations/0001_*.sql | ~100 | SQL | Database schema |
| FULL_DEVELOPMENT_HISTORY.md | ~790 | Markdown | Documentation |

**Всего:** ~3885 строк кода (без node_modules, dist, .wrangler)

---

## 🔌 API Endpoints (26 шт)

### Authentication (2)
```
POST   /api/auth/login          - Логин пользователя
PATCH  /api/users/profile       - Обновление профиля (требует auth)
```

### Data CRUD (5)
```
GET    /api/years               - Получить список доступных годов
GET    /api/records             - Получить records (по месяцу/году)
GET    /api/records/:id         - Получить один record
POST   /api/records             - Создать новый record
PUT    /api/records/:id         - Обновить record
DELETE /api/records/:id         - Удалить record (soft delete)
```

### Status Management (13)
```
PATCH  /api/records/:id/status                - Toggle date field
PATCH  /api/records/:id/worksheets-cycle      - 3-step worksheets cycle
PATCH  /api/records/:id/notes                 - Обновить notes
PATCH  /api/records/:id/problems              - Обновить problems + error flags
PATCH  /api/records/:id/material-confirmed    - Toggle MAT-1 checkbox
PATCH  /api/records/:id/material2-confirmed   - Toggle MAT-2 checkbox
PATCH  /api/records/:id/price-paid            - Обновить price paid status
PATCH  /api/status/:recordId/:field           - Обновить date field
PATCH  /api/status/:recordId/:field/error     - Обновить error flag
PATCH  /api/status/:recordId/:field/confirm   - Обновить confirmation flag
```

### Pages (6)
```
GET    /                        - Главная страница (HTML)
GET    /test-click              - Тестовая страница для clicks
GET    /test-datepicker         - Тестовая страница для date picker
GET    /static/*                - Статические файлы (app.js, styles.css)
GET    /favicon.ico             - Favicon (empty response)
```

---

## 🗄️ Database Schema

### Tables (4)

#### production_records
```sql
- id INTEGER PRIMARY KEY
- month INTEGER          -- 1-12
- year INTEGER           -- 2024, 2025, etc.
- client_name TEXT
- type TEXT
- offer_number TEXT
- work_number TEXT
- quantity INTEGER
- color TEXT
- notes TEXT
- problems TEXT
- installer TEXT
- price REAL
- created_at DATETIME
- updated_at DATETIME
- deleted_at DATETIME
- deleted_by INTEGER
```

#### status_checkboxes
```sql
- id INTEGER PRIMARY KEY
- record_id INTEGER (FK → production_records.id)
- material_date DATE
- material2_date DATE
- package_date DATE
- worksheets_date DATE
- cutting_date DATE
- glazing_date DATE
- ready_date DATE
- issued_date DATE
- worksheets_error BOOLEAN
- cutting_error BOOLEAN
- glazing_error BOOLEAN
- ready_error BOOLEAN
- issued_error BOOLEAN
- material_confirmed BOOLEAN
- material2_confirmed BOOLEAN
- worksheets_confirmed BOOLEAN
```

#### users
```sql
- id INTEGER PRIMARY KEY
- username TEXT UNIQUE
- password_hash TEXT
- full_name TEXT
- role TEXT (admin/user)
- created_at DATETIME
- updated_at DATETIME
- deleted_at DATETIME
```

#### audit_log
```sql
- id INTEGER PRIMARY KEY
- user_id INTEGER (FK → users.id)
- record_id INTEGER (FK → production_records.id)
- field_name TEXT
- old_value TEXT
- new_value TEXT
- action_type TEXT
- created_at DATETIME
```

---

## 🔄 Development Workflow

### 1. Локальная разработка
```bash
# 1. Build проекта
npm run build

# 2. Запуск с PM2
pm2 start ecosystem.config.cjs

# 3. Миграции базы данных
npm run db:migrate:local

# 4. Тестирование
curl http://localhost:3000/api/records?month=1&year=2025

# 5. Логи
pm2 logs webapp --nostream
```

### 2. Обновление кода
```bash
# 1. Изменить код
nano public/static/app.js

# 2. Обновить версию
sed -i 's/app.js?v=4.0.13/app.js?v=4.0.14/' public/original.html

# 3. Пересоздать embedded HTML
node -e "..."

# 4. Rebuild
npm run build

# 5. Restart PM2
pm2 restart webapp
```

### 3. Git workflow
```bash
git add .
git commit -m "Fix: описание изменения"
git push origin main
```

### 4. Deployment на Cloudflare
```bash
# 1. Build
npm run build

# 2. Deploy
npx wrangler pages deploy dist --project-name webapp
```

---

## 🔗 Важные ссылки

- **Sandbox URL**: https://3000-iabcqs9fpouqnd3allaai-82b888ba.sandbox.novita.ai
- **Local URL**: http://localhost:3000
- **Git Repository**: /home/user/webapp
- **Cloudflare Pages**: (при деплое)

---

## 📚 Документация

| Файл | Размер | Описание |
|------|--------|----------|
| README.md | ~5KB | Основная документация |
| FULL_DEVELOPMENT_HISTORY.md | 25KB | Детальная история всех версий |
| VERSION_SUMMARY.md | 3KB | Краткая сводка версий |
| PROJECT_STRUCTURE.md | Этот файл | Структура проекта |

---

**Конец документа**