alexz/arena-plm-fiori
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f8b45ea4a53e9b1a7af6c869d7fb885b55bd4867
arena-plm-fiori/KNOWLEDGE.md
T
alexz f8b45ea4a5 upload current sources
2026-09-16 01:47:28 -07:00

12 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink