# Ukrtruboizol — BAS ERP штрихкодування виробничого циклу

> **Стан на 2026-05-25:** ТЗ v0.5 — **ОДИН живий документ з progressive disclosure** (toggle «👨‍💼 Клієнт / 👨‍💻 Розробник»). 27 розділів (11 клієнтських + 16 технічних). Annotation-система працює.

---

## 0. Швидкий контекст для наступної сесії

### Що це за проект
Доопрацювання BAS ERP клієнта **ТОВ НВП з ІІ «Укртрубоізол»** (ЄДРПОУ 31017014) — повний штрихкодний облік виробничого циклу: точка входу (1-й виробничий етап) → проміжні етапи (легка реєстрація проходження) → точка виходу (ОТК).

### Як швидко продовжити
1. `cd C:\AI\Ukrtruboizol`
2. `node dashboard/server.js` (якщо ще не запущено) — піднімає dashboard на 8767
3. Відкрити http://localhost:8767/
4. Перевірити `dashboard/annotations.json` — нові правки від користувача
5. Якщо є — застосувати через `build_tz.py` + `build_tz_living.py`, заархівувати у `annotations_history.json`

### Файли-якорі для розуміння стану
- `CONTEXT.md` (цей файл) — повний знімок
- `dashboard/index.html` — головний дашборд (sticky notes праворуч)
- `dashboard/tz_living.html` — основний робочий доку ТЗ v0.4
- `docs/ТЗ_BAS_ERP_штрихкодування_v0.4_22.05.2026.docx` — клієнтський deliverable
- `docs/№1_21.05.2026.docx` — Протокол зустрічі №1

---

## 1. Замовник: профіль

| Поле | Значення |
|--|--|
| Повна назва | ТОВ Науково-виробниче підприємство з іноземними інвестиціями «Укртрубоізол» |
| ЄДРПОУ | 31017014 |
| Засновано | 27.08.2000 |
| Адреса | Дніпропетровська обл., м. Нікополь, вул. Патріотів України, 169 |
| Сайт | https://uti.ua |
| Сфера | Повний цикл виробництва сталевих і поліетиленових труб + антикорозійна ізоляція |
| Позиція ринку | 1-ше місце в Україні з ізоляції труб. Найбільший виробник великого діаметру (426–1422 мм) longitudinal SAW сталевих труб з покриттям |

### Виробничі лінії (з відкритих джерел — верифікувати з замовником)
- 3× лінії зовнішньої ізоляції екструдованим поліетиленом
- Лінія внутрішнього гладкого та антикорозійного епоксидного покриття труб 57–1420 мм
- Лінія зовнішньої поліуретанової ізоляції
- Лінія відновлення вживаних труб 219–1420 мм
- Цех ПЕ-труб (до Ø 1200 мм, обʼєм 3.5 км/міс) + попередньо ізольовані Ø 133 мм (12 км/міс)

---

## 2. Учасники зустрічі №1 від 21.05.2026

### З боку Виконавця (ТОВ «СофтІнформ»)
- **Юрій Валентинович Магера** — керівник проекту, директор SoftInform (це сам користувач системи)
- **Аня** — аналітик-консультант
- **Вадим Іванович** — епізодично (приєднався у файлі C)

### З боку Замовника (Укртрубоізол)
- **Наталя Вікторівна** — фінансовий директор
- **Таня** — аналітик-консультант

### Згадані треті особи (НЕ присутні на зустрічі)
Олена (помилково «Лєна»/«Лена»; працює з документом «Звіт за зміну»), Лариса (звільняється), Марина/Маріна, Настя, Вася.

