eshmeshek
302c7ab9f5
- install.bat downloads exe from Gitea release or uses local copy - Adds to user PATH automatically - README with full usage guide, file structure, conflict resolution Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
162 lines
5.7 KiB
Markdown
162 lines
5.7 KiB
Markdown
# kisync — KIS API Builder Sync CLI
|
||
|
||
CLI-клиент для двусторонней синхронизации локальных файлов с сервером [KIS API Builder](https://gitea.esh-service.ru/public/api_builder_cli_client).
|
||
|
||
## Установка
|
||
|
||
### Вариант 1: Автоматическая (Windows)
|
||
|
||
Скачать и запустить [`install.bat`](https://gitea.esh-service.ru/public/api_builder_cli_client/releases/download/v1.0.0/install.bat) — он сам скачает `kisync.exe`, установит в `%LOCALAPPDATA%\kisync\` и добавит в PATH.
|
||
|
||
### Вариант 2: Ручная
|
||
|
||
1. Скачать `kisync.exe` со [страницы релиза](https://gitea.esh-service.ru/public/api_builder_cli_client/releases/tag/v1.0.0)
|
||
2. Положить в любую папку, которая есть в PATH (например `C:\Users\<user>\AppData\Local\kisync\`)
|
||
3. Проверить: `kisync --help`
|
||
|
||
---
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
# 1. Создать папку проекта
|
||
mkdir my-api-endpoints
|
||
cd my-api-endpoints
|
||
|
||
# 2. Подключиться к серверу API Builder
|
||
kisync init
|
||
# Server URL: http://your-server:3000
|
||
# Username: admin
|
||
# Password: ****
|
||
|
||
# 3. Скачать все эндпоинты с сервера
|
||
kisync pull
|
||
|
||
# 4. Редактировать файлы (запросы, скрипты)
|
||
# ... правишь query.sql, main.js, request.http ...
|
||
|
||
# 5. Проверить что изменилось
|
||
kisync status
|
||
|
||
# 6. Отправить изменения на сервер
|
||
kisync push
|
||
```
|
||
|
||
---
|
||
|
||
## Команды
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `kisync init` | Подключиться к серверу (ввести URL, логин, пароль) |
|
||
| `kisync pull` | Скачать эндпоинты с сервера в локальные файлы |
|
||
| `kisync pull --force` | Перезаписать локальные изменения версией с сервера |
|
||
| `kisync push` | Загрузить локальные изменения на сервер |
|
||
| `kisync push --force` | Принудительно перезаписать сервер, игнорируя конфликты |
|
||
| `kisync status` | Показать что изменилось локально и на сервере |
|
||
|
||
---
|
||
|
||
## Структура файлов
|
||
|
||
После `kisync pull` в папке появится такая структура:
|
||
|
||
```
|
||
my-api-endpoints/
|
||
├── .kisync.json # Конфиг (host, token) — НЕ коммитить!
|
||
├── .kisync-state.json # Состояние синхронизации — НЕ коммитить!
|
||
│
|
||
├── Пользователи/ # Папка (Folder в API Builder)
|
||
│ ├── _folder.json # Метаданные папки
|
||
│ │
|
||
│ ├── Получить список/ # Эндпоинт (SQL)
|
||
│ │ ├── endpoint.json # Настройки: method, path, parameters...
|
||
│ │ └── query.sql # SQL-запрос
|
||
│ │
|
||
│ ├── Создать/ # Эндпоинт (Script)
|
||
│ │ ├── endpoint.json
|
||
│ │ ├── main.js # JavaScript код (или main.py)
|
||
│ │ └── queries/ # Запросы, используемые в скрипте
|
||
│ │ ├── _index.json # Индекс запросов (имена, БД)
|
||
│ │ ├── insert.sql # SQL-запрос
|
||
│ │ └── notify.http # HTTP-запрос (AQL)
|
||
│ │
|
||
│ └── Внешний сервис/ # Эндпоинт (AQL / HTTP)
|
||
│ ├── endpoint.json
|
||
│ └── request.http # HTTP-запрос
|
||
│
|
||
└── _no_folder/ # Эндпоинты без папки
|
||
└── ...
|
||
```
|
||
|
||
### Файлы по типу эндпоинта
|
||
|
||
| Тип | Файлы |
|
||
|-----|-------|
|
||
| **SQL** | `endpoint.json` + `query.sql` |
|
||
| **Script** | `endpoint.json` + `main.js`/`main.py` + `queries/*.sql` |
|
||
| **AQL (HTTP)** | `endpoint.json` + `request.http` |
|
||
|
||
### Формат `request.http`
|
||
|
||
```http
|
||
POST /api/v1/patients
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "{{name}}",
|
||
"age": {{age}}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Конфликты
|
||
|
||
При `push` и `pull` kisync проверяет, не менял ли кто-то эндпоинт на сервере с момента последней синхронизации.
|
||
|
||
```
|
||
$ kisync push
|
||
|
||
! CONFLICT: Пользователи/Создать
|
||
server updated: 14.03.2026, 15:42:31
|
||
your base: 14.03.2026, 12:00:00
|
||
|
||
Use "kisync push --force" to overwrite server changes.
|
||
Or run "kisync pull --force" to get the latest version first.
|
||
```
|
||
|
||
**Варианты решения:**
|
||
- `kisync push --force` — перезаписать сервер своей версией
|
||
- `kisync pull --force` — забрать серверную версию (потерять свои правки)
|
||
- Сделать копию своих файлов, `pull --force`, вручную смержить
|
||
|
||
---
|
||
|
||
## Работа в команде с Git
|
||
|
||
Можно хранить эндпоинты в Git-репозитории. Добавьте в `.gitignore`:
|
||
|
||
```
|
||
.kisync.json
|
||
.kisync-state.json
|
||
```
|
||
|
||
Workflow:
|
||
1. `kisync pull` — скачать с сервера
|
||
2. `git commit` — зафиксировать
|
||
3. Редактировать файлы
|
||
4. `kisync push` — отправить на сервер
|
||
5. `git commit` — зафиксировать изменения
|
||
|
||
---
|
||
|
||
## Сборка из исходников
|
||
|
||
```bash
|
||
git clone ssh://git@gitea.esh-service.ru:2222/public/api_builder_cli_client.git
|
||
cd api_builder_cli_client
|
||
npm install
|
||
npm run package # → release/kisync.exe
|
||
```
|