7.8 KiB
7.8 KiB
员工端 H5 前端经验总结
这份文档记录当前员工端 H5 在页面规划、接口接入、移动端兼容、扫码核销和部署上的经验。后续改页面时，优先按这里的约定处理，避免重复踩坑。
页面规划
- 第一版页面以业务闭环为主，不做后台管理式的大而全页面。
- 当前核心页面包括：登录、工作台、订单列表、订单详情、扫码核销、核销确认、核销结果、事件列表、发布事件、我的。
- 工作台上的统计数据必须有明确后端依据。没有独立统计接口时，可以展示列表接口能稳定支持的指标，例如待确认订单、生效事件、近期订单、近期事件。
- 不要把 mock 推导出的数据当成真实业务指标。比如订单表没有可直接查询的核销状态或核销时间时，不要在工作台展示“今日核销”这类指标。
- 页面文案保持员工端视角，产品名称统一使用“员工端”。
登录与组织关系
- 登录使用手机号验证码流程，登录成功后必须主动调用
/hotelStaff/organizationMember/bindUserInfoAndGetUserMemberInfoByPhone获取当前用户组织关系。 - 如果组织关系获取失败，统一提示“未绑定组织，请联系管理员”。
- 当前不需要调用
/user/checkUserHasBindPhone。 - 登录态只代表认证成功，不代表用户一定拥有员工端组织关系，业务页面入口应以后续组织关系接口成功为准。
- 接口返回“请求令牌已过期”、
401或 token 失效类错误时，要统一清理本地登录态并跳转/login，同时带上当前页面作为redirect，避免用户继续停留在失效页面。
接口路径
- 所有真实接口都通过后端网关访问，由网关按路由转发到具体服务。
- 本地开发使用 Vite proxy，当前开发网关是
http://192.168.3.211:9999。 - 员工端接口前缀是
/hotelStaff，订单接口路径是/hotelStaff/order/...，事件接口路径是/hotelStaff/event/...。 - 登录接口走
/auth，验证码和用户相关接口走/admin。 - 不要在业务代码里硬编码完整网关地址，统一从环境变量和
src/utils/env.ts读取。
环境与部署
- 本地开发使用
.env.local，测试打包使用.env.test，生产打包使用.env.production。 VITE_API_BASE_URL为空时，前端会按当前站点同源请求接口，适合 Nginx 反向代理部署。- 前后端分离部署时，优先用 Nginx 把
/auth、/admin、/hotelStaff、/hotelBiz等路径代理到后端网关，这样浏览器看到的是同源请求，跨域问题最少。 - 如果直接把
VITE_API_BASE_URL配成后端网关 IP 或域名，跨域就需要后端网关正确返回 CORS 头；这不是前端代码能完全解决的。 - SPA 路由需要 Nginx
location / { try_files $uri $uri/ /index.html; }。
移动端布局
- H5 页面不要依赖固定宽度，所有主容器都应具备
width: 100%、max-width: 100%、min-width: 0这类约束。 - flex 或 grid 中承载长文本的区域要使用
min-width: 0，grid 列建议用minmax(0, 1fr)，否则长订单号、手机号、商品名容易撑出横向滚动。 html、body、#app可以限制overflow-x: hidden，但这只是兜底。真正要处理的是子元素宽度、长文本换行和 flex 收缩。- 图片、视频、canvas 必须有
max-width: 100%，避免媒体元素撑破视口。 - 固定底部导航、按钮区域需要考虑
safe-area-inset-bottom，兼容 iPhone 底部安全区。
输入框兼容
- iOS Safari 和微信内置浏览器中，输入框字号小于 16px 时，聚焦输入框会触发页面自动放大，容易出现横向滚动和布局错位。
- 全局真实输入控件，包括
input、textarea、select、.van-field__control，应保持font-size: 16px。 - 不建议通过
maximum-scale=1或user-scalable=no禁止用户缩放，这会影响可访问性，也不能从根上解决布局问题。 - 搜索框、登录手机号、验证码、日期时间输入都要按真实输入控件处理，不要只调整外层字体。
Vant 组件样式
- 修改全局样式时要避免过宽的选择器，例如
.meta-row span会误伤 Vant 的van-tag，导致“生效中”“已取消”等标签在 Chrome 里被拉伸或错位。 - 对普通文本列可以使用
.meta-row > span:not(.van-tag)，状态标签应单独设置flex: 0 0 auto和white-space: nowrap。 - Vant 组件内部结构可能使用
span、button、input等基础标签，写全局选择器时要先确认是否会影响组件内部 DOM。 - 共享样式要放在
src/styles/main.css，页面个性化样式放在对应.vue的 scoped style。
扫码核销
- 当前二维码内容规则是
orderId&packageName，其中packageName是套餐名称。 - 前端解析时必须兼容只有
orderId的情况。 - 扫码流程是：点击进行扫码 -> 调起摄像头 -> 解析二维码 -> 查询订单详情 -> 展示核销确认 -> 调用核销接口。
- 当前核销入口不提供手动输入订单号兜底，页面文案保持“点击进行扫码”。
- 扫码内容带
packageName时，核销确认页只能展示并核销当前扫码进入的套餐商品；不能让员工切换到其他套餐。 - 扫码内容只有
orderId时，核销确认页可以按订单详情里的套餐配置展示可选套餐。 - 浏览器扫码优先使用原生
BarcodeDetector，不支持时使用jsQR读取视频画面进行解析。 - 摄像头能力通常要求 HTTPS 或 localhost。微信内置浏览器如果
getUserMedia受限，后续可以考虑接入微信 JSSDK 的scanQRCode，但需要公众号配置、签名接口和 JS 安全域名配合。
订单与核销记录
- 订单列表当前保留手机号搜索和订单状态筛选。
- 订单详情可以发起核销，核销确认页需要展示订单核心信息，避免员工误核销。
- 核销确认页必须展示可核销商品数、已核销商品数、总数量，优先使用后端套餐配置里的
count、writeOffCount、packageStatus字段。 - 当可核销商品数为 0 时，确认核销按钮应禁用，并提示当前套餐商品已核销完。
/hotelStaff/order/writeOff返回值是Boolean，前端不能只看 HTTP 成功；如果返回false，必须按核销失败处理。- 后端状态机会限制超量核销并控制核销记录数量，前端职责是正确展示剩余数量并正确处理失败态。后端如果能透传“该套餐商品已被核销完”等具体错误，会让前端提示更准确。
- 订单详情的核销记录中，如果后端返回套餐名称，要展示套餐名称，便于员工核对。
- “使用信息”里不要展示核销地点，当前后端和页面需求不需要这个字段。
事件模块
- 发布事件页面里的“实体名称”已改为“事件标题”。
- 事件列表搜索提示文案为“搜索事件标题”。
- 事件列表不需要开启和关闭按钮，也不需要以开启/关闭作为主要筛选交互。
- 列表上的状态展示要谨慎处理样式，不能影响 Vant 标签的自然宽度。
验证清单
每次改动移动端布局、表单、列表或扫码能力后，至少检查：
yarn typecheckyarn build:test- 320px 和 375px 宽度下是否出现横向滚动
- 登录页输入框聚焦后是否自动放大
- 订单搜索输入框聚焦后是否自动放大
- Chrome 里订单状态、事件状态标签是否保持正常宽度
- 真机或微信内置浏览器里扫码入口是否能正常申请摄像头权限
- 扫码带套餐进入核销确认页时，只能看到当前套餐
- 核销确认页的可核销商品数、已核销商品数、总数量和后端返回一致
/writeOff返回false或失败时，前端不能展示核销成功