177 lines
5.2 KiB
Markdown
177 lines
5.2 KiB
Markdown
# 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.
|