mrlee/MrleeAdmin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
MrleeAdmin/.windsurf/skills/frontend-app-common/SKILL.md
T

13 KiB
Raw Permalink Blame History

name, description, globs
name description globs
frontend-app-common app 移动端公共开发规范，基于 uni-app、Vue 和 uView Pro，覆盖页面组织、路由、组件、扫码交互、视觉字号和交付检查
frontend/app/**/*.vue
frontend/app/**/*.js
frontend/app/pages.json

技术基线

当前 APP 位于 frontend/app/，使用以下技术约定：

  • uni-app 页面运行模式。
  • 页面采用 Vue 单文件组件（.vue）。
  • main.js 注册 @/uni_modules/uview-pro，并注入全局主题 mixin；每个页面可直接通过 themeMode 获取 light/dark，根容器必须绑定 :class="theme-${themeMode}"。
  • 全局主题状态由 utils/theme.js 管理：applyAppTheme(mode) 会持久化 scanapp_theme_mode、同步导航栏颜色并广播 scanapp-theme-change；设置页切换主题时必须调用它，不能只修改本页 class。
  • pages.json 开启 uView Pro Easycom 自动组件扫描。
  • uView Pro 组件使用 u-* 命名，例如 u-icon、u-input、u-form、u-button、u-switch。
  • 兼容 Vue 2 和 Vue 3 入口，新增页面优先遵循现有 Options API 写法，除非项目整体迁移。

目录与页面组织

frontend/app/
├── App.vue
├── main.js
├── pages.json
├── uni.scss
├── pages/
│   ├── auth/
│   │   ├── login.vue
│   │   └── register.vue
│   ├── entry/
│   │   ├── order.vue
│   │   └── machine.vue
│   ├── exception/
│   │   └── index.vue
│   ├── repair/
│   │   ├── index.vue
│   │   └── tasks.vue
│   ├── query/
│   │   ├── index.vue
│   │   ├── index copy.vue
│   │   └── index.vue
│   ├── settings/
│   │   └── index.vue
│   ├── statistics/
│   │   └── index.vue
│   └── index/
│       └── index.vue
└── uni_modules/

新增页面时：

  1. 页面文件放入 pages/<module>/。
  2. 页面入口优先使用 index.vue，业务模式页面可使用明确名称，例如 entry/order.vue。
  3. 必须在 pages.json 的 pages 数组中注册路由。
  4. pages.json 中的路径不带 .vue 后缀，例如 pages/settings/index；设置模块也允许使用与路由同名的平铺页面文件，例如 pages/settings/feedback.vue 对应 pages/settings/feedback。
  5. 页面导航标题通过路由项的 style.navigationBarTitleText 配置。
  6. 不要把未注册的副本页面当作运行页面维护；例如 index copy.vue 不属于正式路由。
  7. pages.json 的首项保持为 pages/index/index，APP 启动默认进入首页，不把登录页放在最前面。

页面结构规范

页面组件按以下顺序组织：

  1. <template>：页面结构和交互绑定。
  2. <script>：data、computed、watch、methods 和生命周期。
  3. <style lang="scss" scoped>：页面局部样式。

页面模板建议采用以下结构：

  • 页面根节点使用语义化页面类名，例如 .settings-page、.query-page、.entry-page。
  • 页面按业务区块拆分为卡片、列表、表单和操作区域。
  • 重复数据使用 v-for，并使用稳定的业务字段作为 :key。
  • 交互统一使用 @tap 或现有组件支持的事件写法。
  • 对话框、提示和扫码等平台能力统一通过 uni.* API 调用。

组件使用规范

优先使用项目已有的 uView Pro 组件，不重复实现同类基础控件：

场景 组件或能力
图标 u-icon
文本输入 u-input
表单 u-form、u-form-item
按钮 u-button
开关 u-switch
空状态 u-empty
页面提示 uni.showToast
操作选择 uni.showActionSheet
页面跳转 uni.navigateTo、uni.navigateBack、uni.reLaunch
基础相机扫码 uni.scanCode
相册识图 / 原生扫码体验 @/uni_modules/mas-code-scan 的 openCodeScan（仅 App-Plus）

使用 uView Pro 组件时：

  • 通过 Easycom 直接使用 u-* 标签，不在页面内重复注册组件。
  • 沿用项目当前属性命名和事件写法。
  • 按钮、输入框、表单等控件保持页面间的尺寸、圆角和状态表现一致。
  • 图标使用 u-icon，不手写重复的 SVG 图标。

