# Локатор: справочник КА не соответствует онлайн-поиску 1С
 
**Запросы:** `locatorCounterpartyDirectory` (офлайн-справочник), `fieldTaskCounterparties` (онлайн-поиск 1С)
**Связано с:** доработкой единого поиска контрагента для независимой отметки
**Статус фронта:** клиент уже переведён на `fieldTaskCounterparties` онлайн и передаёт
`includeWithoutCoordinates: true` в справочник. Оставшееся расхождение — на стороне контракта.
 
---
 
## 1. Описание
 
Один и тот же контрагент находится **онлайн** и не находится **офлайн**.
 
| | офлайн-справочник | онлайн-поиск |
|---|---|---|
| запрос | `locatorCounterpartyDirectory` | `fieldTaskCounterparties` |
| источник данных | карточки CRM | 1С |
| идентификатор | `counterpartyId: Int!` (обязательный) | `id: Float` (nullable), `oneCUid: String!` |
 
Пример: по запросу «Игошина» онлайн возвращаются
«Игошина Наталья Александровна ИП» (ИНН 261901029716) и «Игошина Людмила Германовна».
Офлайн-поиск по справочнику не находит ни одну из них.
 
Причина структурная: `locatorCounterpartyDirectory` отдаёт только те КА, у которых
**уже есть карточка в CRM**. У контрагента из 1С карточки может не быть вовсе
(`FieldTaskCounterparty.id = null` — «ID контрагента в CRM (если уже синхронизирован)»),
и тогда он не попадает в справочник ни при каких значениях `includeWithoutCoordinates`.
 
Для выездных сотрудников это критично: у них часто нет интернета, а офлайн-справочник —
единственный источник данных на устройстве.
 
## 2. Что уже сделано на фронте
 
Чтобы закрыть проблему в пределах возможного без изменений бэка:
 
- независимая отметка использует тот же `fieldTaskCounterparties`, что и форма задачи;
- при сохранении отметки передаётся `counterpartyOneCUid`, если CRM-карточки нет
(иначе `counterpartyId`) — способы привязки взаимоисключающие;
- полная выгрузка справочника идёт с `includeWithoutCoordinates: true`;
- вся успешная выдача 1С сохраняется в локальный кэш устройства, чтобы найденный
однажды онлайн контрагент оставался доступен офлайн.
 
Не решается на фронте: контрагент, которого сотрудник **никогда не искал онлайн**
и которого нет в CRM, офлайн недоступен в принципе — полной выгрузки 1С на устройство нет.
 
## 3. Запрос №1 (основной): включить в справочник КА из 1С без карточки CRM
 
Сейчас `LocatorCounterpartyDirectoryItem.counterpartyId` — `Int!`, поэтому записи
без CRM-карточки в выдаче невыразимы.
 
Предлагаемое изменение контракта:
 
```graphql
type LocatorCounterpartyDirectoryItem {
"ID карточки в CRM; null — контрагент есть только в 1С"
counterpartyId: Int # было Int!
"UID контрагента в 1С"
oneCUid: String # новое поле
title: String!
inn: String
type: String
updatedAt: DateTime!
coordinates: [LocatorCounterpartyCoordinate!]!
}
```
 
и флаг во входе:
 
```graphql
input FindLocatorCounterpartyDirectoryInput {
includeWithoutCoordinates: Boolean
"Включить контрагентов из 1С, у которых ещё нет карточки в CRM"
includeOneCOnly: Boolean # новое поле, по умолчанию false
limit: Int
query: String
skip: Int
updatedSince: String
}
```
 
Требования к поведению:
 
1. по умолчанию (`includeOneCOnly` не передан или `false`) выдача **не меняется** —
старый клиент остаётся совместимым;
2. при `includeOneCOnly: true` в выдачу добавляются КА из 1С без карточки CRM,
у них `counterpartyId: null` и заполненный `oneCUid`;
3. состав и правила поиска совпадают с `fieldTaskCounterparties`, чтобы офлайн-выдача
не расходилась с онлайн-поиском.
 
Если полная выгрузка 1С неприемлема по объёму — просьба сообщить порядок величины
(сколько записей в 1С), тогда обсудим компромисс: например, отдавать только КА,
по которым в этом отделе/у этого сотрудника были задачи или отметки.
 
