技能使用指南

frontend-dev（前端开发）Skill 是什么？如何下载安装？

frontend-dev（前端开发）Skill 内置 ztjg-ui 管理端与 ztjg-app 移动端开发规范，覆盖 Vue 3、TypeScript、Element Plus、Pinia 与 uni-app，明确多组织数据视角透传与失效降级做法，并提供列表页开发步骤、联调排查清单与交付检查表。立即阅读，提升效率！

前端开发Skillfrontend-dev
8 个章节 约 19 分钟阅读 AI 智能生成

前端开发Skill：让 AI 按仓库规范写 Vue 页面，而不是凭记忆猜

  • 它是“带规则的编码助手”，而非通用代码生成器：frontend-dev 把 ztjg-ui（Vue 3 + TypeScript + Element Plus + Pinia + Vite）与 ztjg-app（uni-app）两套工程的目录约定、请求封装、代码规范固化成技能说明，AI 调用时会先读文档再动代码。
  • 最值得关注的是“多组织数据视角”：技能内置 X-Data-View-Id 自动透传、视角切换器复用、菜单按视角下发、VIEW_EXPIRED 降级等一整套硬性约束，直接叫停“前端拼 orgId 模拟数据权限”这类常见错误。
  • 它提供完整的开发流程：从请求层、列表页、弹窗表单、菜单配置到自测命令（管理端 8888、移动端 8088），再到交付前检查清单，可以按步骤执行。
  • 它内置排查决策树：切换视角后数据没变化、菜单 404、接口 403、本地联调全 404 等场景，技能会给出“先查什么、再查什么”的顺序，而不是靠猜。
  • 适合三类人：刚接手这套仓库的前端新人、需要跨管理端与移动端改需求的开发者，以及想把团队规范“喂”给 AI 的负责人。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 前端开发Skill
技能英文名 frontend-dev
技能ID 2120440319009521666

它到底解决什么问题

大多数 AI 编码助手在写 Vue 代码时靠“通用最佳实践”，于是经常产出与本仓库格格不入的东西：自己用 axios 发请求、手写菜单路由、在列表接口里拼 orgId、移动端新页面忘了登记 pages.json。frontend-dev 的作用是把这些“隐形的团队规则”变成 AI 可执行的显式约束。它明确覆盖两套工程：

  • 管理端 ztjg-ui/：Vue 3.5 <script setup> + TypeScript、Element Plus 2.13 + Tailwind + DaisyUI、Pinia（含 persist）、Vue Router 4 后端菜单驱动动态路由、Axios 统一封装（含加解密与视角头）、Vite、本地端口 8888、包管理 pnpm。
  • 移动端 ztjg-app/：uni-app（Vue 3.2.47）+ Pinia、Vite 4、H5 本地端口 8088、页面必须在 src/pages.json 注册、uni-push 2.0 推送。

技能描述里还给出了触发示例，比如「用 frontend-dev 帮我加一个页面」「给管理端加一个 XX 管理模块」「移动端加一个页面」。

一键安装的思路与步骤

技能详情本身是仓库内的规范文档（含 name / description 元信息），并未附带具体的安装命令或下载链接，因此下面给出通用安装思路，具体命令、入口与是否收费请以官方说明为准：

  1. 确认安装前提：你使用的 AI 客户端/IDE 插件支持挂载“技能（Skill）”；本地已克隆该前端仓库，能读取 docs/07-项目分析文档/、.agent/PROJECT_CONTEXT.md 等文档；本地已装好 Node 与 pnpm（管理端用 pnpm，移动端沿用团队现有方式，详情中标注移动端包管理器“不确定”）。
  2. 获取技能：在技能市场或团队内部技能库中搜索“前端开发”或 frontend-dev，按平台指引加入/下载到本地技能目录（入口与命令以官方说明为准）。
  3. 让技能能“看到”仓库上下文：技能的规则大量引用仓库相对路径（如 src/utils/request.ts、src/components/DataViewSwitch/index.vue、src/router/backEnd.ts），请在仓库根目录打开会话，保证文档可读。
  4. 重启会话使其加载：多数客户端需要重新开启对话或刷新技能列表后生效。

如何验证是否生效

