# Auction API / Socket Audit Report

Date: 2026-08-02  
**Final classification: READY AFTER MANUAL QA**

Not “100% verified”: authenticated staging lifecycle (provider create → approve → live bid → finalize → winner pay → Order) was **not** executed here.

---

## 1–3. Test results

| Run | Command | Result |
|---|---|---|
| Baseline | `npm test` | **892** · **891** pass · **1** fail |
| Similar Ads fix | `node --test test/productDetailsSimilarAds.test.js` | **5/5** |
| Concurrency | `AUCTION_CONCURRENCY_DB=auction_concurrency_test node --test test/auctionBidConcurrency.integration.test.js` | **4/4** · ~11.3s |
| All `auction*.test.js` (incl. concurrency) | same env | **77/77** |
| Targeted catalog/socket/swagger/postman/similar | | **87/87** |
| Final | `npm test` | **902** · **902** pass · **0** fail |

### Mongo concurrency evidence
- MongoDB **8.0.28**
- Topology **replicaSet:atlas-10sf5u-shard-0**
- Database **`auction_concurrency_test`** (isolated; not app DB)
- Transactions supported
- Scenarios: concurrent stale race · idempotent replay · anti-sniping/maxExtensions · post-end reject

---

## 4. Canonical API inventory

**Customer/public**
- `GET /auctions` · `GET /auctions?auctionId=`
- `GET /auctions/bids` · `GET /auctions/similar`
- `POST|DELETE /auctions/favourite`
- `POST /auctions/report` · `POST /conversations/auction`
- `GET /auctions/deposit-status` · `POST /auctions/deposit`
- `GET /auctions/my-result` · `POST /auctions/winner-payment`

**Provider**
- `GET|POST|PATCH /provider/auctions`
- `POST /provider/auctions/submit|cancel`
- `POST /provider/auctions/price-suggestion?productId=`

**Socket (only)**
- client: `auction:enter|leave|bid`
- server: `auction:bid-updated|extended|ended`
- No `POST /place-bid`

---

## 5–6. Legacy cleanup matrix (Endpoint | Duplicate? | Replacement | Active dependency | Decision | Evidence)

| Endpoint | Duplicate? | Replacement | Active dependency | Decision | Evidence |
|---|---|---|---|---|---|
| `GET /list-auctions` | Yes | `GET /auctions` | None in repo | **REMOVE** | Route absent; OpenAPI absent |
| `GET /auction-details` | Yes | `GET /auctions?auctionId=` | Was push deep-link | **REMOVE** | Push → `/auctions`; route removed |
| `GET /auction-bids` | Yes | `GET /auctions/bids` | None | **REMOVE** | BidRoute no longer registers it |
| `GET /bids-list` | Yes | `GET /auctions/bids` | Admin DOM id only | **REMOVE** | Route absent |
| `POST /create-product-auction` | Yes | `POST /provider/auctions` | Docs/QA only | **REMOVE** | Route absent |
| `POST /pay-auction-deposit` | Yes | `POST /auctions/deposit` | Docs/QA only | **REMOVE** | Same service via catalog |
| `PATCH /pay-auction` | Yes | `POST /auctions/winner-payment` | Docs/QA only | **REMOVE** | Catalog → `payAuction` |
| `PATCH /update-auction` | Yes | `PATCH /provider/auctions` | Dashboard has own ctrl | **REMOVE** | API route absent |
| `PATCH /cancel-auction` | Yes | `POST /provider/auctions/cancel` | Dashboard has own ctrl | **REMOVE** | API route absent |
| `GET /auction-subscriptions` | No (list vs status) | — | Deposit participation list | **KEEP DISTINCT** | Runtime yes; Swagger no |
| `GET /my-bids` | No (cross-auction) | — | Client bid history | **KEEP DISTINCT** | BidRoute; Swagger no |
| `POST /auctions/purchase-request` | N/A unsupported | — | Always fail | **REMOVE** | Always `directPurchaseNotSupported` |
| `POST /auctions/share-event` | N/A no persistence | — | Ack-only | **REMOVE** | No analytics store |
| `GET /providers/public-profile` | Embedded in details | Auction details DTO | No separate screen | **REMOVE** | Provider card in details |

