chore: шаблон команды (из DKB_ARMKA@c8fca3d5)
This commit is contained in:
Andrey Epifancev
commit
0a24489112
23
CLAUDE.md
Normal file
23
CLAUDE.md
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
# CLAUDE.md — arm-core (ядро АРМ КА)
|
||||||
|
|
||||||
|
Общий контекст системы — `../CLAUDE.md` и `../docs/` (workspace). Этот файл — только про этот репозиторий.
|
||||||
|
|
||||||
|
## Что это
|
||||||
|
Ядро: справочники, файлы/документы, маппинг результатов распознавания, вычисления консолидации, маршрут согласования,
|
||||||
|
ЕХ, аудит, права. **Единственный писатель в PostgreSQL.** Монорепо `backend/` (FastAPI) + `frontend/` (React/TS) по
|
||||||
|
шаблону команды (из нулевого коммита репозитория `<имя>`, коммит `<sha>`).
|
||||||
|
|
||||||
|
## Соглашения шаблона
|
||||||
|
<!-- заполняет агент в Срезе 0: структура, DI, ORM/миграции, тесты, линтеры, сборка, фронт -->
|
||||||
|
|
||||||
|
## Зависимости от соседей
|
||||||
|
- Контракты: `../docs/contracts/recognition-result.schema.json` (вход из парсера/шлюза), `ex-payload-v1.schema.json`.
|
||||||
|
- Фикстуры: `../fixtures/` (env `ARM_KA_FIXTURES`); в CI — checkout `arm-ka-fixtures`.
|
||||||
|
- NATS subjects и схема ключей S3 — `../docs/context/03-architecture.md`.
|
||||||
|
|
||||||
|
## Правила репозитория
|
||||||
|
- ORM 1:1 с `../docs/model/data-model-v5.13.dbml`; `scripts/check_dbml_vs_orm.py` — обязательная проверка CI.
|
||||||
|
- Алгоритмы — только из `../docs/context/05-domain-rules.md`; номер § — в docstring.
|
||||||
|
- Вычисляемые объекты консолидации — `backend/app/domain/`, без ORM-таблиц.
|
||||||
|
- Фронт: пользователь слаб во фронте — для TS/React изменений делай ревью сам и объясняй решения в PR.
|
||||||
|
- OpenSpec: `openspec/` здесь; сквозные изменения — change в `../docs`.
|
||||||
163
README.md
Normal file
163
README.md
Normal file
@ -0,0 +1,163 @@
|
|||||||
|
[](https://github.com/psf/black) [](https://pycqa.github.io/isort/) [](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
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user