写业务页面时最常用的三样东西:组件沙箱里能看到组件库的每个组件、调它的属性、直接复制代码;组件库 packages/ui 不依赖仓库里的任何业务包,可以整包搬进别的 React 项目;前后端契约 packages/api 从后端的 OpenAPI 离线生成类型。

在界面上哪里找?
Section titled “在界面上哪里找?”| 入口 | 路径 | 谁能用 |
|---|---|---|
| 侧边栏「开发工具 → 组件沙箱」 | /sandbox/components | 登录即可;沙箱开着时才在侧边栏出现 |
| 查询区演练 | /sandbox/query | 登录即可;从沙箱里的链接进,不在侧边栏 |
| 表格演练 | /sandbox/table | 同上 |
「开发工具」这个侧边栏节点不在菜单表里,是前端在沙箱开着时自己加上的,所以它不占权限码、在「菜单管理」里也看不到。沙箱开不开由参数配置「高级 → 开发」组里的 DEV_SANDBOX_ENABLED 决定:种子数据里是 true;库里没有这一项时,开发环境默认开、生产环境默认关。上线前不想让人看到,就在参数配置里关掉。沙箱判断开关走的是一个只读这两个布尔值的专用接口,不需要参数配置的查看权限。
组件沙箱里有什么?
Section titled “组件沙箱里有什么?”49 个演示,分成输入与表单、数据展示、反馈与状态、弹层、导航、表格、成套能力、主题几组。页面三栏:
- 左:挑组件,可以搜索
- 中:舞台和代码。旋钮一改,舞台实时变,代码跟着变 —— 代码里只列和默认值不同的属性,复制走就能用
- 右:旋钮(这个组件能调的属性)
每个演示还写着用在哪、别用在哪和源码路径。当前看的是哪个组件、搜索词写进地址栏,链接发给别人打开就是同一屏;旋钮值不进地址栏(它是草稿,换个组件就没意义了)。
调色盘(主题分组里)读的是页面上真实生效的颜色令牌,不是硬编码的色卡:在个人中心切换主题色、深色模式,这一页跟着变。它还能看圆角和字级。业务代码里的颜色只该从这些令牌来,不手写 #rrggbb 或 emerald-500。
查询区(QueryBar)和数据表格的可调项太多,沙箱的小舞台放不下,各有一个单独的演练页,把它们的配置项摆开来试(表格那页能切服务端分页 / 全量滚动、分组、排序、拖拽、密度和斑马纹)。
能把组件库搬进别的项目吗?
Section titled “能把组件库搬进别的项目吗?”能,这是刻意设计的:packages/ui 对仓库里其他的包一处 import 都没有(连语言包都是运行时注入的),pnpm arch:check 在 CI 里守着这条。步骤在 packages/ui/PORTING.md:
- 拷
packages/ui下的组件和样式 - 装它依赖的 npm 包
globals.css必须一起拿走,并把 Tailwind 的@source指到你自己的源码目录 —— 指错了不会报错,表现是按钮全变成白底黑字- 翻译三选一:什么都不接(显示中文原文)、接你自己的 i18next、或者把翻译拆掉
- 照文档最后的清单验一遍:按钮有没有底色、表格滚动时表头有没有钉住、分页条上是
共 42 条还是共 {{total}} 条、深色模式是不是整体反过来
还有一份可读的组件目录在 packages/ui/AGENTS.md,写着每个组件什么时候用、尺寸覆盖为什么不生效这类坑。
前后端契约是怎么来的?
Section titled “前后端契约是怎么来的?”pnpm --filter @admin/api gen:api 直接 import 后端的 FastAPI 应用拿 OpenAPI,生成 packages/api/src/schema.d.ts。不用起后端服务(生成契约和运行时无关)。后端接口改了之后跑一次。
这个包里还有请求客户端和成败判定:只有信封里 code === 200 才算成功,HTTP 200 不够 —— 后端的 fail() 返回的是 HTTP 200 加 code: 400,只看 HTTP 状态码会把所有业务失败读成成功。
类型推断的现状要说清楚:
- 移动端的每个请求都从
schema.d.ts推断路径、参数、请求体和返回字段,接口改了而页面没跟上,pnpm typecheck直接报错(突变验证过:写错字段名、路径、请求体字段、查询参数名,四种都报)。 - 网页端还没切过去:请求封装是
api.GET<T>(path: string),路径是普通字符串、返回类型T在各调用点手写,所以后端改了字段名,网页端的类型检查发现不了。挡着它的是几处结构性问题(动态拼出来的路径、约 20 个页面用函数拼查询串),细节在packages/api/AGENTS.md。
还有哪些守着代码的检查?
Section titled “还有哪些守着代码的检查?”都在 CI 里跑,本地也能跑:
| 命令 | 查什么 |
|---|---|
pnpm typecheck --force | 类型。要加 --force:turbo 缓存命中时打印的是上一次的日志 |
pnpm lint | 每个包的 ESLint(用 pnpm <任务> 跑,不要 --filter 某个包,否则别的包从来没被检查过) |
pnpm arch:check | 包之间的依赖方向、页面不许直接读路由、隐藏页签里的全局 DOM 查询、功能引导的目标元素存在…… |
pnpm i18n:check | 中英文案的键齐全 |
pnpm ctx:check | 各目录 AGENTS.md 里提到的文件、脚本、testid 还在不在 |
这些规矩的来龙去脉写在根目录的 CLAUDE.md「硬纪律」一节。
- 组件沙箱只演示
packages/ui的组件,不演示业务页面。 - 「开发工具」节点不在菜单表里,没法用角色权限控制谁看得到 —— 开着就是所有登录用户都能看。
- 网页端的接口类型还没从契约推断,见上文。
- 组件沙箱:
pages/dev-sandbox/(demos/是每个演示,api.ts是开关判断)· 演练页pages/playground-query/·pages/playground-table/· 侧边栏节点在shell/use-sidebar.ts - 组件库:
packages/ui/· 主题令牌packages/ui/src/styles/globals.css - 契约:
packages/api/(生成脚本scripts/gen.mjs) - 检查脚本:
scripts/
在演示站里试试
Section titled “在演示站里试试”在线演示(admin / 123456):侧边栏最下面「开发工具 → 组件沙箱」,选「按钮」,在右边把变体改成 outline、尺寸改成 lg,看中间的代码只多了这两个属性;再到「调色盘」,去个人中心切一下主题色回来对比。