116 lines
6.7 KiB
Markdown
116 lines
6.7 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
|
|
(`my429480.s4hana.cloud.sap` productive; development tenant `my431353.s4hana.cloud.sap` since 2026-09-15 — API-only tenants: no RFC, no custom IDocs):
|
|
materials, BOMs, change masters, documents. 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-002, 2026-09-04 — on-stack first)
|
|
|
|
The application lives **in the tenant**: a custom RAP business object for the
|
|
approval domain, a Fiori Elements app in the tenant's Fiori launchpad, IAM
|
|
app / business catalog / business roles as the only access control, and custom
|
|
CDS views for discoverability. Side-by-side is reduced to one hardened
|
|
TypeScript **connectivity worker** (Arena webhook/poll/session/files + initial
|
|
sync executor) — machine-to-machine only, no UI, no user-facing URLs.
|
|
|
|
The acceptance test: a business user finds the app in the Fiori launchpad and
|
|
its data in the Custom CDS Views app. Anything that fails that test is not done.
|
|
|
|
## 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 development tenant (create/activate/transport/ATC/unit tests) | `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 (verified 2026-09-15): the `sap-api` CLI
|
|
(`/usr/local/bin/sap-api`) reaches the **development** tenant `my431353` by
|
|
default (credentials in `~/projects/sap-integrations/_shared/.env`; the
|
|
productive credential is `.env.prod-my429480.bak`) 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.
|
|
|
|
## 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 | `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-14)
|
|
|
|
Implementation so far: the TypeScript connectivity worker in `worker/`
|
|
(Fastify surface + Arena session core; sync executors are stubs until V-2).
|
|
The on-stack RAP track has no code yet — gated on V-1. The Fiori Elements app
|
|
(`app/`, TypeScript) is scaffolded against a **mock** OData V4 service:
|
|
`npm run start-mock` serves it on port 8082; its service identity is
|
|
provisional until reconciled with the live RAP UI binding at V-2.
|
|
|
|
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-001 amended by ADR-002) |
|
|
| `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 |
|