页面交互规范

页面跳转

使用 uni 导航 API，并与 pages.json 中已注册路径保持一致：

uni.navigateTo({
  url: '/pages/settings/index'
})

APP 默认允许直接进入首页和访问普通页面；登录页只在用户点击需要登录的能力时出现。需要登录的入口先检查本地登录态，未登录时使用 uni.showModal 提示，再跳转 /pages/auth/login?redirect=<目标页>；登录成功后写入登录态并使用 uni.redirectTo 回到 redirect 指定页面。普通功能页之间使用 uni.navigateTo。

扫码

基础相机扫码可使用 uni.scanCode：

uni.scanCode({
  onlyFromCamera: true,
  scanType: ['barCode', 'qrCode'],
  success: (res) => {
    this.form.code = String(res.result || '').trim()
  },
  fail: () => {
    uni.showToast({ title: '未完成扫码', icon: 'none' })
  }
})

要求：

  • 扫码结果先转为字符串并去除首尾空格。
  • 同时支持条码和二维码时使用 ['barCode', 'qrCode']。
  • 扫码失败必须给出中文提示。
  • 扫码后的结果应回填当前字段，不要跨页面隐式修改无关状态。
  • 若业务需要相册识图、图片预览加载态、智能变焦或多码点选，使用 @/uni_modules/mas-code-scan 的 openCodeScan，并以 // #ifdef APP-PLUS 包裹导入与调用；success 中读取 result.content 后回填字段，9021003 视为用户取消不提示，其他错误显示中文提示。
  • 有效识别区域通过 options.scanRegion 传给 openCodeScan，结构为 fullScreen 或 width、height、centerX、centerY 的 0~1 比例；业务页面统一调用 @/utils/scan-settings.js 的 getScanRegionSetting()，设置按 scanapp_settings_<userCode> 持久化。未配置时返回空对象，保持插件原有整帧识别行为。
  • APP-PLUS Android 原生 uni.showModal 的按钮视觉顺序与 H5 不一致时，统一由 main.js 的平台适配层交换显示文本，并还原 success/Promise 的 confirm、cancel 语义；业务页面继续按标准语义编写，不要逐个页面交换按钮或回调判断。

表单与提示

  • 提交前先执行页面级校验。
  • 校验失败通过 uni.showToast({ title, icon: 'none' }) 提示。
  • 提交期间使用 loading 或 submitting 状态防止重复提交。
  • 成功、失败和异常状态使用明确的中文提示。
  • 原型阶段可以使用本地 mock 数据，但要保持数据结构与真实业务字段一致，并将接口接入限制在 service/API 层，不在模板中直接拼接请求。

接口封装

  • APP 对接后端时统一通过 frontend/app/utils/request.js 发起 uni.request，页面中不要直接调用 uni.request。
  • 请求配置集中放在 frontend/app/config/index.js，当前生产插件 APP 业务端默认 baseURL 为 /appapi；主项目系统 API（例如 /file/image 上传）实际注册在 /api，调用时必须显式传入 baseURL: config.apiBaseURL，不能沿用默认基址。
  • 业务接口按模块放入 frontend/app/api/<module>/，例如生产扫码接口放在 api/produce/data-entry.js。
  • API 函数命名按页面语义表达，例如 getProcessOptions、submitOrderRecord、getOrderStatistics，页面只调用这些函数。
  • 业务表单中的图片统一采用“本地预览、提交时上传”：选图后仅保存 tempFilePaths 用于立即预览；提交时调用 @/api/upload.js 的 uploadImage(filePath, subDir)，将返回的服务器 URL 放入业务请求。上传失败时中止提交并保留本地图片，便于用户重试。
  • 图片上传使用 /api/file/image 和 config.apiBaseURL；公共 normalizeImageUrl() 会将后端本地存储返回的 127.0.0.1 / localhost URL 改写为配置的局域网后端地址，避免 Android 真机将回环地址解析为手机自身。历史记录中的服务器图片地址也必须经过该方法规范化。
  • 响应格式沿用后端 Json::success / Json::fail：code === 0 时默认返回 data，失败使用 msg 做中文提示。
  • token 从本地 scanapp_token 读取并写入 Authorization 请求头；后续接真实登录接口时替换原型 token 来源，不改页面调用方式。

