commit f353113ed4cc2ccde12293f2105ca2b065fe3d48 Author: Andrey Epifancev Date: Fri Oct 2 23:09:17 2026 +0400 chore: шаблон команды (из DKB_ARMKA@c8fca3d5) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b942918 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,22 @@ +# CLAUDE.md — tabular-parser + +Общий контекст системы — `../CLAUDE.md` и `../docs/`. Этот файл — только про этот сервис. + +## Что это +Stateless-сервис разбора XLS/XLSX/XLSB: ОСВ по счетам (§1 правил) и ББ/ОФР из Excel (§12). Вход — NATS +`recognition.tabular.request` + файл в S3 `uploads/`; выход — JSON по `../docs/contracts/recognition-result.schema.json` +в S3 `results/` + NATS `recognition.result`. **Нет доступа к БД.** Не знает про организации, периметры, план счетов — +возвращает структуру файла; нормализация и резолв — в arm-core. + +## Главное правило +Структура определяется динамически по содержимому (§1.0 правил): никаких координат ячеек, имён листов, букв колонок +в коде. Словари синонимов — `rules/*.yaml`. Фикстуры `../fixtures/osv/**` — регрессия, не спецификация формата: +новый формат = новая фикстура + синоним, не новый `if`. + +## Тесты +- property-тесты инвариантов (§1.4) на всех файлах `../fixtures/osv/**` и `../fixtures/statements-xlsx/**`; +- снимки `../fixtures/golden/expected_osv_parse/*.json` — после ручной сверки «Итого»; +- синтетика только для вариантов, которых нет в фикстурах (шапка вариант 2, Вал./Кол., xlsb, без outline level). + +## Соглашения шаблона + diff --git a/README.md b/README.md new file mode 100644 index 0000000..6b8cbb1 --- /dev/null +++ b/README.md @@ -0,0 +1,163 @@ +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/) [![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint) +__________________________________________________________________________________________________________ +# dkb_armka, v 0.0.1 +____ + +| | Исполнитель | Заказчик | +|-----------|:----------------------------------------:|:----------------------------------------------:| +| Сотрудник | raykov-mse | raykov-mse | +| Отдел | aurora | aurora | +| Контакты | raykovmse@rshb.ru | raykovmse@rshb.ru | +----- +# Шаблон FastAPI + +## Описание + +Данное шаблон предоставляет проект, в котором приложение состоит из API и UI. При использовании данного типа проекта, Вы можете разрабатывать, как отдельные API сервисы, так и WEB приложения с интерфейсом. Для построения WEB интерфейса используется React. Далее описаны основные иснтрументы предустановленные данным шаблоном: + +### Подготовка к разработке + +Для удобной настройки проекта под разработку. Перейдите в каталог setup и выполните слудеющие команды: + +```bash +cd setup +chmod +x setup.sh +./setup.sh +``` + По итогу успешного выполнения Вы получите сообщение следующего + +```bash +complete setup web application +To start api, cd to api directory, and use venv, start run_server.py +To start api, cd to web directory, and use command npm run start! +Happy Hacking! :) +``` + +Далее просто запускайте проекты и приступайте к разработке + +### Backend + +Исходный код API находится в каталоге api. После клонирования репозитория требуется создать виртуальное окружение и установить зависимости, это достигается следующими командами: + +```bash +cd api +python -m venv ./.venv +cp ./../setup/pip.conf ./.venv/pip.conf +source ./.venv/bin/python +pip install -r requirements.txt +``` + +Запуск приложения осуществляется через файл: run_server.py + +В качестве фреймворка ля api используется FastAPI. (Как понятно из названия шаблона) Подробнее ознакомится с возможностями Fast API вы можете в официальной документации: [Fast API документация](https://fastapi.tiangolo.com/) + +Вы можете дополнительно устанавливать библиотеки необходимые для разработки. Настоятельно не рекомендуется изменять базовые предустановки из файла requirements.txt + +Базовый шаблон предоставляет минимальный функционал по работе с данными. Далее описаны основные моменты влияющие на работу приложения. + +#### Основная структура проекта + +```bash +api +├── requirements.txt +├── run_server.py +├── src +│ ├── app.py +│ ├── __init__.py +│ ├── settings +│ │ ├── __init__.py +│ │ ├── models.py +│ │ └── settings.py +└── web +``` + +Вы можете придерживатся любой структуры проекта, главное, чтобы у Вас присутствовал файл run_server.py. Который запускает web сервер uvicorn или gunicorn. Также обязательно Ваш сервер должен подниматся на определенном хосте и порте. Требуемый хост и порт передаются внутрь через переменные окружения SERVER_HOST, SERVER_PORT + +```python +uvicorn.run( + app, + host=settings.server.HOST, + port=settings.server.PORT, + lifespan="on" + ) +``` + +#### Отказ от ui (react) + +Если внутри вашего приложения не требуется добавлять визуальный интерфейс, а Вам требуется исключительно разработать API, то в таком случае не стоит удалять директорию web находящуюся на уровне с директорией api. ТРебуется внести небольшие правки в конфигурацию приложения, в частности в файл: /api/src/app.py, удалив следующее содержимое. В таком случае Fast API сервис не будет обрабатывать статические файлы, от web приложения. + +```python +#Подключение собранного web приложения +app.mount("/", StaticFiles(directory="web", html=True), name="web") +``` + +### Frontend + +Исходный код UI находится в каталоге web. После клонирования репозитория требуется установить зависимости, это достигается следующими командами: + +```bash +cd web +npm install +``` + +Запуск приложения осуществляется через файл команду: + +```bash +npm run start +``` + +В качестве фреймворка для ui используется React. Подробнее ознакомится с возможностями React вы можете в официальной документации: [React документация](https://react.dev/reference/react) + +Вы можете дополнительно устанавливать библиотеки необходимые для разработки. Настоятельно не рекомендуется изменять базовые предустановки из файла package.json + +Базовый шаблон предоставляет минимальный интерфейс по работе с данными. Далее описаны основные моменты влияющие на работу web приложения. + +#### Основная структура проекта + +```bash +web +├── biome.json +├── .npmrc +├── dist +├── package.json +├── postcss.config.cjs +├── public +│ └── index.html +├── README.md +├── rsbuild.config.ts +├── src +│ ├── App.tsx +│ ├── config.ts +│ ├── env.d.ts +│ ├── index.css +│ └── index.tsx +├── tailwind.config.js +└── tsconfig.json +``` + +Вы можете придерживатся любой структуры проекта, внутри src. Но на верхнем уровне находятся файлы конфигурации и сборки их требуется изменять только в крайнем случае. Для сборки приложения используется [RSBuild](https://rsbuild.dev/) + +Для создания UI настоятельно рекомендуется использовать предустановленную библиотеку компонентови стилей: + +- tailwindcss +- daisy-ui +- react-daisy-ui +- raisa-ui + +!!! Важно, если внутри web приложения Вы хотите обращатся к API данного проекта, используйте следующую конструкцию: + +```javascript + +fetch(`${Config.API_URL}/api`, { + headers: { + 'Accept': 'application/json', + 'Content-Type': 'application/json' + }, + method: 'GET' +}) + +``` + +Речь идет об вызываемом эндпоинте ${Config.API_URL}/api, Обязательно используйте конструкцию данного вида т.к. при сборке приложения статический сайт обращается относительно api и вместо +запросов вида http://localhost:8000/api должно быть так: /api +