188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
# KNOWLEDGE — tombstones & landmines
|
||
|
||
Carried across the 2026-09-04 knowledge bankruptcy from the working Express
|
||
predecessor. Filter applied: an item was kept only if it (a) cannot be
|
||
re-derived from code or a live query, AND (b) is expensive or harmful to
|
||
re-learn. Everything else was deliberately left behind to be re-derived from
|
||
ground truth. Every entry is dated; re-verify on first POC contact. Add new
|
||
entries the same way — dated and falsifiable.
|
||
|
||
## SAP S/4HANA (tenant `my429480`, Public Cloud, API-only)
|
||
|
||
- [2026-09-04, verified by predecessor in live use] **BOM items must be POSTed
|
||
sequentially** after the header POST. Parallel item POSTs fail SAP's
|
||
consistency check.
|
||
- [2026-09-04, same] **`AvailabilityCheckType` is not exposed in the Product
|
||
API V4** — requires the V2 `API_PRODUCT_SRV` fallback for that one field.
|
||
- [2026-09-04, same] **BOM read works only on the v1 service**;
|
||
`API_BILL_OF_MATERIAL_SRV;v=0002` rejects guid key lookups. Writes go to
|
||
`;v=0002`.
|
||
- [2026-09-04, same] OData V2 date format is `/Date(ms)/`; the "end of time"
|
||
value (9999-12-31) is `/Date(253402214400000)/`.
|
||
- [2026-09-04, same] **Idempotency pattern that works: SAP is the ledger.** The
|
||
Arena ECO number is stamped into `ReasonForChangeText`; no local sync-state
|
||
database is needed or wanted.
|
||
- [2026-09-10, predecessor code read] **BOM header create must use
|
||
`EngineeringChangeDocForEdit`** — `EngineeringChangeDocument` is
|
||
`sap:creatable=false` and silently dropped. ECM BOM items must carry
|
||
`HeaderChangeDocument` = the header's change number or SAP answers "Input
|
||
parameters are initial". (arena-plm.js:785-846)
|
||
- [2026-09-10, same] **`A_ChangeMasterObjTypeAssgmt` POST requires
|
||
`IsActiveForChangeNumber: true`** — without it SAP returns 201 and silently
|
||
discards the row. (arena-plm.js:914-924)
|
||
- [2026-09-10, same] **ProductDescription updates: PATCH by full key**
|
||
(`Product=…,Language='EN'`); PATCH via the nav property returns HTTP 501;
|
||
fall back to POST on 404/405. (arena-plm.js:1411-1414)
|
||
- [2026-09-10, same] `ProcurementType` can only be written together with
|
||
`MRPType` in the same `ProductPlantSupplyPlanning` PATCH.
|
||
(arena-plm.js:1623-1640)
|
||
|
||
## Arena PLM API (`api.arenasolutions.com/v1`)
|
||
|
||
- [2026-09-04, same] Session auth: `POST /login` → `arenaSessionId`, ~25-minute
|
||
TTL. Concurrent logins race — serialize login behind a promise lock and
|
||
re-login automatically on 401.
|
||
- [2026-09-10, predecessor code read] **WORKING-revision overlay is
|
||
load-bearing**: the seven SAP classification attributes (SAP Product Type,
|
||
SAP Plant, …) are writable only on the WORKING revision (Arena error 3224),
|
||
while `/items?number=` resolves the EFFECTIVE revision — merge those
|
||
attributes from WORKING over EFFECTIVE, and treat overlay failure as fatal
|
||
(the predecessor's best-effort overlay silently turned valid items into
|
||
NO_PRODUCT_TYPE errors). (arena-plm.js:508-552)
|
||
- [2026-09-10, same] `/items/{guid}/changes` does not exist (404) — derive the
|
||
ECO from `/items/{guid}/revisions`, first EFFECTIVE revision with
|
||
`change.number`. (arena-plm.js:1799-1806)
|
||
- [2026-09-10, same] The `/changes` feed has **no working server-side date
|
||
filter** — delta detection must filter client-side (the predecessor pages
|
||
the whole feed, O(history)). The outbound-integration queue
|
||
(`/outboundintegrations/{guid}/events`, `reconciled` flag as a cursor held
|
||
by Arena) is the clean delta mechanism. (arena-plm.js:1117-1263)
|
||
|
||
## Toolchain (worker)
|
||
|
||
- [2026-09-10, npm registry] **TypeScript `latest` is the 7.x native-compiler
|
||
major** (no stable 6.x; only `6.0.0-beta`). typescript-eslint 8.70.0
|
||
declares peer `typescript >=4.8.4 <6.1.0`, silently forcing the 5.9.x line —
|
||
the worker pins `~5.9.3`. Falsifiable: recheck
|
||
`npm view typescript-eslint peerDependencies` before any TS bump.
|
||
- [2026-09-10, npm registry] **`@types/node` `latest` dist-tag points at
|
||
22.x** while 24.x/26.x lines exist — an unpinned install silently targets
|
||
Node 22 types. Pin the major (`^24`) to match the runtime.
|
||
|
||
## Landmines
|
||
|
||
- [2026-09-15] **abapGit is not a prerequisite for SAP's ADT for VS Code.** The
|
||
`sapse.adt-vscode` extension talks ADT/HTTP to the tenant and ships no git or
|
||
abapGit commands (extension 1.1.2 `package.json`/readme, verified 2026-09-15).
|
||
The "abapGit must be set up in the ABAP system" idea comes from the community
|
||
extension `murbani.vscode-abap-remote-fs` (installed on this host), whose
|
||
abapGit commands need the open-source `ZABAPGIT` report in the backend — which
|
||
cannot be installed in a Public Cloud tenant. In ABAP Cloud, abapGit exists
|
||
only as SAP's supported fork behind the **Eclipse** ADT plug-in
|
||
(`https://eclipse.abapgit.org/updatesite/`, "abapGit Repositories" view); no
|
||
VS Code variant exists [source: sap-docs sap-help loio
|
||
2002380aeda84875a5fae4adc66b3fdb; /btp-cloud-platform/30-development/
|
||
import-content-from-abapgit-repository-into-the-abap-environment-0b0d894;
|
||
https://github.com/abapGit/ADT_Frontend, verified 2026-09-15]. It imports
|
||
released object types only, from an internet-reachable repository (no Cloud
|
||
Connector), into a chosen package/transport.
|
||
|
||
- [2026-09-15] **ADT MCP `x-ui-service` generator quirks (my431353, ADT VS
|
||
Code 1.1.2):** every field needs `semanticType` (else "Builtin type of
|
||
field is invalid"); it prepends its own `Z` to your prefix and appends
|
||
`000` even with an empty suffix (`Z` + `ARENA_CHANGE_APPROVAL` →
|
||
`ZZUI_ARENA_CHANGE_APPRVL000_O4`), names SRVD and SRVB identically, and
|
||
the schema's `required` lists a non-existent `businessEntity` key — omit
|
||
it. `get_schema` session ids are single-use. It returns only the SRVB URI;
|
||
other object URIs follow `abap:/repotree-v1/<dest>/System Library/ZLOCAL/<pkg>/…`
|
||
with extensions `.tabl.json`, `.ddls.acds`, `.bdef.json`, `.ddlx.acds`,
|
||
`.dcls.acds`, `.clas.abap`, `.srvd.acds`, `.srvb.json`, `.ront.json`,
|
||
`.nont.json`. `create_object` for SRVD needs `"sourceType":"S"`; BDEF and
|
||
SRVB creation validate the referenced object's ACTIVE version, so create
|
||
and activate DDLS/SRVD sources first. ATC via MCP rejects RONT/NONT.
|
||
|
||
- [2026-09-15] **Developer business catalogs: `SAP_A4C_BC_*` is the Public
|
||
Cloud / BTP ABAP family; `SAP_A4_BC_*` is on-premise / Private Cloud.** On
|
||
`my431353` the developer role carries the A4C catalogs (e.g.
|
||
`SAP_A4C_BC_DEV_OBJ_DIS_PC`, `SAP_A4C_BC_DEV_UID_PC` [source: sap-docs
|
||
sap-help loio f4881a9b9141430dba1c6a76e7f456dc, verified 2026-09-15]); the
|
||
`SAP_A4_BC_DEV_UID_PC` name in the fiori-tools-samples README is the wrong
|
||
family for this tenant. Split stated by the tenant owner 2026-09-15; no SAP
|
||
Help page in the loadout spells it out — do not "fix" a role toward A4.
|
||
- [2026-09-15] **Write probes on the dev tenant: `$TMP` and `ZLOCAL` both
|
||
fail, for different reasons.** `$TMP` is a classic package, so creating
|
||
there checks the Standard ABAP language version and a cloud-development
|
||
role is denied with "not authorized to make changes (S_ABPLNGVS)"; `ZLOCAL`
|
||
is a structure package ("cannot contain development objects"). Objects go
|
||
in a sub-package of `ZLOCAL` (prototyping, no workbench request for
|
||
sub-packages created from release 2508) or of `ZCUSTOM_DEVELOPMENT`
|
||
(transport layer YDEV, importable into test/prod); ZLOCAL→ZCUSTOM
|
||
reassignment is allowed, the reverse is not; `ZLOCAL` plays the `$TMP` role
|
||
in Public Cloud [source: sap-docs sap-help loio
|
||
a0d80f14fcb74cb1ac8fb6f3d9ad48cc (2608), verified 2026-09-15]. Refusals
|
||
verified live via ADT MCP, 2026-09-15.
|
||
|
||
- [2026-09-14] `sap-released-objects` has no `DDLS` type for public_cloud;
|
||
CDS views are catalogued as `CDS_STOB`. A "not found" for `I_PRODUCT` under
|
||
`DDLS` is a type-key artefact, not a release verdict — query with
|
||
`object_type=CDS_STOB` (verified 2026-09-14).
|
||
- [2026-09-14] **A Fiori Elements app generated on hand-written mock metadata
|
||
agrees with itself and hides service-shape mismatches.** ABAP Cloud OData V4
|
||
services emit `Schema Namespace="com.sap.gateway.<srvd|srvd_a2x>.<service-binding-name>.v0001"
|
||
Alias="SAP__self"` — the name in the namespace is the **service binding
|
||
(group)**, which is also the first URL segment; the service definition /
|
||
alias is the second segment (`/api_currencyexchangerate/srvd_a2x/sap/currencyexchangerate/0001`
|
||
→ `…srvd_a2x.api_currencyexchangerate.v0001`; `/api_product/srvd_a2x/sap/product/0002`
|
||
[source: sap-docs sap-help loio 5f45f125dfe84c20beb18f5de1512f5a, verified
|
||
2026-09-14]). Shown for released A2X services; for custom UI (`srvd`)
|
||
bindings it is strongly indicated, not proven — V-2 confirms. Also, entity types suffixed `_Type`, un-suffixed entity sets,
|
||
and vocabulary aliases `SAP__common`/`SAP__capabilities`/`SAP__core`
|
||
[source: live tenant my429480 EDMX `~/projects/sap-apps/exchange-rates-cap/srv/external/API_CURRENCYEXCHANGERATE.edmx`
|
||
lines 13–31, 55, 57, 95, verified 2026-09-14]. Front-end annotation targets
|
||
written against any other namespace silently match nothing at runtime (no
|
||
columns, no filters, no actions). Reconcile every `Annotations Target`, the
|
||
`edmx:Reference` include namespace, and every `DataFieldForAction.Action`
|
||
against the live `$metadata` before the first deploy — never trust the mock.
|
||
|
||
- [2026-09-04] The predecessor's `config/procurement-type.json`,
|
||
`catalog-to-planning-strategy.json`, and `arena-category-to-sap.json` were
|
||
loaded but **never read by any code path**, and procurement-type's keys
|
||
(`MTS`/`OTS`) and values (`E`) do not match the Arena field (`1`–`9` Item
|
||
Type) or SAP values (`X`) the code actually used. Do not port these configs
|
||
on trust — re-derive every mapping via POC.
|
||
- [2026-09-04] Deployment/exposure target is an OPEN decision (PRD OQ-3). The
|
||
old estate fronts apps through a shared `mcl-apps` approuter with shared
|
||
XSUAA; a CF route mapped to more than one app round-robins and causes ~50%
|
||
intermittent 404s. Whatever is chosen, audit routes after every push.
|
||
- [2026-09-04] HANA Cloud compute is the dominant cost lever of the old estate;
|
||
an auto-stop systemd timer (`sap-apps/ops/hana-autostop`) guards it. If this
|
||
package binds HANA, account for the stop/start cycle in the design.
|
||
- [2026-09-04] The predecessor kept its approval queue in a SQLite file inside
|
||
the CF droplet — wiped on every restart. Durable persistence is a hard
|
||
requirement of the rebuild (PRD ARN-003), not an optimization.
|
||
- [2026-09-10] Predecessor BOM and DOCUMENTS syncs are **non-idempotent**
|
||
(re-approval creates a second MaterialBOM header / duplicate attachments) —
|
||
the rebuild's executors must check existence first (ARN-006).
|
||
- [2026-09-10] The predecessor uses **two disagreeing change-master lookup
|
||
keys** (`startswith(ChangeNumberDescription,'ECO:')` in the product link vs
|
||
`ReasonForChangeText eq 'ARENA <eco>'` everywhere else; the 40-char
|
||
truncation can split them). The rebuild uses exactly one key.
|
||
- [2026-09-10] Document sync links only Arena files with
|
||
`storageMethodName === 'WEB'` (URL links, no bytes) — blob-stored files are
|
||
silently skipped, and the DOKAR mapping config existed but was ignored
|
||
(`BUS1001006`/`text/url` hardcoded). Decide blob handling explicitly in the
|
||
rebuild.
|
||
- [2026-09-04] **If `.github/agents/sap-odata-*.agent.md`, a root `AGENTS.md`
|
||
about "SAP OData Workspace", or `.vscode/mcp.json` pointing at
|
||
`sap-odata-mcp.exe` appear in this repo — delete them.** They are scaffolded
|
||
(evidence points to the `harieprasad.sap-odata-mcp` VS Code extension writing
|
||
its workspace kit on folder open; observed 2026-09-04 14:40, removed same
|
||
day). The referenced MCP binary is a Windows .exe that cannot run on this
|
||
host, so those agents fabricate SAP results — the documented failure the
|
||
founding kit exists to prevent. The root `AGENTS.md` is the dangerous part:
|
||
Claude Code reads it as project instructions. [Update 2026-09-04 15:32] The
|
||
suspect extension was uninstalled from all machines (verified: deregistered
|
||
and marked obsolete on this host; directory purges on next VS Code reload).
|
||
If the bundle STILL reappears after this, the extension hypothesis was wrong
|
||
— hunt the real writer instead of re-deleting silently.
|