add build development phases
This commit is contained in:
hamid
@@ -0,0 +1,50 @@
|
||||
# Shared working context — the parallel-agent handoff
|
||||
|
||||
This folder lets a **backend agent** and a **frontend agent** work **at the same time** without ever
|
||||
editing the same file. It is the running, append-only record of what each side has done and what it
|
||||
needs from the other. (Stable API shapes live in [`../contracts/`](../contracts/README.md); this folder
|
||||
is the *running coordination* on top of them.)
|
||||
|
||||
## Lane ownership — the one rule that keeps it safe
|
||||
|
||||
> **Each lane writes only its own files. Neither lane edits the other's.**
|
||||
|
||||
| Lane | Writes (only) | Reads |
|
||||
| --- | --- | --- |
|
||||
| **Backend** | `backend/STATUS.md`, `backend/handoff/after-backend-phase-N.md` (new file per phase), `reports/backend-phase-N-report.md`, `reports/mocks-registry.md` | `frontend/requests/for-backend.md`, prior backend handoffs |
|
||||
| **Frontend** | `frontend/STATUS.md`, `frontend/requests/for-backend.md` (append), `reports/frontend-phase-N-report.md` | `backend/handoff/*`, `../contracts/*`, prior frontend reports |
|
||||
|
||||
Because each handoff is a **new file per phase** and each STATUS/requests file is **append-only**, two
|
||||
agents can run concurrently and only ever *append* — no merge conflicts, no clobbering.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
shared-working-context/
|
||||
├── backend/
|
||||
│ ├── STATUS.md # append: one block per backend phase (what shipped, gate status)
|
||||
│ └── handoff/
|
||||
│ └── after-backend-phase-N.md # "context for frontend after backend phase N" (one per phase)
|
||||
├── frontend/
|
||||
│ ├── STATUS.md # append: one block per frontend phase
|
||||
│ └── requests/
|
||||
│ └── for-backend.md # append: contract gaps / shape requests the backend should fulfil
|
||||
└── reports/
|
||||
├── README.md # the per-phase report template
|
||||
├── mocks-registry.md # master list of every mock/seam + how to make it real (backend-owned)
|
||||
├── backend-phase-N-report.md # what was built / testable / mocked (one per backend phase)
|
||||
└── frontend-phase-N-report.md # one per frontend phase
|
||||
```
|
||||
|
||||
## The handoff note (backend → frontend), per phase
|
||||
`backend/handoff/after-backend-phase-N.md` should answer, for the frontend agent:
|
||||
- Which endpoints/contracts are now **live** (link the `contracts/domains/*` doc + the swagger snapshot).
|
||||
- What the frontend can now build because of this phase.
|
||||
- What is **mocked** server-side (so the frontend knows responses are fake-but-shaped) and what's real.
|
||||
- Any auth/enum/format detail the frontend must mirror.
|
||||
- Open questions / things the frontend should *not* assume yet.
|
||||
|
||||
## The request note (frontend → backend)
|
||||
`frontend/requests/for-backend.md` is where the frontend appends: missing endpoints, fields it needs,
|
||||
shape mismatches, pagination/filter needs — anything that should land in a later backend change. The
|
||||
backend agent reads this at the start of each phase. The frontend never edits backend code to "fix" it.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Backend status log (append-only)
|
||||
|
||||
One block per completed backend phase. Newest at the top. Backend lane writes here; frontend reads.
|
||||
|
||||
<!-- TEMPLATE — copy for each phase
|
||||
## backend-phase-N — <Title> — <YYYY-MM-DD>
|
||||
- **Shipped:** <entities/endpoints/seams in one or two lines>
|
||||
- **Contracts:** dev/contracts/domains/<domain>.md + openapi snapshot refreshed (yes/no)
|
||||
- **Mocked:** <which seams> (see reports/mocks-registry.md)
|
||||
- **Gate:** build clean / tests green
|
||||
- **Handoff:** backend/handoff/after-backend-phase-N.md
|
||||
- **Notes for frontend:** <anything load-bearing>
|
||||
-->
|
||||
|
||||
_(no phases completed yet)_
|
||||
@@ -0,0 +1,15 @@
|
||||
# Frontend status log (append-only)
|
||||
|
||||
One block per completed frontend phase. Newest at the top. Frontend lane writes here; backend reads
|
||||
for awareness.
|
||||
|
||||
<!-- TEMPLATE — copy for each phase
|
||||
## frontend-phase-N-bM — <Title> — <YYYY-MM-DD>
|
||||
- **Shipped:** <screens/flows/services/hooks/components in one or two lines>
|
||||
- **Consumes:** dev/contracts/domains/<domain>.md (backend phase bM)
|
||||
- **Mocked client-side:** <which services are mocked pending which backend phase>
|
||||
- **Gate:** npm run check green / tests green
|
||||
- **Requests filed:** frontend/requests/for-backend.md (yes/no)
|
||||
-->
|
||||
|
||||
_(no phases completed yet)_
|
||||
@@ -0,0 +1,15 @@
|
||||
# Frontend → Backend requests (append-only)
|
||||
|
||||
The frontend lane appends here when it needs a contract that doesn't exist yet, finds a shape mismatch,
|
||||
or needs a new field/filter/endpoint. The backend agent reads this at the start of each phase and
|
||||
delivers fixes in its own change. **Frontend never edits backend code to "fix" a gap — it requests it.**
|
||||
|
||||
<!-- TEMPLATE — copy per request
|
||||
## REQ-NNN — <short title> — filed by frontend-phase-N-bM — <YYYY-MM-DD>
|
||||
- **Need:** <endpoint / field / filter / shape>
|
||||
- **Why:** <which screen/flow needs it>
|
||||
- **Proposed shape:** <JSON sketch, optional>
|
||||
- **Status:** open | delivered in backend-phase-K
|
||||
-->
|
||||
|
||||
_(no requests yet)_
|
||||
@@ -0,0 +1,32 @@
|
||||
# Phase reports — template
|
||||
|
||||
Every phase writes a report here when it finishes (operating-rules §7, Definition of Done). The report
|
||||
is the durable answer to *"what did this phase do, what can I test now, and what's still fake?"* — saved
|
||||
to a file, not left in chat.
|
||||
|
||||
File name: `backend-phase-N-report.md` or `frontend-phase-N-bM-report.md`.
|
||||
|
||||
```markdown
|
||||
# <Backend|Frontend> Phase N — <Title> — Report (<YYYY-MM-DD>)
|
||||
|
||||
## What was built
|
||||
- Bullet list of concrete deliverables (entities/migrations/endpoints, or screens/services/components).
|
||||
|
||||
## What is now testable (and exactly how)
|
||||
- Step-by-step for a human: e.g. "Swagger → POST /api/v1/auth/otp/request with {phone} → 200; the OTP is
|
||||
logged to the console; POST /api/v1/auth/otp/verify with that code → returns access+refresh tokens."
|
||||
- For the frontend: which screen, which route, what to click, expected result, how mock data shows up.
|
||||
|
||||
## What is mocked / waiting on a real service
|
||||
- Each seam touched: interface + file, what's faked, and a link to its entry in `mocks-registry.md`.
|
||||
|
||||
## Contracts
|
||||
- Produced (backend): which `contracts/domains/*.md` + openapi snapshot.
|
||||
- Consumed (frontend): which contract/version; any request filed in `frontend/requests/for-backend.md`.
|
||||
|
||||
## Docs updated
|
||||
- Which CLAUDE.md / product doc / conventions were updated and why.
|
||||
|
||||
## Follow-ups for later phases
|
||||
- Anything intentionally deferred, with the phase that should pick it up.
|
||||
```
|
||||
@@ -0,0 +1,36 @@
|
||||
# Mock & integration registry
|
||||
|
||||
The master list of every external dependency that is **mocked behind a DI seam** in this build, and the
|
||||
exact steps to make each one real. Backend lane owns this file; every phase that introduces or touches a
|
||||
seam updates its row. This is the checklist the team works through to go from "MVP with mocks" to
|
||||
"production with real providers".
|
||||
|
||||
Status legend: 🔴 not built · 🟡 mocked (seam + fake impl in place) · 🟢 real integration live.
|
||||
|
||||
| Seam (interface) | Introduced in | What it fakes | Config keys | Make it real → | Status |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `ISmsSender` | backend-phase-2 | OTP/SMS delivery — logs the code instead of sending | _tbd_ | Implement a Kavenegar/Ghasedak/SMS.ir client; keep idempotency + rate-limit | 🔴 |
|
||||
| `IObjectStorage` | backend-phase-0/6 | File storage — local/in-memory instead of object store | _tbd_ | Point at MinIO/S3/ArvanCloud; presigned upload/download; bucket + creds | 🔴 |
|
||||
| `ICacheService` | backend-phase-0 | Caching — in-memory dictionary | _tbd_ | Swap to Redis (`StackExchange.Redis`); keep key/TTL scheme | 🔴 |
|
||||
| `IDistributedLock` | backend-phase-10 | Money-path locks — no-op/in-proc | _tbd_ | Redis lock (RedLock); DB constraint remains the backstop | 🔴 |
|
||||
| `INurseSearch` | backend-phase-7 | Search — SQL over `nurse_search_index` | _tbd_ | Elasticsearch index + feeder; reimplement the interface | 🔴 |
|
||||
| `IPaymentProvider` | backend-phase-10 | Card PSP/IPG — deterministic success | _tbd_ | ZarinPal/Sadad/Vandar/Jibit + Shaparak; merchant/terminal/تسهیم | 🔴 |
|
||||
| `ISettlementSplitProvider` | backend-phase-10 | تسهیم split — accepts any balanced legs | _tbd_ | Provider split-by-ratio to registered Shebas | 🔴 |
|
||||
| `IWebhookVerifier` | backend-phase-10 | Callback auth — always valid | _tbd_ | Per-provider HMAC/signature + server-side re-verify | 🔴 |
|
||||
| `IBnplProvider` | backend-phase-12 | BNPL — drives state machine, fake settle/revert | _tbd_ | SnappPay/Digipay OAuth + verb set; encrypted creds in `payment_gateways.config_json` | 🔴 |
|
||||
| `ICurrencyNormalizer` | backend-phase-12 | Toman↔IRR — ×10 | _tbd_ | Config-driven per provider boundary | 🔴 |
|
||||
| `IBankTransferProvider` | backend-phase-13 | PAYA/SATNA payout — fake transfer ref | _tbd_ | Jibit/Vandar/Sadad payout; source account; PAYA vs SATNA | 🔴 |
|
||||
| `IHolidayCalendar` | backend-phase-1 | Bank holidays — seeded static table | _tbd_ | Iranian banking-holiday feed / sync job | 🔴 |
|
||||
| `IShahkarVerifier` | backend-phase-6 | Phone↔national-id match — fake pass | _tbd_ | Real Shahkar/KYC vendor; persist `external_response_json` | 🔴 |
|
||||
| `IIdentityKycProvider` | backend-phase-6 | National-ID + liveness — fake pass | _tbd_ | Finnotech/U-ID/Jibbit/Verify liveness+OCR | 🔴 |
|
||||
| `ICredentialVerifier` | backend-phase-6 | MoH/INO/criminal-record — manual/fake | _tbd_ | Manual admin today; API when a portal appears (`verification_method=api`) | 🔴 |
|
||||
| `IBankAccountOwnershipVerifier` | backend-phase-3/6 | استعلام شبا IBAN↔national-id — fake match | _tbd_ | Real KYC vendor; store `ownership_vendor_ref` | 🔴 |
|
||||
| `IGeocoder` | backend-phase-4 | Address→lat/lng — echo/static | _tbd_ | Neshan/Google geocoding | 🔴 |
|
||||
| `IMoadianClient` | backend-phase-11 | سامانه مودیان e-invoice — leaves ref pending | _tbd_ | Real مودیان submission → 22-digit ref | 🔴 |
|
||||
| `IReviewModerationService` | backend-phase-14 | AI moderation — keyword/pass-through | _tbd_ | Real classifier/LLM endpoint | 🔴 |
|
||||
| `IFieldEncryptor` | backend-phase-0 | PII encryption — local symmetric key | _tbd_ | KMS / column encryption / Key Vault / HSM | 🔴 |
|
||||
| `INotificationDispatcher` | backend-phase-0/15 | Notification channels — in-app write only | _tbd_ | Add SMS/push (FCM); polling → Redis pub/sub or SignalR later | 🔴 |
|
||||
| `ILicenseVerificationService` | backend-phase-15 | eNamad / MoH establishment-permit — manual approve | _tbd_ | Real registry/API | 🔴 |
|
||||
|
||||
> Exact config keys and file paths get filled in by the phase that builds each seam. Keep the
|
||||
> "Make it real →" column actionable enough that a developer can pick up any single row and ship it.
|
||||
Reference in New Issue
Block a user