alexzandClaude Opus 5
ffd33f4ec0
Both tenants belong to the same starter system: my429480 is its customizing tenant (client 100, key-user extensibility only, no ABAP) and my431353 is its development tenant (client 080). This package had recorded my429480 as "productive" and ADR-002 had assumed it offered developer extensibility; both were wrong. - ADR-004 withdraws the on-stack RAP route and moves the application to a side-by-side runtime against released OData APIs. ADR-002 marked superseded. - Development tenant my431353 parked: all 19 ZARENA_PLM objects left active, sources kept in docs/handover/rap/ as reference, so the route stays reversible. - Replacement host left open as OQ-11 (key-user extensibility vs CAP side-by-side); recommendation recorded as CAP. No build starts until OQ-11 is closed. - RAP-dependent items V-2, V-3, OQ-5, OQ-8, OQ-9, OQ-10 parked rather than closed. - Tenant references corrected across CLAUDE.md, KNOWLEDGE.md, app/README.md, the RAP handover README, the rap-developer agent and the reentrance-login helper README. No SAP tenant was modified. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
154 lines
8.9 KiB
Markdown
154 lines
8.9 KiB
Markdown
# arena-plm — Arena PLM → SAP S/4HANA Integration (standalone)
|
|
|
|
> This file is a MAP, not a cache. It says where things are and how to verify
|
|
> them — it does not store conclusions. Every factual claim in this repo carries
|
|
> a verified-on date; an undated claim is a hypothesis, not a fact.
|
|
|
|
## What this is
|
|
|
|
Approval-gated sync of Arena PLM items into SAP S/4HANA Public Cloud:
|
|
materials, BOMs, change masters, documents.
|
|
|
|
Both tenants named in this repo belong to the **same starter system**. The
|
|
working target is the starter system's **customizing tenant**
|
|
`my429480.s4hana.cloud.sap` (client 100 — key-user extensibility and
|
|
configuration only; no ABAP, no RAP). The starter system's **development
|
|
tenant** `my431353.s4hana.cloud.sap` (client 080 — developer extensibility) is
|
|
**parked as of 2026-09-29**, with the objects I built there left in place. Both
|
|
tenants are API-only: no RFC, no custom IDocs.
|
|
|
|
Standalone successor to the Express
|
|
implementation at `~/projects/sap-apps/arena-plm`, which is **reference-only**
|
|
— consult it for behavior, never extend it.
|
|
|
|
## Architecture (ADR-004, 2026-09-29 — side-by-side against released APIs)
|
|
|
|
The on-stack RAP route of ADR-002 is **withdrawn and superseded**. The starter
|
|
system's customizing tenant `my429480` (client 100) supports key-user
|
|
extensibility only — no ABAP, no RAP — so the custom RAP business object ADR-002
|
|
called for has no home in the tenant I work in.
|
|
|
|
The application therefore runs **side-by-side against released OData APIs**,
|
|
with the customizing tenant as the sync target and configuration home. The
|
|
replacement host is deliberately left **open as OQ-11**: key-user extensibility
|
|
in the customizing tenant (custom business object plus a low-code UI) versus a
|
|
CAP service side-by-side on BTP. My recommendation is **CAP** — the
|
|
connectivity worker has to live side-by-side whatever else happens, and one
|
|
runtime beats two. **No build starts until OQ-11 is closed.**
|
|
|
|
Kept, unchanged in value: the hardened TypeScript **connectivity worker**
|
|
(Arena webhook/poll/session/files + initial sync executor) — machine-to-machine
|
|
only, no UI, no user-facing URLs, and needed under either OQ-11 option — and
|
|
the Fiori Elements app in `app/`, which is repointable.
|
|
|
|
**Parked reference, not deleted:** the RAP approval business object I built on
|
|
the starter system's development tenant `my431353` (client 080). All 19
|
|
`ZARENA_PLM` objects are left active there and their sources stay in
|
|
`docs/handover/rap/`, so that route stays reversible at zero cost.
|
|
|
|
The acceptance test, as amended by ADR-004: a business user finds the
|
|
application from the S/4HANA launchpad and access is governed by business
|
|
roles. The "its data in the Custom CDS Views app" clause is withdrawn — it is
|
|
unreachable from client 100.
|
|
|
|
## Operating rules
|
|
|
|
1. **Never guess SAP behavior.** Query the MCP servers below first — do not
|
|
first decide whether the question "needs" a lookup; that judgment is the
|
|
thing that fails. If no source confirms it, say "I don't know."
|
|
2. **POC before spec.** Field mappings and integration specs are unusable until
|
|
validated by a working POC against real endpoints.
|
|
3. **No hand-rolled SAP plumbing.** On-stack: RAP/EML and released ABAP APIs
|
|
only. In the worker: released OData APIs through the established destination
|
|
(`mc-s4hana`) — never hand-managed CSRF or auth.
|
|
4. **Mappings live in the tenant.** Evaluate Business Configuration
|
|
maintenance objects before any file-based config (PRD ARN-004).
|
|
5. **Read `KNOWLEDGE.md` before designing any SAP write path.** It holds
|
|
paid-for negative results; re-learning them costs hours against live systems.
|
|
6. **Cite or it didn't happen.** Every SAP behavioral claim recorded in
|
|
PRD/ADR/KNOWLEDGE carries `[source: <server> <doc-id/URL>, verified
|
|
YYYY-MM-DD]`. Enforcement is structural (ADR-003): hooks inject this charter
|
|
each session, and a consultation gate denies edits to SAP artifacts unless an
|
|
MCP/web consultation happened in the last 30 minutes. (`*.md`, `docs/`, and
|
|
`.claude/` paths are exempt; a denial names the server to consult — consult
|
|
it, then retry the edit.)
|
|
7. **API-first (adopted 2026-09-10, PRD ARN-009).** Any interface this package
|
|
creates or changes gets its OpenAPI 3.1 **JSON** contract authored or
|
|
updated under `docs/api/` before or with the change; implementation
|
|
conforms to the contract. Consumed SAP released APIs keep SAP's published
|
|
contracts — `docs/api/` holds only surfaces this package owns.
|
|
|
|
## MCP routing (this package's loadout — deliberately slim, matched to ADR-002)
|
|
|
|
| Working on | Server |
|
|
|---|---|
|
|
| ABAP Cloud / RAP / CDS statement syntax & semantics | `abap-docs` |
|
|
| RAP guides, extensibility docs, SAP Help / Community | `sap-docs` |
|
|
| Is this SAP object released for ABAP Cloud? Successors? | `sap-released-objects` |
|
|
| Fiori Elements, `@UI` annotations, manifest | `fiori-mcp-server` |
|
|
| Writing objects INTO the starter system's development tenant (create/activate/transport/ATC/unit tests) — **parked 2026-09-29 with that tenant** | `adt-mcp` — SAP ADT MCP Server from `sapse.adt-vscode`, `http://127.0.0.1:2236/mcp`; bearer token lives in `~/.vscode-server/data/Machine/settings.json` and changes on VS Code reload — refresh `.mcp.json` then |
|
|
| UI5 controls/views (only if custom UI proves necessary) | `ui5-mcp-server` |
|
|
|
|
When MCP guidance conflicts with training knowledge, follow MCP.
|
|
|
|
Live system checks from this box: as of 2026-09-29 the `sap-api` CLI
|
|
(`/usr/local/bin/sap-api`) reaches the starter system's **customizing tenant**
|
|
`my429480` by default (credentials in
|
|
`~/projects/sap-integrations/_shared/.env`; the parked development-tenant
|
|
credential is `.env.starter-dev-my431353.bak` and the customizing-tenant copy is
|
|
`.env.starter-cust-my429480.bak`, both in the same folder) and Arena — API catalog search,
|
|
EDMX fetch, OpenAPI generation (`sap-api apis generateOpenapi --service …`),
|
|
communication arrangements (`comm`), user/role admin (`users`), and read paths
|
|
for the released business APIs and Arena items. Read commands are fair game
|
|
for design and acceptance; mutating commands are delegated like any other
|
|
write. The retarget is in place, but the `my429480` credential itself answered
|
|
HTTP 401 ("Anmeldung fehlgeschlagen") on 2026-09-29 — it needs refreshing before
|
|
any CLI call against that tenant succeeds.
|
|
|
|
## Delegation (project agents in `.claude/agents/`)
|
|
|
|
Implementation goes to the specialists below; their tool restrictions are the
|
|
role contract (the reviewer cannot write, the test agent runs on the low-cost
|
|
model). All inherit the ADR-003 hooks automatically. Design record and
|
|
verified sources: `docs/agent-roster.md`.
|
|
|
|
| Work | Agent |
|
|
|---|---|
|
|
| On-stack ABAP Cloud: RAP BO, CDS, behavior, IAM artifacts — **dormant** while the RAP route is parked (ADR-004) | `rap-developer` |
|
|
| Fiori Elements app, `@UI` annotations, manifest, launchpad | `fiori-developer` |
|
|
| TS connectivity worker: Arena API, Cloud SDK OData writes | `worker-developer` |
|
|
| Read-only SAP review: clean core, contracts, tombstones | `sap-code-reviewer` |
|
|
| Tests for worker + service layers | `test-engineer` |
|
|
|
|
## Repo state & commands (verified 2026-09-29)
|
|
|
|
Nothing in this package has ever been deployed or reached a business user, and
|
|
no build resumes until OQ-11 is closed. What exists:
|
|
|
|
- `worker/` — the TypeScript connectivity worker (Fastify surface + Arena
|
|
session core; sync executors are stubs). Built, 137 tests green, never
|
|
deployed. Needed under either OQ-11 option.
|
|
- `app/` — the Fiori Elements app (TypeScript), bound to a **mock** OData V4
|
|
service: `npm run start-mock` serves it on port 8082. Its service identity is
|
|
provisional; it gets repointed once OQ-11 names the host.
|
|
- `docs/handover/rap/` — the sources for the 19 `ZARENA_PLM` objects I
|
|
activated on the starter system's development tenant `my431353`, parked
|
|
2026-09-29 with the objects left in place. Reference and a reversible route,
|
|
not a live track.
|
|
|
|
In `worker/`: `npm run build` (tsc), `npm run lint` (eslint), `npm test`
|
|
(vitest), `npm run dev` (tsx watch). The worker's HTTP surface is governed by
|
|
`docs/api/worker.openapi.json` (rule 7) — change the contract first.
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `PRD.md` | Living requirements, target architecture, contracts, verification items |
|
|
| `CHANGELOG.md` | Append-only decision log |
|
|
| `KNOWLEDGE.md` | Dated tombstones & landmines — the only knowledge carried from the predecessor; also check it when anything unexpected appears in the repo |
|
|
| `docs/adr/` | Architecture decision records (ADR-004 supersedes ADR-002 and partly revives ADR-001) |
|
|
| `docs/agent-roster.md` | Specialist-agent design + verified sources |
|
|
| `docs/predecessor-flow.md` | How the Express predecessor actually works (extracted 2026-09-10) — read before designing executor, poller, or approval behavior |
|
|
| `.claude/hooks/` | ADR-003 enforcement scripts (grounding injections, consult gate, consult marker); `tests/run.sh` pipe-tests them — run it after any hook change |
|