Peach: Local-first video metadata scraper and media manager.
前端层
本页说明前端构建、挂载契约和页面迁移。按任务进入:
Peach 按 ADR-0031 接入 React + Tailwind + BoardUI。主界面由 frontend/src/react/bootstrap.tsx 启动 Application,应用域控制器负责骨架、容器和页面助手,React 路由树负责客户端导航、页面与详情内容。主界面的入口是 peach-app.js 与 peach-app.css,低频页面按路由拆成带内容哈希的 chunk(ADR-0118),控制器与组件引用同一源码图。
只有一条不可变的约束:运行时没有 Node。Python 服务、PyInstaller 包和 macOS 上的
检出都直接读 web/,所以构建产物提交进 Git,不用任何 CDN。
目录与产物
| 路径 | 是什么 |
|---|---|
frontend/src/react/bootstrap.tsx、application.tsx |
主界面启动入口与 Application 生命周期;配置共享状态、挂载路由树、启动应用域控制器并在卸载时清理 |
frontend/src/api.ts |
带 AbortController 的取数封装 |
frontend/src/management.ts |
数据管理首屏 Fieldset 与网盘能力显隐 |
frontend/src/appearance/ |
外观与版式设置(@peach/appearance):偏好 store、主题、强调色、密度、卡片版式与光晕配色。别名直接解析到本目录,控制器与组件读写同一实例 |
frontend/src/core/ |
DOM 取元素、请求、转义、格式化与路由常量(index.ts)、标签显示名(tags.ts)、番号标题(jav-title.ts)。@peach/legacy/* 是源码别名,主包直接包含唯一实现 |
frontend/src/ui-kit/ |
共享控件与模板:滚动条、Collapse、锚定菜单、Select、来源站标、读数动效、骨架、横滚、开关、拉条、确认框、音效与中段截断。@peach/legacy/ui 直接解析到 index.ts;独立页面包仅打入用到的控件 |
frontend/src/onboarding/ |
安装后教程状态(post-setup-tutorial.ts):本地键、签名与请求代际,控制器直接引用共享源码 |
frontend/src/application/ |
按职责拆分的应用适配:目录、关注、实体、索引、布局、导航、媒体与全局动作。initializeApplication 按启动次序连接控制器,副作用由生命周期管理 |
frontend/src/react/pages/ |
独立页面包:index.tsx 是 vite.pages.config.ts 的构建入口,按挂载点的 data-page 画 SPA 外壳之外的三张页:首启(setup/)、登录(login/)与错误页(error/)。auth-card.tsx 是它们共用的外框 |
frontend/src/react/ |
路由页面、常驻组件与组件;entry.tsx 是内部命令式适配,application-residents.ts 连接常驻组件,bundle.d.ts 声明内部接口,boardui/ 逐字复制上游源码 |
frontend/src/query/ |
全站唯一 TanStack Query 客户端(@peach/query)与共享来源查询。Application 的 fetchQuery、页面 prefetch 和 Providers 读同一实例;media-sources.ts 声明 /api/sources 与查询键 |
frontend/src/react/query.ts |
React 子树里取那一个客户端的入口,转出 @peach/query |
frontend/src/history/ |
全站唯一浏览器历史(@peach/history),与路由树共用 React Router 的 createBrowserHistory。地址经 shellNavigate 写入;覆盖条目在 usr 中记录背景,启动不读取背景 |
frontend/src/shell/ |
目录口径、选择集、详情来处与一次性请求的共享单例。控制器与组件直接引用活绑定;整体换值用 writeShell,原地修改后用 notifyShell 通知订阅者 |
frontend/src/react/router/ |
客户端导航:<Router> 接管那一份历史,后退前进由它自己处理;每条路径的页面(管理区、播放列表页、关注页、目录网格、索引页、资料页与沉浸)、覆盖组的详情与队列,以及首页筛选条、新作行、处理横幅与搜索下拉这四个页面内组件由它画(managed-routes.tsx);页面组按条目记的背景匹配,覆盖组按真实地址匹配详情与队列 |
frontend/src/catalog-bars.ts |
首页筛选栏与侧栏的两份聚合:['facets', 口径] 与 ['tops', 参数, 口径],续页 ['tops', 参数],30 秒复用,状态页名单为空时退回全库口径;壳的 getBarsData 只算参数串 |
frontend/src/react/components/ |
Peach 自己的组合件(说明条、进度、空态、等待点),BoardUI 注册表里没有对应条目的那些 |
frontend/src/react/taste/ |
口味页:taste.ts 是契约与几何算法,charts.tsx 是雷达/名次条/热力/桑基,taste-page.tsx 是整页 |
frontend/test/ |
vitest 用例与遗留模块的桩;test/react/ 直接挂组件,*-routes.test.tsx 走路由树的开收契约 |
web/dist/peach-app.js、peach-app.css |
主界面入口,进 Git,固定文件名,由 web/index.html 引用;服务端通过 /dist/{name} 提供,ETag 复验 |
web/dist/peach-app.<名字>-<哈希>.js |
低频页面的 chunk,进 Git,由入口动态导入;服务端只认这一种形态,按长期不变缓存。每次构建先删上一批,提交时连同删除一起暂存 |
web/dist/peach-pages.js、peach-pages.css |
首启、登录与错误页的独立构建产物,进 Git,固定文件名。主包构建后追加构建(emptyOutDir: false);只有这两份产物允许免登录读取 |
首次运行页(未配置时的 GET /)、登录页(GET /login)与浏览器导航撞上的错误页是 SPA
外壳之外的三张独立页面。服务端对三页都只回同一张薄壳(web_entry.page_shell()):主题预读
脚本、Inter、/dist/peach-pages.css、挂载点 #peach-page,data-page 取 setup、login
或 error,服务端才知道的变量写成挂载点上转义过的 data-*(登录页的 next、invalid、
error,错误页的 status、detail),首启页另带表单用到的三枚雪碧图字形。页面整个由页面包
/dist/peach-pages.js 用 BoardUI 画出,所以三页都离不开脚本:禁用脚本时只剩空白页。
- 首启页的题目取自
GET /api/setup/questions,提交走POST /api/setup,形态见docs/OPERATIONS.md「首次设置的内部流程」。 首启与配置页共用媒体目录行,只展示运行 Peach 的设备能读取的目录;Docker 填容器内目录。页面不展示内部路径输入。请求可省略root,服务端补齐数据库路径;已有行仍携带原root,修改媒体目录时保留对应关系。 - 登录页是原生
<form method="post" action="/login">,字段token、next、勾选时days=30。POST /login拒收时(口令错、429、400),HTML 请求回登录页并原位报错,状态码 照旧,其余回 JSON。 - 错误页按
status定标题(403、404、409 各一句,其余一句通用),404 不显示说明,只给一个 「返回首页」。 - 三页用原生滚动条,不挂覆盖式滚动条。
页面包自成一份,不加载主包 peach-app.js,也不建 Query 客户端,
请求用裸 fetch。原因有三条:未配置的机器还没有数据库,主界面那一套一上来就打 /api/items;
首启只开一次,不为它改动每天加载的主包或拆出共享块;登录页在没有会话时就要画出来,免登录面只多这两份产物,不连带主界面的包。和配置页共用的控件(媒体目录行、密码与确认两格、忙态属性)在
frontend/src/react/settings/,两边各自打进自己的包。@peach/legacy/ui 在页面包里由别名落到
pages/legacy-ui.ts,只把来源站标与折叠的源码打进独立包。
样式层:pages.css 与主界面的 styles.css 共用 base.css(暗色变体、Inter、阴影 token 与
.peach-react 容器基线、输入框静止态边线),Preflight 同样限定在 .peach-react 里,薄壳把这个类挂在 <body> 上,弹出层落进 body 也在范围内。
styles.css 以 @source not "./pages" 排除页面包,三页的工具类只进 peach-pages.css。
深浅色读 localStorage 的 peach.settings.v1,同时写 data-theme 与 <html> 的 .dark。
完成态在独立包上过 RESTART_REDIRECT_MS(frontend/src/react/restart-redirect.ts,与配置页
保存后的跳转同一个数)自动跳到入口。
配置页
配置好之后改文件夹与端口的那张页整个是 React(frontend/src/react/settings/,入口 configuration-page.tsx)。/configuration 是唯一的编辑页,进管理菜单;媒体库选单、统计页与首次配置引导都指向它。
- 结构:一条窄列里排「通用 / 媒体 / 下载 / 网络与访问 / 维护」五组,每组一个
h2.ui-configgroup小标题,没有内容的组连标题一起省略。页面自己画顶上那排页签(.ui-board-local-nav,role="tablist",方向键与 Home/End 在整排里走),一组一格,一次只显示选中的那一组;页签条和整页同一次提交画出,第一帧就在。 - 数据契约是
/api/configuration(src/peach/routes_configuration.py)。端点字符串只在frontend/src/configuration-endpoints.ts声明一次,整页和设置弹层的摘要卡读同一个queryKey。 - 第一帧必须同步:壳挂完这一页紧接着按地址里的
#peachProxy滚到那一块,所以路由树用flushSync画第一帧,往后的更新照常异步。.ui-configpage的第一层依次是页签条、各组的小标题与面板;每组的根节点就是那一格role="tabpanel",选中的那一组带ui-board-group-active。 - 跳到某一组:React 页面(统计页「添加媒体」、诊断页、关注管理的凭据入口)直接链到这一组的地址
/settings/<组>,页面按地址定第一帧选中哪一格;遗留层的空库提示与媒体库选单「管理媒体库」把组名记进壳单例configurationRequestedSection,壳打开这一页时作为open.section交进去、页面画上之后清空。 - 设置弹层「这台电脑」一格只挂
configuration-summary(configuration-summary.tsx):媒体库数、端口、更新状态和「打开配置页」,不放可编辑的控件(ADR-0050)。媒体库数取/api/configuration的library_count,由服务端按media_libraries.libraries分组数好,页面不自己归并。 - 相邻的两处不在这页:媒体修复是数据管理页 React 子树里的一张卡(
frontend/src/react/media-repair/),订阅源是关注管理页的「订阅源」页签(follow-manage/feed-sources.tsx,读/api/feeds)。 - 服务端检查部署方式和请求来源:桌面服务由托盘管理且请求来自本机;Docker 服务由容器入口管理,允许经过登录验证的本机或私有网络请求,拒绝携带代理转发头的管理请求。
/healthz按调用方返回configurable,页面据此显示配置入口;入口隐藏不能替代服务端访问检查。 - 表单校验的原因由服务端按字段给(400 的
errors),页面写回原位,不在前端复制判定。 - 浏览器直接导航撞上
HTTPException时,api.py的处理器按Accept回一张 HTML 错误页(routes_pages.error_page,薄壳由页面包画),/api/下和非导航请求仍回 JSON。
索引页
/performers、/creators、/studios、/agencies、/tags 五张索引页整个是 React(frontend/src/react/index/,入口 index-page.tsx),由路由树画进 #index。
- 地址栏是唯一真相。索引元素从地址读出
q、scope、view、category,经openManagedRoute作初值交给页面;页面换档只改自己的状态,经ShellActions.routeIndex交壳,由shellNavigate写回地址并认领,不重挂。后退前进到另一份 search 时领新的页面打开序号,按地址重开。从侧栏进来一律回到本地、字母表、全部类型。 - 本地名册与词表读
/api/index,在线那一档读/api/follow/authors与/api/follow/tags,键建在frontend/src/react/follow/online-vocab.ts,归关注那一侧。四份都是useInfiniteQuery,「载入更多」取下一页;打字过滤时新结果到手前留着上一份,不铺骨架。 - 圆框里那段 HTML 由
card-art/markup.ts的avatarInner拼,经壳的personAvatar递进来;原尺寸摆图、补底与首字母收起的规则在web/css/01-base.css的[data-person-ring],量图的是installCardArt()挂在文档上的load监听。 - 顶栏选择键归壳,选择模式记在
@peach/shell的 store 里:索引元素订阅它,推给画着的本地标签页;关掉时页面清空所选。所选标签的操作条三颗键都不写账本,「显示结果」回目录按所选标签筛选。 - 数据回来之前的骨架由索引元素写进
#index,模板在frontend/src/index-skeleton.ts(正文那段是ui-kit/skeleton.ts的indexSkeletonHtml),页头骨架与页面同一组文字。本地艺人那一排身份分类在骨架里就是最终长相,词表与骨架都在frontend/src/identity-filter.ts,页面与骨架模板共用。
资料页
/performers/:name*、/studios/…、/creators/…、/series/…、/agencies/… 五类资料页是同一个 React 页面(frontend/src/react/entity-page/),在 ENTITY_ROUTES 里按 /performers/* 这样的模式登记,由路由树按匹配画进 #index;种类与名字由元素从地址读出(先 decodeURIComponent 再匹配,名字里的斜杠吃掉剩下全部段)。
- 资料卡、筛选浮层、新作那一行与正文是同一页的四块。资料页元素排好框架(加载骨架的形状仍由壳经
ShellActions.entity.loading画,它依赖目录的形状名单与卡片比例),经openManagedRoute的place在首屏取齐那一刻换进#index,页面画进资料卡那一格,再 portal 进另外三块:浮层吸顶要它的父盒就是#index,新作那一行是遗留层卡片、不进.peach-react。 - 地址栏是筛选与媒体视图的唯一真相。页面改筛选调
actions.route,壳的routeEntityPage写好地址再经updateManagedRoute推回新的filters/media;版式、选择态与展示设置由pushEntityPage推。后退前进落在同一位的另一份筛选上时只推新值,不重挂;刷新经revision加一重取。 - 筛选条的语境由
currentBarsContext()推:作品详情开着时用openItem记下的那一份,#index里画着资料页时按那一页的 props,其余用首页那份。
播放列表页
/playlists 列表页整个是 React(frontend/src/react/playlists/,入口 playlists-page.tsx),登记在 BROWSE_ROUTES,由路由树画进 #stats;点开一份之后的 /playlists/:playlist/:item 仍是遗留层 openPlaylist。这一页不进 isManagedPath,页面里的跳转都交壳。
- 读
/api/playlists,首屏prefetch写明staleTime: 0:首页刚存的 Mix 进来就要看得到。新建、改名、删除都 POST/api/playlist,写完让列表键重取,不拿回话拼缓存。 - 删除先过遗留层
confirmModal,删之前 GET?id=取回内容,撤销按原内容与来源重建一份;取不到就不给撤销。回执与撤销失败的说法归actionReceipt。 - 页面画着时壳要求重读(顶栏「换一批」),壳把
@peach/shell的playlistsRevision加一,页面只重取、不重挂。从播放队列返回、后退前进与侧栏进来都整页打开一次。 - 每份列表是共用的 Mix 卡
components/mix-card.tsx:纸边、黑底封面、玻璃徽标、叠放头像,几何写在styles.css的[data-mix-*];悬停翻页是components/use-stack-flip.ts(关注页卡叠也用它),时序钉在use-stack-flip.test.tsx,翻页门槛(多选、遮挡、减少动效、滚动中)由壳经ShellActions.canFlip递进来。 - 改名弹层、换头像与裁剪封面共用
components/modal-frame.tsx的外壳,form档 540px 同ui-kit/modal.css的.ui-geist-modal。
关注页
/follow 列表页整个是 React(frontend/src/react/follow-feed/,入口 follow-feed-page.tsx),登记在 BROWSE_ROUTES,由路由树画进 #stats。它不进 isManagedPath,由 frontend/src/react/router/pages/follow.tsx 的元素按匹配打开;重新进入时重掷种子由壳写进 store,元素按 store 的代次重取。
- 地址栏是筛选的唯一真相。页面改筛选、排序、换一批调
actions.route,壳的routeFollowFeed写好地址并认领,再经pushFollowFeed把新的view/seed用updateManagedRoute推进画着的那一页:代次不变、不重挂。判据是#stats的managedEntry记着/follow。 - 助手与动作是壳里各一份、身份不变的对象(卡片按引用比较),跟着打开交进来,不进
ShellActions。标签的界面名称列表页与卡片直接从@peach/legacy/tagsimport。 - 骨架淡出:关注页元素经
place交自己的reveal,它在revealSkeleton的 write 里只放空宿主,页面紧接着在同一个任务里画进去,骨架淡出时底下已是整页。 - 深链
/follow/item/:id开在舞台里:壳的renderForDetail只让出列表区,回到列表时才画;followDetailActions、openFollowDetail、closeFollowDetail按「列表页还画着」决定就地关还是重开。
馆藏网格
目录(/ 与筛选态、/trash)、资料页作品区和详情页的接着看画的都是同一张网格(frontend/src/react/catalog-grid/)。作品卡是 components/media-card.tsx,Mix 卡用播放列表页那张 components/mix-card.tsx。三种取数按 mode 分:
catalog登记在CATALOG_ROUTES,由路由树画进#grid。表按页面分键:目录各路径与回收站都用/打开,槽里的路径说的是画着哪一页、不是地址;CATALOG_PATHS只进<Routes>的声明,不进isManagedPath。筛选态是壳的state,打开时连同版式、选择态、助手与动作整份交进来;之后壳的paintGridPage看#grid的managedEntry:画着就经updateManagedRoute推新筛选与revision,查询换键重取、不重挂;首屏还在途就重开一次。冷启动经place交revealRoutedPage,骨架淡出与整页同批交接。读数行#count的结构归壳,读数那一格、#loadSentinel的自动续页、Mix 落位、竖屏带与分卷/版次折叠都在页面里。判据钉在test/react/catalog-routes.test.tsx。- 垃圾文件队列(
/junk-files,frontend/src/react/junk-queue/)不是这张网格,是CATALOG_ROUTES的另一页,同样画进#grid:打开前不取数,画上就铺自己那份骨架;换分类、换视图与处置后重读经updateManagedRoute推进来。它与目录网格换页时先由clearCatalogGrid收,计数行里归它的那一格随之同步撤掉,壳再往#count铺骨架。 entity由资料页正文entity-body(frontend/src/react/entity-body/)直接渲染在它的作品视图里,不另挂岛:第一页随资料页首屏一起取来,续页由资料页按查询键取。同一块的另两个视图是名册(索引页的PeopleGrid)与照片墙(样张分段在前、本地图片在后;直接打开 React 灯箱(photo-lightbox/),定位源文件调actions.revealSource)。items挂在#nrow上:壳手上已有那一批,岛只画卡。- 馆藏表格由
catalog-list-page.tsx渲染,默认依次显示名称、时长、分辨率、体积、星级评分和观看次数。「显示列」可开启番号、高潮计数、观看时间、入库时间和发行时间;全部列按身份、媒体规格、个人记录、时间信息排列。隐藏某列仍可按该字段排序。名称过长时省略显示,悬停可查看全文。拖动表头分隔线调整列宽;键盘操作时聚焦分隔线,按 Enter 进入调整,再用左右方向键改变宽度,按 Enter 或 Tab 结束。列宽与显示选择保存在当前浏览器;「重置列宽」恢复默认宽度,「恢复默认显示」恢复默认列。桌面和手机均在表格内横向滚动,不扩大页面宽度。 - 表格的表头和行分隔线铺满外框,右侧余量由独立空白列承接,保存的列宽保持不变。鼠标按住非控件区域可左右拖动所有数据表格,滚轮维持浏览器行为。馆藏表格只在手动开启多选后显示勾选框,底部「取消」清空选择并退出多选。评分与详情页共用
RatingStars:点击星星保存,再点当前星级取消;保存失败时在原单元格显示原因和「立即重试」(无障碍名称「立即重试评分」),成功回执提供撤销。 - 所有数据表格共用
TableColumnControls、useTablePreferences和DataTableFrame,提供显示列、恢复默认显示、重置列宽及鼠标/键盘调整列宽。各表单独保存浏览器偏好;身份列与勾选列保留,其余列可隐藏,排序菜单继续列出可排序字段。馆藏、关注来源、JAV 订阅源、两张别名表和数据管理表均使用这套组件。 - 关注来源与 JAV 订阅源的表头提供「全选本页」,再次点击取消本页选择。表格链接只占文字或图标本身的范围;管理表空白处用于选择行。关注卡片每条来源的站点图标放在行首,JAV 订阅源站点复用缓存的
SiteLabel图标。 - 已保存别名的「修改统一名称」打开改名对话框,可输入名称或直接选用已有别名。
POST /api/follow/author-alias接受action: "rename"、canonical_key和canonical;原名称保留为别名,关联的创作者名称及作品创作者字段在同一事务中同步。名称冲突或关联多个创作者档案时返回错误并回滚。 - 外置按钮控制的正文使用
CollapseRegion,原生详情使用Disclosure;两者共用ui-kit/collapse.ts的高度过渡和反向点击保护。关注卡片、任务通知、教程及侧栏保留正文状态,箭头使用同一元素旋转;详情标题箭头共用CollapseChevron。减少动态效果时遵守全站设置。 - 排序方向共用
IconSwap的双图标结构与--motion-swap,覆盖数据表、关注管理及实体/关注页排序;键盘操作即时更新。换批按钮保持同一枚 shuffle SVG,等待时继承共享描线参数;首页、实体和关注浮层共用这套忙态。JAV 详情的标题和元信息通过data-reveal-line接入 Stage 既有逐行揭示与清理。 - 版式、选中态与快进秒数经
updateManagedRoute(资料页作品区经pushEntityPage)推进来:换版式只重画,已载入的分页原样保留。selected每次推一个新的Set。 - 卡上的悬停预览、封面取景与图片微光都在
frontend/src/card-art/:卡片直接调wireHover/releaseHover(状态写在卡的data-previewing/data-longhover上)与relayoutCovers,微光由installCardArt装的监听按PENDING_IMAGES认[data-media-art]>img;壳只经configureHoverPreview告诉悬停预览多选态、打码与延迟。卡片的结构钩子全是data-media-*;悬停预览插进封面格的video.hv、img.ui-hvframes与封套img.poster用自己的类名;.ui-hvframes的样式在同目录的card-art.css,另两样在12-cards.css。 - 离场:去目录、回收站与垃圾文件以外的页面时由
clearCatalogGrid收#grid那一页(claimSurface只收#stats与#index);资料页正文随资料页由releaseManagedRoute收起;接着看是作品详情里的子组件,随舞台的内容一起卸。 - 屏外卡用
content-visibility跳过封面与元信息区的渲染,不做虚拟列表。 - 单卡写操作都由用户点击触发:稍后看走
actions.watchLater,回收站卡的还原走actions.resourceOperation,做完给撤销;彻底删除只在批量条上,先过confirmModal的危险档。
舞台与播放器
作品详情与关注详情都开在常驻组件 stage 里(frontend/src/react/stage/),由路由树画。宿主 div[data-stage-host] 是 body 的直接子元素、整页只有一个、换详情不换,不包 .peach-react;这一面拥有 dialog#stage、进出场、骨架、关闭键 #closeStage 与小窗 #miniplayer,两座详情是它的子组件,与页面共用同一份 Query 缓存。
- Application 使用命令式入口:
loadStage(host)第一次打开详情时连接常驻组件,configureStage接上播放器,再经openResidentSurface('stage', …)建宿主、在画出小窗节点的同一个任务里挂到 body 末尾,画上之后才交出句柄;此后stageApi()同步可取,契约在stage/stage-api.ts。来处(detailReturnPath、followDetailReturnPath、detailOriginAnchor)、地址与顶栏上下文由应用域维护。 - 句柄写本模块的 store 再
flushSync通知:open(含原地换条)、update、dispose里每一次绘制都在返回之前画完,骨架量尺寸、showModal、标题揭示与焦点交给关闭键读到的是刚画好的结构。两座详情画出来时报给壳的present排到微任务里:壳收到后画侧栏与顶栏,那几座常驻组件的句柄也flushSync,在路由树的提交阶段里画不出来;那一条已经换走或舞台已经收起就不报。 - 舞台抛错时只卸组件:浮窗与小窗节点跟着消失,宿主与 body 上的
data-detail-open留着,之后句柄各成员照调不抛,空到刷新为止。 - 关掉详情 push 来处:点进来的是点卡那一页;同一个队列里换条不变,播放列表关掉回列表页并重读;后退前进进来的取条目记的背景(关注详情连筛选一起保住);刷新、新标签页与深链落在详情上不读条目,作品详情下面补画目录网格、关掉回
/,关注详情关掉回/follow。 - 焦点:骨架期间焦点停在 dialog 本身、不画焦点环,内容到了交给关闭键。Escape 先关最里层(右键菜单、标签搜索等弹层先吃掉),没人拦才关舞台。
- 播放器在
frontend/src/player/,用 vendored 的 Video.js。入口mountPlayer(video, options)把媒体框里的<video>换成 Video.js 并返回拆除函数;详情只画媒体框,挂载由舞台的attachStagePlayer做。 - 小窗与舞台共用同一个播放器实例:离开详情时正在放的那一个搬进小窗,展开回同一条时认领回来,不重建。显式关闭、暂停着、设置里关了小窗、换到别的条目时随舞台拆掉。交接判据钉在
test/stage-player.test.ts,真 Video.js 的行为在e2e/stage.test.ts。
侧栏与标签抽屉
左侧抽屉 #drawer 里滚动的那一层(#drawerScroll)是常驻组件 sidebar(frontend/src/react/sidebar/),由路由树画:导航那一列、导航上那块滑动玻璃(use-view-glide.ts,经 portal 画在 #drawer 上),以及按语境出现的筛选分组。抽屉本身、它的开合与遮罩、底栏三枚键、品牌与开合键归壳。
- 壳在启动时写一份骨架(
sidebar-skeleton.ts,与组件画的导航同一份顺序与按下态),随后loadSidebar(sidebarHost())经openResidentSurface('sidebar', #drawerScroll, place)登记进常驻表,宿主就是#drawerScroll本身,不包.peach-react。place在画首帧的同一个任务里清掉骨架;画上之后先调attached(壳把品牌与开合键挪进标题行的空槽),再交出句柄,此后sidebarApi()同步可取,契约在sidebar/sidebar-api.ts。覆盖式滚动条由壳挂在#drawerScroll上:轨道与边缘渐隐挂在#drawer里,滚动层本身只多几个属性、样式变量与监听,子节点全归组件。 - 内容由壳推:
paintSidebar(patch)合并content、filters、latest后调render。目录与资料页的聚合在buildBars里换成{kind:'catalog'},关注页与关注详情的内容标签由renderFollowDrawer推{kind:'follow'};就地改筛选时applyFilterStateInPlace只推filters,refreshFacetCounts只推latest。点下去的动作回到壳的navTo、commitContextFilter与关注页的筛选。render与navChanged写组件模块里的 store 再flushSync,返回时已经画好。 - 导航顺序读
appSettings这一份 store 的sidebarOrder:拖动排序先落 store 再写/api/settings,设置面板改顺序也写同一份 store,侧栏按通知当场重排。按下态换了由壳的paintNav调navChanged:它跑在route()的同步段里,玻璃拿到的是旧位置到新位置。 - 标题行
[data-sidebar-head]是组件画的空槽,品牌与开合键是壳挪进去的节点;组件不往这个槽里画子节点,重画不碰它们。 - 样式在
sidebar/sidebar.css,只认data-sidebar-*;组件里不写 className。行为在test/react/sidebar.test.tsx,量布局的玻璃滑动、拖动、各页计数与窄屏开合在e2e/sidebar.test.ts;当前项玻璃、标题行间距、时长拉条与窄屏遮罩的外观在e2e/design-detail.test.ts读计算值。
客户端导航
React Router 以 Declarative 模式接管历史(frontend/src/react/router/)。管理区十一页(统计、口味、复核、数据管理、重复文件、高清版、来源与凭证、配置、活动、关注管理、诊断)、五张索引页与五类资料页由路由树按匹配打开,/resource-sync 与 /configuration#libraryProcessing 由元素用 replace 改写到数据管理页;目录六条路径、播放列表页与关注页同样由路由树按匹配打开;作品详情、四种队列与关注详情由覆盖组按匹配送进舞台,沉浸由页面组的 /immerse 元素打开。壳没有路由表。
- 历史只有一份:
@peach/history直接解析到共享源码,随主包发出,壳的route()经shellNavigate写地址,<Router>的navigator也是它。路由树挂在一个不进文档的容器上,管理区那一页与播放列表页、关注页经 portal 画进#stats,索引页与资料页画进#index,目录网格与垃圾队列画进#grid。 - 元素打开那一屏的动作排在提交阶段之后的微任务里:侧栏等常驻组件的句柄内部用
flushSync当场画完,同一棵根在提交阶段里不会同步刷新。页面组的<Routes>里每条路径都挂着元素,/immerse也在这一组;它按条目usr.backgroundLocation匹配,详情压在哪一页上就还匹配那一页,启动那一条不读背景。覆盖组按真实地址匹配OVERLAY_PATHS(详情、四种队列、关注详情),元素把那一条详情送进舞台常驻组件,按派发序号挂 key。两组都不会报没有路由。 - 页面的宿主跟地址:元素挂上经
surfaceChanged让壳收起别的面,再由元素铺这一页的骨架,然后openManagedRoute(path, open, {container, isCurrent, place})。覆盖元素离开时,去处不是覆盖地址才收舞台。它领一个代次、先取首屏,取齐后在同一个任务里清掉骨架、放进.peach-react宿主(给了place就由它把壳排的框架换进容器、交出宿主),宿主用flushSync当场画完,骨架与正文之间没有空白帧;同一路径再打开就是新代次,页面重挂重取。三个容器各记一条、互不相收,releaseManagedRoute逐个点名容器:claimSurface收#stats与#index,showHomeSurfaces只收#index那一条,#grid只由clearCatalogGrid收,资料页压在管理页上时管理页藏着照常活;详情舞台推/item/:id不经过它们,页面留在舞台下面。打开之后壳的开关(选择键、资料页换筛选与版式)经updateManagedRoute(container, patch)合进画着的那一页:代次不变,不重挂、不重取,照常排进下一次渲染。 open只带那一次才算得出的值(地址上的分类与页签、只读状态、引导标记、配置页页签),由元素自算;回执与换到还归壳的那几屏走壳交给configureRouter(actions)的ShellActions,经 Context 下发。站内跳转交navigate(壳那边是actions.navigate,同样不认领),派发后由对应元素按页面打开序号打开。壳要重开画着的索引页或资料页(批量操作后重取、筛选回退、点开的正是画着的那一位)时把@peach/shell的pageOpens计数加一,元素整页重开;同一微任务里的换页与重开合成一次。元素从 effect 里写地址一律排进微任务并带存活守卫:路由根同步提交,提交阶段里同步写地址会出 flushSync 告警。配置页页签先交给壳再换地址,不进地址栏。判据钉在test/react/managed-routes.test.tsx。- 每次历史变化领一个
seq。页面元素经useOpenEpoch()读页面打开序号、按它挂 key:壳的shellNavigate写地址时当场认领,页面不重开;后退前进、React 子树里的navigate与壳的actions.navigate领新代次,页面重挂重取。覆盖元素按seq挂 key,接手该次详情请求;详情内改写地址时认领序号,不重复打开。队列打开意图经queueOpens交给元素,取齐数据后才写入实际队列地址。actions.navigate照route()写好标题,使用shellNavigate(path, {claim: false})。地址不变的popstate也领新序号与新代次。 - 路由根同步提交:
PeachRouter在历史变化的同一调用里flushSync换上新地址,shellNavigate与后退前进返回时两组<Routes>已经换好匹配、上一页的元素已经卸掉。派发不在这次提交里,仍排在其后的微任务。判据钉在test/react/router-sync.test.tsx。 - 管理区十一条路径的标题、侧栏身份(
section)与顶栏「换一批」的行为(refresh)登记在@peach/history的ROUTE_META:Application 启动与路由元素都直接读这份源码。壳的读者经routeMeta(path)读它;同一身份按登记顺序取第一条,数据管理排在重复文件与来源和凭证前面。 - 启动:壳完成来源、页面结构与运行态准备后推进
pageOpens,路由树按当前地址匹配首屏;启动条目不读取历史背景。Router 挂载前发生的后退前进,在挂载时按当前地址匹配一次。判据钉在test/react/router.test.tsx。
队列首屏取齐前,打开意图由源导航序号持有取消权。新的非覆盖导航(包括同地址 POP)撤回意图、清空待写地址并作废舞台代次;意图微任务、舞台装载和响应回调都检查取消状态。成功首屏在写队列地址前解除取消权,覆盖详情之间换条不会关闭新舞台。
产物缓存
产物使用固定文件名,由 web/index.html 与独立页面薄壳引用。服务端对 /dist/ 与 /app.css 返回 Cache-Control: no-cache 和 mtime+字节数的 ETag;浏览器每次重新验证,内容未变时返回 304。index.html 使用 no-store,确保入口能看到当前产物。
样式表分区
样式表按界面分区拆在 web/css/ 下,/app.css 把它们按文件名顺序拼成一份交付
(src/peach/routes_pages.py 的 stylesheet_response())。拆分只为让两处改动落在不同
文件上:一整份两千七百行的样式表,两个分支各改一处几乎必然撞在一起。页面仍然只取
一份 /app.css:不给首屏加二十来个阻塞请求,层叠顺序也不必写进 index.html。
两条规则:
- 两位数前缀就是层叠顺序,
sorted()出来的顺序即生效顺序。新增分区要同时改tests/test_web_ui.py里StylesheetPartitionTests.PARTITIONS:插在哪一档决定谁覆盖 谁,那是判断,不该由 glob 顺手发现。 - 切口只许落在花括号深度 0、注释之外。规则或
@media被切成两半时拼起来仍然完全 正确,只有单独看每一份才会发现,所以每份分区自己的花括号和注释必须闭合。
| 分区 | 覆盖 |
|---|---|
01-base.css |
主题变量、色板、字号、Geist 基元、滚动条 |
02-topbar.css |
顶栏与顶部三层 |
03-filterbar.css |
常驻筛选层、combo、页面提要 |
04-manage.css |
统计页、播单、复核、元数据、数据管理 fieldset |
05-insights.css |
Analytics/Speed Insights,以及口味页骨架的板块与指标条 |
06-index.css |
索引页首屏骨架、资料页名册格 |
07-entity.css |
实体资料页头、外链、相关人物 |
08-photos.css |
灯箱打开时的页面锁滚、共用折叠 |
09-skeleton.css |
Geist Skeleton 与各页骨架变体 |
11-identity.css |
身份组、演员与系列链接、重复项、质量清单、复核对照 |
12-cards.css |
壳自己画的卡片(垃圾文件、新作)、悬停预览层与密度 |
15-detail.css |
壳画的源文件管理(定位与目录对账) |
16-settings.css |
设置面板打开时的页面锁滚(面板归常驻组件 settings-panel) |
17-overlay.css |
Toast 与审查遮挡 |
18-chips.css |
产地选择与详情里次要操作的标签按钮(侧栏筛选标签归常驻组件 sidebar) |
19-immersive.css |
加载更多、空状态、选择条与批量条、窄屏总表(沉浸模式归常驻组件 immerse) |
21-online.css |
关注页骨架与关注详情(列表归路由树画的关注页) |
22-followmanage.css |
关注管理页 |
开发循环
改前端代码时怎么看到效果、怎么跑测试,以及提交前必须做什么。
npm --prefix frontend ci # 首次或改了依赖之后
npm --prefix frontend run dev # vite build --watch,改完存盘就重建 web/dist
npm --prefix frontend run build # 出一次正式产物,提交前必须跑
没有 dev server:index.html 归 Python 服务,页面照常从 Peach 自己的端口打开,
watch 模式只负责把产物写回 web/dist/。刷新页面就能看到改动。
测试与类型仍然只有一个入口:
& .\scripts\test.ps1 -Scope web # Windows;含 tsc、vitest、产物与契约断言
./scripts/test.sh web # macOS
vitest 转译时只剥掉类型、不做检查,所以 web 域另跑一遍 npm --prefix frontend run typecheck。
两者在本机没有 npm 或没装 frontend/node_modules 时显式跳过,不会让测试域变红;
CI(GITHUB_ACTIONS=true)里缺这些就判失败,由工作流负责装齐。「产物是否由当前源码构建出来」这一条本机验不了(不装 Node 就无法重建),
它的门槛在 CI 的 web-bundle job:npm run build 之后 git diff --exit-code -- web/dist。
改了 frontend/src 就必须重新构建并把 web/dist/ 一起提交,否则 CI 会红。
同一个域里还有真浏览器冒烟 tests/test_web_e2e.py:它在临时 Peach 数据目录上生成 12 条合成演示库、
起回环 peach serve --no-auth,再按批调起 node --test 跑 frontend/e2e 下全部用例(调度见 docs/TESTING.md)。冒烟用例在
frontend/e2e/smoke.test.ts,每条主路由在桌面与 390×844 下先等到目标页面主体出现(路由自己的标题,
加上内容区、索引条目或明确的空态),再断言:无页面异常与 console.error、无同源 4xx/5xx 与失败请求、
aria-busy 与 data-skeleton 会消失、无横向溢出、无越出视口的元素。主体一项不能省:页面完全没渲染时,
其余几条照样全部成立。新增路由要在 ROUTES 里写明它的主体。
浏览器取本机 Google Chrome(PEACH_E2E_CHROME 可指定),短片由 ffmpeg 编码;缺 npm、
playwright-core、ffmpeg 或 Chrome 时本机显式跳过,CI 里判失败。浏览器 CI 由 web-e2e 矩阵分片,
分片与平台范围以 测试与依赖 和工作流为准。界面验收里发现的同类问题,
先在这里补一条用例再修。
设计决定另有 frontend/e2e/design-*.test.ts(按页面区域分文件,共用 design-fixture.ts),读 getComputedStyle 断言用户定过的外观:React 输入框不带旧焦点环、
React 子树读到 BoardUI 的 token 原值、持久警示是状态色块、一张卡底下只有写入那一颗是主按钮。页面迁到 React 时,旧的源码字符串断言按 ADR-0031
分三类再删:设计决定进这里或 lint,行为进 vitest,布局与运行期进冒烟。
导航按用途定位:页面分区在正文上方;配置、复核与设置弹窗的分类目录在桌面左侧,窄屏移到正文上方;图表维度与显示方式用内容附近的分段控件。目录选中态使用填充,未选中项悬停只提亮文字。 配置保存使用主按钮,检查、添加、刷新与取消使用次按钮,移除使用删除按钮。安装教程与系统诊断入口使用单行设置;活动后继明细可展开和收起,进行中及失败的后继默认展开。
npm --prefix frontend run lint 检查 src/、test/、e2e/ 的 correctness 规则、严格相等比较和累积展开;== null 保留同时匹配 null 与 undefined 的语义。设计系统规则只作用于 src/react/,排除 BoardUI 与 EvilCharts 的上游副本。web 域与 CI 都跑。no-restyle 报在
BoardUI 组件上的间距或外观,处理办法是在组件外面套一层普通元素,不给规则加例外。
src/react/boardui/ 只加不改,UPSTREAM.sha256 记着复制时每个文件的哈希,由 tests/test_frontend_build.py 比对。
界面标注
指认界面上的某一块时,用 Agentation 在页面上点中元素、写下意见,
复制出 markdown 直接贴给智能体,不必再用话描述「侧栏那块光斑」。复制内容的多少由工具栏
Settings 里的 Output Detail 决定,设一次就存在这台浏览器里:默认 Standard 只有选择器;
Detailed 加上 class 与附近文字;Forensic 再加上带 id 的完整 DOM 路径(如
main#main > div#libraryProcessingNotice > …)和计算样式,交给智能体时用这一档。
npm --prefix frontend run build:agentation # 在要用它的那份检出里构建一次
然后在页面地址后加 ?agentation=on,仅在当前页面加载标注工具。刷新或重新打开页面时不会
自动加载;?agentation=off 也可用于关闭。浏览器中的持久开启标记在页面初始化时清理。
- 产物写到
build/agentation/peach-agentation.js,由/dev/agentation.js提供,口令同/dist/。 它不进 Git、不进独立包:Agentation 是 PolyForm Shield 许可,只许自用,不随 Peach 分发, 所以不放在会被打包整个带走的web/下。没构建过的检出里这条路由是 404,Application静默跳过。 - 产物是本机构建的:换检出、升级依赖之后重跑一次,刷新页面即生效。
- 标注里拿不到源文件路径:它靠 React 的
_debugSource,React 19 已移除这个字段;组件名也被peach-app.js的压缩改掉了。要在 Tailwind 类名之外给智能体更稳的抓手,给区块加data-component(Agentation 默认采集的属性之一)。 - Agentation 自己的全局快捷键已关闭,避免与 Peach 的 Esc、方向键冲突,只用工具栏按钮操作。
- 标注工具挂在自己的容器里;适配入口为它的 Shadow DOM 表单字段补齐名称。
- 标注同步到本机
agentation-mcp(http://localhost:4747),智能体用它的 MCP 工具直接读、 回复和标记已处理,不必复制粘贴。服务由注册了它的 Claude Code 会话拉起:claude mcp add agentation -- npx -y agentation-mcp server,注册后新开的会话才有这组工具。 服务没起时标注照存浏览器里,起来后补传;它只接受回环来源的请求,局域网其他设备连不上。 浏览器若询问是否允许页面访问本机上的应用和服务,选允许。
挂载契约
页面、页面里的页面内组件与已收进常驻表的常驻组件只由路由树画(ADR-0031)。壳决定什么时候开、什么时候收,props 由壳算好推进来;
React 路由树(RouterRoot)是唯一的一棵根,按 frontend/src/history/managed.ts 的登记把各面 portal 进壳的容器。
下面每条都是为了不出现两段等待态或离场后还在轮询的页面。
// 路由元素直接引用共享源码:import { openManagedRoute } from '../../../history/managed'
await openManagedRoute('/playlists', props, {container: $('#stats'), isCurrent: () => surfaceCurrent(surface)});
await openManagedRoute('search', props, {container: $('#searchMenu'), isCurrent: () => true});
- 登记键是「面」:页面用路径(
/stats、/performers/*、/),页面内组件用名字(catalog-filter、feed-new、library-processing、search),常驻组件也用名字(batch-dock、glow-picker、manage-header、immerse、settings-panel、sidebar、stage),三者不重叠。路由树按键查managed-routes.tsx里的同一组表,每条是{prefetch, page};页面内组件与常驻组件不进<Routes>,也不进ROUTED_PATHS。 - 常驻组件是不跟某一页走的那几座,登记在常驻表
RESIDENT_ROUTES里,由application-residents.ts的loadXxx(host)经openResidentSurface(name, container, place?)打开一次(沉浸模式、设置面板与舞台在第一次打开时,其余几座在壳 启动时):没有首屏取数,一直算当前页,宿主就是那个常驻节点本身([data-batch-dock]、#boardGlowMenu、[data-manage-header]、[data-immerse-host]、[data-settings-host]、#drawerScroll、[data-stage-host]),组件直接画成它的 子节点,DOM 和各自建根时一样,不包.peach-react。壳照旧经命令式 句柄说话:组件订阅自己模块里的 store,句柄写 store 再flushSync通知,返回时已经画好;loadXxx等这一面 画上才交出句柄。宿主里先有壳的启动骨架时(管理区页头、侧栏),openResidentSurface的place在画首帧的 同一个任务里清掉骨架,句柄交出之前骨架上的点击归壳;宿主不在壳的页面里时(沉浸模式、舞台),loadImmerse与loadStage新建[data-immerse-host]与[data-stage-host],place在画首帧(沉浸是藏着的外框,舞台是藏着的 小窗)的同一个任务里把它挂到 body 末尾。沉浸的句柄open(startId)里骨架、列表与播放器那几次绘制都在返回前画完;方向键、改窗口大小与离开页面的监听挂在模块上, 不随组件卸掉。设置面板在第一次按齿轮时才装载:loadSettingsPanel建一枚[data-settings-host],place把它 放进document.body末尾,路由树在同一个任务里画出收着的面板,之后开合只换hidden;open(section)写 store 当场画完,锁滚、取数与焦点紧跟在后面,isOpen()读的是同一份 store。常驻组件从不收,只有错误边界会卸它的组件, 宿主始终留在文档里。 openManagedRoute(key, props, options)是 async 且取完数才画。壳已经铺了骨架,页面若先画一个空容器 再自己转圈,同一次进入就会出现两段等待态。它先收起同一容器里的上一面,prefetch(props, signal)把首屏 写进共用的 Query 缓存,取齐后在同一个任务里换掉骨架、放进.peach-react宿主(或options.place排好的 框架),路由树用flushSync当场画完。路由树尚未接上时,打开先等待路由树连接再取数。搜索下拉与首页筛选条在 Application 启动阶段登记,页面与常驻组件的代码均已包含在主包内。options.isCurrent是换页判据。壳用「代」而不是AbortSignal判当前页(claimSurface/surfaceCurrent), 取数期间用户走开时靠这个谓词决定不画。一打开就不会走开的页面内组件(搜索下拉、首页筛选条)传() => true; 常驻组件的判据由openResidentSurface定成恒真。managedTaken(el)回答这个容器归没归路由树:已经画着,或首屏还在取。壳据此决定要不要再开一次,在途时 再开会把那一趟中止、重取一遍。managedEntry(el)只认已经画上的那一面。- 壳手里的一项状态变了、页面又不该重挂时,用
updateManagedRoute(el, patch):它把patch合进打开时的 props,代次不变,页面就地重渲染。重挂会把页面里打了一半的字和滚动位置一起换掉。还没画上时是空操作。 releaseManagedRoute(el, …more)中止在途取数,卸掉页面并撤掉宿主;常驻组件的宿主归壳,只卸组件。还没画就 收起时容器里是壳的骨架,那不属于路由树,原样留着。- 离场有两道闸。第一道是壳的公共点:
claimSurface是所有页面共同经过的换页点,它收#stats与#index, 也在离开目录页时收处理横幅(#libraryProcessingNotice);showHomeSurfaces是索引页与资料页重画前的公共点, 收#index那一页;#grid那一页离开目录时由clearCatalogGrid收,首页新作行由clearHomeFeed收;搜索 下拉壳从不收,常驻表里的面结构上就不收。多数页面的离场路径是直接innerHTML=,页面被挤出文档却照样活着,所以收起必须由这几个 公共点负责,而不是逐页判断。第二道是isCurrent:取数落地时用户可能已经走开,这时不画。 - 抛错的那一面:每一面各套一层错误边界(
router.tsx的SurfaceBoundary,按代次挂 key)。某一面渲染 抛错时只空出那一面,failManagedRoute撤掉它的登记与宿主,managedTaken回 false、推补丁是空操作,壳 下次打开就重开;首帧就抛错时openManagedRoute照样回 true,回来时登记已经撤了。错误经根的onCaughtError交给reportError,每次一条,边界自己不再报。根上不套边界:派发点与两组<Routes>不随某一面卸掉。确定性的抛错每重开一次就再报一次;搜索下拉只在壳启动时打开,抛错后空到刷新为止。 常驻组件抛错时只卸组件、不撤宿主,同样空到刷新为止:loadXxx是缓存的 Promise,不会再开第二次;之后壳调句柄 只写进没人订阅的 store,不画、不抛、不再上报,所以确定性的抛错只报一次。不在下一次推内容时自动重开,因为 重开要等一次异步打开,那一次句柄就不再是同步画完。
共享助手 LOC、fmtDur、fmtSize、emptyStateHtml、noteHtml、javTitleHtml 与 tagLabel 直接来自 core/、ui-kit/ 的唯一源码。@peach/legacy/* 是源码别名,不对应浏览器垫片或外置产物。应用动作(如 srcBadge、openItem)由各域控制器经有限 props/actions 接口交给组件;路由层的跨域动作由 ShellActions 下发。
两条跨层都成立的硬约束:
- 数据库元数据不得插值到 inline JavaScript 事件属性:真实厂牌名里的撇号会直接造成 Firefox 语法错误。
- 前端 API 包装必须先检查 HTTP 状态再返回 JSON:冲突只读时写端点返回
409和错误 JSON,当成普通成功对象会清空选择并重载,用户只看到条目原样回来。批量处置和详情反馈必须保留当前选择并显示失败原因。
共享状态怎么写
判据只有一条:这份数据有没有第二个读者。
没有就用 hooks。展开、悬停、翻到第几页这些东西只属于一页,提上去只是把本来局部的 东西变成全局的。
有第二个读者就让两个读者读同一个 queryKey,不另建一份状态。全站只有
src/query/client.ts 那一个 QueryClient(tests/test_frontend_build.py 盯着),壳与
React 岛都从 @peach/query 取它;页面级 prefetch 或壳写进去的那一份,任何组件的
useQuery 都直接读得到,谁先谁后都是同一个数。
现成的例子是扫描与采集那趟后台任务:/data-cleanup 上的卡片(容器 #libraryProcessing)
要进度、结果和重试,目录页顶上那条横幅(容器 #libraryProcessingNotice)只要一句话和一个
去处。两个容器不相邻,各由遗留层自己的时机挂载,读的却是同一个 LIBRARY_PROCESSING_KEY:
// src/react/library-processing/use-library-processing.ts —— 卡片与横幅都调它
const job = useQuery({
queryKey: LIBRARY_PROCESSING_KEY,
queryFn: ({ signal }) => fetchLibraryProcessing(signal),
refetchInterval: (query) => pollInterval(query.state.data, watching),
});
两处同时在场时一个周期只发一趟请求:两个 observer 的定时器在每次查询更新后一起重排,
并发的 fetch 由 Query 自己合并。反过来各存一份状态的话,两边的轮询各走各的节律,卡片
说「已完成」、横幅还挂着进度。
数据管理页(src/react/data-cleanup/)顶上五张读数卡是同一条判据的例子:「高清版」只要
total,读的仍是 /quality-goals 整页那一把 QUALITY_GOALS_KEY;「重复文件」读
/duplicates 整页的 DUPLICATES_KEY。同一个数在两页上永远是同一份,谁先进哪一页都一样。
复核计数不读 REVIEW_KEY:那一把是整条队列,?counts=1 响应形状不同,是另一份资源。
五张卡各自一个 useQuery,一张取不到只写那一张「读取失败」。
遗留层里的读者等它所在的页面迁过来再接,不为它在产物上另开一个通知入口。
这一页下半截的卡片各是一趟后台任务或一次写入:链接检查与删除、资源同步的扫描与清理走
useBackgroundJob,整理的预览与执行、重复文件的批量保留走 useMutation。
写真实 ledger 的动作(资源同步清理、/api/batch、整理执行与回滚、链接删除)
都由用户点击触发、先过 confirmModal;资源同步清理永久删除失效记录与空文件夹,走危险档。
资源同步只在有来源配了根目录时出现,它的两份任务状态也只在那时进首屏预取;
直达 #resource-sync(/resource-sync 转过来的)时,它上面那几份懒取的读数也一并等齐,
免得滚到位之后又被撑下去。
端点和查询键由页面的数据模块统一提供(如 src/react/quality-goals/quality-goals.ts)。组件测试验证请求次数、请求体和缓存更新;跨组件共享由同一个 QueryClient 提供。
首屏要不要吃缓存看路由表:/quality-goals 是 refresh:'reopen',刷新就是重新进这一页,
所以它的 prefetch 不给 staleTime,每次进来都重取。要按节律更新的页面写
refetchInterval(活动页 2 秒/10 秒),不另起 setInterval:轮询跟着组件走,
换页时壳在 claimSurface 卸根,它自己就停了。
统计页(src/react/stats/)是这条判据的另一端:整页只有 STATS_KEY 这一个键,读的是账本
此刻的样子,没有后台任务也不轮询。一屏里的四个读数和下面三个面板分开取的话,就会出现这一格
是新的、那一格是旧的。四张读数卡同时是页签(React Aria 的 Tabs),因为这一页没有别的主
动作,读数本身就是入口;环形库存图用 SVG 画,pathLength={100} 把一圈钉成 100,颜色只取
BoardUI 的 chart-* 档。点一个内容标签是「回目录并按它筛选」,整页换成目录仍归遗留壳,页面
只把标签键交回去(onTag)。
口味页(src/react/taste/)把「同一份真相换一个范围看」写进键里:['taste', window],换范围
就是换键,上一份靠 placeholderData: keepPreviousData 留在屏幕上。范围是组件状态而不是 URL:
它不进路由表,壳只按 /taste 一条路由挂岛,刷新回到默认的「全部」。服务端的 _get_taste 自己
按 taste:{window} 缓存,演示库上一趟往返十几毫秒,所以这一页不设 staleTime。后台重算是另
一个键 ['taste','refresh'],running 时两秒问一次、闲时十秒,终态按下面第 2 条的判据认。
雷达、名次条、活动热力和创作者桑基都是 React 组件,几何落在 SVG 属性上,颜色只取 BoardUI 的
chart-* 档。
迁移下一个页面
整页归 React(ADR-0031)。先挑一个容器不与别人共用的页面;写操作和后台任务的 写法已经定型,见下面第 2 条。
frontend/src/react/<page>/<page>.ts:端点常量、queryKey、数据类型和纯折算函数, 外加一个prefetch<Page>(signal),用queryClient.fetchQuery包住src/api.ts的apiGet,信号透到真正的fetch上。同一份真相只用一个queryKey:一屏里的几段要是 分开取,就会出现这一段是新的、那一段是旧的。节律不同的两份才分键:来源和凭证页的 来源列表由用户改,抓封面的任务状态由后台推进,合成一个键的话每两秒的一轮轮询都会把 用户正在填的那张卡重画一遍。frontend/src/react/<page>/<page>-page.tsx:组件用useQuery读同一个queryKey, 要轮询就写refetchInterval,间隔按上一次拿到的内容算,不另起setInterval。 写操作是useMutation,不进 Query 的缓存节律:成功后用setQueryData把服务端回的 那一条换进列表,而不是把整页重取一遍,因为用户可能正在填同一屏的另一张卡;失败只在卡内 留一句原因,缓存里的上一份不动,刚填的内容也不清。同一张卡上互斥的动作共用一个isPending,进另一个动作前reset()掉上一个的结果,屏幕上不会同时挂着两次的结论。 跟后台任务一律用frontend/src/react/background-job.ts的useBackgroundJob,不在页面里 自己拼useQuery+useMutation+ effect:按running开关轮询、首屏读到的旧终态 不冒充新结果、启动时先换进这一趟的快照再重读,这三条时序在 hook 里定死,由frontend/test/react/background-job.test.tsx拖住重读逐条验。页面只交任务键、读取与启动 函数和onFinish;缓存的是整张卡时再交jobOf/withJob。frontend/src/react/router/managed-routes.tsx:在对应的表里登记{prefetch, page},页面用路径、 页面内组件用名字;打开时交进来的 props 类型写进router/shell-actions.ts里那张表,壳经openManagedRoute打开(见 挂载契约)。- 外观按 BoardUI:注册表里有的条目逐字复制进
src/react/boardui/,哈希记进ORIGIN.md与UPSTREAM.sha256;注册表里没有的(分区标题、空态、进度、说明条) 用src/react/components/下 Peach 自己的组合件,第二个页面要用就搬进那里,不复制一份。auto-fill网格、固定像素的封面这类工具类里没有的档位,在styles.css里加@theme或@utility,类名照常由 Tailwind 生成;lint 不收任意值。 卡面取components/card.tsx的cardClass(),不自己拼描边卡:Board 的卡一律是--ground填充面,各页自拼rounded-2xl border border-separator-border的结果是同一种 卡片长出十几种空心壳。读数卡与分段控件同理,走stat-card.tsx、segmented.tsx。 frontend/test/react/<page>.test.tsx:假 fetch 加test/react/render.tsx的挂载助手, 断言结构、请求次数、轮询节律和失败时留下什么,用例之间queryClient.clear()。 有写操作就再断言交上去的请求体、成功后页面上不再留着秘密输入、失败后输入原样还在; 有后台任务就用假时钟推到终态,看回执只发一次、卸载之后不再问。 外观决定进对应区域的frontend/e2e/design-*.test.ts:page.route造出真实数据里凑不齐的状态, 断言读getComputedStyle。- 页面接入
react/router/,所需助手复用core/、ui-kit/或域内 typed controller。只有应用动作通过 props/actions 传入;通用块用components/的组合件。清理只服务该页正文的web/css/与web/board.css规则,保留骨架及其他读者仍需的规则。 - 路由、菜单入口和骨架由组件与浏览器测试验证。
tests/test_web_ui.py只保留通用样式规范、CSS 分区层叠与隐私边界,不按页面逐段比对实现源码;已有行为验证的文本断言直接清退。 - 跑
& .\scripts\test.ps1 -Scope web(含 tsc、lint、vitest 与真浏览器冒烟), 再npm --prefix frontend run build并把web/dist/一起提交。
应用骨架与全局外壳沿用 web/css/ 下仍被读取的分区。主界面组件与共享控件样式由 react/styles.css 汇入 peach-app.css。
只由 frontend/src 产出标记的规则(含 ui-kit 模板与骨架拼的 HTML)住在组件旁的 css,类名带 ui- 前缀,经 react/styles.css 引入、随 peach-app.css 加载;壳也拼的类和尚未搬的类仍在 web/css/ 与 web/board.css。原地换态的动效类在 ui-kit/motion.css。播放器皮肤与字幕外观由 player/player.css、player/subtitles.css 随主界面样式加载;Video.js 10 的控件模块由 player/videojs.ts 按需加载。
React 子树的样式是 Tailwind v4 加 BoardUI 主题,产物 peach-app.css;它与旧样式表同处一页的
三条约束(工具类不分层、只扫描 src/react/、Preflight 限定在 .peach-react 里)写在
frontend/src/react/styles.css 开头,逐字复制与没有复制的上游文件见 frontend/src/react/boardui/ORIGIN.md。
Preflight 给每张 img max-width:100%;card-art 拼的人脸头像由 avatarFrame 在图上内联撤掉这条,
岛里放这种头像的容器不必再各写 max-width:none。封面与带脸框的头像取景完才显示(09-skeleton.css)。
.oxlintrc.json 里的例外也在那儿定:ui-configpage、ui-configgroup、ui-board-local-nav 是配置页自己的类名,
骨架(configuration-skeleton.ts)与 React 页输出同一组类名,样式在组件旁的 configuration-page.css 与 board-controls.css,这条规则不读这些样式表;swiper、swiper-wrapper、swiper-slide、
swiper-zoom-container 是 Swiper 核心 API 认的结构类名(图片灯箱),不写它就找不到轮播的
容器与每一张;mono 是 01-base.css 的等宽数字字体栈,和 Tailwind 的 font-mono 不是同一组字体;
javedition 与色调(censored 等)是目录卡片也用的版次徽章;chip 是 18-chips.css 的标签按钮,壳的产地选择用它,作品详情里脱盘与在线说明块的按钮沿用它(侧栏的筛选键归侧栏组件,不用这个类);geist-button、primary 是
舞台模态里各处按钮共用的遗留按钮,设置面板的「添加」「恢复默认」也沿用;popmenu 是遗留浮层菜单的盒子,
presentMenu/dismissMenu 的开合动效按它起,设置面板的色板弹层与侧栏「添加」菜单都是它;geist-input
是 01-base.css 的输入框,设置面板的数值框沿用。这几个在它们的主人(卡片、浮层菜单等)归 React 时一起收回。
舞台、两座详情共用的格子与队列、小窗的样式在 frontend/src/react/stage/stage.css,沉浸模式在
frontend/src/react/immerse/immerse.css,播放器画面框、
统计角标与右键菜单在 frontend/src/player/player.css,都由 styles.css 引入、只认 data-*;
shadow-dropdown 是 BoardUI 主题里的 --shadow-*,
no-raw-colors 只认 --color-*,把它当成了未声明的颜色。
依赖清单
frontend/package.json 和根 package.json 是两份,各管一件事:根清单只登记手工
vendor 到 web/vendor/ 的四个包(video.js、swiper、lucide-static、healthicons),
构建依赖不许混进去(tests/test_dependency_policy.py 卡着那份清单)。
两份都精确钉版本,lockfile 进 Git。
| 依赖 | 为什么需要它 |
|---|---|
vite |
构建入口。库模式出单个 ES module,external + output.paths 把遗留模块留在外面 |
typescript |
类型即契约:注册表、props 与端点响应都靠它在编译期拦住漂移 |
vitest |
前端测试运行器。与 Vite 共用同一份配置解析,不必再维护第二套转译 |
happy-dom |
vitest 的 DOM 环境。断言的是真实 DOM 结构,比 jsdom 轻且启动快 |
playwright-core |
frontend/e2e/ 的浏览器驱动,只驱动本机 Chrome、不下载浏览器。happy-dom 没有布局,横向溢出、等待态卡住这类事实只有真浏览器测得出;不用 @playwright/test,用例跑在 node:test 上,与 docu.md(markdown-viewer/markdown-viewer-extension 的 test/helpers/browser-render-harness.ts)同一做法 |
oxlint、@shadcn/lint |
npm run lint:Oxlint 原生规则覆盖源码与测试,六条 shadcn 设计规则检查自有 React 源码。使用 TypeScript 与 Oxc 插件;规则集见 .oxlintrc.json。eslint 作为 @shadcn/lint 的 peer 安装,不作为检查入口 |
react、react-dom |
前端唯一的渲染层。BoardUI 源码是 React 组件,交互建在 React Aria 上;不经兼容层运行它(ADR-0031)。react-dom 的 flushSync 还负责配置页那一帧:壳挂完紧接着按 #peachProxy 滚过去 |
react-aria-components |
BoardUI 输入框、勾选框、开关、下拉与弹出面板的交互和无障碍语义:标签关联、键盘操作、焦点进出、aria-invalid |
react-aria |
只用 UNSAFE_PortalProvider:把 Popover 与下拉列表挂进 body 末尾同样带 .peach-react 的容器,弹层读到与页面内一致的 token 与 Preflight |
@tanstack/react-query |
React 页面的取数与缓存:页面级 prefetch 与组件里的 useQuery 共用一份缓存,「取完数才画」不必把首屏数据当 props 串一路;轮询写成 refetchInterval,卸载时跟着组件一起停 |
@tanstack/query-core |
QueryClient 本体。Application 与 React 页面直接引用同一客户端源码,运行时只有一份;版本与 @tanstack/react-query 同步固定 |
react-router |
Declarative 客户端导航:Router、Routes 与共享浏览器历史包含在主包内,地址经唯一历史对象派发。@remix-run/route-pattern、cookie-es 是它的依赖 |
@tanstack/react-table |
v9 的 useTable、tableFeatures 与列 helper 驱动关注列表、JAV 订阅源和创作者别名表格,只注册各表需要的分页、行选择与排序状态。行身份是业务 ID(getRowId);关注列表跨页跨视图共用勾选集合,排序作用在全集上,分页只切最后一步;别名表按平台别名和规范创作者键标识行 |
tailwind-merge |
BoardUI 的 cx() 合并类名时去掉互相冲突的工具类 |
@remixicon/react |
BoardUI 组件内置的图标 |
tailwindcss、@tailwindcss/vite |
按 src/react/ 里实际用到的类名生成 peach-app.css |
@types/react、@types/react-dom |
React 子树的类型检查 |
agentation |
本机开发用的界面标注工具栏,单独构建、不进产物与独立包(见「界面标注」) |
主界面由 vite.config.ts 从 src/react/bootstrap.tsx 构建为 peach-app.js 与 peach-app.css。Application、路由树、常驻组件与共享状态同属一份源码图,@peach/* 直接解析到源码,不外置 React、Query、历史、shell 或 UI 模块。路由表里的低频页面经 src/react/router/route-chunk.ts 的 routeChunk(() => import(...)) 拆出:首屏取数阶段与接口并行装载,取齐后同步画页,首屏稳定后空闲时预热;首屏用得到的模块由 codeSplitting.groups 的 $initial 收回入口,chunk 从 ./peach-app.js 导入它们。新增低频页照这个写法接进路由表;page() 只在 preload() 落地后调用,组件测试直接读 page() 时先等 loadRouteChunks()。样式仍合成一份 peach-app.css,低频页模块带的样式排在首屏样式之后。开发取证工具 /dev/agentation.js 是独立的按需外部模块。
npm run build 先构建主界面并清空 web/dist/,再用 vite.pages.config.ts 追加独立页面包。浏览器基线是 Chrome 111、Firefox 128、Safari 16.4,oklch 原样输出;随主题变化的值用 .dark 与自定义属性,不写 light-dark(),由 react-color-scheme.test.ts 检查产物。
Vitest 的模块别名也指向共享源码;@peach/legacy/ui 在组件测试中可落到 test/stubs/legacy-ui.ts,需真实控件的测试直接引用 src/ui-kit/。tests/test_web_js.py 使用 Node 类型剥离验证 src/core/ 纯函数,不加载需要 document 的主包。
没有引入 @testing-library/react:createRoot 加 querySelector 已经够用
(挂载与输入的助手在 frontend/test/react/render.tsx),断言的本来就是真实 DOM。