## 4. Запрос №2: добавить `oneCUid` в справочник в любом случае
 
Даже без п.3 поле `oneCUid` в `LocatorCounterpartyDirectoryItem` нужно:
 
- сейчас офлайн-запись и результат онлайн-поиска невозможно надёжно сопоставить —
общий идентификатор только один, `counterpartyId`, и он есть не у всех записей 1С;
- из-за этого один и тот же контрагент может показаться в списке дважды
(строка из кэша и строка из 1С), пока у CRM-карточки не совпадёт `id`.
 
Поле нужно только на чтение, ломающих изменений не несёт.
 
## 5. Запрос №3: уточнить семантику `skip`
 
Противоречие в текущей документации:
 
- описание поля в схеме: **«Значение пропуска страниц, по-умолчанию 0»** → `skip` = индекс страницы;
- переданная фронту инструкция по выгрузке: «начните с `skip: 0`, после каждой страницы
увеличивайте `skip` на число полученных элементов» → `skip` = смещение в записях.
 
Это взаимоисключающие трактовки. Сейчас клиент следует инструкции (шаг = число элементов)
и дополнительно защищён дедупликацией и остановкой, если страница не принесла новых записей, —
поэтому при любой из трактовок данные не задваиваются, но при страничной семантике
справочник обрежется на первых 500 записях.
 
Просьба зафиксировать один вариант. Сейчас справочник помещается в одну страницу
(`limit: 500`), поэтому расхождение ещё не проявляется, — но проявится при росте.
 
## 6. Приёмочная матрица
 
1. КА есть в 1С, нет в CRM: находится и онлайн, и (при `includeOneCOnly: true`) офлайн;
отметка сохраняется как `LINKED`, карточка CRM создаётся.
2. КА есть в CRM без координат: приходит при `includeWithoutCoordinates: true`
с `coordinates: []`, выбирается вручную, в `nearbyCounterparties` отсутствует.
3. КА есть в CRM с координатами: находится вручную и через геопоиск.
4. Выдача справочника и выдача `fieldTaskCounterparties` по одной и той же строке
поиска содержат один и тот же набор контрагентов.
5. Старый клиент (без новых флагов) получает прежнюю выдачу без изменений.
6. Постраничная выгрузка целиком воспроизводит `paginationInfo.totalItems`
без дублей и пропусков.
 

Локатор: справочник КА не соответствует онлайн-поиску 1С

Запросы: locatorCounterpartyDirectory (офлайн-справочник), fieldTaskCounterparties (онлайн-поиск 1С) Связано с: доработкой единого поиска контрагента для независимой отметки Статус фронта: клиент уже переведён на fieldTaskCounterparties онлайн и передаёт includeWithoutCoordinates: true в справочник. Оставшееся расхождение — на стороне контракта.


1. Описание

Один и тот же контрагент находится онлайн и не находится офлайн.

офлайн-справочниконлайн-поиск
запросlocatorCounterpartyDirectoryfieldTaskCounterparties
источник данныхкарточки CRM1С
идентификаторcounterpartyId: Int! (обязательный)id: Float (nullable), oneCUid: String!

Пример: по запросу «Игошина» онлайн возвращаются «Игошина Наталья Александровна ИП» (ИНН 261901029716) и «Игошина Людмила Германовна». Офлайн-поиск по справочнику не находит ни одну из них.

Причина структурная: locatorCounterpartyDirectory отдаёт только те КА, у которых уже есть карточка в CRM. У контрагента из 1С карточки может не быть вовсе (FieldTaskCounterparty.id = null — «ID контрагента в CRM (если уже синхронизирован)»), и тогда он не попадает в справочник ни при каких значениях includeWithoutCoordinates.

Для выездных сотрудников это критично: у них часто нет интернета, а офлайн-справочник — единственный источник данных на устройстве.

2. Что уже сделано на фронте

Чтобы закрыть проблему в пределах возможного без изменений бэка:

  • независимая отметка использует тот же fieldTaskCounterparties, что и форма задачи;
  • при сохранении отметки передаётся counterpartyOneCUid, если CRM-карточки нет (иначе counterpartyId) — способы привязки взаимоисключающие;
  • полная выгрузка справочника идёт с includeWithoutCoordinates: true;
  • вся успешная выдача 1С сохраняется в локальный кэш устройства, чтобы найденный однажды онлайн контрагент оставался доступен офлайн.

