@ryuzaki13/react-foundation-api 1.1.16 → 1.1.18

package/src/adt/README.mdx

@@ -0,0 +1,461 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/SAP/ADT Transports" />
+
+# SAP ADT transports через `@ryuzaki13/react-foundation-api/adt`
+
+Модуль получает transport requests текущего пользователя из SAP ADT endpoint и преобразует XML в простой массив объектов.
+
+## Содержание
+
+- [Когда использовать](#когда-использовать)
+- [Установка и импорт](#установка-и-импорт)
+- [Быстрый старт](#быстрый-старт)
+- [`fetchUserTransports`](#fetchusertransports)
+- [`parseUserTransportsXml`](#parseusertransportsxml)
+- [Формат результата](#формат-результата)
+- [Ошибки и ограничения](#ошибки-и-ограничения)
+- [Полный API](#полный-api)
+
+## Когда использовать
+
+Используйте `adt`, если backend доступен по `/sap/bc/adt/cts/transports` и возвращает ADT XML. Если нужны отдельные UI2 списки workbench/customizing в JSON, используйте [`@ryuzaki13/react-foundation-api/transport`](../transport/README.mdx).
+
+```text
+SAP ADT XML
+    │
+    ▼
+parseUserTransportsXml
+    │
+    ▼
+UserTransport[]
+```
+
+## Установка и импорт
+
+```bash
+npm install @ryuzaki13/react-foundation-api @ryuzaki13/react-foundation-lib fast-xml-parser
+```
+
+```ts
+import { fetchUserTransports, parseUserTransportsXml } from "@ryuzaki13/react-foundation-api/adt";
+
+import type { UserTransport } from "@ryuzaki13/react-foundation-api/adt";
+```
+
+## Быстрый старт
+
+```ts
+async function loadTransports() {
+	try {
+		const transports = await fetchUserTransports();
+		return transports;
+	} catch (error) {
+		console.error("Не удалось получить transports", error);
+		return [];
+	}
+}
+```
+
+`fetchUserTransports` возвращает Promise. Пока он выполняется, данных ещё нет; ошибку нужно обработать через `try/catch`, TanStack Query или error boundary владельца сценария.
+
+## `fetchUserTransports`
+
+Функция выполняет GET:
+
+```text
+/sap/bc/adt/cts/transports?_action=FIND&trfunction=K
+```
+
+Запрос отправляется через SAP/OData transport пакета с:
+
+- `Accept: application/xml, text/xml, */*`;
+- cookies через `credentials: include`;
+- SAP language/client и SSO policy общего OData transport;
+- пустым base URL, потому что ADT endpoint уже содержит `/sap/...`.
+
+Ответ читается как text и передаётся `parseUserTransportsXml`.
+
+Если сервер вместо XML вернул HTML login/error page, функция выбросит ошибку. Это защищает UI от ситуации, когда HTML ошибочно принимается за пустой список transports.
+
+## `parseUserTransportsXml`
+
+Parser можно использовать отдельно, например в тесте или при получении XML другим transport:
+
+```ts
+const xml = `
+<root>
+	<CTS_REQ_HEADER>
+		<TRKORR>DEVK900001</TRKORR>
+		<AS4TEXT>Исправление отчёта</AS4TEXT>
+		<AS4USER>IVANOV</AS4USER>
+		<TARSYSTEM>QAS</TARSYSTEM>
+		<TRFUNCTION>K</TRFUNCTION>
+		<TRSTATUS>D</TRSTATUS>
+	</CTS_REQ_HEADER>
+</root>`;
+
+const transports = parseUserTransportsXml(xml);
+```
+
+Алгоритм:
+
+1. Пустая или состоящая из пробелов строка превращается в `[]`.
+2. XML разбирается `fast-xml-parser`.
+3. Во вложенной структуре рекурсивно ищутся узлы `CTS_REQ_HEADER`.
+4. Поля преобразуются в `UserTransport`.
+5. Записи без непустого `TRKORR` отбрасываются.
+6. Дубликаты `transportNo` удаляются; сохраняется первая запись.
+7. Если header-узлы не найдены, parser ищет вложенные `TRKORR` и создаёт минимальные записи.
+
+Parser делает `trim` строковых полей, но не декодирует бизнес-значения статуса/function и не проверяет их по справочнику SAP.
+
+Некорректный XML может привести к исключению parser-а. Функция не заменяет его пустым массивом: повреждённый ответ должен быть виден как ошибка.
+
+## Формат результата
+
+```ts
+interface UserTransport {
+	transportNo: string;
+	description: string | undefined;
+	owner: string | undefined;
+	targetSystem: string | undefined;
+	functionCode: string | undefined;
+	statusCode: string | undefined;
+	parentTransportNo: string | undefined;
+}
+```
+
+Соответствие XML:
+
+| XML | Поле | Значение |
+| --- | --- | --- |
+| `TRKORR` | `transportNo` | Обязательный номер transport |
+| `AS4TEXT` | `description` | Описание |
+| `AS4USER` | `owner` | Владелец |
+| `TARSYSTEM` | `targetSystem` | Целевая система |
+| `TRFUNCTION` | `functionCode` | SAP transport function code |
+| `TRSTATUS` | `statusCode` | SAP status code |
+| `STRKORR` | `parentTransportNo` | Родительский request/task |
+
+Optional-поле может быть `undefined`. Проверяйте его перед отображением:
+
+```ts
+const label = transport.description
+	? `${transport.transportNo} — ${transport.description}`
+	: transport.transportNo;
+```
+
+## Как устроен ADT response
+
+ADT endpoint возвращает не OData JSON, а ABAP XML. Реальный документ обычно содержит namespace и несколько служебных обёрток:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+	<asx:values>
+		<DATA>
+			<CTS_REQ_HEADER>
+				<TRKORR>DEVK900001</TRKORR>
+				<AS4TEXT>Исправление отчёта</AS4TEXT>
+				<AS4USER>IVANOV</AS4USER>
+				<TARSYSTEM>QAS</TARSYSTEM>
+				<TRFUNCTION>K</TRFUNCTION>
+				<TRSTATUS>D</TRSTATUS>
+				<STRKORR>DEVK900000</STRKORR>
+			</CTS_REQ_HEADER>
+		</DATA>
+	</asx:values>
+</asx:abap>
+```
+
+Parser намеренно не зависит от точного положения `CTS_REQ_HEADER`: он рекурсивно обходит objects и arrays. Поэтому дополнительная server wrapper-структура не ломает parsing, пока имена полезных tags остаются прежними.
+
+### Request parameters endpoint
+
+```text
+_action=FIND
+trfunction=K
+```
+
+Они зафиксированы внутри `fetchUserTransports`. Consumer не может изменить owner, function, status или paging через options. Если нужен другой ADT query, создайте отдельный API у владельца package, а не подменяйте поведение этой функции string manipulation-ом.
+
+### Почему используется общий SAP transport
+
+Хотя response не OData, `fetchUserTransports` использует `fetchBase` из `/odata`, потому что ему нужны те же infrastructure concerns:
+
+- cookies текущей SAP session;
+- `sap-language` и configured `sap-client`;
+- manual redirect detection;
+- automatic SSO recovery;
+- единая HTTP error policy.
+
+Base URL передаётся как пустая строка, потому что path уже начинается с `/sap/bc/adt`.
+
+## Подробный алгоритм parser-а
+
+### 1. Пустой документ
+
+```ts
+parseUserTransportsXml("");
+// []
+
+parseUserTransportsXml("   \n\t");
+// []
+```
+
+Whitespace-only input не отправляется в XML parser.
+
+### 2. XML остаётся строковым
+
+`fast-xml-parser` настроен с `parseTagValue: false`. Значения вроде `0001`, `D` или transport number не превращаются автоматически в numbers/booleans.
+
+Это важно:
+
+```xml
+<TRKORR>DEVK900001</TRKORR>
+```
+
+должен остаться exact identifier, а не пройти numeric coercion.
+
+### 3. Поиск всех headers
+
+Parser собирает каждый nested value по key `CTS_REQ_HEADER`. Один XML parser может представить:
+
+- один header как object;
+- несколько соседних headers как array;
+- headers внутри дополнительных wrappers.
+
+Оба случая нормализуются к одному массиву.
+
+### 4. Runtime narrowing
+
+Любой найденный value сначала проверяется как record. Primitive/null не превращаются в transport.
+
+### 5. Нормализация text
+
+Все SAP fields проходят text normalization:
+
+```text
+"  DEVK900001  " -> "DEVK900001"
+"   "            -> undefined
+null             -> undefined
+```
+
+Запись без `transportNo` отбрасывается полностью.
+
+### 6. Дедупликация
+
+```ts
+parseUserTransportsXml(`
+<root>
+	<CTS_REQ_HEADER>
+		<TRKORR>DEVK900001</TRKORR>
+		<AS4TEXT>Первое описание</AS4TEXT>
+	</CTS_REQ_HEADER>
+	<CTS_REQ_HEADER>
+		<TRKORR>DEVK900001</TRKORR>
+		<AS4TEXT>Второе описание</AS4TEXT>
+	</CTS_REQ_HEADER>
+</root>
+`);
+```
+
+Вернёт первую запись. Parser не объединяет optional fields дубликатов.
+
+### 7. Fallback без `CTS_REQ_HEADER`
+
+Некоторые responses содержат только nested `TRKORR`. Тогда parser формирует минимальные records:
+
+```ts
+parseUserTransportsXml(`
+<root>
+	<RESULT><TRKORR>DEVK900003</TRKORR></RESULT>
+	<RESULT><TRKORR>DEVK900004</TRKORR></RESULT>
+</root>
+`);
+```
+
+```ts
+[
+	{
+		transportNo: "DEVK900003",
+		description: undefined,
+		owner: undefined,
+		targetSystem: undefined,
+		functionCode: undefined,
+		statusCode: undefined,
+		parentTransportNo: undefined
+	},
+	// ...
+]
+```
+
+Fallback включается только если ни одного корректного header record не найдено.
+
+## Использование с TanStack Query
+
+Модуль не навязывает query key/stale policy. Их определяет feature:
+
+```tsx
+import { queryOptions, useQuery } from "@tanstack/react-query";
+import { fetchUserTransports } from "@ryuzaki13/react-foundation-api/adt";
+
+const adtTransportKeys = {
+	all: ["adt-transports"] as const,
+	list: () => [...adtTransportKeys.all, "list"] as const
+};
+
+export const adtTransportsQueryOptions = () =>
+	queryOptions({
+		queryKey: adtTransportKeys.list(),
+		queryFn: fetchUserTransports,
+		staleTime: 5 * 60 * 1000
+	});
+
+function TransportSelect() {
+	const query = useQuery(adtTransportsQueryOptions());
+
+	if (query.isPending) return <p>Загрузка транспортов…</p>;
+	if (query.isError) return <p>{query.error.message}</p>;
+	if (query.data.length === 0) return <p>Доступных транспортов нет</p>;
+
+	return (
+		<select>
+			{query.data.map((item) => (
+				<option key={item.transportNo} value={item.transportNo}>
+					{item.transportNo}
+					{item.description ? ` — ${item.description}` : ""}
+				</option>
+			))}
+		</select>
+	);
+}
+```
+
+`fetchUserTransports` не принимает `AbortSignal`, поэтому query cancellation не прерывает underlying fetch через этот API. Не обещайте UI мгновенный transport abort. Если это станет обязательным, контракт должен быть расширен в package.
+
+Query key не должен содержать user secrets. Если список зависит от logged-in user, смена user/session должна сопровождаться очисткой auth-sensitive Query cache на project boundary.
+
+## Parent request и task
+
+`parentTransportNo` обычно помогает отличить task от верхнеуровневого request:
+
+```ts
+function getTransportLabel(transport: UserTransport) {
+	const kind = transport.parentTransportNo ? "Задача" : "Запрос";
+	return `${kind}: ${transport.transportNo}`;
+}
+```
+
+Это только presentation inference. Модуль не интерпретирует SAP status/function codes и не гарантирует бизнес-классификацию. Для правил конкретной системы используйте domain mapping приложения.
+
+## Тестирование
+
+Parser — pure function, поэтому тестируйте fixtures без network:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { parseUserTransportsXml } from "@ryuzaki13/react-foundation-api/adt";
+
+it("сохраняет leading zeros и optional fields", () => {
+	const result = parseUserTransportsXml(`
+		<root>
+			<CTS_REQ_HEADER>
+				<TRKORR>DEVK900001</TRKORR>
+				<TRSTATUS>D</TRSTATUS>
+			</CTS_REQ_HEADER>
+		</root>
+	`);
+
+	expect(result).toEqual([
+		{
+			transportNo: "DEVK900001",
+			description: undefined,
+			owner: undefined,
+			targetSystem: undefined,
+			functionCode: undefined,
+			statusCode: "D",
+			parentTransportNo: undefined
+		}
+	]);
+});
+```
+
+Минимальный набор cases:
+
+- single header;
+- array headers;
+- nested wrappers/namespaces;
+- duplicate number;
+- whitespace fields;
+- empty XML;
+- fallback `TRKORR`;
+- malformed XML и ожидаемая ошибка.
+
+Для transport integration mock-айте `fetch`/MSW и проверяйте Content-Type `text/html`, XML body и HTTP error. Не используйте real SAP credentials в tests.
+
+## Частые ошибки
+
+### Использовать поля `function` и `status`
+
+Правильные имена public contract — `functionCode` и `statusCode`.
+
+### Считать status code готовым label
+
+`"D"` остаётся строкой `"D"`. Расшифровка зависит от SAP contract проекта и не выполняется package-ом.
+
+### Принимать пустой array за любую ошибку
+
+Пустой или whitespace XML даёт `[]`, но HTTP, HTML и malformed XML errors выбрасываются. Обрабатывайте error отдельно от empty state.
+
+### Объединять ADT и UI2 records без mapper-а
+
+`/adt` и `/transport` имеют разные source contracts. Если feature показывает их вместе, создайте явную domain model и collision policy.
+
+### Deep import parser-а
+
+Используйте только:
+
+```ts
+import { parseUserTransportsXml } from "@ryuzaki13/react-foundation-api/adt";
+```
+
+## Ошибки и ограничения
+
+- `fast-xml-parser` должен быть установлен в host, использующем этот entrypoint.
+- Это не generic ADT client: endpoint и query parameters зафиксированы.
+- Функция не создаёт/не освобождает transport и не проверяет authorization.
+- SSO/cookies требуют browser/proxy окружения SAP. На server runtime поведение зависит от переданного глобального `fetch` и cookie boundary.
+- HTML-response, HTTP error и XML parse error не превращаются в `[]`.
+- Дедупликация выполняется только по `transportNo` и сохраняет первую найденную запись.
+
+## FAQ
+
+### Можно ли передать другой endpoint?
+
+Нет. `fetchUserTransports` — конкретный ADT use case с фиксированным endpoint.
+
+### Можно ли получить только transports конкретного owner?
+
+Не через текущий public API. Фильтруйте result локально либо расширьте package contract, если server-side filter является общей потребностью.
+
+### Parser меняет исходную XML string?
+
+Нет. Он создаёт новые JS objects.
+
+### Почему optional fields явно содержат `undefined`?
+
+Таков стабильный `UserTransport` shape. Consumer может безопасно destructure поля без проверки их наличия как properties.
+
+### Работает ли в Node?
+
+Pure parser работает при наличии `fast-xml-parser`. Network function зависит от общего SAP transport, URL/cookies/build constants и в первую очередь рассчитана на browser application.
+
+## Полный API
+
+| Export | Назначение |
+| --- | --- |
+| `fetchUserTransports` | Загружает и разбирает ADT XML |
+| `parseUserTransportsXml` | Преобразует XML string в массив |
+| `UserTransport` | Контракт результата |