feat(web): scaffold client-side rendered SPA foundation

- feat: initialize Vite project with React 19, React Router 8, TanStack
  Query, Ant Design 6, and Tailwind CSS 4
- feat: add Oxlint with React/TypeScript rules, strict TypeScript
  config, and layered CSS import order
- docs: add decision record for client-rendered Web foundation with
  React, Ant Design, and Tailwind CSS
- docs: create web roadmap defining architecture boundaries and deferred
  dependencies
- build: pin Node.js 24 in mise.toml
This commit is contained in:
2026-07-14 16:50:13 +08:00
parent a62a5bc0e2
commit b49bf648be
20 changed files with 3093 additions and 0 deletions
+49
View File
@@ -0,0 +1,49 @@
# Web Roadmap
## Product Boundary
- The Web client is a pure client-side rendered single-page application.
- Vite produces static assets only. The project does not use SSR, React Server Components, a Node API server, or a browser-specific business backend.
- The Web client consumes the same versioned REST API as future Android and other native clients.
- Production may serve `web/dist` from MyGO or a reverse proxy.
- Shared API contracts should remain client-neutral and eventually be described by OpenAPI.
## Foundation
The initial project contains only the framework and styling foundation:
- Node.js 24 and npm
- Vite
- React
- TypeScript in strict mode
- TanStack Query provider
- Tailwind CSS 4 through its Vite plugin
- Ant Design provider and components
- Oxlint from the Vite template
Ant Design owns reusable UI components and theme tokens. Tailwind CSS is initially limited to application layout, spacing, and responsive utilities.
## Planned Structure
```text
web/src/
├── app/ # Router, providers, and application composition
├── api/ # API client and generated contracts
├── components/ # Shared presentation components
├── features/ # Auth, files, account, and admin features
├── pages/ # Route entry points
├── lib/ # Framework-independent utilities
└── test/ # Shared test setup and fixtures
```
## Deferred Dependencies
Some dependencies are suggested for future implementation. Refer these only when the corresponding feature is implemented and propose better choices if any:
- `@ant-design/icons`: Add Ant Design-consistent application and action icons when real screens require them.
- `openapi-typescript`: Generate TypeScript API types from the shared OpenAPI document.
- `openapi-fetch`: Provide a small type-safe Fetch client based on generated OpenAPI types.
- `openapi-react-query`: Connect generated OpenAPI operations to TanStack Query if handwritten query adapters become repetitive.
- `zustand`: Manage a cross-route upload queue, bulk selection, or other complex client-only state if React state is insufficient.
- `vitest`: Run unit and integration tests using the Vite toolchain.
- `pdfjs-dist`: Preview PDF files in the browser when document preview is implemented.