Не решается на фронте: контрагент, которого сотрудник никогда не искал онлайн и которого нет в CRM, офлайн недоступен в принципе — полной выгрузки 1С на устройство нет.

3. Запрос №1 (основной): включить в справочник КА из 1С без карточки CRM

Сейчас LocatorCounterpartyDirectoryItem.counterpartyId — Int!, поэтому записи без CRM-карточки в выдаче невыразимы.

Предлагаемое изменение контракта:

type LocatorCounterpartyDirectoryItem {
  "ID карточки в CRM; null — контрагент есть только в 1С"
  counterpartyId: Int          # было Int!
  "UID контрагента в 1С"
  oneCUid: String              # новое поле
  title: String!
  inn: String
  type: String
  updatedAt: DateTime!
  coordinates: [LocatorCounterpartyCoordinate!]!
}

и флаг во входе:

input FindLocatorCounterpartyDirectoryInput {
  includeWithoutCoordinates: Boolean
  "Включить контрагентов из 1С, у которых ещё нет карточки в CRM"
  includeOneCOnly: Boolean     # новое поле, по умолчанию false
  limit: Int
  query: String
  skip: Int
  updatedSince: String
}

Требования к поведению:

  1. по умолчанию (includeOneCOnly не передан или false) выдача не меняется — старый клиент остаётся совместимым;
  2. при includeOneCOnly: true в выдачу добавляются КА из 1С без карточки CRM, у них counterpartyId: null и заполненный oneCUid;
  3. состав и правила поиска совпадают с fieldTaskCounterparties, чтобы офлайн-выдача не расходилась с онлайн-поиском.

Если полная выгрузка 1С неприемлема по объёму — просьба сообщить порядок величины (сколько записей в 1С), тогда обсудим компромисс: например, отдавать только КА, по которым в этом отделе/у этого сотрудника были задачи или отметки.

4. Запрос №2: добавить oneCUid в справочник в любом случае

Даже без п.3 поле oneCUid в LocatorCounterpartyDirectoryItem нужно:

  • сейчас офлайн-запись и результат онлайн-поиска невозможно надёжно сопоставить — общий идентификатор только один, counterpartyId, и он есть не у всех записей 1С;
  • из-за этого один и тот же контрагент может показаться в списке дважды (строка из кэша и строка из 1С), пока у CRM-карточки не совпадёт id.

Поле нужно только на чтение, ломающих изменений не несёт.

5. Запрос №3: уточнить семантику skip

Противоречие в текущей документации:

  • описание поля в схеме: «Значение пропуска страниц, по-умолчанию 0» → skip = индекс страницы;
  • переданная фронту инструкция по выгрузке: «начните с skip: 0, после каждой страницы увеличивайте skip на число полученных элементов» → skip = смещение в записях.

Это взаимоисключающие трактовки. Сейчас клиент следует инструкции (шаг = число элементов) и дополнительно защищён дедупликацией и остановкой, если страница не принесла новых записей, — поэтому при любой из трактовок данные не задваиваются, но при страничной семантике справочник обрежется на первых 500 записях.

Просьба зафиксировать один вариант. Сейчас справочник помещается в одну страницу (limit: 500), поэтому расхождение ещё не проявляется, — но проявится при росте.

6. Приёмочная матрица

  1. КА есть в 1С, нет в CRM: находится и онлайн, и (при includeOneCOnly: true) офлайн; отметка сохраняется как LINKED, карточка CRM создаётся.
  2. КА есть в CRM без координат: приходит при includeWithoutCoordinates: true с coordinates: [], выбирается вручную, в nearbyCounterparties отсутствует.
  3. КА есть в CRM с координатами: находится вручную и через геопоиск.
  4. Выдача справочника и выдача fieldTaskCounterparties по одной и той же строке поиска содержат один и тот же набор контрагентов.
  5. Старый клиент (без новых флагов) получает прежнюю выдачу без изменений.
  6. Постраничная выгрузка целиком воспроизводит paginationInfo.totalItems без дублей и пропусков.