This is a React 18 administration application built with Vite. Application code lives in `src/`: route-level features are grouped in `src/pages/`, reusable UI in `src/components/` and `src/common/`, API clients in `src/api/`, and shared hooks and helpers in `src/hooks/` and `src/utils/`. Routing, layout, and state are maintained in `src/routes/`, `src/layout/`, and `src/store/`. Styles are primarily colocated Less files. Static assets belong in `src/assets/`; files that must be served unchanged belong in `public/`. The formula editor source and its built output are under `public/formula-editor/`.
This repository is a pnpm workspace. Use Node >=22.13 and pnpm 11.13.1 from the repository root.
## Build, Test, and Development Commands
-`apps/admin` is the legacy JavaScript/JSX administration app. It remains on React 18 and Ant Design 5 in Stage 0; Redux, Redux Toolkit, React Redux, and Redux Persist are allowed there. Do not make broad dependency upgrades unless a later task explicitly authorizes them.
-`apps/learning` is the planned TypeScript learning app. It uses React/ReactDOM 19, TanStack React Query for server state, nuqs for URL-restorable page state, and Zustand only for transient cross-component client state. The Redux family is forbidden: `redux`, Redux Toolkit, React Redux, and Redux Persist.
- Apps own their routes, state, API clients, dependencies, and build outputs. Never import another app's `src` directory; extract a deliberate shared package only when a task calls for it.
- Do not add Ant Design to the learning placeholder. If learning later adopts it, use the current stable v6 baseline (`^6.5.1` as of this plan), never admin's v5 dependency.
-`npm ci` installs the exact dependency versions from `package-lock.json`.
## Commands
-`npm run dev` starts Vite with HTTPS and the API proxy configured in `vite.config.js`.
-`npm run build` creates a production bundle in `dist/`.
-`npm run build:dev` builds with Vite's development mode settings.
-`npm run preview` serves the production bundle for a local smoke test.
-`npm run lint` runs ESLint on `src/` and automatically fixes supported issues. Review the resulting diff.
## Coding Style & Naming Conventions
Currently available root commands:
Follow the existing JavaScript/JSX style: two-space indentation, single quotes, no semicolons, and functional React components. Use `PascalCase` for component names, `camelCase` for functions and variables, and `useXxx` for hooks. Existing feature folders generally use lowercase or kebab-case names and expose entry points as `index.jsx`. Prefer the `@/` alias for imports rooted at `src/`. ESLint extends the recommended React and React Hooks rules; keep hook dependency arrays accurate.
-`pnpm install`
-`pnpm dev:admin`
-`pnpm build:admin`
-`pnpm lint:admin` — the inherited admin script uses `--fix`; inspect its diff and do not run it for read-only validation.
## Testing Guidelines
Learning commands (`dev:learning`, `build:learning`, `test:learning`, and `lint:learning`) and root verification commands are planned, but do not exist until their corresponding Stage 0 tasks create them.
No automated test framework or coverage threshold is currently configured. For every change, run `npm run lint` and `npm run build`, then smoke-test affected routes with `npm run dev`. Verify editor changes with realistic content, uploads, and API failure states. If adding tests, colocate them as `*.test.jsx` or `*.test.js` and add the associated runner command to `package.json`.
## Code and documentation
## Commit & Pull Request Guidelines
Keep admin's existing JavaScript/JSX conventions: two-space indentation, single quotes, no semicolons, functional components, `PascalCase` components, `camelCase` utilities, and `useXxx` hooks. Keep learning code strict TypeScript and follow its state boundaries above.
Recent history follows Conventional Commit-style prefixes such as `feat:`, `fix:`, `refactor:`, and `chore:`. Keep the subject concise, imperative, and focused on one change. Pull requests should explain the user-facing impact, list validation performed, link the relevant issue, and include screenshots or recordings for UI changes. Call out API, proxy, dependency, or configuration changes explicitly; never commit credentials or environment-specific secrets.
Root `docs/` contains implementation plans and repository documentation. Root `scripts/` is reserved for workspace-wide automation; do not place application code there. Keep app-specific code and assets inside the owning app.
Use concise Conventional Commit subjects (`feat:`, `fix:`, `refactor:`, `chore:`, or `docs:`). Preserve user changes, do not modify sibling repositories, and do not push or deploy unless explicitly asked.
**Architecture:** Keep admin and learning as separate Vite applications with separate routers, state, API clients, dependencies, and outputs. The learning app follows the `saas-bi` module structure, uses TanStack React Query for server state, nuqs for recoverable URL state, and Zustand only for transient cross-component client state.
**Architecture:** Keep admin and learning as separate Vite applications with separate routers, state, API clients, dependencies, and outputs. The learning app follows the `saas-bi` module structure, uses TanStack React Query for server state, nuqs for recoverable URL state, and Zustand only for transient cross-component client state.
**Tech Stack:** pnpm 11.13.1, Node >=22.13, Vite ^8.1.5 with @vitejs/plugin-react ^6.0.3, TypeScript, React Router 7, TanStack React Query 5, nuqs 2, Zustand 5, Axios, Vitest ^4.1.10, Testing Library. Admin preserves legacy React 18.3.1 and Ant Design 5; learning uses React/ReactDOM ^19.2.7 with @types/react ^19.2.17 and @types/react-dom ^19.2.3.
## Global Constraints
## Global Constraints
...
@@ -16,7 +16,10 @@
...
@@ -16,7 +16,10 @@
- Do not modify `com-ebook-app-api`, `com-ebook-pc-api`, `book-app`, or `book-app-h5` in Stage 0.
- Do not modify `com-ebook-app-api`, `com-ebook-pc-api`, `book-app`, or `book-app-h5` in Stage 0.
- Do not refactor existing admin business pages while moving them.
- Do not refactor existing admin business pages while moving them.
- The admin app remains JavaScript/JSX and may retain its existing Redux usage.
- The admin app remains JavaScript/JSX and may retain its existing Redux usage.
- Admin remains on its current React 18 and Ant Design 5 stack in Stage 0; upgrade it only in a separate later task.
- The learning app must use TypeScript and must not depend on Redux, Redux Toolkit, React Redux, or Redux Persist.
- The learning app must use TypeScript and must not depend on Redux, Redux Toolkit, React Redux, or Redux Persist.
- Learning uses React and ReactDOM ^19.2.7 with @types/react ^19.2.17 and @types/react-dom ^19.2.3.
- Do not add Ant Design to the Stage 0 learning placeholder. If learning later adopts Ant Design, use the current stable v6 baseline (^6.5.1 as of this plan), never admin's Ant Design v5 dependency.
- The learning app uses TanStack React Query for all server state.
- The learning app uses TanStack React Query for all server state.
- The learning app uses nuqs for recoverable and shareable page operation state.
- The learning app uses nuqs for recoverable and shareable page operation state.
- The learning app uses Zustand only for transient cross-component client state that is neither URL state nor server state.
- The learning app uses Zustand only for transient cross-component client state that is neither URL state nor server state.
@@ -1272,7 +1275,7 @@ Expected: both commands exit 0 and print `Build layout verified`.
...
@@ -1272,7 +1275,7 @@ Expected: both commands exit 0 and print `Build layout verified`.
-[]**Step 4: Write app-specific AI instructions**
-[]**Step 4: Write app-specific AI instructions**
Update root `AGENTS.md` to describe the Monorepo layout, root commands, and the rule that `apps/admin` and `apps/learning` do not import each other's `src`.
Verify/refine root `AGENTS.md` to describe the monorepo layout, current versus planned root commands, dependency boundaries, and the rule that `apps/admin` and `apps/learning` do not import each other's `src`.
