docs(spec): add monorepo implementation and access layer notes

Add documentation of the monorepo layout, describing the `docmost-client` and `sync` packages and their responsibilities. Clarify that all Docmost access is performed via REST for reads, while writes use collab/Yjs, documenting the architectural decision and its rationale.
This commit is contained in:
vvzvlad
2026-06-16 19:11:53 +03:00
parent ef223e13ff
commit 2f92dc4c1f

11
SPEC.md
View File

@@ -27,6 +27,11 @@
- lossless-конвертер `convertProseMirrorToMarkdown` / `markdownToProseMirror`;
- collab-путь записи `replacePageContent` / `mutatePageContent` (Hocuspocus/Yjs).
Реализация — **monorepo (npm workspaces)**: `packages/docmost-client` (выносной
`DocmostClient` + `lib/*`, лейаут 1:1 с `docmost-mcp/src/` — sync-методы дописываем
сюда, изменения бэкпортятся в `docmost-mcp` вручную) и `packages/sync` (движок
синхронизации).
**Важно:** MCP-инструменты — это тонкая обёртка над HTTP API Docmost. Синк-движок
ходит в REST Docmost **напрямую** и волен использовать любые эндпойнты, которых
нет в MCP (в частности — листинг корзины и restore, см. §8).
@@ -323,7 +328,11 @@ git диффает побайтово. Если export недетерминир
Будущая фаза (флаг `includeAttachments` у export уже есть) сможет качать бинари
в vault и переписывать ссылки. Сейчас — вне scope.
### Остаются открытыми
### Решение по слою доступа
- **Доступ к Docmost — всегда REST** (решено). Прямое чтение Postgres отвергнуто:
выигрыш на чтении не окупает связку с внутренней схемой, обход сайд-эффектов
сервисов (поиск/аудит/websocket) и недоступность против Docmost Cloud. Запись —
через collab/Yjs (§2), чтение — REST (§16).
---