# Development Guide

## Prerequisites

* **Node.js** ≥ 20.10
* **npm** ≥ 10 (or pnpm / yarn — adjust commands accordingly)

## First-time setup

```bash
git clone <repo>
cd Dolphin_Japan_frontend
npm install
cp .env.local.example .env.local
npm run dev
```

The app boots on `http://localhost:3000`.

## Useful scripts

| Script              | What it does                                   |
| ------------------- | ---------------------------------------------- |
| `npm run dev`       | Next.js dev server with hot reload             |
| `npm run build`     | Production build                                |
| `npm run start`     | Run the production build                       |
| `npm run lint`      | ESLint over the project                        |
| `npm run typecheck` | `tsc --noEmit`                                 |
| `npm run format`    | Prettier write all files                       |

---

## Adding a new feature

1. Create the folder: `src/features/{feature}/`.
2. Inside, scaffold what you actually need:

   ```
   components/    # UI
   types/         # `{feature}.types.ts`
   services/      # `{feature}Api.ts`
   data/          # `dummy.ts`
   store/         # zustand slice (only if state spans 2+ components)
   hooks/         # convenience hooks
   utils/         # helpers
   ```

3. Define types first (`{feature}.types.ts`).
4. Add dummy data (`data/dummy.ts`).
5. Add the service file. Wrap public methods in `withDummyFallback`:

   ```ts
   export const listThings = (q: ListQuery = {}) =>
     withDummyFallback(
       () => api.get<Paginated<Thing>>(`/things${buildQuery(q)}`),
       () => ({ items: DUMMY_THINGS, total: DUMMY_THINGS.length, page: 1, pageSize: 10, pageCount: 1 }),
     );
   ```

6. Build the UI under `components/`. Add `'use client'` only if needed.
7. Wire it up in the App Router by creating a thin `page.tsx`:

   ```tsx
   import { ThingPage } from '@/features/thing/components/ThingPage';
   export default function Page() { return <ThingPage />; }
   ```

8. Document the endpoints in [`docs/API.md`](API.md) (start as 🟡 Planned).

---

## Adding a shadcn primitive

The shadcn UI files live in `src/shared/components/ui/`. To add a new
primitive, run the shadcn CLI with the project root configured to point at
that folder, or copy the file from the shadcn docs and adjust `cn` import:

```ts
import { cn } from './utils'; // resolves via re-export to @/shared/lib/utils
```

---

## Working with the dummy fallback

While the backend is ramping up, **every list/detail/submit call** falls back
to dummy data when the API returns 4xx/5xx or fails to connect.

Toggle behaviour from `.env.local`:

```env
NEXT_PUBLIC_USE_DUMMY_FALLBACK=true   # default — silent fallback (good for dev)
NEXT_PUBLIC_USE_DUMMY_FALLBACK=false  # strict — errors bubble up
```

Once an endpoint is live, prefer adjusting only the relevant call (e.g.
swap `withDummyFallback(call, dummy)` for plain `call()`) rather than
flipping the global flag, until the whole feature is migrated.

---

## Coding standards

* **TypeScript strict** — no implicit `any`. Avoid `as unknown as T`; model the
  type properly.
* **No cross-feature imports.** If feature A needs feature B's component or
  type, lift it to `src/shared/`.
* **No `process.env` outside of `src/shared/lib/constants.ts`.**
* Use the `cn(...)` helper for conditional classNames; never string-concat.
* Format prices via `formatJPY` / `formatUSD`; never inline `Intl.NumberFormat`.
* Keep `page.tsx` files in `src/app/` thin — composition lives in features.

---

## Git workflow

1. Branch off `main`: `git checkout -b feat/short-description`
2. Commit with conventional-commit prefix:
   `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`.
3. Push and open a PR. Run `npm run lint` and `npm run typecheck` first.

---

## Troubleshooting

* **Tailwind classes not applying** — confirm the file lives under one of the
  paths in `@source` directives in `src/styles/tailwind.css`.
* **`useRouter` / `usePathname` errors during build** — those are client-only
  hooks. Add `'use client'` at the top of the file.
* **Dummy data still shown after backend is live** — check
  `NEXT_PUBLIC_USE_DUMMY_FALLBACK` is `false`, and that the request URL is
  correct in the Network tab.
* **Import resolution issues** — check `tsconfig.json` paths
  (`@/* → ./src/*`) and re-run `npm run dev`.