**Retained compatibility adapters:** none.

---

## 7. Socket inventory
Verified contract tests + helper uses `placeBidAtomic` only (no `Bid.create` in socket helper).

## 8. Query-param compliance
No `/auctions/:auctionId` or `/provider/auctions/:auctionId`. Identity from auth/socket only.

## 9. Files changed (Auction audit scope)
New: `AuctionCatalog.js`, `auctionCatalogController.js`, `publicLabels.js`, `auctionReportModel.js`, `docs/AUCTION_HTTP_API.md`, `docs/openapi/paths/auctions.yaml`, `test/auctionCatalogApi.test.js`, `test/auctionLegacyCleanup.test.js`  
Updated: `AuctionRoute.js`, `BidRoute.js`, validators, fav model, returnObject DTOs, socket helper, pushNotification, OpenAPI/Postman, socket/subscription/concurrency/similarAds tests, docs

## 10. Defects found and fixed
1. **Similar Ads pipeline length** — expected 7, actual 9 after AI pricing `$lookup` stages. Root cause: stale test vs `buildClientAiPricingLookupStages()`. Fixed test to assert 9 stages + pricing lookup. Not caused by Auction catalog.
2. **Legacy duplicates in Swagger/runtime** — removed; regression `auctionLegacyCleanup.test.js`.
3. **Concurrency suite skipped** — looked for `MONGO_URI` but project uses `MONGO_URL`. Fixed resolver + isolated DB `auction_concurrency_test`.

## 11. Similar Ads root cause
**Stale fixture expectation**, not Auction leakage. Pipeline intentionally grew by AI pricing stages. Proven by inspecting `Product.js` `buildSimilarAdsPreviewPipeline`.

## 12–17. Evidence summary
| Area | Evidence type | Status |
|---|---|---|
| Public/provider HTTP contract | Route + OpenAPI + catalog/socket tests | Pass (static + unit/contract) |
| Deposit | subscribeDeposit + eligibility + OpenAPI | Pass (unit/contract); **no live wallet staging** |
| Winner pay / Order | Catalog delegates `payAuction` | Pass (wiring); **no live Order staging** |
| Socket | Contract tests + placeBidAtomic | Pass (handler/contract); **no live Socket client staging** |
| Cron/finalize | Lifecycle + finalize source tests | Pass (unit); **no live cron staging** |
| Concurrency | Real replica-set Mongo | **Pass 4/4** |

## 18–20. Security / OpenAPI / Postman
- Reserve omitted from public/socket DTOs (tests).
- Ownership predicates `provider: req.user._id` on provider mutations.
- OpenAPI Auction paths = canonical only; no `/place-bid`.
- Postman regenerated from OpenAPI; export tests pass.

## 21. Staging QA
**Skipped** — no safe staging accounts/wallets/moderation harness available. Classification remains READY AFTER MANUAL QA.

## 22. Skipped
- Full authenticated lifecycle staging (infra/accounts).
- Live Socket.IO client E2E against running server (not available in this session).
- App DB concurrency intentionally avoided; used `auction_concurrency_test`.

## 23–24. Limitations / merge

| Limitation | Impact | Merge blocker? |
|---|---|---|
| No staging lifecycle | Deposit/refund/Order/notifications not live-proven | Yes for “READY TO MERGE” |
| Price suggestion is advisory stub | No external AI | No |
| Purchase/share/public-profile removed | Clients must use embedded details / OS share | No |
| Haraj-era routes still runtime (hidden) | Old domain noise | No |

**Merge recommendation:** merge to `dev` for API/Socket contract is reasonable after review; **do not** treat as production-complete until staging checklist in `docs/AUCTION_MANUAL_QA.md` is green.