在对话里输入一句触发语：用 frontend-dev 帮我加一个页面。观察 AI 的回答是否具备这些“指纹特征”：

  • 先反问或判断“改管理端 ztjg-ui 还是移动端 ztjg-app”；
  • 提到请求必须走 src/utils/request.ts、URL 要带网关前缀；
  • 明确“不要在前端拼 orgId/deptId 等组织过滤参数”；
  • 提到新增移动端页面必须登记 src/pages.json。

如果它直接甩出一段脱离仓库的通用 Vue 代码，说明技能没有正确加载。

2. 该技能的主要功能和特点

  • 双工程自动分流：按需求判断落在 ztjg-ui/（PC 管理后台、表格/表单/权限菜单）还是 ztjg-app/（H5 / App / 小程序），并强调两套工程互不共享代码，禁止跨工程 import 或复制组件。
  • 多组织数据视角的端到端规范：这是本项目的核心特性。技能把“用户 → 任职 → 组织/岗位 → 角色 → 功能权限 + 数据范围”以及 L1/L2 两级视角翻译成前端可执行的 6 条纪律：视角头由请求拦截器自动注入、切换器复用 DataViewSwitch、菜单来自 GET /admin/data-view/menus、VIEW_EXPIRED 时清 DATA_VIEW_ID 并降级、空视角是常态不得白屏、切换视角后整页刷新。
  • 明确划定“前端不修数据权限”的边界：数据多少由后端 DataScopeInnerInterceptor 下推 SQL 决定，前端能做的只有带对头、处理失效、切回视角对比，避免开发者浪费时间在前端“模拟权限”。
  • 标准工作流配方（recipe）：新增列表页的四步（请求层 → 页面 → 表单 → 菜单）精确到参考文件，例如请求层照抄 src/api/management/bizProject.ts，页面照抄 views/management/bizProject/index.vue，列表统一用 useTable、字典用 useDict、按钮用 v-auth。
  • 现象级排查决策树：把“切换视角后列表没变化 / 列表为空 / 菜单 404 / 菜单空白 / 提示视角非法 / 接口 403 / 本地全 404”七种现象拆成“先查什么、再查什么”的两级路径。
  • 禁止事项清单：绕过 request.ts 直接用 axios/fetch/uni.request、手工伪造 X-Data-View-Id、管理端手写菜单路由、.vue 里泛滥 any 与 console.log（ESLint error）、擅自升级 Vue/Element Plus/Vite 版本等，全部列为红线。
  • 交付前检查清单：11 条勾选项，涵盖 API 目录位置、pages.json 登记、至少切换 2 个视角验证、lint 与 build 通过、权限码与后端 @HasPermission 一致。
  • 联调与灰度约定：VITE_API_URL=/api、Vite 代理到 VITE_ADMIN_PROXY_PATH（默认 127.0.0.1:9999）并剥掉 /api、本地灰度用 .env.development.local 写 VITE_GRAY_VERSION、请求自动带 Authorization/TENANT-ID/X-Data-View-Id/VERSION。
  • 诚实标注不确定项：技能末尾列出 7 条“不确定点”（组件是否全局自动注册、无测试脚本、/management 路由是否由 sys_route_conf 补录等），减少 AI 编造结论的概率。

和普通代码补全工具相比，它强在边界与顺序：先告诉你该读哪几份文档、哪个文件只能改、哪件事前端根本不该做。

3. 如何使用该技能？

第 1 步：判断改哪个工程。 需求提到“表格/表单/权限菜单/管理后台”默认选 ztjg-ui/；提到“移动端、uni-app、扫码确认、消息推送”选 ztjg-app/。

第 2 步：让 AI 先读必读文件。 管理端至少包含 ztjg-ui/AGENTS.md、ztjg-ui/CLAUDE.md、src/utils/request.ts、src/hooks/table.ts、src/hooks/dict.ts、src/api/management/bizProject.ts、src/router/backEnd.ts；涉及视角时再加 src/api/admin/dataView.ts 与 src/components/DataViewSwitch/index.vue。

第 3 步：用自然语言下达带上下文的指令。 输入示例：

用 frontend-dev 给管理端加一个“项目台账”管理模块，列表要分页、带字典字段和新增/编辑弹窗，按钮要有权限码。

