agentleFS
pa001024pa001024/dna-builder/.agents/skills/admin-management-page/SKILL.md

admin-management-page

Skill159 starsChanged 2 days agoMITView on GitHub

在 dna-builder 里新增一个 /admin 后台管理页(侧边栏菜单 + 路由 + REST 封装 + 统计卡/筛选卡/表格/分页 + 详情弹窗),并在本地实测验证。当需要给后台加新的管理页面、或改动 apps/web/src/admin/ 下的页面结构时使用。

The file

Files
SKILL.md

新增后台管理页

apps/web/src/admin/ 下有 15+ 个同构管理页(UserManagement.vue、RankingManagement.vue …), 改造或新增前先挑一个同类的读一遍当模板,别从零写。

两类页面,先分清

类型适用落点
GraphQL CRUD增删改查挂在 GraphQL schema 上的普通实体不写页面,往 apps/web/src/admin/crud-config.ts 加一段配置,复用 AdminCrudPage.vue
自定义 REST 页数据不在数据表里(文件分片、外部服务、聚合统计)新建 apps/web/src/admin/<Feature>Management.vue,按下面的配方

判据:数据是「数据库里的一行」→ 配 CRUD;是「磁盘文件 / 日志 / 外部接口」→ 自定义页。

改动清单(自定义 REST 页)

  1. apps/web/src/api/<feature>.ts — REST 封装,抄 apps/web/src/api/modShare.ts 的写法:
    • 内部一个 request<T>(path, token, params?, init?):拼 ${env.apiEndpoint.replace(/\/$/, "")}/api/v1/<...>、 用 URLSearchParams 丢空值、头带 token、非 2xx 或 {success:false} 统一抛 Error(error 文案)。
    • 导出具名函数(listXxx / readXxx / …),每个都要 JSDoc;不要把接口类型塞进 apps/web/src/api/app.ts(那里只 re-export)。
  2. apps/web/src/admin/<Feature>Management.vue — 页面本体,结构固定四段: 统计卡(grid 一排 4 张)→ 筛选卡(起止日期/关键字/下拉 + 查询/重置)→ 结果表 → PageFoot。
  3. apps/web/src/router.ts — 在 /admin 的 children 里加懒加载路由: { name: "admin-<kebab>", path: "<kebab>", component: () => import("./admin/<Feature>Management.vue") }
  4. apps/web/src/admin/AdminLayout.vue — menuItems 数组加 { name: "中文菜单名", path: "/admin/<kebab>", icon: "ri:xxx-line" }。

硬约定(踩过)

  • 图标必须在 apps/web/src/components/Icon.vue 注册,否则全量 vue-tsc 报 TS2820(Type '"ri:xxx"' is not assignable)。 用项目工具加:bun tools/icon-tool.ts add ri:xxx-line,别手改那个大对象。
  • 组件是全局自动注册的(unplugin-vue-components):Icon / Dialog / ScrollArea / PageFoot 直接用, 不要写 import,写了反而与同目录文件不一致。
  • Dialog.vue 的 max-w-[450px] 是写死的。要放整段对话 / 大表格这类宽内容时,自绘遮罩 (fixed inset-0 z-100 flex items-center justify-center bg-gray-900/50 p-4 + 内层 w-full max-w-6xl max-h-[88vh] flex flex-col), 改成 Dialog 加宽会波及其它调用方。
  • 页面里的用户可控文本一律 {{ }} 插值,禁止 v-html(日志、标题、错误原文都属于用户可控)。
  • 分页是两条独立的轴:PageFoot 只管「当前已加载集合」的翻页; 服务端 limit(默认 200 / 上限 2000)是另一条——返回带 truncated 时,底部给「加载更早记录」按钮, 点了把 limit 翻倍重查。别把两者混成一个。
  • 统计接口失败不能挡住列表:loadStats 与 search 分开 try/catch,各自降级。
  • 加减列时 thead th 与 tbody td 必须同增同减(列数错位不会报错,只会静默串列)。 探针里别硬编码列序号:const i = headers.indexOf("列名") 再按 row.children[i] 取值。
  • 长标识类取值(trace id / 会话 id / 哈希)的展示规格:列表里只显示前 10 位加省略号, 完整值挂 title,点一下复制完整值——半截值对排查没用,全值又排不进一列。
  • 复制统一走 copyText(text, label)(AiLogManagement.vue / AiLogSessionDialog.vue 各一份), 不要再写 copyXxx() 那种单用途 helper,提示文案由 label 拼。

验证

  1. 类型/lint:增量 lint 是最省的路径
    DNA_LINT_NODE="<managed node 绝对路径>" bun tools/incremental-lint.ts
    环境声明文件(*.d.ts、vite-env.d.ts、components.d.ts)被判为有改动时会退回全量,属正常。 整项目 vue-tsc 会因大工程把 V8 打崩(exit 134),别单独去跑它。
  2. 布局必须量出来,不靠肉眼:探针脚本放 .tmp/*.mjs,读 getBoundingClientRect / getComputedStyle, 断言 table.getBoundingClientRect().width <= document.documentElement.clientWidth(无横向溢出)。
    • 脚本用 import { chromium } from "@playwright/test" —— 仓库里没有裸 playwright 包。
    • ⚠️ 提交进仓库的 e2e 用 bun-webview-test(.agents/skills/bun-webview-test),Playwright 只用于 .tmp 里的临时探针。
    • 后端在生产域(env.apiEndpoint)时,本地页面发不出可用的真实请求 → 用 page.route("**/api/v1/<...>/**", …) 拦截并喂 fixture,别去请求真接口。
    • 点击前先清遮挡层:document.querySelectorAll("dialog").forEach(n => n.remove()) + 移除 .modal-backdrop。 数据包安装弹窗是异步挂载的,会重新出现——page.screenshot 之前再清一次,否则截图上糊一层弹窗。
  3. 开发服务器固定 http://localhost:1420,不要自己起 dev/build。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.