# Specialist Report — agent-feature (AssetType↔SystemType mappings + Asset `systemId`)

Spec: `docs/specs/20260715-154549-agent-feature.md` — status set to `done`.

## What was implemented

Four new API2 endpoints for AssetType↔SystemType mappings, plus a derived
scalar `systemId` on both Asset GET endpoints.

- `POST   /api/v2/projects/{projectId}/asset-types/system-type-mappings`
- `GET    /api/v2/projects/{projectId}/asset-types/system-type-mappings`
- `GET    /api/v2/projects/{projectId}/asset-types/system-type-mappings/{mappingId}`
- `DELETE /api/v2/projects/{projectId}/asset-types/system-type-mappings/{mappingId}`
- `GET    /api/v2/projects/{projectId}/assets/{assetId}` → now returns `systemId`
- `GET    /api/v2/projects/{projectId}/assets` → each record now returns `systemId`

All wiring follows the existing routes → controller → validator → service
layering, mirroring the sibling `system-types` and `assets` resources.

## Files changed

New (production):
- `src/api/v2/projects/assettypes/systemtypemappings/asset.type.systemtype.mappings.routes.ts` — router + swagger JSDoc for the 4 endpoints.
- `src/api/v2/projects/assettypes/systemtypemappings/asset.type.systemtype.mappings.controller.ts` — list/get/create/delete handlers.
- `src/api/v2/projects/assettypes/systemtypemappings/asset.type.systemtype.mappings.validator.ts` — projectId/mappingId/body validation.
- `src/services/asset.type.systemtype.mappings.service.ts` — DB access + `getAssetTypeToSystemTypeMap` helper.

Modified (production):
- `src/api/v2/api.v2.routes.ts` — mounted the mappings router **before** the asset-types router.
- `src/services/assets.service.ts` — added optional `systemId` to `Asset`; populate it in `getAssetById` and `listAssets`.
- `src/swagger.components.schemas.json` — added `AssetTypeSystemTypeMapping` schema; added nullable `systemId` to `Asset`.

Tests:
- `test/unit/api/v2/assetTypeSystemTypeMappings/asset.type.systemtype.mappings.controller.spec.ts` — controller 200/201/204/400→404/409/500 paths.
- `test/unit/services/asset.type.systemtype.mappings.service.spec.ts` — row mapping, NotFound, 409 conflict, delete-guard, map builder.
- `test/unit/services/assets.service.spec.ts` — `systemId` derivation (mapped + null) for get and list.
- `test/e2e/api/asset.type.systemtype.mappings.e2e.spec.ts` — full CRUD + validation + not-found paths.
- `test/e2e/api/assets.e2e.spec.ts` — extended with a `systemId` derivation block (mapped / unmapped / list).
- `test/e2e/util/db-helper.ts` — added `getAssetTypeSystemTypeMappingById` / `...ByProject` for e2e verification.

## Acceptance criteria

- [x] Behavior implemented on the listed surfaces.
- [x] Existing behavior unchanged when the feature is not exercised (`systemId` is
      read-only/optional; POST/PATCH asset responses untouched; mappings router
      mounted so it cannot shadow existing asset-type routes).
- [x] Unit + e2e tests cover the new behavior.

## Commands run

- `npx tsc --noEmit` — **skipped**: dependencies are not installed in this
  environment (`node_modules` absent, no local `tsc`). Per task instructions the
  toolchain was not installed; the pipeline runs the suite afterward.
- Unit / e2e tests — **not run** for the same reason.
- Manual verification done: swagger JSON parses; all relative import targets
  resolve; import depths checked against the sibling (one-level-shallower)
  asset-types router.

## Deviations from the spec

1. **`egress.ts` not modified.** The spec's `files:` list includes
   `src/models/egress.ts`, but this repo keeps Asset/mapping DTOs in their
   service files (`SystemType` in `system.types.service.ts`, `Asset` in
   `assets.service.ts`). I followed that convention instead of adding a stray
   DTO to `egress.ts`.
2. **`src/services/asset.service.ts` (singular)** in the spec does not exist; the
   real file is `src/services/assets.service.ts`, which is what I edited.

## Open questions for the human reviewer

1. **Field name `systemId` vs `systemTypeId`.** The spec calls the new Asset
   field `systemId` but derives it from the AssetType→SystemType mapping, whose
   target is a SystemType. I returned the mapping's `SystemTypeId` under the key
   `systemId` exactly as written. Confirm the field name is intended (vs.
   `systemTypeId`), since it affects the public API contract.
2. **DB function/column names.** No SQL for the mapping lives in this repo, so I
   assumed the sibling naming convention (`fn_GetAssetTypeSystemTypeMappingList`,
   `fn_GetAssetTypeSystemTypeMapping`, `fn_InsertAssetTypeSystemTypeMapping`,
   `usp_DeleteAssetTypeSystemTypeMapping`) and PK column
   `AssetTypeSystemTypeMappingId`. Please confirm these match the actual DB
   objects; if not, only the `SQL`/`mapRow` in the mappings service need editing.
3. **List pagination.** The mappings `GET` list returns a plain array (like
   `system-types`) rather than a paginated envelope (like `assets`). Confirm
   which shape is desired.
4. **Uniqueness / 409.** I map a unique-constraint violation containing
   `AssetTypeSystemTypeMapping` to a 409 (one mapping per asset type). Confirm
   the intended uniqueness rule and constraint name.