docs(files): unified file client + backends после #58–#61 (#53)

AGENTS.md

@@ -9,8 +9,8 @@ Canonical Go client for OnlyOffice Workspace (Projects + Calendar + CRM) and the
   - `request.go` — `Request`, `Query`, `Time`, `Token`, `MetaResponse`, `Permissions`.
   - `auth.go` — `Authenticate`, `AuthenticateContext`, `InvalidateToken`, `Auth`, token lifecycle.
   - `http.go` — transport + DRY response decoders (`ResponseArray`/`ResponseObject`/`postFormObject`/`putFormObject`/`deleteObject`).
-  - `projects.go`, `tasks.go`, `users.go`, `calendar.go`, `crm.go`, `files.go`, `files_webdav.go`, `files_stem.go`, `retry.go`, `mails.go`, `invoices.go` — typed / untyped domain methods. **`files.go`** — CRM opportunity upload plus **project/task Documents** (`UpdateFile`, `UploadToFolderReplacing`). **`files_webdav.go`** — Documents module by id (`ListDavFolder`, `MoveDavItems`/`CopyDavItems` with per-operation error surfacing, `ListFileOps`). **`retry.go`** — `DoRetry`: deterministic linear backoff (no jitter) on 429/502/503/504; every bulk tool routes API calls through it, and the HTTP transport + auth (`retryRaw`, `AuthenticateContext`) retry transient answers centrally. **`mails.go`** — OnlyOffice Workspace Mail. **`invoices.go`** — CRM invoices, PDF regen/cleanup, status. Association rules: [`docs/crm-associations.md`](docs/crm-associations.md).
-  - **Unified file client (epic #34) — `file_core.go`, `file_rest.go`, `file_dav.go`, `file_pg.go`, `file_es.go`, `file_es_text.go`, `file_text_index.go`, `file_facade.go`.** `file_core.go` — model (`Entry`, `Kind`) + `FileStore`/`Searcher`; `file_rest.go`/`file_dav.go` — REST/WebDAV adapters; `file_pg.go` — **read-only** SQL store (PostgreSQL/MySQL, `ErrReadOnly` on writes); `file_es.go` — OnlyOffice Elasticsearch searcher; `file_es_text.go`/`file_text_index.go` — own PDF/scan index (`oo_docs_text`, PDF attachments via pdfdetach); `file_facade.go` — `FileClient` with read/write/search order and transient fallback. Use `c.Files()` (facade), `c.FileStore("rest"|"dav"|"pg"|"sql")` or `c.SQLFileStore()`; contract and how to add a backend: [`docs/unified-file-client.md`](docs/unified-file-client.md).
+  - `projects.go`, `tasks.go`, `users.go`, `calendar.go`, `crm.go`, `files.go`, `files_webdav.go`, `files_stem.go`, `files_dedupe.go`, `retry.go`, `mails.go`, `invoices.go` — typed / untyped domain methods. **`files.go`** — CRM opportunity upload plus **project/task Documents** (`UpdateFile`, `UploadToFolderReplacing`). **`files_webdav.go`** — Documents module by id (`ListDavFolder`, `MoveDavItems`/`CopyDavItems` with per-operation error surfacing, `ListFileOps`). **`files_dedupe.go`** — stem|ext duplicate scans (`FindProjectDuplicates`, `DedupeProject`, `ApplyDedupGroups`; backs `oo projects files dedupe`). **`retry.go`** — `DoRetry`: deterministic linear backoff (no jitter) on 429/502/503/504; every bulk tool routes API calls through it, and the HTTP transport + auth (`retryRaw`, `AuthenticateContext`) retry transient answers centrally. **`mails.go`** — OnlyOffice Workspace Mail. **`invoices.go`** — CRM invoices, PDF regen/cleanup, status. Association rules: [`docs/crm-associations.md`](docs/crm-associations.md).
+  - **Unified file client (epic #34) — `file_core.go`, `file_rest.go`, `file_dav.go`, `file_pg.go`, `file_es.go`, `file_es_text.go`, `file_text_index.go`, `file_facade.go`.** `file_core.go` — model (`Entry`, `Kind`) + `FileStore`/`Searcher`; `file_rest.go`/`file_dav.go` — REST/WebDAV adapters; `file_pg.go` — **read-only** SQL store (PostgreSQL/MySQL, `ErrReadOnly` on writes); `file_es.go` — OnlyOffice Elasticsearch searcher; `file_es_text.go`/`file_text_index.go` — own PDF/scan index (`oo_docs_text`, PDF attachments via pdfdetach); `file_facade.go` — `FileClient` with read/write/search order and transient fallback. Use `c.Files()` (facade), `c.FileStore("rest"|"dav"|"webdav"|"pg"|"sql"|"postgres"|"mysql")` or `c.SQLFileStore()`. Integration: `file_store_integration_test.go` runs the full read+write set through the REST and DAV stores. Contract and how to add a backend: [`docs/unified-file-client.md`](docs/unified-file-client.md); the rclone WebDAV FUSE mount: [`docs/rclone-webdav.md`](docs/rclone-webdav.md).
   - Pure stdlib + `google/go-querystring`; no UI, no dotenv.
 - **CLI — `cmd/oo/` as `package main`.** Cobra wrapper that loads `.env` via `godotenv` at startup. **Subject-based command tree** mirroring [`tea`](https://gitea.com/gitea/tea):
   - `main.go` — entry point (docstring lists the command tree).
@@ -51,7 +51,22 @@ write `mux.HandleFunc("/api/2.0/...")` to emulate OnlyOffice, we write an
   `ONLYOFFICE_USER`, `ONLYOFFICE_PASS` (aliases `_HOST`/`_NAME`/`_PASSWORD`
   also accepted). Tests **skip** cleanly when credentials are missing so
   `go test ./...` remains green in CI.
-- Run integration with: `go test -tags=integration ./...`.
+- Backend-specific env (each test skips when its env is missing):
+  - REST/DAV store: `ONLYOFFICE_URL/USER/PASS` — `file_store_integration_test.go`
+    (`TestIntegrationFileStores`, destructive, throwaway project).
+  - SQL store: `ONLYOFFICE_DSN` (+ `ONLYOFFICE_PG_TENANT`,
+    `ONLYOFFICE_PG_TEST_FILE_ID`, `ONLYOFFICE_PG_TEST_FOLDER_ID`);
+    `MINIO_*` to compare `Download` with REST — `file_pg_integration_test.go`
+    (`TestIntegrationPGStore`, `TestIntegrationSQLFacade`).
+  - Elasticsearch: `ONLYOFFICE_ES_URL` (+ `ONLYOFFICE_ES_INDEX`,
+    `ONLYOFFICE_TENANT`) — `file_es_integration_test.go`
+    (`TestIntegrationESFacadeUsesES` proves `c.Files().Search()` is the ES
+    backend), `file_es_text_integration_test.go` (own `oo_docs_text`).
+- Run unit with `-race`: `go test -race ./...`. Run integration with:
+  `go test -tags=integration ./...`.
+- The HTTP transport and auth retry transient answers (429/502/503/504)
+  centrally via `retryRaw`/`DoRetry`, so parallel integration runs survive the
+  shared openresty rate limit (#57).
 - New endpoints **must** ship with an integration test before merge.
 
 ## Related