System wersjonowania KB (ChangeLog)

Opis

System śledzenia zmian w bazie wiedzy pozwala na:

• Zapisywanie historii zmian wpisów (Entry) i helplinków
• Podgląd diffów (różnic między wersjami)
• Śledzenie kto, kiedy i z jakiego źródła wprowadził zmianę
• Synchronizację zmian między środowiskami (dev → produkcja)

Architektura

Model Kb::ChangeLog

Tabela kb_change_logs przechowuje snapshoty zmian:

Pole Typ Opis

record_type	string	entry lub helplink
action	string	create, update lub delete
old_content	text	Poprzednia treść
new_content	text	Nowa treść
diff	text	Wygenerowany diff tekstowy
source	string	Źródło zmiany: api, cms, claude, script
server	string	Serwer na którym dokonano zmiany
title	string	Tytuł wpisu/klucz helplinka

Generowanie diffa

System używa gema Diffy do generowania czytelnych diffów:

# app/models/kb/change_log.rb
def generate_diff
  return if old_content.blank? || new_content.blank?
  self.diff = Diffy::Diff.new(old_content, new_content, context: 3).to_s
end

Diff jest generowany automatycznie przy tworzeniu wpisu changelog (callback before_create).

Sposoby logowania zmian

1. Przez API (InConnector)

# Logowanie zmiany wpisu
POST /connect/connectors/:id/action?action_kind=log_entry
{
  "entry_id": 123,
  "action": "update",
  "old_content": "stara treść",
  "new_content": "nowa treść",
  "source": "api"
}

# Logowanie zmiany helplinka
POST /connect/connectors/:id/action?action_kind=log_helplink
{
  "key": "app.feature.name",
  "action": "create",
  "new_content": "treść helplinka",
  "source": "script"
}

2. Przez model Ruby

# Logowanie zmiany wpisu
Kb::ChangeLog.log_entry(
  entry: entry,
  action: "update",
  old_content: old_text,
  new_content: new_text,
  source: "cms"
)

# Logowanie zmiany helplinka
Kb::ChangeLog.log_helplink(
  helplink: helplink,
  action: "create",
  new_content: content,
  source: "claude"
)

Przeglądanie historii

KB Changelog App

Aplikacja Connect do przeglądania historii zmian z UI:

• Lewa kolumna: lista zmian z ikonami akcji
• Prawa kolumna: szczegóły zmiany z diffem

URL: /connect/app/kb-changelog

Konfiguracja (fields):

• knowledge_base_id - ID bazy wiedzy do śledzenia

API do pobierania listy zmian

# Lista ostatnich zmian
GET /connect/connectors/:id/action?action_kind=list&limit=50

# Filtrowanie po typie
GET /connect/connectors/:id/action?action_kind=list&type=entry

# Szczegóły zmiany
GET /connect/connectors/:id/action?action_kind=show&change_id=123

Źródła zmian (source)

Source Opis

api	Zmiana przez zewnętrzne API
cms	Zmiana przez panel CMS
claude	Zmiana przez Claude Code/skrypty AI
script	Zmiana przez skrypty batch
web	Zmiana przez interfejs web

Akcje (action)

Action Ikona Kolor

create	➕	Zielony
update	✏️	Żółty
delete	🗑️	Czerwony

Ważne uwagi

1. Brak automatycznego śledzenia - zmiany nie są zapisywane automatycznie przez callbacki modeli. Trzeba jawnie wywołać log_entry lub log_helplink.

2. Diffy to tylko display - gem Diffy służy wyłącznie do generowania czytelnego diffa. Nie jest to system wersjonowania - to prosty changelog ze snapshotami.

3. Snapshoty, nie wersje - system przechowuje pełne kopie old_content i new_content, nie przyrostowe delty.

Pliki źródłowe

• app/models/kb/change_log.rb - model ChangeLog
• app/src/connect/connector/service/kb_changelog.rb - connector API
• app/src/connect/app/service/kb_changelog_app.rb - aplikacja UI
• db/migrate/20251212095034_create_kb_change_logs.rb - migracja