第 4 步：按工作流落地代码。

  1. 在 src/api/<业务域>/<feature>.ts 新建请求文件，import request from '/@/utils/request'，导出 fetchList / addObj / getObj / putObj / delObjs，URL 以网关前缀开头（/admin/...、/management/...、/auth/...、/app/...、/task/...）。
  2. 在 src/views/<业务域>/<feature>/index.vue 写列表页：useTable 管分页与查询，useDict + DictTag 处理字典，v-auth 控制按钮显隐。
  3. 同目录 form.vue 用 el-dialog + el-form，父页面通过 ref 调打开方法。
  4. 菜单不要在前端手写路由，去后台“菜单管理”配置并分配权限码（必要时配 module_code），路由来自 GET /admin/data-view/menus。
  5. 列表接口不要传组织参数，若返回空先确认当前视角。

第 5 步：跑起来自测。

# 管理端
pnpm install
pnpm dev        # 端口 8888
pnpm lint:eslint
pnpm build

# 移动端
npm install
npm run dev:h5  # 端口 8088
npm run lint

管理端自测的关键动作是切换至少 2 个视角：看菜单是否变化、列表数据量是否变化、有无白屏或报错、VIEW_EXPIRED 是否被静默兜底。

第 6 步：移动端加页面的额外动作。 新建 src/pages/<name>/<name>.vue 后，必须在 src/pages.json 的 pages 数组追加同路径条目（含 navigationBarTitleText 等），否则无法跳转；API 路径不要硬编码 /api（H5 走 /api 代理，App/小程序直连 VITE_APP_BASE_URL）。

输出说明：正常情况下你会得到“请求文件 + 列表页 + 表单弹窗 + 自测步骤 + 检查清单勾选结果”这一整套交付物，而不是一段孤立代码。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
frontend-dev（本技能） 仓库专用前端开发技能 双工程分流、多组织视角规范、列表页 recipe、排查决策树、禁止事项与交付清单 需支持技能挂载的 AI 客户端 + 本地仓库可读；具体入口以官方说明为准 本仓库管理端/移动端日常改需求、视角联调排障、新人上手 优势：规范贴合真实代码，能拦住“拼 orgId”“手写菜单路由”等错误，附带排查顺序；不足：只服务这两套工程，换仓库不通用，且部分“不确定点”仍需人工确认
通用 AI 编码助手（如代码补全/对话类工具） 通用编码辅助 代码补全、自由问答、跨语言生成 门槛低，装插件即可 写零散函数、查语法、通用重构 优势：通用性强、上手快；不足：不了解本仓库约定，容易产出绕过 request.ts、漏登记 pages.json 的代码，视角相关逻辑几乎必踩坑
团队规范文档 / AGENTS.md、CLAUDE.md 静态规范文档 记录硬性规范、目录约定、命令 零门槛，直接读 人工开发时对照查阅 优势：权威、可评审；不足：需要人主动读，AI 不会自动遵守，新人容易漏读；frontend-dev 相当于把这类文档“可执行化”
低代码/脚手架生成器 页面结构生成 可视化拖拽或模板生成表格、表单 需接入平台或模板库 结构高度标准化的中后台页面 优势：出页面快；不足：难以表达“视角头透传、VIEW_EXPIRED 降级、后端菜单下发”这类领域逻辑，生成结果仍需按仓库规范改造

5. 该技能的典型应用场景与实际体验情况

场景一：前端新人接“加一个管理模块”的需求

角色是新入职前端，痛点是不清楚请求该写在哪、菜单为什么在前端搜不到。使用方式：直接说「用 frontend-dev 帮我加一个 XX 管理模块」。技能会先带他读 src/api/management/bizProject.ts 与对应页面模板，再产出请求文件与 index.vue+form.vue，并提醒菜单要去后台配置。体验：上手难度低，最大的价值是“顺序正确”——先读文档再写码；注意事项是必须真的去后台配菜单与权限码，代码生成完不会自动出现在侧边栏。

场景二：切换视角后列表“没变化 / 变空了”的排查

角色是负责联调的中级前端，痛点是分不清问题在前端还是后端。使用方式：把现象贴给技能，它会给出两级排查路径——先看 Network 里 X-Data-View-Id 是否真的发出、DATA_VIEW_ID 是否写进 Session，再查后端 Mapper 是否声明 DataScope、该视角是否 L2 收窄导致 visible-orgs 为空。体验：定位效率明显提升，尤其“前端不修数据权限”这句边界提示能省掉大量无效改动；注意接口 403 在 L2 收窄视角下属预期行为，切回 L1 再验证。

