前端技术文档

更新日期：2026-05-31。

本文记录当前前端工程：admin、client、ops、h5。所有包管理命令统一使用 bun。

工程总览

四个前端工程共用同一后端业务域，但使用场景不同。admin 偏管理和批量操作，页面以表格、筛选、弹窗和表单为主；client 偏消费者购物，页面以商品、订单和个人中心为主；ops 偏现场作业，页面需要优先支持扫码、快速确认、状态提示和异常原因展示；h5 偏活动内容展示，通过静态资源和接口代理承接会场访问。

admin

技术栈

• Vue 3、TypeScript、Vite Plus。
• Element Plus 作为管理端 UI 组件库。
• Pinia 管理用户、菜单、设置、标签页和表格状态。
• Vue Router 支持静态路由和后端菜单转路由。
• Axios 封装在 src/utils/http，业务接口集中在 src/api。

主要目录

状态与路由

admin 支持前端静态路由和后端动态菜单两种方式。src/router/routes/asyncRoutes.ts 中的泛资源路由会把 baseUrl、主键、表单字段、远程选择器和动作按钮下发给 AdminResource 页面，适合营销、消息、基础资料等标准 CRUD 页面。业务页面应以菜单配置为入口，避免只添加页面文件但没有菜单和权限。

页面模块

• 账号：员工、企业、政府、商户、个人账户。
• 商品：类目、品牌、属性、SPU、SKU、SKU 管理、库存、价格策略、上架、上架审核、商品创建流程。
• 业务：订单、发货、物流相关业务视图。
• 运营：Banner、Banner 分组、广告、公告、营销活动、优惠券、券池、预算、活动价、佣金、钱包、物流公司、运费规则、包裹类型。
• 组织：组织信息、物流组织、我的店铺、组织订单、仓库。
• 系统：用户、角色、菜单、字典、地区、通知、日志、系统设置、用户中心。
• 文件：文件中心和图片选择能力。

请求约定

