Add self-downloading installer and README
- 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>
This commit is contained in:
161
README.md
Normal file
161
README.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user