样式与视觉规范

基础单位

  • 移动端尺寸统一使用 rpx。
  • 不在同一页面混用无必要的 px、rem 和 rpx。
  • 页面根节点设置 min-height: 100vh，并统一使用 box-sizing: border-box。
  • 卡片、按钮和输入区域的尺寸应保持稳定，避免文字变化造成布局跳动。

字号层级

正式运行页面统一使用以下字号档位，不新增其他字号：

字号 使用场景
38rpx 页面主标题、品牌主标题
32rpx 核心数据、关键数字、弹层主编号
28rpx 区块标题、记录主标题、主要设置项
26rpx 字段值、重点内容、次级编号
24rpx 操作文字、重要次级内容
22rpx 正文、按钮文字、表单标签
20rpx 说明文字、筛选项、辅助信息
18rpx 状态、时间、标签、脚注

字号要求：

  • 最大字号不得超过 38rpx。
  • 最小字号不得低于 18rpx。
  • 不使用 23rpx、30rpx、34rpx、36rpx、40rpx 等非标准档位。
  • 同一语义在不同页面使用相同字号，例如所有页面的卡片标题统一为 28rpx。
  • 只因字号调整而产生的视觉问题，优先调整容器宽度或换行，不随意增加新的字号档位。

颜色与层级

沿用当前 APP 的清爽生产工具风格：

  • 页面背景使用浅色中性背景，例如 #f4f6fb、#f5f7fb。
  • 内容卡片使用白色背景和轻量阴影。
  • 主色优先使用项目现有蓝色 #1677ff 或 #2f6cf6。
  • 成功状态使用绿色，失败或危险状态使用红色，警告状态使用橙色或黄色。
  • 文字颜色按主标题、正文、说明、辅助信息分级，不使用过多高饱和颜色。
  • 不在单个页面引入与现有页面不一致的主题色、渐变方向或状态颜色。

布局一致性

  • 页面内容使用统一的左右内边距和卡片间距，除非现场扫码等业务场景确实需要特殊布局。
  • 卡片圆角、边框、阴影应与同类页面保持一致。
  • 列表项使用分隔线或稳定卡片层级，不将多个卡片无意义地嵌套。
  • 右侧操作统一使用开关、值文本、箭头或图标表达，不重复增加装饰性按钮。
  • 小屏幕上长单号、商品编码等业务文本允许换行或使用 word-break: break-all。
  • 安卓端需要控制图标、文字、开关之间的横向距离时，优先使用显式 margin-left / margin-right 或固定 flex-shrink: 0，不要把关键间距只交给 gap；涉及 u-switch、自定义开关和扫码结果卡片时尤其如此。
  • 如果同一行里有图标+文字+开关这类组合，先确认安卓端真机表现，再决定是否保留 gap，默认把分离距离写在紧邻元素上。

状态与数据规范

  • 页面临时状态放在当前页面 data 中；跨页面共享状态需要先确认项目是否已有 store 方案。
  • 加载、空数据、提交中、成功、失败和禁用状态必须有明确表现。
  • mock 数据仅用于原型展示，不应伪装成已接入后端。
  • 不在本次样式任务中删除已有功能、字段、交互或路由。
  • 修改中心样式或公共能力前，先搜索所有页面调用方。

维护与演进规则

当项目实际实现与本技能不一致时：

  1. 先读取真实入口、路由、组件配置和页面调用方式。
  2. 以项目代码为准，不强行套用旧模板。
  3. 将已验证的新约定同步到本技能文件。
  4. 技能更新只描述确认过的差异，不进行无关重写。

开发检查清单

  • 页面文件位于 frontend/app/pages/ 合适目录。
  • 新页面已注册到 pages.json。
  • 导航路径与 pages.json 完全一致。
  • 已复用 uView Pro 组件和现有 uni.* 能力。
  • 扫码结果已清理空格，并处理成功和失败状态。
  • 表单已处理空值、重复提交和失败提示。
  • 字号只使用 18/20/22/24/26/28/32/38rpx。
  • 页面没有超过 38rpx 或低于 18rpx 的字号。
  • 同类页面的标题、正文、说明、状态字号一致。
  • 未修改与需求无关的功能、数据和路由。
  • 真机或移动端预览已检查长文本、空状态、弹层和底部操作区域。
Reference in New Issue View Git Blame Copy Permalink