• 接口封装使用相对业务路径，例如 product/spu/page、logistics/delivery-order/page。
• 请求基础地址由环境配置和代理决定。
• 业务模块新增接口应放到对应 src/api/*Api.ts，页面不直接拼接底层请求细节。

管理端接口封装建议按业务域维护：

管理端新增标准资源页时，优先复用 ResourceService 和泛资源配置；涉及状态流转的按钮，例如启动、暂停、恢复、结束、结算归档、取消、充值和退回，应配置为独立动作接口，不能用普通编辑接口替代。

client

技术栈

• 微信原生小程序工程，页面由 .js、.wxml、.wxss、.json 组成。
• Vant WeApp 提供小程序组件。
• Big.js 用于购物车和订单金额计算。
• 全局样式集中在 app.wxss，公共工具类和语义样式优先在这里维护。
• 不使用 weapp-vite、Tailwind CSS、SCSS 或 TypeScript 编译链。

主要目录

页面模块

• 登录：账号密码登录、微信登录、手机号绑定。
• 首页与导购：首页、分类、搜索、搜索结果、商品列表、商品详情。
• 店铺：店铺入口、店铺列表、店铺主页、店铺分类、店铺收藏。
• 交易：购物车、订单确认、订单列表、订单详情、订单成功、支付、支付结果。
• 售后与评价：退款申请、退款列表、退款详情、评价列表、评价创建。
• 个人中心：我的、个人资料、地址、地址管理、优惠券、收藏、店铺关注、足迹、钱包、支付记录、社交账号、账户安全、客服、帮助、设置、关于。
• 消息与物流：消息列表、消息偏好、消息订阅、待办、公告、物流详情。
• 营销：营销活动、优惠券、卡券钱包、秒杀、拼团页面。

消费者关键流程

请求环境

请求封装在 api/request.js，环境配置在 api/config.js。小程序根据 envVersion 选择环境，开发版、体验版和正式版应分别配置后端域名。正式版域名上线前需要替换占位值。

小程序本地缓存需要谨慎处理：

• 未完成手机号绑定时，不写入完整登录态。
• 用户资料、头像 URL 和账户关系更新后，要同步刷新本地缓存。
• 订单、购物车和地址页面进入时应重新拉取关键数据，避免跨页面状态过期。
• 多语言切换后，登录参数和页面文案都需要保持一致。

消费者金额展示

订单确认页应展示后端返回的完整金额结构，不自行根据券面额重算最终金额。

优惠券交互建议：

1. 进入订单确认页先做不带券试算。
2. 调用可用券接口展示可选平台券和商户券。
3. 用户选券后重新试算，展示后端返回金额。
4. 创建订单时传入同一组卡券钱包项。
5. 支付失败、取消或返回订单确认页时重新查询可用券和卡券状态。

ops

技术栈

• 微信原生小程序工程，页面由 .js、.wxml、.wxss、.json 组成。
• Vant WeApp 提供小程序组件，公共组件在 app.json 中注册。
• 接口封装集中在 api/auth.js、api/logistics.js、api/system.js。
• 请求、会话、鉴权和页面工具集中在 utils/。
• 不使用 weapp-vite、Tailwind CSS、SCSS 或 TypeScript 编译链。

页面模块

• 登录：运营角色登录和本地会话维护。
• 首页：按角色展示商户、仓库、配送相关入口。
• 商户发货：商户发货单列表和发货详情。
• 仓库作业：国内或通用仓作业入口。
• 海外仓作业：到仓确认、入库预查询、正式入库、仓内复核、中转、派送准备。
• 配送员任务：本人派送任务查询、签收、失败上报、退仓。

运营关键流程

业务注意事项

• 当前海外仓页面不调用 /api/v1/logistics/overseas-warehouse/...，而是使用通用仓接口 /api/v1/logistics/warehouse/...。
• 配送员接口在后端 wt-admin 下，路径包含 /api/v1/logistics/dispatcher/query 和 /api/v1/logistics/dispatcher/task。
• 仓派送加包存在包裹状态前置条件，前端页面需要展示后端返回的阻断原因，不应自行判断可派送。

现场作业页面应优先保证操作反馈明确。所有扫码、确认、出库、签收等动作都需要展示后端返回结果；失败时展示业务错误原因，不只显示“操作失败”。

ops 作业恢复

ops 现场作业页面不能依赖本地缓存作为流程事实来源。用户退出后重新进入，应通过业务编号恢复现场：

h5

技术栈

• 使用 Bun.serve 提供本地或部署后的静态服务。
• 静态活动页放在 h5/public/activity/<活动标识>/，公共图片放在 h5/public/assets/<活动标识>/。
• 构建脚本在 h5/scripts/build.ts，产物输出到 h5/dist。

请求和路由

h5 只承接活动会场和素材展示，不承接登录态复杂业务。需要下单、领券或查看订单时，应跳转小程序页面或调用 client 侧已有接口能力。

常用命令

前端工程均使用 bun 管理依赖。admin 有完整开发和构建脚本：

bun install
bun run dev
bun run build
bun run check

client 与 ops 以微信开发者工具编译、预览和真机调试为准：

bun install
bun run check

h5 可直接用 Bun 启动活动服务：

bun run start

补充说明：

• admin 的脚本来自 package.json，构建会先执行类型检查。
• client 使用微信开发者工具打开 client/project.config.json，依赖变化后执行“构建 npm”。
• ops 使用微信开发者工具打开 ops/project.config.json，依赖变化后执行“构建 npm”。
• h5 默认访问 http://localhost:3016/activity/618/，根路径会按默认活动入口跳转。
• 小程序样式优先复用各自 app.wxss 中的公共变量和工具类。

开发约定

• admin 新接口先落到 src/api，小程序新接口先落到各自 api/，再由页面调用。
• 优先使用 async/await。
• 除非确有必要，接口调用层不额外包裹 try/catch。
• 中文文案与英文、数字之间保留空格，避免乱码。
• 小程序页面新增后需要同步各自 app.json。

联调检查清单