> **For agentic workers:** Use `superpowers:subagent-driven-development` for module implementation and `superpowers:test-driven-development` for each behavior change. Each worker owns one module and must not edit another module without coordinator approval.
**Goal:** Build `apps/learning` as a PC-browser implementation of the existing Flutter `book-app`, first establishing the correct application shell and module boundaries, then completing browsing, reading, personal-center, transaction, and admin-SSO workflows against browser-safe APIs.
**Source of truth:**`docs/architecture/flutter-app-to-pc-feature-map.md` and the actual Flutter/API code paths cited there. The earlier Stage 0 proof UI is not a product specification.
**Architecture:** React 19 + TypeScript + Vite 8 application, Ant Design 6 primitives, TanStack React Query for server state, nuqs for recoverable URL state, Zustand only for truly transient cross-component state. The app remains independent from `apps/admin`; production serves learning at `/` and admin at `/admin/`.
**Execution rule:** Complete Milestone A before sending Home, Library/Book, Reader, and My to separate Terra workers. Those workers may run in parallel only when their file ownership does not overlap. Shared router, HTTP, authentication, layout, theme, and generated API types remain coordinator-owned.
## Global constraints
- Work only in `/Users/max/code/book/admin/center-book` on branch `next`.
- Treat `/Users/max/code/book/app/book-app` and both API repositories as read-only unless a later task explicitly authorizes backend edits.
- Preserve the user-owned `skills-lock.json` change and any unrelated worktree changes.
- Do not copy Flutter widgets mechanically. Preserve business behavior and data, then adapt the interaction to PC.
- Do not put APP `appSecret`, signing secret, member token, admin token, or payment data in URL or browser bundles.
- Do not use `X-Skip-Sig` as a browser integration mechanism.
- Use Ant Design directly for standard controls; create only domain components with meaningful behavior.
- A route view coordinates URL state, Query hooks, semantic handlers, and domain components. It must not become the entire page implementation.
- Each list/detail mutation must have explicit Query invalidation or optimistic-update behavior and tests.
- Every recoverable page operation must have a URL contract before UI implementation.
## Milestone A — Reconcile the shell with the audited APP
This milestone is the next executable unit. It deliberately builds structure and contracts, not fake business responses.
### Task A1: Remove proof-only business assumptions
- Replace proof fields `sort=latest|popular` and `tab=all|course` with the actual APP library protocol: `category`, `label`, `price`, `sortField`, `sortOrder`, `page`, `pageSize`, and `view`.
- Map URL values to API fields only in `api.ts`: `category_id`, `label_id`, `is_free`, `sort_field`, `sort`, `page`, `page_size`.
- Keep default values out of the serialized URL.
- Do not call the protected upstream API until browser-safe authentication is available; the shell must show a documented unavailable/loading boundary rather than fabricated books.
- Move standalone book details out of the library implementation into the `book` module.
**Tests first:**
- Parse all valid values and fall back on invalid enum/integer values.
- Reset page to 1 when a filter changes.
- Use `replace` for text/view changes and `push` for explicit filter, sort, and page actions.
- Query key contains only the normalized API inputs and changes for every input that changes the response.
### Task A2: Establish shared HTTP and response contracts
-`/my/books` and `/my/bookshelf` are real independent child routes.
- Use `Layout.Sider`, `Menu`, `Content`, and `Outlet` directly.
- Menu selection must work for nested detail URLs by longest-prefix matching, not exact pathname equality.
- The three initial pages show layout regions and domain responsibilities only. Do not invent server data.
-`menu.ts` records the future groups from the feature map (learning assets, account assets, settings), but do not expose dead menu links before their route exists.
### Task A5: Record maintenance boundaries
**Create:**
-`apps/learning/AGENTS.md`
**Modify:**
-`AGENTS.md`
**Document:**
- Flutter is the functional source of truth.
- Exact route/module ownership.
- Query/nuqs/Zustand decision tree.
- Ant Design direct-use and no-over-encapsulation rules.
- API signature/session security boundary.
- Reader is an independent layout/domain.
- My submodules must remain nested under `modules/my/<domain>`.
### Task A6: Verify and commit the reconciled shell
Expected: no proof-only library values, no secret/signature implementation, no Redux, and no scattered search-param parsing. Commit only reviewed project changes; leave `skills-lock.json` untouched unless the user explicitly asks to include it.
## Milestone B — Browser authentication and application context
- One-time ticket request and `/admin/sso` exchange; no admin password re-entry.
Do not start protected live-data integration until this backend contract is confirmed. Mock Service Worker may be introduced only for tests and local UI scenarios, never as hidden production fallback.
## Milestone C — Home module
**Owner:**`modules/home/**` only, plus tests.
**APP source:**`pages/course/**`.
Deliver Query/API/types and UI for course pagination, progress/status, continue learning, advertisements, recent learning, and message badge. Course filters/pagination use URL state where applicable. Continue-learning navigation resolves the latest book detail and routes to the saved chapter.
Acceptance: empty/loading/error/paginated states, progress semantics, detail/reader navigation, and query-key tests.
## Milestone D — Library, search, and book details
**Owners:**`modules/library/**`, `modules/search/**`, and `modules/book/**`; no shared-file edits without coordinator review.
2.`notes`, including per-book details and reader positioning.
3.`discussions`, including replies, likes, and deletion.
4.`wrong-questions` and `reports`.
Each child owns its API/query/state/types/components/views. All list state is URL-restorable. Successful mutations invalidate only the affected book, aggregate, and statistic keys.
## Milestone F — Reader and learning loop
Reader work is isolated because it has the highest migration risk.
- Locked chapter, preview, purchase, expired session, and retry states.
Offline ZIP/SQLite synchronization is a separate later plan after the online reader passes cross-device parity tests.
## Milestone G — My account, transactions, and settings
Split by ownership:
-`messages`.
-`orders` and PC QR payment state machine.
-`coupons` and `wallet`.
-`profile` and `security`.
-`feedback` and `help`.
PC payment replaces native SDK/iOS IAP with server-created WeChat/Alipay QR orders, idempotent status polling, timeout, cancel, and entitlement refresh. Amounts and discounts are always calculated on the server.
## Milestone H — Deployment, security, and parity verification
- One Jenkins Pipeline builds both applications and verifies `dist/learning` plus `dist/admin`.
- Nginx serves learning `/`, admin `/admin/`, and proxies `/api/web/` plus `/api/admin/` before SPA fallback.
| My | `modules/my/**` | root layout, auth, other modules |
The coordinator integrates module route exports, shared API types, theme tokens, authentication, and dependency changes. Workers report any required shared change rather than editing it opportunistically.
