Add AI DEV Node deployment foundation

docs/node-migration-plan.md

@@ -0,0 +1,176 @@
+# ACS Node.js Migration Plan
+
+## Goal
+
+Convert ACS from the current Spring Boot backend deployment model to an AI DEV compliant Node.js application.
+
+The target deployment must:
+
+- Run as a Node.js app.
+- Run on port `3000`.
+- Use `process.env.DATABASE_URL` supplied by `.project-env` / AI DEV.
+- Avoid self-managed PostgreSQL containers in the deployment path.
+- Build through the root `Dockerfile`.
+- Preserve the existing React frontend where possible.
+- Preserve the current `/api` contract and response envelope:
+
+```json
+{ "code": 200, "message": "OK", "data": {} }
+```
+
+## Target Architecture
+
+```text
+Node.js app
+├─ /api/*                  Express API
+├─ /assets, /index.html    Static React build from frontend/dist
+├─ PostgreSQL              process.env.DATABASE_URL
+└─ migrations              SQL files adapted from existing Flyway migrations
+```
+
+Recommended stack:
+
+- Runtime: Node.js + TypeScript
+- HTTP: Express
+- Database: `pg`
+- Session: `express-session` with PostgreSQL-backed store
+- Password hashing: `bcrypt`
+- QR generation: `qrcode`
+- Excel import/export: `multer` + `exceljs`
+- Frontend: existing React/Vite app
+
+## Migration Principles
+
+1. Keep the frontend API surface stable.
+2. Reuse the current PostgreSQL schema as much as possible.
+3. Convert by feature slice, not by framework layer.
+4. Keep Spring Boot code available as the behavior reference until parity is verified.
+5. Make AI DEV deployment simple: `npm install`, `npm run build`, `npm start`.
+
+## Feature Migration Order
+
+### Phase 1. Node Foundation
+
+- Add root Node package and TypeScript config.
+- Add `server/` source tree.
+- Add env loader for local `.project-env` compatibility.
+- Add PostgreSQL connection pool using `DATABASE_URL`.
+- Add migration runner using SQL files in `migrations/`.
+- Add health check endpoint: `GET /api/health`.
+- Add AI DEV health check endpoint: `GET /healthz`.
+- Add AI DEV DB check endpoint: `GET /db`.
+- Add S3 status endpoint: `GET /s3` with an explicit skip response because ACS does not use S3/MinIO.
+- Serve `frontend/dist` for non-API routes.
+
+### Phase 2. Auth and Common Infrastructure
+
+- Implement API response helper.
+- Implement error handler.
+- Implement session middleware.
+- Implement role guard middleware.
+- Implement:
+  - `POST /api/auth/login`
+  - `POST /api/auth/logout`
+  - `GET /api/auth/me`
+  - `POST /api/auth/change-password`
+
+### Phase 3. Read-First Business APIs
+
+- `GET /api/zones`
+- `GET /api/visit-requests`
+- `GET /api/visit-requests/pending`
+- `GET /api/visit-requests/:id`
+- `GET /api/stats/summary`
+
+### Phase 4. Visit Request and Approval Workflow
+
+- `POST /api/visit-requests`
+- `POST /api/visit-requests/:id/cancel`
+- `POST /api/approvals/:id/approve`
+- `POST /api/approvals/:id/reject`
+- Generate `qr_token` on approval.
+- Insert approval and audit log records.
+- Preserve "notification failure must not rollback approval" behavior.
+
+### Phase 5. Pass, QR, and Access Control
+
+- `GET /api/passes/:id`
+- `GET /api/passes/:id/qr.png`
+- `GET /api/public/passes/:token`
+- `GET /api/public/passes/:token/qr.png`
+- `POST /api/access/check-in`
+- `POST /api/access/check-out`
+- `GET /api/access/inside`
+- `GET /api/access/today`
+- Public kiosk check-in/out endpoints.
+
+### Phase 6. Admin Features
+
+- Blacklist CRUD.
+- Audit log list.
+- Delivery outbox list and retry.
+- Excel upload for visit requests.
+- XLSX visit report download.
+
+### Phase 7. Deployment Cleanup
+
+- Update README and AI DEV run instructions.
+- Mark Spring Boot backend and Docker Compose deployment as legacy.
+- Keep or remove legacy files after user confirmation.
+- Verify deployment in AI DEV with real `.project-env`.
+
+## API Compatibility Rules
+
+- Keep `/api` prefix.
+- Keep frontend DTO field names in camelCase.
+- Keep HTTP status behavior close to the Spring implementation:
+  - 400 validation error
+  - 401 unauthenticated
+  - 403 forbidden
+  - 404 missing resource
+  - 409 business conflict
+- State-changing APIs must require an authenticated session unless they are public token endpoints.
+- Public pass endpoints must not require login.
+
+## Database Migration Strategy
+
+Existing files:
+
+- `V1__init.sql`
+- `V2__audit_log.sql`
+- `V3__pass_delivery.sql`
+- `V4__visit_request_contact_fields.sql`
+
+Node target:
+
+- Copy SQL into `migrations/001_init.sql` etc.
+- Create a `schema_migrations` table.
+- Apply migrations in filename order.
+- Do not create or manage a PostgreSQL container.
+- Use only `DATABASE_URL`.
+
+## Verification Checklist
+
+- `npm run typecheck`
+- `npm run build`
+- `npm run db:check` in AI DEV/Coder with `.project-env` loaded
+- `npm run minio:check` returns a documented skip because ACS does not use S3
+- `npm start`
+- `GET /healthz`
+- `GET /db`
+- `GET /api/health`
+- Login with seeded admin user.
+- Create visit request.
+- Approve request and confirm QR token.
+- Open public pass page.
+- Check in and check out.
+- Confirm inside/today access views.
+- Confirm blacklist blocks check-in.
+- Download report XLSX.
+
+## Open Decisions
+
+- Exact AI DEV Node version.
+- Whether AI DEV automatically runs `npm run build` or only `npm start`.
+- Whether `.project-env` exists in the repository root or must be sourced by the shell before startup.
+- Whether the production app should seed initial users automatically or require an explicit seed command.