From b2f8aaa17e2d31800ea3393020e295bb72f28653 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Sun, 4 Oct 2026 07:26:37 +0400 Subject: [PATCH] =?UTF-8?q?docs:=20.env.example=20=E2=80=94=20scan-gateway?= =?UTF-8?q?=20=D1=82=D0=BE=D0=B6=D0=B5=20=D0=BE=D1=82=D0=B2=D0=B5=D1=80?= =?UTF-8?q?=D0=B3=D0=B0=D0=B5=D1=82=20OPENBAO=5F=5FDATABASE=5F=5F*=20(N-1?= =?UTF-8?q?=20=D1=84=D0=B8=D0=BD=D0=B0=D0=BB=D1=8C=D0=BD=D0=BE=D0=B3=D0=BE?= =?UTF-8?q?=20=D1=80=D0=B5=D0=B2=D1=8C=D1=8E)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit В OpenBAOSettings scan-gateway нет поля DATABASE (extra_forbidden), поэтому общий dev/.env.example годится только arm-core как есть. Исправлены комментарий в .env.example, раздел dev/README.md, решение №44 в design.md и OQ-84. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2 --- context/07-open-questions.md | 2 +- dev/.env.example | 3 ++- dev/README.md | 2 +- openspec/changes/slice-0-skeleton/design.md | 2 +- 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/context/07-open-questions.md b/context/07-open-questions.md index 526c9a4..50e6ae4 100644 --- a/context/07-open-questions.md +++ b/context/07-open-questions.md @@ -89,7 +89,7 @@ | OQ-81 | Переменные `ARM_KA_DOCS` / `ARM_KA_FIXTURES` поддержаны неравномерно: `arm-core` — обе; `tabular-parser` — только `ARM_KA_DOCS`; `scan-gateway` — ни одной (жёстко `../docs`, `../../fixtures/ocr`). Текст причины skip («fixtures недоступен: положите репозиторий…») не содержит строки «ARM_KA_FIXTURES недоступен» из сценария «Нет фикстур» spec `quality-checks`; для docs-теста текст тоже без `ARM_KA_DOCS`. Нарушение spec — править сервисы? | scan-gateway и tabular-parser (тесты, Makefile); docs: O-3 (задача 1 фазы 2), `dev/checks.md`; spec `quality-checks` | срез 0 (процесс), все сервисы | допущение принято: расхождение описано в `dev/checks.md`; правка тестов и Makefile в scan-gateway и tabular-parser — follow-up человеку (сервисы не правились) | | OQ-82 | `.dockerignore` в `arm-core` не исключает `api/.env.test`: файл попадает в образ (у `tabular-parser` и `scan-gateway` исключён). Исправлять? | arm-core `.dockerignore`; docs: T3.2 (задача 3 фазы 2) | срез 0 (образы), прод-сборка | допущение принято: безвредно (в файле стандартные dev-учётные данные compose, не секреты), в Срезе 0 не правилось; добавить исключение в arm-core — follow-up | | OQ-83 | Контейнеры профиля `services` подписаны на те же subject и queue group общего NATS, что и экземпляры в интеграционных тестах сервисов (`recognition.result` / `arm-core`, `*.request`): NATS может отдать сообщение теста контейнеру и наоборот; интеграционные тесты `scan-gateway` и `arm-core` одновременно тоже делят NATS. Сделать queue group и subject-префикс настраиваемыми для тестов (например `NATS_TEST_PREFIX`) или поднимать отдельный NATS на тесты? | scan-gateway: п. 11 таблицы предложений (T14.1, T11.8); docs: O-11 (задача 3 фазы 2; подтверждено ревью для tabular-parser и scan-gateway), `dev/README.md` | срез 0 (процесс), интеграционные тесты | допущение принято: в `dev/README.md` предупреждение и команда `stop` для контейнеров профиля; не гонять `make test-integration` двух сервисов одновременно | -| OQ-84 | Запуск сервисов из venv без Nexus (`make venv` + `python run_server.py` из `api/` с `.env` из `docs/dev/.env.example`, healthcheck по `localhost`) в Срезе 0 не проверялся ни в одном из трёх сервисов. Известно по чтению конфигов (design #44): `.env.example` в нынешнем виде отвергнет `tabular-parser` (`OPENBAO__DATABASE__*`, `OPENBAO__SMB__*` — `extra_forbidden`), в нём нет `OPENBAO__MINIO__MINIO_SECURE=false` (по умолчанию `true` — https к http-MinIO). Прогнать сценарий, зафиксировать набор переменных и портов (`SERVER__PORT`, `SCAN_HOTFOLDER_PATH` для `scan-gateway`), решить, нужен ли отдельный `.env.example` на сервис, и снять пометку «черновик» с раздела `dev/README.md`? | spec `dev-environment`, сценарий «Запуск из venv против compose без Nexus»; docs: design #43, `dev/README.md` («Запуск сервисов из venv без Nexus»); финальное ревью фазы 2: I-1 | срез 0 (процесс, окружение разработки); кандидат в follow-up issue | вопрос: допущение Среза 0 — раздел README остаётся черновиком, сценарий не подтверждён (проверка требовала `.venv` внутри сервисных репозиториев, в фазе 2 доступных только для чтения) | +| OQ-84 | Запуск сервисов из venv без Nexus (`make venv` + `python run_server.py` из `api/` с `.env` из `docs/dev/.env.example`, healthcheck по `localhost`) в Срезе 0 не проверялся ни в одном из трёх сервисов. Известно по чтению конфигов (design #44): `.env.example` в нынешнем виде отвергнут `scan-gateway` (`OPENBAO__DATABASE__*`) и `tabular-parser` (`OPENBAO__DATABASE__*`, `OPENBAO__SMB__*` — `extra_forbidden`), в нём нет `OPENBAO__MINIO__MINIO_SECURE=false` (по умолчанию `true` — https к http-MinIO). Прогнать сценарий, зафиксировать набор переменных и портов (`SERVER__PORT`, `SCAN_HOTFOLDER_PATH` для `scan-gateway`), решить, нужен ли отдельный `.env.example` на сервис, и снять пометку «черновик» с раздела `dev/README.md`? | spec `dev-environment`, сценарий «Запуск из venv против compose без Nexus»; docs: design #43, `dev/README.md` («Запуск сервисов из venv без Nexus»); финальное ревью фазы 2: I-1 | срез 0 (процесс, окружение разработки); кандидат в follow-up issue | вопрос: допущение Среза 0 — раздел README остаётся черновиком, сценарий не подтверждён (проверка требовала `.venv` внутри сервисных репозиториев, в фазе 2 доступных только для чтения) | Служебные идентификаторы в DBML/аналитике: `ANL-nnn` — замечания аналитика к макету; `ARCH-nnn` — архитектурные решения; `DECISION-n` — решения по модели; `FIX-nn` — исправления дефектов v4. diff --git a/dev/.env.example b/dev/.env.example index 79a296c..c50f3ff 100644 --- a/dev/.env.example +++ b/dev/.env.example @@ -49,7 +49,8 @@ OPENBAO__NATS__NATS_SEED= OPENBAO__NATS__NATS_JWT= # SMB — заглушки (в Срезе 0 не используется); блок необязателен для arm-core и scan-gateway (режим local). -# tabular-parser неизвестные ключи OPENBAO__* отвергает: для него удалите блоки DATABASE и SMB (см. dev/README.md) +# Блок OPENBAO__DATABASE__* знает только arm-core: scan-gateway и tabular-parser неизвестные ключи OPENBAO__* отвергают +# (extra_forbidden) — для scan-gateway удалите блок DATABASE, для tabular-parser удалите блоки DATABASE и SMB (см. dev/README.md) OPENBAO__SMB__SMB_HOST=localhost OPENBAO__SMB__SMB_PATH=share OPENBAO__SMB__SMB_LOGIN=user diff --git a/dev/README.md b/dev/README.md index 630f05a..0b94c19 100644 --- a/dev/README.md +++ b/dev/README.md @@ -344,7 +344,7 @@ curl -s localhost:<порт сервиса>/healthcheck одновременно или сервис из venv рядом с профилем `services` требуют разных `SERVER__PORT`. Для `arm-core` в ответе `/healthcheck` ожидаются `version` и `nats = ok` — при `NATS_ENABLED=true` (задан в `.env.example`; без него `nats = off`). Поля `/healthcheck` в контейнерах: `tabular-parser` — `uptime`, `version`, `nats`; `scan-gateway` — ещё -`hotfolder` (шлюзу нужен `SCAN_HOTFOLDER_PATH`). Набор переменных сервисов для запуска из venv не проверялся (см. черновик выше и OQ-84). По чтению конфигов: `tabular-parser` отвергает неизвестные ключи `OPENBAO__*`, поэтому в его `.env` нужно удалить строки `OPENBAO__DATABASE__*` и `OPENBAO__SMB__*`; для MinIO по `http` нужен `OPENBAO__MINIO__MINIO_SECURE=false` (в `.env.example` его нет, по умолчанию `true`). +`hotfolder` (шлюзу нужен `SCAN_HOTFOLDER_PATH`). Набор переменных сервисов для запуска из venv не проверялся (см. черновик выше и OQ-84). По чтению конфигов: `scan-gateway` и `tabular-parser` отвергают неизвестные ключи `OPENBAO__*`, а поле DATABASE есть только у `arm-core`. Поэтому в `.env` `scan-gateway` нужно удалить строки `OPENBAO__DATABASE__*` (SMB в режиме `local` допустим), а в `.env` `tabular-parser` — `OPENBAO__DATABASE__*` и `OPENBAO__SMB__*`; для MinIO по `http` нужен `OPENBAO__MINIO__MINIO_SECURE=false` (в `.env.example` его нет, по умолчанию `true`). ## Интеграционные тесты сервисов против compose (черновик) diff --git a/openspec/changes/slice-0-skeleton/design.md b/openspec/changes/slice-0-skeleton/design.md index 9b3cdc9..07bc89d 100644 --- a/openspec/changes/slice-0-skeleton/design.md +++ b/openspec/changes/slice-0-skeleton/design.md @@ -175,4 +175,4 @@ PostgreSQL 16, схемы создавать можно. Остаются (не | 41 | 2026-10-04 | В реестр **не** внесены, а оставлены в отчёте задачи 6 (кандидаты в follow-up issue при закрытии): scan-gateway п. 7 (рестарт NATS не автоматизирован), п. 8 (`stop()` не публикует конверты принятым заданиям), п. 9 (`/healthcheck` всегда 200), п. 13 (`DEBUG` не используется), п. 14 (`ResourceWarning` aiohttp), п. 15 (SMB без `connection_timeout`); tabular P-4, scan-gateway п. 10 и 16 (порты, `SCAN_GATEWAY_PORT`, устаревший README) — закрыты задачами 3–5 и `dev/README.md`; O-22 и T3.7/O-20 — процессные пункты задачи 7 | это инженерные доработки или уже исправленные расхождения документов, вопроса к человеку/аналитикам в них нет; реестр остаётся списком решений, которые принимает человек | пункты могут потеряться, если follow-up issue не будет заведена (чеклист закрытия, п. 6): они перечислены в отчёте с маркерами | | 42 | 2026-10-04 | Формулировка статусов в новых строках: «допущение принято: …» — в коде/спеке Среза 0 действует рабочее допущение, вопрос открыт для подтверждения; «вопрос: …» — человек должен принять решение, допущение Среза 0 указано после двоеточия (аудит на уровне БД, `attempt + 1`, образцы ответов ИС, формат `data_ocr`, имя файла ответа, `.part` в `Input`) | правило файла: агент вопросы не закрывает, а помечает допущение; слово «закрыт» нигде не использовано | различение статусов — рекомендация, не контракт; при несогласии префикс правится в реестре | | 43 | 2026-10-04 | Сценарий spec `dev-environment` «Запуск из venv против compose без Nexus» (`make venv` + `python run_server.py` + healthcheck) в Срезе 0 **не прогонялся**; раздел «Запуск сервисов из venv без Nexus» в `dev/README.md` остаётся черновиком, вопрос вынесен в OQ-84 (кандидат в follow-up issue) | проверка требует создать `.venv` внутри сервисных репозиториев (`make venv` пишет в `api/.venv`), а в фазе 2 они были доступны только для чтения (их worktree с открытыми PR не правятся); сквозная проверка шла на профиле `services` (контейнеры из тех же исходников) | сценарий spec может оказаться неработоспособным (набор переменных, `requirements.txt` без `raisa_*`, порты) — разработчик без Docker для сервисов узнает об этом при первом запуске; правится README или `.env.example` | -| 44 | 2026-10-04 | Уточнение к №18: блок `OPENBAO__SMB__*` **не обязателен**. В `arm-core` `OpenBAOSettings.SMB = SMBSettings()` с пустыми значениями по умолчанию (`api/src/core/config.py`), в `scan-gateway` блок необязателен в режиме `SCAN_HOTFOLDER_MODE=local` (по умолчанию) и обязателен целиком при `smb`, в `tabular-parser` блока нет, и `OpenBAOSettings` отвергает неизвестные ключи (`extra_forbidden`; проверено на копии его `config.py` с `.env` из `dev/.env.example`: падает на `OPENBAO.smb`, так же упадёт на `OPENBAO__DATABASE__*`) — `extra="ignore"` относится только к верхнему уровню `Settings`. Заглушки в `dev/.env.example` оставлены; комментарий и README исправлены и говорят, что `.env.example` годится для `arm-core` и `scan-gateway`, а для `tabular-parser` из него нужно убрать блоки `DATABASE` и `SMB` | в момент решения №18 `Settings` arm-core требовал блок; затем в arm-core блок сделан необязательным (в Срезе 0 SMB ядру не нужен), а формулировка осталась в `.env.example` и README | ложное утверждение «обязателен» заставляло бы переносить заглушки в окружение, где они не нужны; цена низкая — у `arm-core` и `scan-gateway` заглушки безвредны, а `tabular-parser` с неотредактированным `.env.example` не стартует (описано в README, часть OQ-84) | +| 44 | 2026-10-04 | Уточнение к №18: блок `OPENBAO__SMB__*` **не обязателен**. В `arm-core` `OpenBAOSettings.SMB = SMBSettings()` с пустыми значениями по умолчанию (`api/src/core/config.py`), в `scan-gateway` блок необязателен в режиме `SCAN_HOTFOLDER_MODE=local` (по умолчанию) и обязателен целиком при `smb`, в `tabular-parser` блока нет, и `OpenBAOSettings` отвергает неизвестные ключи (`extra_forbidden`; проверено на копии его `config.py` с `.env` из `dev/.env.example`: падает на `OPENBAO.smb`, так же упадёт на `OPENBAO__DATABASE__*`) — `extra="ignore"` относится только к верхнему уровню `Settings`. Заглушки в `dev/.env.example` оставлены; комментарий и README исправлены и говорят: `.env.example` годится для `arm-core` как есть; для `scan-gateway` из него нужно убрать блок `DATABASE` (в его `OpenBAOSettings` поля нет, `extra_forbidden`), для `tabular-parser` — блоки `DATABASE` и `SMB` (уточнено 04.10 по ревью, N-1) | в момент решения №18 `Settings` arm-core требовал блок; затем в arm-core блок сделан необязательным (в Срезе 0 SMB ядру не нужен), а формулировка осталась в `.env.example` и README | ложное утверждение «обязателен» заставляло бы переносить заглушки в окружение, где они не нужны; цена низкая — у `arm-core` заглушки безвредны, а `scan-gateway` и `tabular-parser` с неотредактированным `.env.example` не стартуют (описано в README, часть OQ-84) |