初始化本地仓库

.windsurf/skills/cross-plugin-web-development/SKILL.md

@@ -0,0 +1,480 @@
+---
+name: cross-plugin-web-development
+description: Madong 插件 Web 端开发规范，覆盖 Web 模板源、运行目录同步、页面路由、Web 菜单、API、认证、Element Plus 页面实现、验证与重装防回退。
+globs:
+  - "backend/plugin/**/resource/menu/web.php"
+  - "backend/plugin/**/resource/template/web/**/*"
+  - "frontend/web/app/apps/**/pages/**/*.vue"
+  - "frontend/web/app/apps/**/api/**/*.ts"
+  - "frontend/web/app/apps/**/pages/routes.ts"
+  - ".windsurf/skills/**/*.md"
+---
+
+# Madong 插件 Web 端开发技能
+
+用于开发和维护插件的 Web 前台功能。重点解决 Web 页面模板源、安装复制、插件路由、Web 菜单、API 调用和卸载重装后的防回退问题。
+
+## 适用场景
+
+- 为已有 Madong 插件增加 Web 页面。
+- 将移动端或后台已有业务迁移为 Web 页面。
+- 为插件补齐 Web API、路由和 Web 菜单。
+- 修复插件卸载重装后 Web 页面、路由或菜单回退。
+- 维护插件 Web 模板源与安装后的 Web 运行目录一致性。
+
+## 总原则
+
+1. 先核对项目真实实现，再编写或修改 Web 插件代码。
+2. 插件 Web 的权威模板源是 `backend/plugin/{plugin}/resource/template/web`。
+3. 安装后的 Web 运行目录是 `frontend/web/app/apps/{plugin}`，属于模板复制产物。
+4. 正式修改优先落在模板源，完成后再同步到 Web 运行目录。
+5. 页面、API、路由、菜单和后端接口的路径必须一致。
+6. 优先复用当前项目的 `~/utils/request`、Element Plus、Pinia 和既有页面风格，不直接照搬移动端 UI。
+7. 先解决业务根因，不通过页面层伪造数据或绕过后端校验。
+8. 不删除未经确认的内容；新增页面时不要覆盖已有业务页面。
+
+## 目录与复制关系
+
+### 模板源
+
+```text
+backend/plugin/{plugin}/resource/template/web/
+├── api/
+│   ├── data-entry.ts
+│   └── exception.ts
+├── pages/
+│   ├── routes.ts
+│   └── {module}/
+│       ├── index.vue
+│       ├── tasks.vue
+│       └── components/
+└── .gitkeep
+```
+
+### 安装后的运行目录
+
+```text
+frontend/web/app/apps/{plugin}/
+├── api/
+├── pages/
+│   ├── routes.ts
+│   └── {module}/
+└── ...
+```
+
+当前项目的实际对应关系：
+
+```text
+backend/plugin/produce/resource/template/web/
+frontend/web/app/apps/produce/
+```
+
+修改 Web 插件时，必须核对以下文件是否同步：
+
+- `api/**/*.ts`
+- `pages/**/*.vue`
+- `pages/routes.ts`
+- 页面使用的组件和辅助文件
+
+## 开发前检查
+
+开始开发前至少核对：
+
+1. 插件名和 Web 运行目录：`frontend/web/app/apps/{plugin}`。
+2. 模板源是否存在：`backend/plugin/{plugin}/resource/template/web`。
+3. Web 主应用是否通过 `router.options.ts` 加载插件路由。
+4. 后端接口的真实路径、请求方法、参数和响应结构。
+5. 登录用户信息来源和认证请求头。
+6. `resource/menu/web.php` 的真实菜单字段格式。
+7. 可参考的 Web 页面，例如：
+   - `frontend/web/app/apps/produce/pages/data-entry/index.vue`
+   - `frontend/web/app/apps/produce/pages/data-entry/components/OrderEntryPanel.vue`
+8. 移动端页面仅作为业务流程参考，不作为 Web 布局和组件规范来源。
+
+## Web 路由规范
+
+### 1. 插件路由入口
+
+当前 Web 主应用通过以下方式加载插件路由：
+
+```text
+frontend/web/app/router.options.ts
+```
+
+该文件使用 `import.meta.glob('~/apps/**/pages/routes.ts', { eager: true })` 加载插件路由。因此插件页面应在以下文件注册：
+
+```text
+backend/plugin/{plugin}/resource/template/web/pages/routes.ts
+frontend/web/app/apps/{plugin}/pages/routes.ts
+```
+
+### 2. 路由写法
+
+```typescript
+export default [
+  {
+    path: '/{plugin}/{module}',
+    component: () => import('~/apps/{plugin}/pages/{module}/index.vue'),
+    meta: {
+      title: '页面标题',
+      layout: 'default',
+    },
+  },
+]
+```
+
+要求：
+
+- 页面路径使用业务语义，保持与 Web 菜单 URL 一致。
+- 组件路径使用 `~/apps/{plugin}/pages/...`。
+- 默认使用 `layout: 'default'`，除非已核对项目存在其他布局。
+- 一个页面只能注册一次，避免主站路由和插件路由重复。
+- 带参数页面使用 Nuxt 约定的 `[param].vue`，但当前插件也可按项目路由表显式注册页面。
+
+### 3. 认证与权限
+
+Web 路由是否需要登录由当前项目权限中间件和路由元信息共同决定。涉及用户数据、异常提报、维修提交等业务时：
+
+- 页面必须使用真实的登录用户信息。
+- 不要在前端硬编码用户工号作为提交值。
+- 需要登录的页面应按当前项目实际权限配置 `meta.permissions`，先核对现有菜单和中间件实现。
+- 如果后端接口本身标记为公共接口，也不能因此在页面中跳过业务必填校验。
+
+## Web 菜单规范
+
+### 1. 菜单文件
+
+插件 Web 菜单文件：
+
+```text
+backend/plugin/{plugin}/resource/menu/web.php
+```
+
+Web 菜单不是 Admin 菜单，不能直接复制 `resource/menu/admin.php` 的结构。当前项目 Web 菜单使用记录数组，例如：
+
+```php
+return [
+    [
+        'app'        => 'web',
+        'category'   => 1,
+        'source'     => 'plugin',
+        'code'       => null,
+        'name'       => '业务页面',
+        'url'        => '/{plugin}/{module}',
+        'icon'       => 'ri:apps-line',
+        'level'      => 1,
+        'type'       => 2,
+        'sort'       => 10,
+        'target'     => 1,
+        'is_show'    => 1,
+        'enabled'    => 1,
+        'created_at' => time(),
+        'updated_at' => time(),
+        'deleted_at' => null,
+    ],
+];
+```
+
+字段要求以当前项目和菜单导入实现为准，至少核对：`app`、`source`、`name`、`url`、`type`、`sort`、`is_show`、`enabled`。
+
+### 2. 菜单与路由一致
+
+新增 Web 页面时必须同时检查：
+
+- `resource/menu/web.php` 是否有对应菜单。
+- 菜单 `url` 是否等于路由 `path`。
+- 路由组件是否真实存在。
+- 菜单是否需要显示为一级菜单或子菜单。
+- 图标是否使用项目已有图标格式。
+
+不要只添加路由而不添加菜单，也不要只添加菜单而不注册路由。
+
+### 3. 菜单安装行为
+
+菜单通常在插件安装时导入系统菜单。修改 `resource/menu/web.php` 后，当前数据库中已存在的菜单不一定会自动刷新。验证菜单时应区分：
+
+- 文件配置是否正确。
+- 安装导入后的系统菜单是否已更新。
+- 当前用户是否有访问该菜单的权限。
+
+不要通过前端硬编码菜单代替插件菜单导入机制。
+
+## Web API 规范
+
+### 1. API 文件位置
+
+插件 Web API 正式放在模板源：
+
+```text
+backend/plugin/{plugin}/resource/template/web/api/
+```
+
+运行目录对应：
+
+```text
+frontend/web/app/apps/{plugin}/api/
+```
+
+当前项目的实际写法是业务 API 直接放在插件目录，例如：
+
+```typescript
+import request from '~/utils/request'
+
+export function getExampleList(params: Record<string, unknown> = {}) {
+  return request.get('/{plugin}/{resource}', params)
+}
+```
+
+### 2. 请求约定
+
+- 使用 `~/utils/request`，不要在业务 API 中直接调用 axios 或 fetch。
+- 传入后端业务路径，例如 `/produce/process`，不要手动拼接 `/api/`。
+- GET 参数作为第二个参数传入。
+- POST 数据作为第二个参数传入。
+- 默认响应已经解包为 `data`。
+- 只有确实需要状态码、消息或完整响应时，才使用 `returnFullResponse: true`。
+- 上传使用 `request.upload` 和 `FormData`，统一由 API 层封装。
+- API 层负责类型声明、路径和参数；页面负责交互状态和展示。
+- 错误提示优先使用请求层统一处理，页面避免重复弹出相同错误。
+
+### 3. API 类型
+
+应根据后端真实返回结构定义接口，例如：
+
+```typescript
+export interface ExampleItem {
+  id: string | number
+  name?: string
+  status?: number
+}
+
+export function getExampleDetail(id: string | number) {
+  return request.get<ExampleItem>(`/example/${id}`)
+}
+```
+
+列表接口要确认返回的是数组还是 `{ items, total }`，不能凭页面名称猜测。
+
+### 4. API 与页面解耦
+
+页面中不要重复实现：
+
+- 基础 URL 拼接。
+- Authorization 认证头。
+- 响应解包。
+- 上传认证。
+- 通用错误弹窗。
+
+如果多个页面共享业务请求，应提取到插件 Web API 文件，而不是复制请求代码。
+
+## 页面开发规范
+
+### 1. 技术栈
+
+当前项目 Web 端使用：
+
+- Vue 3 `<script setup lang="ts">`。
+- Nuxt 4。
+- Element Plus。
+- Pinia。
+- 当前项目已有的 SCSS / CSS 变量和布局。
+
+### 2. 页面结构
+
+建议结构：
+
+```vue
+<template>
+  <div class="produce-work-page">
+    <div class="page-shell">
+      <section class="page-hero">...</section>
+      <div class="content-grid">
+        <main class="main-column">...</main>
+        <aside class="side-column">...</aside>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+要求：
+
+- 页面应适配 `layouts/default.vue` 的滚动区域。
+- 页面主体避免依赖移动端 `view`、`text`、`u-*` 组件。
+- Web 页面使用 `div`、`button`、Element Plus 组件和原生表单语义。
+- 页面需要考虑 1440px、1024px、768px 等宽度下的响应式布局。
+- 重要操作按钮必须有 loading、禁用或重复提交保护。
+- 空数据、加载中、提交失败和成功状态要有明确反馈。
+- 不要为了追求视觉效果引入项目没有使用的新 UI 框架。
+
+### 3. 业务迁移
+
+从移动端迁移时：
+
+- 保留业务流程、校验规则、接口参数和状态含义。
+- 将 `u-popup` 改为 `el-dialog`、`el-drawer`、`el-select` 或页面内面板。
+- 将 `u-input` 改为 `el-input`。
+- 将 `u-button` 或自绘点击区域改为 `el-button` 或符合语义的按钮。
+- 将移动端图片选择改为 `el-upload`，上传由 API 层完成。
+- 将 `uni.showToast` 改为 `ElMessage` 或 `ElNotification`。
+- 将移动端本地用户信息读取改为 `useMemberStore()`，但要以当前项目真实 Store 结构为准。
+- 不要把移动端的 `uni`、`rpx`、原生扫码插件直接带入 Web 页面。
+
+### 4. 图片上传
+
+推荐流程：
+
+1. 使用 `el-upload` 设置 `:auto-upload="false"`。
+2. 读取 `UploadUserFile.raw`。
+3. 调用插件 API 的上传方法。
+4. 将返回的 URL 放入业务提交参数。
+5. 限制文件类型、数量和必要的大小。
+6. 上传失败时停止提交并保留用户选择，方便重试。
+
+## 模板源优先与同步流程
+
+标准流程：
+
+1. 核对插件后端接口和业务返回结构。
+2. 在 `backend/plugin/{plugin}/resource/template/web` 中创建或修改 Web API。
+3. 在模板源中创建或修改页面及页面组件。
+4. 在模板源 `pages/routes.ts` 注册路由。
+5. 在 `resource/menu/web.php` 增加或更新 Web 菜单。
+6. 核对模板源文件之间的导入路径和路由路径。
+7. 将模板源同步到 `frontend/web/app/apps/{plugin}`。
+8. 核对模板源与运行目录内容一致。
+9. 启动 Web 端，验证菜单、路由、页面和接口。
+10. 如菜单由安装流程导入，重新安装或执行项目规定的菜单刷新流程后再验证菜单。
+
+禁止只修改以下运行目录而不更新模板源：
+
+```text
+frontend/web/app/apps/{plugin}
+```
+
+## 验证清单
+
+### 文件与同步
+
+- [ ] 模板源 Web API 存在。
+- [ ] 模板源页面存在。
+- [ ] 模板源 `pages/routes.ts` 已注册。
+- [ ] `resource/menu/web.php` 已配置对应菜单。
+- [ ] 运行目录已同步。
+- [ ] 模板源与运行目录文件内容一致。
+
+### 页面与交互
+
+- [ ] 页面使用 Web 组件，不包含移动端 `uni`、`u-*`、`rpx`。
+- [ ] 加载、空数据、错误和提交状态完整。
+- [ ] 提交按钮有重复提交保护。
+- [ ] 关键字段有前端校验，后端校验仍然保留。
+- [ ] 用户信息来自真实 Store 或当前项目认证机制。
+- [ ] 页面在窄屏下仍可用。
+
+### API
+
+- [ ] API 使用 `~/utils/request`。
+- [ ] 请求路径未重复拼接 `/api/`。
+- [ ] 请求方法、参数名称和响应结构与后端一致。
+- [ ] 文件上传通过 API 层完成。
+- [ ] 错误提示没有重复弹出。
+
+### 路由与菜单
+
+- [ ] 菜单 URL 与路由 path 一致。
+- [ ] 路由 component 路径真实存在。
+- [ ] 菜单排序、图标、显示状态符合项目实际格式。
+- [ ] 菜单导入后的系统数据已经刷新或重新安装验证。
+
+### 构建与运行
+
+- [ ] Web 端定向 ESLint 检查通过，或已区分本次新增问题与项目历史问题。
+- [ ] Web 端类型检查通过，或已记录项目历史类型错误。
+- [ ] 页面可以正常打开。
+- [ ] API 请求返回预期数据。
+- [ ] 提交、上传、跳转和返回流程正常。
+
+## 防回退规则
+
+卸载重装插件会重新从模板源复制 Web 文件。以下情况会导致回退：
+
+- 只修改了 `frontend/web/app/apps/{plugin}`。
+- 模板源缺少新增页面或 API。
+- 模板源 `pages/routes.ts` 没有同步。
+- `resource/menu/web.php` 没有同步。
+- 运行目录临时修复后没有回写模板源。
+
+最终交付必须同时满足：
+
+- 模板源版本正确。
+- Web 运行目录版本正确。
+- 路由和菜单版本正确。
+- 重新安装插件后页面不会回退。
+
+## 常见问题
+
+### 1. 页面 404
+
+排查顺序：
+
+1. 页面文件是否位于 `frontend/web/app/apps/{plugin}/pages`。
+2. 插件 `pages/routes.ts` 是否存在。
+3. `router.options.ts` 是否仍使用插件路由 glob。
+4. 路由 `path` 是否与访问地址一致。
+5. import 路径大小写是否正确。
+6. 模板源和运行目录是否都包含该页面。
+
+### 2. 菜单不显示
+
+排查：
+
+- `resource/menu/web.php` 是否新增记录。
+- `app` 是否为 `web`。
+- `enabled`、`is_show` 是否启用。
+- 菜单是否已重新导入系统表。
+- 当前登录用户是否具备对应菜单访问权限。
+
+### 3. 页面打开但请求 404
+
+常见原因：
+
+- API 路径多拼了 `/api/`。
+- 请求路径与后端控制器路由不一致。
+- 后端插件未加载或运行进程未重载。
+- API 文件只同步到了运行目录，重装后被旧模板覆盖。
+
+### 4. 模板源文件出现模块找不到
+
+模板源不一定是主 Web 项目的 TypeScript 编译入口。若编辑器提示 `vue`、`element-plus`、`~/stores/member` 或 `~/apps/{plugin}/api` 找不到，先确认运行目录中的同一文件可以解析，再区分编辑器静态提示和真实构建错误。
+
+### 5. 页面使用了公共接口但无法提交
+
+公共接口不等于无需业务校验。应继续检查：
+
+- 当前用户工号是否存在。
+- 必填字段是否完整。
+- 业务状态是否允许操作。
+- 后端是否要求先校验订单或维修任务。
+
+### 6. Windows 下模板修改未生效
+
+如果修改模板源、菜单、安装逻辑后运行结果仍是旧版本：
+
+- 确认 Webman 进程是否已重新加载插件代码。
+- 确认插件安装流程是否重新复制模板。
+- 确认菜单数据是否重新导入。
+- 不要只根据浏览器缓存判断模板是否更新。
+
+## 输出契约
+
+完成一个插件 Web 功能时，至少交付：
+
+- Web API 模板源。
+- Web 页面模板源。
+- 插件 Web 路由模板源。
+- `resource/menu/web.php` 菜单配置。
+- 同步后的 `frontend/web/app/apps/{plugin}` 运行目录。
+- 页面、接口、菜单和路由一致性验证。
+- 构建或定向检查结果。
+- 如发现既有 Web skill 与项目真实实现不一致，应同步更新对应 skill，并说明更新内容。