249 lines
13 KiB
Markdown
249 lines
13 KiB
Markdown
---
|
||
name: frontend-app-common
|
||
description: app 移动端公共开发规范，基于 uni-app、Vue 和 uView Pro，覆盖页面组织、路由、组件、扫码交互、视觉字号和交付检查
|
||
globs:
|
||
- "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 写法，除非项目整体迁移。
|
||
|
||
## 目录与页面组织
|
||
|
||
```text
|
||
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` 中已注册路径保持一致：
|
||
|
||
```js
|
||
uni.navigateTo({
|
||
url: '/pages/settings/index'
|
||
})
|
||
```
|
||
|
||
APP 默认允许直接进入首页和访问普通页面；登录页只在用户点击需要登录的能力时出现。需要登录的入口先检查本地登录态，未登录时使用 `uni.showModal` 提示，再跳转 `/pages/auth/login?redirect=<目标页>`；登录成功后写入登录态并使用 `uni.redirectTo` 回到 `redirect` 指定页面。普通功能页之间使用 `uni.navigateTo`。
|
||
|
||
### 扫码
|
||
|
||
基础相机扫码可使用 `uni.scanCode`：
|
||
|
||
```js
|
||
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` 的字号。
|
||
- [ ] 同类页面的标题、正文、说明、状态字号一致。
|
||
- [ ] 未修改与需求无关的功能、数据和路由。
|
||
- [ ] 真机或移动端预览已检查长文本、空状态、弹层和底部操作区域。
|