Meik
eb2031feb0
Record the requirement to start from a clean worktree, preserve the running Docker state as production reference, commit and push every completed change, and deploy features and fixes live via Docker.
55 lines
5.2 KiB
Markdown
55 lines
5.2 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- `src/` holds the React client: `App.js` bootstraps the main views (“Slots buchen”, Store-Watch) and composes feature-specific components (z. B. `DashboardView`, `StoreWatchPage`) plus hooks/utilities in neighboring folders.
|
||
- `public/` contains the static shell served during development; only add files that must be copied verbatim into the build output.
|
||
- `server.js` is the Express backend that serves the built client, exposes the REST APIs used by the UI (e.g. `/api/stores`, `/api/store-watch/*`, `/api/user/preferences/*`, `/api/location/nearest-store`) und persistiert Daten über die Stores in `config/`.
|
||
- `config/` stores generated runtime state (`<profileId>-pickup-config.json`, Admin-Settings, Preferences, Watcher etc.). Keep it writable but untracked so local credentials never leak.
|
||
- `build/` is created by `npm run build` and shipped by the Express server or Docker image; never edit files here manually.
|
||
- `docker-compose.yml`, `Dockerfile`, and `rebuildContainer.sh` encapsulate deployment; update them when server ports, env vars, or base images change.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `npm install` – restore dependencies in `package.json`.
|
||
- `npm start` – launch the CRA dev server on port 3000 with live reload.
|
||
- `npm run build` – emit the production bundle into `build/`; run before `node server.js` or container builds.
|
||
- `npm test` – run React Testing Library suites in watch mode; append `-- --watch=false` in CI.
|
||
- `npm run check:foodsharing-api` – verify the Foodsharing endpoints used by the app against `https://foodsharing.de/api/doc`.
|
||
- `node server.js` – serve the prebuilt UI and REST API using values from `.env` (e.g., `PICKUP_TOPIC`, credentials, ports).
|
||
- `docker-compose up --build` – rebuild and start the containerized service, syncing the bundled UI and server.
|
||
|
||
## Required Close-Out Steps
|
||
- After changes to `server.js`, `services/`, `src/`, `Dockerfile`, `docker-compose.yml`, or the Foodsharing API integration, always run this sequence completely:
|
||
- `CI=true npm test -- --watch=false`
|
||
- `npm run build`
|
||
- `npm run check:foodsharing-api` when Foodsharing endpoints, payloads, or response mappings are affected
|
||
- `docker compose up -d --build`
|
||
- `curl http://localhost:3005/api/health` and confirm the response contains `"status":"ok"`
|
||
|
||
## Git & Deployment Workflow
|
||
- Before making any code, config, Docker, or documentation change, verify `git status --short` is clean. If it is not clean, stop and reconcile the current worktree first; the running Docker service on port 3005 is the relevant production reference when deciding which state to preserve.
|
||
- If the running Docker service contains changes that are not committed, compare its `/app` contents against the worktree, commit the Docker-live state, and push it before starting a new feature or fix.
|
||
- After every completed feature or fix, update `.commitmessage`, stage it with `git add -f .commitmessage`, create a conventional commit, and push `main`.
|
||
- Features and fixes must go live in Docker after the commit: run `docker compose up -d --build` and verify `curl http://localhost:3005/api/health` returns a JSON response containing `"status":"ok"`.
|
||
- Keep `config/`, credentials, request logs, HAR captures, and other runtime state out of commits unless explicitly requested.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Use 2-space indentation and Standard/Prettier-compatible formatting; rely on the CRA ESLint config (`react-app`, `react-app/jest`) for feedback.
|
||
- Favor functional React components with PascalCase filenames (`PickupConfigEditor.js`) and camelCase props/state keys.
|
||
- Keep config schema fields (e.g., `desiredWeekday`, `onlyNotify`) camelCase across client and API payloads.
|
||
- Prefer descriptive folder-local CSS files rather than global selectors; co-locate assets next to their component whenever possible.
|
||
|
||
## Testing Guidelines
|
||
- React Testing Library + Jest underpin `App.test.js`; add `<Component>.test.js` files alongside components to exercise rendering and validation.
|
||
- Initialize helpers inside `setupTests.js` to keep suites lean.
|
||
- Aim for meaningful edge cases (blank config, duplicate IDs, toggling `onlyNotify`). Pull requests should demonstrate passing `npm test` output or CI logs.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Follow conventional commits (e.g., `feat: add notification panel`, `fix: debounce config saves`) and keep subjects ≤72 characters.
|
||
- After every change, refresh `.commitmessage` with the final commit text and ensure it is staged (e.g., `git add -f .commitmessage`) so tooling can reuse it automatically.
|
||
- Reference issues or API endpoints impacted inside the body, and describe user-visible changes plus verification steps.
|
||
- PRs must include: summary of API/UI changes, screenshots or JSON samples when modifying config shape, notes on new env vars, and confirmation that `npm test` and `npm run build` succeed.
|
||
|
||
## Security & Configuration Tips
|
||
- Store secrets in `.env`, not in version control; provide `.env.example` updates when new variables (ports, credentials) are introduced.
|
||
- The server writes to `config/pickup-config.json`; ensure the directory exists and has the correct permissions before deploying or running containers.
|