# Документы GolemCRM — первая версия, 23.09.2026

## Где искать

- Карточка Pipeline / клиента → «Документы» → «Открыть документы».
- Компания → «Изменить» → «Документы и проекты компании».
- В разделе документов можно создать проект, привязать его к карточке той же компании и открыть документы проекта.
- В форме загрузки явно выбрать уровень: компания, клиент, проект или карточка. Наследуются ссылки, не копии файлов.
- Закрытый документ виден только автору и администраторам, и только при доступе к исходному контексту. Обычный документ следует правам контекста. Наследование не расширяет права.

## Версии и согласование

PDF, CSV (UTF-8), XLSX и DOCX; размер файла от 1 байта до 10 МиБ. Скачать можно любую доступную версию. Предпросмотра/редактирования содержимого в браузере пока нет.

Рабочей служит последняя утверждённая версия; если её нет — последняя неутверждённая. Новая версия не перезаписывает старую. Названия файлов не используются для автоматического объединения документов.

Цикл: черновик → на согласовании → утверждена. Утверждает владелец контекста или администратор; API-ключ следует правам своего владельца. Возврат в черновик требует причины. Утверждённую версию нельзя вернуть или перезаписать — требуется новая версия.

При загрузке можно указать версии исходников. После утверждения новой версии исходника результат получает отметку «Нужно проверить актуальность». Ответственный создаёт новую редакцию либо подтверждает отсутствие влияния с причиной. Следующее изменение исходника снова требует проверки.

Архив сохраняет файл и историю. Окончательное удаление, массовый перенос владельца/компании и автоматическая передача в новую карточку не включены в первую версию. Конвертация существующей сделки в клиента сохраняет документы без копирования.

## Этапы

Администратор настраивает назначения обязательных документов и требование утверждения для существующих стадий Pipeline. По умолчанию требований нет. В первой версии правила выдают предупреждения, но не блокируют движение карточки.

Каждый переход статуса фиксирует ссылки на конкретные версии доступных исполнителю документов; будущие редакции не меняют этот снимок. Закрытые документы не раскрываются другому пользователю через историю.

## API

Для всех маршрутов требуется текущая сессия или `Authorization: Bearer <API key>`. Права и авторство проверяются одинаково. Не помещайте ключ в URL.

### Контекст и проекты

- `GET /api/documents?context_type=work_item&context_id=123` — свои и унаследованные документы; `archive=1` включает архив. Другие типы: `company`, `client`, `project`.
- `GET /api/projects?company_id=123` — доступные проекты компании.
- `POST /api/projects` — `{"company_id":123,"name":"Проект"}`; необязательный `client_id` связывает с клиентской карточкой той же компании/владельца.
- `PUT /api/work-items/456/project` — `{"project_id":789}`. Проект и карточка должны иметь одну компанию/владельца; проект с `client_id` разрешён только для исходной карточки этого клиента.

### Надёжная загрузка через публичный адрес

1. `POST /api/document-uploads` с `{"size":3145728}`. Ответ содержит `id` и `chunk_bytes` (524288).
2. Для каждой части: `PUT /api/document-uploads/{id}` с `{"offset":0,"content_base64":"..."}`. Смещение — в байтах исходного файла, не base64. Повтор той же части безопасен; отличающаяся часть или пропуск смещения возвращают 409.
3. `POST /api/documents` с заголовком `Idempotency-Key: <stable UUID>` и телом:

```json
{
  "context_type": "work_item",
  "context_id": 456,
  "title": "Бриф проекта",
  "purpose": "brief",
  "visibility": "context",
  "filename": "brief.docx",
  "upload_id": "<id from step 1>",
  "comment": "Первая редакция",
  "source_version_ids": []
}
```

Назначения: `contract`, `brief`, `estimate`, `report`, `source`, `result`, `other`. Доступ: `context` или `private`. Исходники должны быть доступны и относиться к той же компании. Для карточки без компании исходники не привязываются по догадке.

Ответ содержит `id` документа, `version_id`, номер версии; `duplicates` предупреждает о совпадении содержимого, не объединяя документы.

Для новой версии: `POST /api/documents/{id}/versions` с теми же полями файла/исходников и новым Idempotency-Key. Контекст, название и доступ наследуются от документа.

Повтор финального запроса с тем же ключом и содержимым возвращает те же ID. Другие данные с тем же ключом — 409. Для небольших файлов можно передать `content_base64` вместо `upload_id`; через публичный адрес рекомендуется всегда использовать части.

Незавершённые части приватны и истекают через час. Максимум незавершённых загрузок пользователя — 100 МиБ. После финализации временный файл удаляется; основная версия сохраняется. Если временная сессия истекла, загрузите файл частями заново и повторите финализацию с исходным ключом.

### Версии и управление

- `GET /api/documents/{id}` — доступные версии, согласование, актуальность, ограниченный журнал действий.
- `GET /api/documents/{id}/versions/{versionId}/download` — файл как attachment, без постоянной публичной ссылки.
- `POST .../state` с `{"state":"review"}`, затем `{"state":"approved"}`; возврат — `{"state":"draft","reason":"..."}`.
- `POST .../recheck` с `{"reason":"Изменение исходника не влияет на результат, потому что ..."}`.
- `PATCH /api/documents/{id}` — `title`, `purpose`, `archived` (boolean). Источник и видимость нельзя незаметно поменять этим запросом.
- `GET /api/work-items/{id}/document-check?stage=proposal` — текущие предупреждения.
- `GET /api/work-items/{id}/document-transitions` — история зафиксированных версий.
- `GET /api/document-stage-rules`; администратор может заменить набор через `PUT` с `{"items":[{"stage":"proposal","purpose":"estimate","require_approved":true}]}`.

Права, архивирование и требования одинаковы в UI и API. При смене статуса `PUT /api/work-items/{id}` возвращает `warnings`; результат перехода остаётся успешным.

## Хранение и резервирование

Метаданные — SQLite. Содержимое — `DATA_DIR/documents`, вне публичной папки; названия на диске случайные. Для полноценной резервной копии после начала использования нужны и SQLite, и каталог документов. Снимок одной БД без файлов недостаточен. Откат к старой БД после появления новых документов недопустим без отдельного плана сохранения новых данных.