### Post-processing нотатки
- «Валентинівна» (анот. #92) — це **помилка моделі**, насправді «Валентинович» (звертання до Юрія)
- «Юр» (анот. #14) — звертання до Юрія Магери (Виконавця)

---

## 3. Аудіо першої зустрічі

| Файл | Тривалість | Розмір | Транскрипт |
|--|--|--|--|
| Новий запис.m4a | 30:35 | 15.4 MB | ✅ Gemini v3 JSON+TXT |
| Новий запис 2.m4a | 29:39 | 15.0 MB | ✅ Gemini v3 JSON+TXT |
| Новий запис 4.m4a | 02:48 | 1.4 MB | ✅ Gemini v3 JSON+TXT |
| **Разом** | **63 хв** | **31.8 MB** | |

**Порядок (підтверджено):** запис → запис 2 → запис 4 (3 фрагменти однієї зустрічі — мобільний з ~30-хв лімітом).

### Транскрипція — обрано Gemini 3.1 Pro Preview
**Чому Gemini, а не Whisper/OpenAI/Deepgram** (тестовано 22.05.2026):
- Структурований JSON output з полями `timestamp_start`, `timestamp_end`, `speaker`, `language` (uk/ru/mixed), `text`
- Розпізнає `mixed` для суржикових сегментів (інші моделі — ні)
- Розпізнає по-батькові («Валентинівна»)
- Doменна термінологія BAS, виробництва — точно
- Швидкість: 8 хв сумарно для 63 хв аудіо (вкл. thinking)
- Помилки моделей які НЕ обрано:
  - Local large-v3 на CPU — ratio 11-15x, занадто повільно
  - OpenAI gpt-4o-transcribe-diarize — 1400 сек ліміт на файл, артефакти діаризації
  - Deepgram Nova-3 — дав 5 спікерів але 1-й артефакт (8 utts на 30 хв)

### Конфігурація Gemini (для відтворення)
- **Модель:** `gemini-3.1-pro-preview` (станом на травень 2026 — flagship; коли вийде stable 3.5 — оновити)
- **API:** Google AI Studio (НЕ Vertex AI), ключ `C:\AI\API\gemini --- soft.txt`
- **Upload:** через `google-genai` SDK, файли копіюються у латин-name у tempdir (Unicode SDK bug з кирилицею у HTTP headers)
- **Generate:** через прямий REST `POST /v1beta/models/gemini-3.1-pro-preview:generateContent` (SDK 1.47 не підтримує `thinkingLevel`)
- **generationConfig:**
  - `responseMimeType: "application/json"`
  - `responseSchema` — structured output
  - `thinkingConfig.thinkingLevel: "high"`
  - **БЕЗ** `temperature` (default 1.0 для Gemini 3)
  - **БЕЗ** `audio_timestamp` (це Vertex AI-only)
- **Domain prompt** з UA/RU bilingual context + перелік термінів
- **Скрипт-еталон:** `research/transcribe_gemini_v3.py`

---

## 4. АРХІТЕКТУРА ДОКУМЕНТАЦІЇ — один документ, progressive disclosure

> **Архітектурне рішення (2026-05-25):** замість окремих PRD + SDD + API Spec + Test cases — **ОДИН живий документ** з toggle «Клієнт / Розробник». Уникає дублювання, sync issues, overhead на 4-5 файлів.

**Чому одна жива специфікація замість шарів:**
- Клієнт і розробник читають одну й ту ж істину про систему. Різниця тільки у *глибині*.
- Toggle у топбарі (з localStorage state) — миттєве перемикання режиму
- 0% дублювання — кожен факт описаний один раз
- Annotation-система працює однаково в обох режимах

**Структура tz_living.html (27 розділів):**

| Режим | Розділи | Аудиторія |
|--|--|--|
| 👨‍💼 **Клієнтський** (default) | §0–11: огляд, ролі, архітектура, сценарії, ескізи, функ-вимоги, API, нефункц, приймальні, ризики, відкриті, глосарій | Замовник (Наталя Вікторівна, Таня), керівництво |
| 👨‍💻 **Розробницький** | додатково §12–27: об'єкти BAS, регістри, довідники, документи, HTTP-сервіс, алгоритми (ВХОД, проміжний, ОТК, зміни), мобільна поведінка, межові випадки, тестові сценарії, out-of-scope | Розробник (BAS + Android), QA |

**CSS-реалізація:**
```css
body[data-mode="client"] .tech-section,
body[data-mode="client"] .tech-toc-item { display: none; }
body[data-mode="dev"]    .tech-section { display: block; }
.tech-section { border-left: 4px solid #6b46c1; }  /* фіолетовий акцент */
```

**JS:**
```js
const savedMode = localStorage.getItem('docMode') || 'client';
document.body.dataset.mode = savedMode;
// toggleMode() — перемикає client ↔ dev + зберігає у localStorage
```

### Архів архітектурних рішень (для майбутніх сесій)

| Дата | Спроба | Результат |
|--|--|--|
| 2026-05-23 | Один tz_living з 12 розділами + окремий tz_sdd.html для розробника + api_spec.html + test_cases.html + mobile_scanner.yaml | ❌ Cargo-cult «layered docs». Дублювання, sync issues, overhead. Користувач: «чому не робиш один якісний документ?» |
| 2026-05-25 | ОДИН tz_living з progressive disclosure (toggle Клієнт/Розробник) | ✅ Жива специфікація. Видалено tz_sdd / api_spec / test_cases / openapi.yaml |

### Шар 1: PRD/Vision (живий ТЗ) — основний наш формат

**Файл:** `dashboard/tz_living.html` (генерується з `research/build_tz_living.py`)

**Призначення:** Узгодження зі Замовником і керівництвом — «що і чому» проекту.

**Візуальна структура (sticky 3-колонковий layout):**
1. **Top bar** (sticky, z-index 100) з:
   - Лого «📋 ТЗ — Living Spec» + версія v0.4 (помаранчевий бейдж)
   - Пошук Ctrl+K (фільтрує секції по тексту)
   - Counter активних правок «N правок» (жовтий)
   - Counter архіву «👁 Архів (N)» (зелений, click → modal)
   - Кнопки: 📥 docx, 🏠 Дашборд
2. **Sidebar TOC** (260px sticky лівий) з 12 секціями + status pills:
   - Pills типи: `pill-done` (зелений), `pill-prog` (жовтий), `pill-open` (червоний), `pill-info` (синій), `pill-risk` (червоний), `pill-low` (сірий)
   - Highlight активної секції при скролі
3. **Main контент** (центральний flex) з секціями:
   - **Hero блок** (gradient синій): заголовок + subtitle + 4 KPI картки (Функц. вимог / Гілки інтеграції / Ролей / Відкритих питань)
   - **Sections** (карти з border, padding 20px 24px): кожна секція = `<section id="..." data-anchor="N">` з заголовком `<h2><span class="num-bdg">N</span>Назва</h2>`
4. **Right sidebar — Free-form notes** (320px sticky, жовтий фон):
   - Заголовок «💬 Загальні коментарі команди»
   - Contenteditable area з placeholder
   - Auto-save кожні 1.5 сек у `tz_general_notes.md`
   - Лічильник символів + кнопки Перечитати/Зберегти

**Технології у Living Spec:**
- **Mermaid 10.x** (CDN jsdelivr) — для архітектурних flowchart і sequence-діаграм
- **SVG inline** — для wireframes мобільних екранів (4 ескізи)
- **HTML + native CSS** (без фреймворків)
- **Vanilla JavaScript** для annotation system + search + TOC scroll

### Що НЕ створюємо окремими файлами (свідоме рішення)

| Що | Чому інтегровано в Living Spec, а не окремий файл |
|--|--|
| **SDD (Engineering Guide)** | Tech-section §12–27 у tz_living. Розробник перемикає toggle і бачить ту ж саму архітектуру з більшою глибиною |
| **OpenAPI 3.1 YAML** | Розділ §6 «API-методи» у Living Spec з прикладами JSON. YAML генерується перед стартом розробки з того ж джерела істини |
| **Figma mockups** | SVG inline ескізи §4. Перед розробкою UI/UX дизайнер створює Figma з цих скетчів |
| **Test cases Gherkin** | §26 «Тестові сценарії» у тех-розділі. Перед автотестами QA може транслювати в Gherkin |
| **Migration plan для BAS** | Створимо окремий короткий артефакт перед стартом — це operational, не специфікаційне |

---

## 5. Документи, що вже створено — формати і деталі

### 5.1. Протокол зустрічі №1 (docx)

**Файл:** `docs/№1_21.05.2026.docx`
**Скрипт-генератор:** `research/build_protocol.py`
**Endpoint:** http://localhost:8767/protocol

**Формат:** Класичний діловий протокол у Word з підписами обох сторін.

**Метадані (реальні, як з MS Word):**
- Author = «Юрій Валентинович Магера»
- Title = «Протокол № 1 від 21.05.2026»
- Application = «Microsoft Office Word»
- AppVersion = «16.0000»
- Company = «ТОВ «СофтІнформ»»
- Manager = «Магера Юрій Валентинович»
- Revision = 1

**Структура (8 розділів):**
0. Заголовок (центрований: «ПРОТОКОЛ № 1», «робочої зустрічі», «від 21.05.2026»)
1. Сторони (Виконавець + Замовник)
2. Учасники зустрічі (списки з обох сторін)
3. Предмет і порядок денний (7 пунктів)
4. Хід обговорення (4 підрозділи з bullet points)
5. Прийняті рішення (5 пунктів)
6. Відкриті пункти (5 пунктів)
7. Наступні кроки і терміни (таблиця 3 колонки: №, Дія, Відповідальний)
8. Підписи сторін (2-колонкова таблиця)

**Шрифт:** Times New Roman 11pt, поля 2/2/2.5/1.5 см.

### 5.2. ТЗ v0.4 (docx — для клієнта)

**Файл:** `docs/ТЗ_BAS_ERP_штрихкодування_v0.5_25.05.2026.docx`
**Скрипт-генератор:** `research/build_tz.py`
**Endpoint:** http://localhost:8767/tz

**Формат:** Класичний інженерний документ Word з 16 розділами + підписи.

**Метадані:**
- Title = «ТЗ — Доопрацювання BAS ERP. Штрихкодування виробничого циклу. v0.4»
- Revision = 4
- Усі інші — як у протоколі

**Заголовки:** справжні `Heading 1/2/3` styles (Word Navigation pane працює, mammoth коректно конвертує у `<h1>/<h2>/<h3>` для preview).

**Структура (16 розділів):**
0. Анотація
1. Загальні положення (Сторони, Підстава, Нормативи)
2. Призначення системи (Мета, Принципи, Користувачі)
3. Існуюча інфраструктура Замовника
4. AS IS (як зараз)
5. TO BE (як буде) — точка ВХОДУ, проміжні, ОТК, перемикання етапу, трасування
6. Функціональні вимоги (Серверна BAS, Мобільний клієнт, ОТК, Адміністратор) — **БЕЗ префіксів F-XX**, просто нумеровані bullet-пункти
7. Нефункціональні (таблиця Категорія/Вимога)
8. Архітектурне рішення (3-рівнева, технологічний стек)
9. Маркування продукції
10. Інтерфейси (екрани мобільного, UI стандарти, ОТК)
11. Звіти (3 підрозділи: ЗП, Журнал, Audit log)
12. Етапи впровадження (таблиця 10 етапів)
13. Приймальні критерії (8 нумерованих)
14. Ризики і припущення (таблиця 6 ризиків з severity)
15. Відкриті пункти (8 нумерованих)
16. Глосарій (таблиця 17 термінів)
+ Сторінка підписів

### 5.3. ТЗ v0.4 Living Spec (інтерактивний HTML — для роботи)

**Файл:** `dashboard/tz_living.html` (генерується)
**Скрипт-генератор:** `research/build_tz_living.py`
**Endpoint:** http://localhost:8767/tz_living.html

**Розмір:** ~120 KB (v0.5 з tech-секціями).

**Унікальні фічі (НЕ в docx):**

- **🔀 Toggle режиму «Клієнт / Розробник»** (топбар, з localStorage) — клієнт бачить §0–11, розробник додатково §12–27 з технічною деталізацією. Tech-секції — фіолетова рамка для візуального відрізнення.

- **Інтерактивні Mermaid діаграми** — рендеряться з CDN на льоту:
  - Рис. 1: загальна архітектура (flowchart LR з 3 гілками)
  - Рис. 2: послідовність точки ВХОДУ (sequence diagram)
  - Рис. 3: послідовність проміжного етапу (sequence)
  - Рис. 4: послідовність ОТК (sequence з alt-блоком звіряння)
- **SVG inline ескізи** мобільного додатку (4 шт.):
  - Екран 1: Вибір етапу (з активним/заблокованим/підсвіченим зеленим)
  - Екран 2: Головний (поточний етап + сканер + 2 лічильники + кнопка sync)
  - Екран 3: Сканер (камера з рамкою yellow dashed + червона лінія)
  - Екран 4: Інформація про лист (з підтвердженням + кнопкою наступного)
- **Картки вимог** (req-grid) — кольоровий border-left за категорією:
  - Сервер BAS — синій (`--brand`)
  - Мобільний — зелений (`--good`)
  - ОТК — фіолетовий (`--purple`)
  - Адміністратор — оранжевий (`--accent`)
- **API endpoints** у Stoplight-стилі: dark code blocks (`#0f172a` bg) з JSON прикладами; method-pills (GET=blue, POST=green)
- **Annotation system** (див. розділ 6.1 нижче)
- **Free-form notes panel** (right column, sticky, auto-save)
- **Archive modal** для оброблених коментарів (green theme)
- **Search Ctrl+K** — фільтр секцій
- **Print-friendly** CSS (ховає sidebars, toolbar)
- **Responsive** breakpoints:
  - ≥1300px — 3 колонки
  - 900-1299 — 2 колонки (notes ховаються)
  - <900 — 1 колонка (TOC ховається)

### 5.3.1. ТЗ docx HTML preview — для коригування перед expоrt у Word

**Файл:** `dashboard/tz_docx_preview.html` (генерується через `research/build_previews.py` з docx через mammoth)
**Endpoint:** http://localhost:8767/tz_docx_preview.html
**Кнопка-завантаження:** http://localhost:8767/tz (той самий docx)

**Призначення:** показати ТОЧНО той контент що буде у Word-документі (16 розділів класичний інженерний формат) у вигляді HTML для коригування. Користувач робить правки через annotation modal → Claude обробляє → регенерує docx через `build_tz.py` → архівує правки.

**Як це відрізняється від tz_living.html:**

| | tz_living.html | tz_docx_preview.html |
|--|--|--|
| Контент | 27 розділів (11 клієнтських + 16 dev) з Mermaid/SVG/інтерактив | 16 класичних розділів docx ОДИН-В-ОДИН як у Word |
| Призначення | Робочий формат для обговорення архітектури + правок | Перевірка саме «як буде у Word», правки перед export |
| Toggle Клієнт/Розробник | ✅ є | ❌ нема (один view) |
| Annotation system | doc_key=`tz` | doc_key=`tz_docx` |
| Free-form notes | tz_general_notes.md | tz_docx_general_notes.md |

**Workflow коригування docx через HTML:**
1. Користувач відкриває http://localhost:8767/tz_docx_preview.html
2. Клікає на проблемний абзац/комірку → modal → коментар або «новий текст»
3. Кожна правка → сторінка показує мітку `[N]`
4. Каже «обробляй tz_docx правки»
5. Claude читає `dashboard/annotations.json` → ключ `tz_docx`
6. Редагує `research/build_tz.py` (контент DOCX)
7. Regenerate: `python research/build_tz.py` → новий docx у `docs/` (bump версію v0.4 → v0.5)
8. Regenerate preview: `python research/build_previews.py` → новий `tz_docx_preview.html`
9. Архівує правки через `safe_archive.py` з `applied_in` міткою
10. User скачує оновлений docx через `/tz`

### 5.4. Транскрипти

| Файл | Призначення | Endpoint |
|--|--|--|
| `audio/*_gemini_v3.json` | Structured JSON (segments з timestamp/speaker/language) | — |
| `audio/*_gemini_v3.txt` | Plain text транскрипт | — |
| `audio/transcript_clean.txt` | Зшитий чистий транскрипт з застосованим глосарієм | http://localhost:8767/transcript_clean (через `/transcript` endpoint) |
| `dashboard/transcript_clean.html` | HTML з ролями, кольоровими спікер-блоками | /transcript_clean.html |
| `dashboard/transcript_review.html` | Review-режим: 97 нумерованих кандидатів з textarea | /transcript_review.html |

**Speaker mapping (гіпотеза, перевірена через перевірку аудіо):**
- Файл A (30 хв): Spk1=Наталя Вікт., Spk2=Юрій Магера, Spk3=Таня, Spk4=Вадим Іванович
- Файл B (29 хв): 3 спікера (Аня не активна) — Spk1=Наталя, Spk2=Таня, Spk3=Юрій
- Файл C (3 хв): 5 спікерів, з 1 artifact

### 5.5. Research findings

**Файл:** `research/research_findings.md`
**Endpoint:** http://localhost:8767/research

Live web research за озвученими у зустрічі темами (BAS HTTP-сервіси, ML Kit + CameraX, виробничі звіти BAS, мобільна аутентифікація).

---

## 6. Annotation system (інтерактивні правки)

### 6.1. Архітектура

**Двошарова система:**
- **Active annotations** — `dashboard/annotations.json` — поточні нові правки, ще не застосовані
- **History annotations** — `dashboard/annotations_history.json` — застосовані, архів з міткою версії

**Endpoints:**
- `GET /annotations?doc=tz` → активні правки для документа
- `POST /save_annotation` (body `{doc, anchor, original, comment, new_text}`) → зберегти/видалити (порожній comment+new_text → видалення)
- `GET /annotations_history?doc=tz` → архів

### 6.2. Формат annotations.json
```json
{
  "tz": {
    "8": {
      "original": "...",
      "comment": "...",
      "new_text": "",
      "ts": "2026-05-22T12:42:44.131Z"
    }
  }
}
```

### 6.3. Формат annotations_history.json
```json
[
  {
    "doc": "tz",
    "anchor": "8",
    "original": "...",
    "comment": "...",
    "new_text": "",
    "ts": "2026-05-22T12:42:44.131Z",
    "applied_at": "2026-05-22T17:00:00Z",
    "applied_in": "ТЗ v0.4 — короткий опис що змінено"
  }
]
```

### 6.4. Workflow обробки правок (SAFE MERGE)

**Чому safe merge критично:**
Поки я обробляю правки, користувач може додати нові. Якщо я просто очищу `annotations.json` — втрачу нові правки.

**Алгоритм** (див. `research/safe_archive.py`):
1. Прочитати поточний `annotations.json`
2. Для кожного anchor що я обробляв — звірити signature comment-а
3. Якщо співпадає → перенести у history з `applied_in` міткою
4. Якщо змінилось (користувач переписав) → ЛИШИТИ для подальшої обробки
5. Інші anchors (нові) — ЛИШИТИ нечіпані

### 6.5. UI попап правки (modal у tz_living.html)

При кліку на будь-який елемент з `data-anchor` атрибутом → відкривається modal:
- Заголовок: «Правка [N]»
- Read-only поле: «Оригінальний текст»
- Textarea: «Коментар (твоя думка / зауваження)»
- Textarea: «Виправлений текст (опційно — на що замінити)»
- Кнопки: 🗑 Видалити правку · Скасувати · 💾 Зберегти
- Hotkeys: Esc=закрити, Ctrl+Enter=зберегти

### 6.6. Archive modal (зелений)

Toggle «👁 Архів (N)» у топбарі → відкривається повноекранний modal зі списком архівних правок:
- Sortованих за датою
- Кожна — зелена картка з: anchor #, applied_in, original (preview), comment, new_text, дата ts і applied_at

---

## 7. Dashboard — основна точка входу

### 7.1. Файлова структура `dashboard/`

| Файл | Призначення |
|--|--|
| `index.html` | Головна сторінка дашборду |
| `server.js` | Node.js сервер (0.0.0.0:8767 для LAN-доступу) |
| `tz_living.html` | ТЗ Living Spec (27 розділів, toggle Клієнт/Розробник) |
| `tz_docx_preview.html` | ТЗ docx HTML preview (16 класичних розділів) для коригування перед export у Word |
| `transcript_clean.html` | Чистий транскрипт зустрічі з ролями |
| `transcript_review.html` | Review транскрипту з 97 нумерованими кандидатами |
| `protocol_preview.html` | Класичний HTML-preview протоколу (mammoth) |
| `user_notes.md` | Free-form нотатки головного дашборду + глосарій |
| `tz_general_notes.md` | Free-form нотатки команди (з tz_living.html) |
| `annotations.json` | Активні правки |
| `annotations_history.json` | Архів застосованих правок |
| `review_answers.json` | Відповіді на 97 уточнень транскрипту |

### 7.2. Endpoints server.js

| Endpoint | Метод | Що повертає |
|--|--|--|
| `/` | GET | `index.html` |
| `/ping` | GET | `pong` |
| `/notes` | GET | `user_notes.md` |
| `/save` | POST (text/plain) | Перезаписує `user_notes.md` |
| `/{doc_key}_notes` | GET | `{doc_key}_general_notes.md` (узагальнений endpoint: працює для tz, protocol, tz_docx, будь-якого нового doc_key) |
| `/{doc_key}_notes` | POST | Перезаписує `{doc_key}_general_notes.md` |
| `/annotations?doc=X` | GET | Активні правки для doc |
| `/save_annotation` | POST (JSON) | Зберегти/видалити annotation |
| `/annotations_history?doc=X` | GET | Архів для doc |
| `/status` | GET | JSON стан транскрипції (legacy від whisper) |
| `/context` | GET | `CONTEXT.md` raw |
| `/transcript` | GET | Зшитий повний транскрипт plain |
| `/protocol` | GET | Download `№1_21.05.2026.docx` |
| `/tz` | GET | Download актуальний `ТЗ_v0.4.docx` |
| `/research` | GET | `research_findings.md` |
| `/transcript_clean.html`, `/transcript_review.html`, `/tz_living.html`, `/protocol_preview.html`, `/tz_docx_preview.html` | GET | Статичні файли |

### 7.3. Запуск/перезапуск
```bash
node "C:\AI\Ukrtruboizol\dashboard\server.js"
```
**LAN-доступ:** http://192.168.168.111:8767/ (auto-detected IP)
**Localhost:** http://localhost:8767/

При додаванні нових endpoints — потрібен перезапуск.

---

## 8. Скрипти `research/`

| Скрипт | Призначення | Коли запускати |
|--|--|--|
| `transcribe_gemini_v3.py` | Транскрипція аудіо через Gemini 3.1 Pro | Якщо є нове аудіо |
| `build_protocol.py` | Генерує `docs/№1_21.05.2026.docx` | Якщо правки у протоколі |
| `build_tz.py` | Генерує `docs/ТЗ_v0.X.docx` | Після правок у ТЗ |
| `build_tz_living.py` | Генерує `dashboard/tz_living.html` | Після правок у ТЗ |
| `build_previews.py` | Генерує `protocol_preview.html` + `tz_docx_preview.html` (mammoth docx→HTML з annotation engine) | Після зміни протоколу або ТЗ docx |
| `generate_review.py` | Генерує `transcript_review.html` з кандидатами | Після нової транскрипції |
| `safe_archive.py` | Безпечне архівування застосованих правок | При обробці правок |
| `analyze_speakers.py` | Аналіз спікерів по файлах | Для перевірки гіпотез mapping |
| `build_clean_transcript.py` | Зшитий clean transcript | Після post-processing глосарію |
| `research_findings.md` | Live web research | Регенерується вручну |

### Стандартний workflow обробки правок

```
1. Прочитати dashboard/annotations.json — нові правки
2. Зрозуміти кожну правку (анот ID + comment + new_text)
3. Внести зміни у build_tz.py і build_tz_living.py
4. Bump версію (v0.3 → v0.4)
5. Видалити старий docx
6. Запустити build_tz.py + build_tz_living.py
7. Оновити server.js (/tz pointer на новий файл)
8. Запустити safe_archive.py — перенести оброблені правки у history
9. Перезапустити server
10. Smoke test (curl /tz_living.html, /tz)
```

---

## 9. AI Routing (підтверджено експериментально)

| Задача | Провайдер / Модель | Ключ |
|--|--|--|
| **STT — транскрипція аудіо** з diarization, UK/RU/суржик | **Gemini 3.1 Pro Preview** через direct REST + structured JSON + thinkingLevel=high | `C:\AI\API\gemini --- soft.txt` |
| **Code / LLM general** | Claude (це я) | — |
| **Image generation** | Grok / xAI | `C:\AI\.shared\credentials\xai.env` |
| **Vision / Image understanding** | OpenAI GPT-4o | `C:\AI\API\ChatGPT.txt` |
| **Live web research** | WebSearch + WebFetch | вбудовано |

Деталі: див. memory file `reference_ai_routing.md`.

### Видалено / deprecated
- Local faster-whisper, openai-whisper, ctranslate2, py-spy, tiktoken — uninstalled 2026-05-22
- Wrapper `C:\AI\.shared\whisper-tools\` — видалено
- Deepgram — credentials видалено (не потрібен)

---

## 10. Архітектура продукту (з ТЗ v0.4) — короткий зміст

### 10.1. Три точки контролю

**🟢 Точка ВХОДУ — 1-й виробничий етап («Фрезерування»)**
- Робітник у мобільному обирає етап з активних
- Сканує ШК листа → перевірка чи є у документі «Приймання листа» (BAS)
- Так → автозапис у локальний буфер
- Ні → поле підсвічується **ЧЕРВОНИМ**, кнопка «Оновити дані»
- При синхронізації — створюється/доповнюється типовий документ «Передача матеріалів до комори»

**🟡 Проміжні етапи (Плазмовий різ, Призолюванні, …)**
- Тільки факт проходження ШК через дільницю
- БЕЗ характеристик листа на екрані (легка операція)
- Автозапис: ШК + етап + час + Device ID
- BAS auto-прив'язка до зміни за часом + графіком підрозділу

**🔴 Точка ВИХОДУ — ОТК (планшет з BAS-клієнтом)**
- НЕ через наш мобільний додаток
- ОТК працює напряму в типовому документі «Виробнича операція»
- Сканування ШК → автоматичне заповнення «Використані листи»
- При збереженні документа — **звіряння серій листа з вкладкою «Забезпечення» етапу**
- Якщо лист не у Забезпеченні → попередження/помилка

### 10.2. Ідентифікація пристрою (НЕ робітника)

- **Android Device ID** (`Settings.Secure.ANDROID_ID`)
- Передається у кожному скан-events до BAS
- BAS веде довідник «Пристрої сканування» з людським іменем («Цех №1 — Сканер А»)
- Один пристрій можуть використовувати різні робітники протягом зміни
- **Прибрано PIN-авторизацію** (виправлення у v0.4 за коментарем користувача)

### 10.3. Етап = Вид робочого центру (типовий BAS)

- Адміністратор у BAS активує потрібні Види робочих центрів як «Етапи»
- У мобільний передаються тільки **активні** етапи (через метод `GetActiveStages`)
- Прив'язка ШК-події до зміни — за часом сканування + графіком підрозділу:
  - Якщо підрозділ працює без змін → загальна інформація у звіті
  - Якщо зі змінами → ШК потрапляє у ту зміну, у часовий інтервал якої сканована

### 10.4. Технологічний стек

| Компонент | Технологія |
|--|--|
| Mobile (Android) | Kotlin · Jetpack Compose · CameraX · Google ML Kit · SQLite · Retrofit |
| Server | BAS ERP HTTP-сервіс «MobileScanner» · JSON через HTTPS · TLS 1.2+ |
| ОТК-планшет | Типовий BAS-клієнт + USB-сканер у HID-режимі |

### 10.5. API endpoints (4 методи)
- `GET /MobileScanner/GetAllowedSheets` — ШК з «Приймання листа»
- `GET /MobileScanner/GetActiveStages` — активні етапи
- `POST /MobileScanner/RegisterEntryScan` — на 1-му етапі (створює «Передача матеріалів до комори»)
- `POST /MobileScanner/RegisterTransitScan` — на проміжному (запис у «Журнал проходження ШК»)

---

## 11. Глосарії

### 11.1. Domain глосарій (для розуміння тексту і документів)

| Термін | Визначення |
|--|--|
| Лист | Стальний лист — основна одиниця обліку сировини |
| Точка входу | 1-й виробничий етап (Фрезерування). Створює «Передача матеріалів до комори» |
| Проміжний етап | Дільниця між точкою входу і ОТК. Лише фіксація проходження |
| Точка виходу | ОТК — присвоює партію/серію готовому виробу, прив'язує до 2-х листів |
| Передача матеріалів до комори | Типовий документ BAS — рух матеріалів зі складу у виробництво |
| Виробнича операція | Типовий документ BAS — фіксує виробничий процес. Доопрацьовується для ОТК |
| Журнал проходження ШК | Регістр відомостей BAS — записи усіх сканувань на проміжних етапах |
| Вид робочого центру | Типовий обʼєкт BAS, використовується як «Етап» у мобільному |
| Device ID | Android Settings.Secure.ANDROID_ID — ідентифікатор пристрою |
| HID-режим | USB-сканер у режимі клавіатури (без драйверів) |

### 11.2. Post-processing глосарій (заміни у транскрипті)

#### Абревіатури
| У сирому транскрипті | У чистому ТЗ/протоколі |
|--|--|
| ГІРПІ / і-ар-пі | ERP |
| БАС | BAS |
| АРІ | API |
| ТВД | ТВД (Труби великого діаметру) |
| ТБД | ТБД (рос. Трубы большого диаметра) |
| ТЗ | ТЗ (Технічне завдання) |
| OTK | ОТК (отдел технического контроля) |
| ТМЦ | ТМЦ (товарно-матеріальні цінності) |
| ДСТО | ДСТУ (виправлення моделі) |
| ПМК | ПМК (Пересувна механізована колона — назва клієнта-контрагента) |
| ГТДшка | ВМД |
| Андроїд/Андроїді | Android |

#### Імена
| Сире | Правильно |
|--|--|
| Лєні/Лєна/Лена | Олена (4 згадки у файлі A) |
| Ань | Ані (звертання у відмінку) |
| Юр | Юра (звертання до Юрія Магери) |
| Валентинівна (файл C, #92) | Валентинович (помилка моделі — це Юрій) |

#### Видалити з тексту
- «Костя запропонував…» (#2) — невпізнане ім'я
- «питання до Фібу, наскільки Тоді ладно…» (#10, 11) — шум моделі

---

## 12. Pip packages — поточний стан системи

**Залишилось після cleanup 2026-05-22:**
- `python-docx` 1.2.0 — генерація docx
- `mammoth` 1.12.0 — docx→HTML (для preview)
- `google-genai` 1.47.0 — Gemini SDK
- `requests` 2.28.1 — HTTP-клієнт
- `psutil` — для діагностики процесів

**Видалено** (більше не потрібно):
- `faster-whisper`, `openai-whisper`, `ctranslate2`, `av`, `onnxruntime`, `py-spy`, `tiktoken`

---

## 13. Файлова структура проекту

```
C:\AI\Ukrtruboizol\
├── CONTEXT.md                                  ← цей файл
│
├── audio\                                      RAW + транскрипти
│   ├── Новий запис.m4a                         (15.4 MB, raw)
│   ├── Новий запис 2.m4a                       (15.0 MB, raw)
│   ├── Новий запис 4.m4a                       (1.4 MB, raw)
│   ├── Новий запис_gemini_v3.json              (78 KB, structured)
│   ├── Новий запис_gemini_v3.txt               (62 KB, plain)
│   ├── ... (×3 для 3 файлів)
│   └── transcript_clean.txt                    (109 KB, зшитий)
│
├── docs\                                       КЛІЄНТСЬКІ DELIVERABLES
│   ├── №1_21.05.2026.docx                      (40 KB, Протокол)
│   └── ТЗ_BAS_ERP_штрихкодування_v0.4_22.05.2026.docx  (52 KB, ТЗ v0.4)
│
├── dashboard\                                  ВЕБ-ДАШБОРД
│   ├── index.html                              (~32 KB, головна)
│   ├── server.js                               (Node.js сервер)
│   ├── tz_living.html                          (~120 KB, ОДИН живий документ з toggle Клієнт/Розробник)
│   ├── transcript_clean.html                   (209 KB)
│   ├── transcript_review.html                  (~330 KB, з review-формами)
│   ├── protocol_preview.html                   (~28 KB)
│   ├── user_notes.md                           (нотатки + глосарій)
│   ├── tz_general_notes.md                     (нотатки команди на сторінці ТЗ)
│   ├── annotations.json                        (активні правки)
│   ├── annotations_history.json                (архів)
│   └── review_answers.json                     (97 відповідей на транскрипт)
│
├── research\                                   СКРИПТИ + ДОСЛІДЖЕННЯ
│   ├── transcribe_gemini_v3.py
│   ├── build_protocol.py
│   ├── build_tz.py
│   ├── build_tz_living.py
│   ├── build_previews.py
│   ├── build_clean_transcript.py
│   ├── generate_review.py
│   ├── safe_archive.py
│   ├── analyze_speakers.py
│   └── research_findings.md
│
├── tasks\                                      (порожньо)
└── bugs\                                       (порожньо)
```

---

## 14. Memory references (загальносистемні правила)

Файли у `C:\Users\Юрий\.claude\projects\C--Users-----\memory\` що дотичні до проекту:

| Memory file | Що містить |
|--|--|
| `reference_ai_routing.md` | Який ШІ для якої задачі |
| `user_profile.md` | Юрій Валентинович Магера, директор SoftInform |
| `feedback_no_hallucination.md` | Не вигадувати — питати з контекстом |
| `feedback_unknown_terms_ask_with_context.md` | Для транскриптів — питати з фрагментом тексту |
| `feedback_bas_standards.md` | Стандарти BAS — у `C:\AI\.shared\bas-standards\` |
| `feedback_client_file_naming.md` | Клієнтські deliverables у форматі клієнта (`№N_DD.MM.YYYY.docx`) |
| `feedback_real_doc_metadata.md` | docx з реальними file properties (Author, Company, Application=MS Office) |
| `feedback_default_max_mode.md` | МАКС-якість як default |
| `feedback_save_context.md` | «зберегти» = update CONTEXT.md + projects_list |

---

## 15. Наступні кроки (порядок)

1. **Чекаємо ще правок користувача** через annotation system у Living Spec
2. **Узгодження ТЗ v0.5 з Замовником** (Наталя Вікторівна, Таня) — наступна зустріч. Перевіряти у Клієнтському режимі (toggle default).
3. **Перед стартом розробки** (на основі Розробницького режиму tz_living):
   - Згенерувати OpenAPI 3.1 YAML з §6 (можна автоматизувати з тих же джерел що генерують tz_living)
   - Створити Figma макети на основі SVG ескізів §4
   - Створити migration plan для BAS (операційний, окремий короткий артефакт)
4. **Старт розробки:**
   - BAS HTTP-сервіс і об'єкти (1-2 тижні, Юрій або команда SoftInform) — джерело істини §12–23
   - Android-додаток (4-6 тижнів, контрактник / freelance) — джерело істини §24–25
   - QA на основі §26 «Тестові сценарії»
5. **Пілот** на одній виробничій дільниці
6. **Розширення** на всі дільниці + ОТК
7. **Передача в експлуатацію** з документацією і навчанням

---

## 16. Як спілкуватися з Замовником

**Стилістичні правила (із досвіду роботи):**
- **Уникати developer-жаргону**: F-SRV-XX, ID, anchor, immutable — англіцизми → українізувати
- **Документи зі своїм іменем компанії** ТОВ «СофтІнформ» (Виконавець) і ТОВ НВП з ІІ «Укртрубоізол» (Замовник)
- **docx з реальними метаданими** (Author = Юрій Магера; Company = ТОВ «СофтІнформ»; Application = Microsoft Office Word; AppVersion = 16.0000)
- **Файлові імена клієнтських deliverables** — формат `№N_DD.MM.YYYY.docx` (наприклад `№1_21.05.2026.docx`)
- **Підпис** = «команда SoftInform» або «Магера Ю.В.» (без «Юрій Магера» — формальніше з ініціалами)

---

## 17. Історія значущих змін

- **2026-05-21** — Проект створено. Зустріч №1 проведена (3 файли аудіо).
- **2026-05-22 ранок** — Транскрипція через Gemini 3.1 Pro Preview (вибір моделі після тесту 4 кандидатів). 97 правок користувача через review-форму застосовано. Глосарій post-processing зведено.
- **2026-05-22 день** — Протокол №1 створено (docx з реальними метаданими, формат клієнта). ТЗ v0.1 → v0.2 → v0.3 → v0.4 (4 ітерації на основі правок користувача через annotation system).
- **2026-05-22 вечір** — Living Spec ТЗ створений як основний робочий формат. Додано annotation system, archive modal, free-form team notes. Залишено тільки 2 формати ТЗ (Living + docx). Прибрано F-SRV-XX/F-MOB-XX жаргон.
- **2026-05-25** — Архітектурна міграція: відмова від layered approach (tz_sdd + api_spec + test_cases + openapi.yaml) на користь **ОДНОГО живого документу з progressive disclosure** (toggle Клієнт/Розробник). Видалено 4 застарілі файли. tz_living v0.5 — 27 розділів (11 клієнтських + 16 технічних). Застосовано 3 правки користувача (#70 GetWorkerShiftInfo→GetActiveStages, #96 Призолюванні→Зварювання, #109 прибрано трасування+журнал ШК зі звітів).
- **2026-05-25 вечір** — API-методи (4 endpoints) перенесено з клієнтського §6 у tech-розділ §18 «HTTP-сервіс» (розробницький режим). Додано `tz_docx_preview.html` — HTML preview саме docx-варіанту ТЗ через mammoth + annotation engine (doc_key=`tz_docx`). Workflow: правки у HTML preview → Claude обробляє → регенерація docx через build_tz.py → export. Узагальнено `/X_notes` endpoint у server.js (працює для будь-якого doc_key).
- **2026-05-25 ніч (audit після зауваження користувача)** — full numbering audit виявив 7 халтур, виправлено:
  1. tz_living: §6.5 → §6 (після видалення §6 API), додано TOC link, hero KPI 29→28, pill §5 «23»→«28», pill §10 «9»→«8», title v0.2→v0.5, TOC pill §0 v0.4→v0.5
  2. ТЗ docx: «призолюванні» (3 згадки з малої — у §5.2, §2.2 принципах, глосарії) → «зварювання» (правка #96 раніше була застосована тільки до tz_living)
  3. ТЗ docx: видалено §11.4 «Трасування виробу» зі звітів (правка #109 раніше була застосована тільки до tz_living)
  4. ТЗ docx: bump v0.4 → v0.5, дата 22.05.2026 → 25.05.2026, revision 4→5
  5. **Критичне:** build_tz.py H1/H2/H3 функції тепер використовують справжні `Heading 1/2/3` styles (раніше — звичайні add_paragraph), завдяки чому mammoth правильно конвертує у `<h1>/<h2>` тегу і tz_docx_preview показує всі 32 підрозділи (раніше пропускав §2.1, §10.2, §11.3)
  6. server.js: `/tz` → новий filename v0.5
  7. index.html: bump карток на v0.5

---

> **Як швидко зорієнтуватися у наступній сесії:** прочитати розділи 0 (швидкий старт), 4 (архітектура документації — щоб зрозуміти що зроблено і що ще треба), 5 (формати створених документів), 7 (dashboard), 8 (скрипти), 15 (наступні кроки).