pma-web

Web 前端实现指南

将此技能与 /pma 一起使用。/pma 负责工作流、审批和任务跟踪；本指南定义工作获批后的实现基线。

保持此入口文件精简。仅加载当前任务所需的参考资料包。

适用范围

适用于使用以下技术的 PMA 管理的 SPA 和内部工具前端项目：

• React + TypeScript + Vite
• TanStack Router，用于基于文件的类型安全路由
• TanStack Query，用于服务端状态
• Zustand，用于仅限 UI 的客户端状态
• shadcn/ui (base-nova)，搭配 @base-ui/react 和 Tailwind CSS——唯一允许使用的 UI 生态系统（references/baseline.md UI Library Policy）

以上技术均采用最新稳定版本；本技能不指定版本（参见 /pma references/workflow.md Dependency Freshness）。

默认采用单应用布局。只有当仓库确实承载多个应用或共享包时，才使用 Bun monorepo——仅将一个 SPA 加到 Rust 或 Go 服务中的情况无需使用工作区。

不适用于以 SSR 为主的网站、内容网站或非 PMA 项目。

加载顺序

1. 始终先加载 references/baseline.md。
2. 涉及路由结构、providers、主题、Tailwind 或 shadcn/ui 时，加载 references/routing-and-ui.md。
3. 涉及 API 集成、查询状态、i18n、Vite 配置或前端开发脚本时，加载 references/runtime-and-data.md。如需了解完整的 nsl 协议（注册模式、--strip、NSL_PORT、回退），加载 /pma references/dev-environment.md。
4. 涉及发布检查、测试、无障碍或安全敏感的 UI 行为时，加载 references/review.md。

快速路由

• 新建应用或重组仓库（单应用还是 monorepo）→ references/baseline.md
• Router、布局、providers、入口点、shadcn、Tailwind、主题 → references/routing-and-ui.md
• runtime（HTTP 客户端、查询客户端、i18n、Vite 配置）→ references/runtime-and-data.md
• 开发 URL 路由（nsl）→ references/runtime-and-data.md（完整协议 → /pma references/dev-environment.md）
• 测试 → references/review.md
• CI 和交付（lint、typecheck、build、无障碍、安全审查）→ references/review.md

参考资料包

• references/baseline.md 技术栈默认项、质量门槛、工作区布局、约定和基线脚本。
• references/routing-and-ui.md TanStack Router 布局、provider 组合、入口点、shadcn/ui、Tailwind 和主题。
• references/runtime-and-data.md 查询客户端、HTTP 层、状态边界、i18n、Vite 配置和前端 nsl 调用。完整 nsl 协议位于 /pma references/dev-environment.md。
• references/review.md 验证门槛，以及 UI 变更的无障碍和安全审查清单。

验收清单

合并前：

• lint、typecheck、build 均通过
• 测试通过且包含覆盖率；目标为 80% 或更高
• 遵守 UI 限制：不得使用 Radix 或其他组件生态系统（grep 门禁见 references/review.md）
• 新组件遵循 references/baseline.md UI Library Policy 中的来源顺序
• 路由保持基于文件的形式，位于 src/app/routes/ 下，并使用生成的 routeTree.gen.ts
• 主题保持双通道（:root / .dark 变量 + @theme inline 映射）；组件中不得硬编码颜色
• nsl 开发路由正常工作（bun run dev 提供 <name>.localhost；API 可通过 /api 访问）

如果项目有意偏离这些默认设置，请在提案中明确说明偏离之处，并始终与仓库现有模式保持一致。