场景三：移动端加页面并接消息推送

角色是同时兼顾双端的开发者，痛点常是页面写完跳不过去（忘登记 pages.json）、H5 正常但 App 请求 404（硬编码 /api）。使用方式：明确说「移动端加一个页面」。技能会要求新建 src/pages/<name>/<name>.vue 并同步 src/pages.json，请求写进 src/api/<name>.ts，并强调移动端没有视角切换器，数据范围由后端按登录用户收敛，不要自行传组织参数。体验：两个高频坑被前置规避；注意移动端包管理器“不确定”，沿用团队现有方式即可。

场景四：本地联调全 404 / 跨域

角色是需要只联调自己改动服务的后端联调者。使用方式：按技能指引检查 VITE_ADMIN_PROXY_PATH 是否指向 http://127.0.0.1:9999、VITE_IS_MICRO 取值、网关是否启动；灰度调试则在 .env.development.local 写 VITE_GRAY_VERSION（被 gitignore，不提交），重启 dev server 后请求自动带 VERSION 头。体验：把“猜环境”变成“查清单”；注意不要把个人本地环境值提交进仓库。

6. 该技能能为用户带来的价值

  • 效率层面：把“翻文档—找模板—改代码—自查”压缩成一次带上下文的对话，列表页这类高频任务从“边查边写”变成“照 recipe 走”，交付前再多一道 11 项清单自动核对，减少返工与二次提交。
  • 门槛层面：多组织数据视角是本项目最容易被误解的部分，技能用 6 条纪律和一张排查表把它拆开，新人不必读完整个权限模型也能写出“带对头、处理失效”的代码。
  • 质量层面：禁止事项直接对应真实事故模式——绕过统一请求出口会丢掉视角头与加解密，前端拼组织参数会制造“看起来生效”的假权限，.vue 里的 console.log 直接触发 ESLint error。
  • 长期价值：技能把仓库规范沉淀为可复用资产，团队规范更新时只需维护这一份“可执行文档”，AI 与人的行为标准保持一致；末尾明确的 7 条“不确定点”也提醒团队持续补齐测试基线、路由种子、包管理器等缺口。

7. 常见问题 FAQ

Q1：怎么安装 frontend-dev？需要付费吗？ 技能详情中给出的是仓库内的规范内容（含 name / description 元信息），未包含具体安装命令、下载链接或价格信息，请以官方说明为准。通用做法是：在支持技能挂载的 AI 客户端中搜索“前端开发”或 frontend-dev，加入本地技能目录后重启会话，再用「用 frontend-dev 帮我加一个页面」验证是否生效。

Q2：用了它是不是就不用看文档了？ 不是。技能本身就是“先读文档再动代码”的导航器：它明确要求先读 ztjg-ui/AGENTS.md、src/utils/request.ts、src/hooks/table.ts 等文件，并指向 docs/07-项目分析文档/ 下的项目介绍、架构分析、接口清单、实战任务等章节。把它当成“知道该读哪一页”的向导更准确。

Q3：它适合谁用？后端或测试能用吗？ 最适合三类人：刚接手本仓库的前端、需要同时改管理端与移动端的开发者、负责把规范喂给 AI 的负责人。后端与测试也能借用它的排查决策树理解“为什么前端传组织参数没用”“40304 与 VIEW_EXPIRED 分别代表什么”，但代码生成部分仅覆盖前端两套工程。

Q4：它和代码补全插件、团队规范文档怎么选？ 三者互补：规范文档是权威来源，代码补全插件负责逐行敲字，frontend-dev 负责“把规范落到具体文件和顺序上”。如果只做通用语法查询，补全插件即可；如果要在本仓库改页面、调视角、排联调问题，优先用 frontend-dev，并把它输出的检查清单当作提交前必过项。

Q5：它会不会自动帮我修好数据权限问题？ 不会，而且技能明确写了“前端不修数据权限”。数据范围由后端 DataScopeInnerInterceptor 下推 SQL 决定，前端的职责只有三件事：把当前视角通过 X-Data-View-Id 带给后端、正确处理 VIEW_EXPIRED（清 DATA_VIEW_ID 后降级，不弹错）、以及切换视角后整页刷新以便对比。数据仍不对，问题通常在 Mapper 是否声明 DataScope 或角色数据范围配置。