This repository is a pnpm workspace. Use Node >=22.13 and pnpm 11.13.1 from the repository root.
This is a pnpm monorepo. `apps/admin` is the React 18 administration app (mostly JavaScript/JSX); `apps/learning` is the React 19 learning app written in TypeScript. Keep application code, assets, routes, API clients, and tests inside the owning app—never import another app’s `src` directory. Shared packages belong in `packages/` only when they are genuinely used by both apps.
-`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 TypeScript learning app. It uses React/ReactDOM 19, Ant Design 6, TanStack React Query for server state, nuqs for URL-restorable list controls, 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.
- Learning uses Ant Design `^6.5.1`; standard forms, controls, navigation, dialogs, and feedback primitives must come from it. Admin's Ant Design 5 remains isolated: never import or copy admin UI source into learning.
Within an app, feature code lives under `src/modules/<domain>/`; reusable UI belongs in `src/components/`; cross-cutting utilities and hooks belong in `src/utils/` and `src/hooks/`. Keep editor features isolated under `apps/admin/src/components/editor/wangeditor-customer/features/`. Put plans and technical notes in `docs/`.
## Commands
## Build, Test, and Development Commands
Currently available root commands:
-`pnpm dev` — run Admin and Learning Vite servers in parallel.
-`pnpm dev:admin` / `pnpm dev:learning` — run one app only.
-`pnpm build` — build Learning, then Admin.
-`pnpm build:admin` / `pnpm build:learning` — build one app.
-`pnpm test`, `pnpm test:admin`, `pnpm test:learning` — run Vitest and Node tests.
-`pnpm lint:admin` / `pnpm lint:learning` — run Oxlint with auto-fix; review the resulting diff.
-`pnpm --filter @ebook/admin format` — format Admin source with Oxfmt; use the equivalent Learning filter when needed.
-`pnpm install`
-`pnpm dev` — runs both apps in parallel.
-`pnpm dev:admin`
-`pnpm dev:learning`
-`pnpm build` — builds learning first, then admin.
-`pnpm build:admin`
-`pnpm build:learning`
-`pnpm test` — runs each workspace package's test command.
-`pnpm test:admin`
-`pnpm test:learning`
-`pnpm lint:admin` — the inherited admin script uses `--fix`; inspect its diff and do not run it for read-only validation.
-`pnpm lint:learning`
## Coding Style & Naming Conventions
## Code and documentation
Use two-space indentation, single quotes, and no semicolons; Oxfmt is authoritative. Prefer functional React components. Components use `PascalCase`, hooks use `useXxx`, and utilities use `camelCase`. Learning code should remain TypeScript-first; avoid `any` and keep server state in React Query, URL state in nuqs, and transient shared state in Zustand. Follow the surrounding module’s established JavaScript/JSX style in Admin.
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.
## Testing Guidelines
For learning modules, route views orchestrate state hooks, semantic handlers, and layout composition; domain UI belongs in module `components/`. Pass explicit values and semantic callbacks rather than whole state objects or URL/query setters. Components must not read URL or global state directly: URL ownership stays in `query-state` hooks and server-query ownership stays in `query` hooks. Use official/library primitives and utilities directly; create wrappers only for meaningful domain composition or behavior, never trivial pass-through wrappers. Split by independent business responsibility or change reason, not element count. List controls belong in nuqs query state; standalone resource pages use route path parameters, never list-detail modals.
Use Vitest for unit/component tests and Node’s test runner where existing Admin tests do. Place tests beside the code as `*.test.ts`, `*.test.tsx`, `*.test.js`, or `*.test.mjs`. Add tests for behavior changes with meaningful branching or data transformation; do not add superficial snapshot-only tests.
The learning shell is `LearningLayout` with top navigation for `/home`, `/library`, and `/my`; `/` and unknown ordinary routes redirect to `/library`. Library URL state is `keyword`, `category`, `label`, `price`, `sortField`, `sortOrder`, `page`, `pageSize`, and `view`; map it to the APP request fields only in its `api.ts`. A nonempty `keyword` uses the APP `searchBook` API and does not combine with category filters. The book detail is the standalone `/book/:bookId` route, while `/reader/:bookId/:chapterId` owns its independent full-screen layout. Complex top-level domains use nested ownership folders under `modules/my`; each submodule may own its API, query, state, components, and views. Keep simple one-page modules shallow. Browser requests retain `/api/web`; learning's Vite proxy targets `https://ebook-app.ezijing.com` and removes `/api/web`. For current local integration only, the shared HTTP client adds `X-Skip-Sig: 1`; module code must not repeat it, and production builds must not send it. See `apps/learning/AGENTS.md` for local ownership details.
## Commit & Pull Request Guidelines
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.
Use concise Conventional Commit subjects, e.g. `feat: add book export styles`, `fix(admin): restore toolbar state`, or `refactor: simplify permission hook`. Keep commits focused. PRs should state scope, verification performed, relevant API/configuration changes, and include screenshots for visible UI changes. Do not commit secrets, local `.env` values, build output, or unrelated formatting changes.
