跳转到内容
GitHub

开发者工具

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

组件沙箱:按钮
入口路径谁能用
侧边栏「开发工具 → 组件沙箱」/sandbox/components登录即可;沙箱开着时才在侧边栏出现
查询区演练/sandbox/query登录即可;从沙箱里的链接进,不在侧边栏
表格演练/sandbox/table同上

「开发工具」这个侧边栏节点不在菜单表里,是前端在沙箱开着时自己加上的,所以它不占权限码、在「菜单管理」里也看不到。沙箱开不开由参数配置「高级 → 开发」组里的 DEV_SANDBOX_ENABLED 决定:种子数据里是 true;库里没有这一项时,开发环境默认开、生产环境默认关。上线前不想让人看到,就在参数配置里关掉。沙箱判断开关走的是一个只读这两个布尔值的专用接口,不需要参数配置的查看权限。

49 个演示,分成输入与表单、数据展示、反馈与状态、弹层、导航、表格、成套能力、主题几组。页面三栏:

  • 左:挑组件,可以搜索
  • 中:舞台和代码。旋钮一改,舞台实时变,代码跟着变 —— 代码里只列和默认值不同的属性,复制走就能用
  • 右:旋钮(这个组件能调的属性)

每个演示还写着用在哪、别用在哪和源码路径。当前看的是哪个组件、搜索词写进地址栏,链接发给别人打开就是同一屏;旋钮值不进地址栏(它是草稿,换个组件就没意义了)。

调色盘(主题分组里)读的是页面上真实生效的颜色令牌,不是硬编码的色卡:在个人中心切换主题色、深色模式,这一页跟着变。它还能看圆角和字级。业务代码里的颜色只该从这些令牌来,不手写 #rrggbb 或 emerald-500。

查询区(QueryBar)和数据表格的可调项太多,沙箱的小舞台放不下,各有一个单独的演练页,把它们的配置项摆开来试(表格那页能切服务端分页 / 全量滚动、分组、排序、拖拽、密度和斑马纹)。

能,这是刻意设计的:packages/ui 对仓库里其他的包一处 import 都没有(连语言包都是运行时注入的),pnpm arch:check 在 CI 里守着这条。步骤在 packages/ui/PORTING.md:

  1. 拷 packages/ui 下的组件和样式
  2. 装它依赖的 npm 包
  3. globals.css 必须一起拿走,并把 Tailwind 的 @source 指到你自己的源码目录 —— 指错了不会报错,表现是按钮全变成白底黑字
  4. 翻译三选一:什么都不接(显示中文原文)、接你自己的 i18next、或者把翻译拆掉
  5. 照文档最后的清单验一遍:按钮有没有底色、表格滚动时表头有没有钉住、分页条上是 共 42 条 还是 共 {{total}} 条、深色模式是不是整体反过来

还有一份可读的组件目录在 packages/ui/AGENTS.md,写着每个组件什么时候用、尺寸覆盖为什么不生效这类坑。

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。

都在 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 的组件,不演示业务页面。
  • 「开发工具」节点不在菜单表里,没法用角色权限控制谁看得到 —— 开着就是所有登录用户都能看。
  • 网页端的接口类型还没从契约推断,见上文。

在线演示(admin / 123456):侧边栏最下面「开发工具 → 组件沙箱」,选「按钮」,在右边把变体改成 outline、尺寸改成 lg,看中间的代码只多了这两个属性;再到「调色盘」,去个人中心切一下主题色回来对比。