前端技术文档

更新日期：2026-06-20。

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

工程总览

六个前端工程共用同一后端业务域，但使用场景不同。admin 偏管理和批量操作，页面以表格、筛选、弹窗和表单为主；client 偏消费者微信小程序购物；app 偏消费者原生 APP 体验，当前复用客户端接口；ops 偏微信现场作业；ops-app 偏原生现场作业和扫码能力；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 选择环境，开发版、体验版和正式版应分别配置后端域名。

当前 client-we/api/config.js、ops-we/api/config.js 和 ops-app/src/services/config.ts 的 release 域名仍是 https://api.example.com/client/api/v1 占位。正式发版前必须统一替换为项目正式客户端网关，并同步微信小程序 request 合法域名、uploadFile 合法域名和 client-we 的 h5BaseURL。

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

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

消费者金额展示

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

优惠券交互建议：

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

app

技术栈

• Expo、React Native、TypeScript。
• React Navigation 负责底部 Tab 和页面栈。
• HeroUI Native、Unwind 和 Tailwind CSS v4 负责移动端组件与样式。
• Lucide React Native 提供图标。
• 接口封装集中在 src/services/trade-api.ts。

主要目录

页面模块

• 登录：账号密码登录、验证码、用户资料拉取。
• 首页：Banner、分类、推荐商品。
• 商品：分类、搜索、商品列表、商品详情和商品卡片。
• 交易：购物车、订单确认、订单列表、订单成功。
• 营销：卡券中心、可领取券、我的卡券。
• 个人中心：个人资料、消息和基础功能入口。

请求约定

app/src/services/trade-api.ts 当前默认请求：

http://47.108.203.59:8092/client/api/v1

主要接口：

app 当前复用 client 侧业务接口，不承接后台审核和仓配作业。发布前需要把 API_BASE_URL 调整为对应环境的正式客户端网关，不能继续依赖测试 IP。

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 编译链。

页面模块

• 登录：运营角色登录、本地会话维护、admin 账户多身份选择和登录后功能直达。
• 首页：按角色展示商户、仓库、配送相关入口；命中直接功能后自动进入对应作业页。
• 商户发货：商户发货单列表和发货详情。
• 仓库作业：国内仓快速流程、车次恢复、批次二维码、连续扫码、封批、封车和出库。
• 海外仓作业：到仓确认、入库预查询、正式入库、仓内复核、中转、派送准备和默认配送员分配。
• 配送员任务：本人派送任务查询、签收、失败上报、退仓。

运营关键流程

业务注意事项

• ops 开发环境预置角色账号为：商户 apple、配送员 dispatcher_01、国内仓 gnck01、海外仓 gwck01，密码均为 123456。
• ops 使用 utils/auth.js 根据权限前缀、选中账户类型、角色关键字和用户名判断功能入口。登录后会调用 getDirectFeatureKey，命中商户、配送员、国内仓或海外仓身份时直接跳到对应页面。
• admin 认证服务登录前会先调用 /api/v1/login/accounts。如果返回多个可选账户，前端会按预置角色的账户类型和关键字选择账户，再把 accountType、accountId 带入 /api/v1/login。
• 当前海外仓页面不调用 /api/v1/logistics/overseas-warehouse/...，而是使用通用仓接口 /api/v1/logistics/warehouse/...。
• 配送员接口在后端 wt-admin 下，路径包含 /api/v1/logistics/dispatcher/query 和 /api/v1/logistics/dispatcher/task。
• 仓派送加包存在包裹状态前置条件，前端页面需要展示后端返回的阻断原因，不应自行判断可派送。
• 国内仓快速流程一次只允许存在一个未封批批次。页面发现未封批批次时，会切回该批次并提示先封批，再创建下一批。
• 国内仓和海外仓页面把主流程按钮放在当前阶段，批次列表、任务详情、查询工具和回退类操作放入“高级操作 / 详情”折叠区。
• 国内仓页面支持按车次号或车次 ID 恢复，支持展示车次号、车次系统编号和批次编号二维码；二维码内容过长时会提示无法生成。
• 海外仓派送不再让现场人员手动选择配送员，页面会在配送员列表中查找 dispatcher_01 对应的员工账号；找不到时阻断创建派送或分配配送员。

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

ops 作业恢复

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

ops-app

技术栈

• Expo、React Native、TypeScript。
• React Navigation 负责页面栈。
• Expo Camera 提供扫码能力。
• HeroUI Native、Unwind 和 Tailwind CSS v4 负责移动端组件与样式。
• Lucide React Native 提供图标。
• 接口封装集中在 src/services/api.ts、src/services/request.ts、src/services/config.ts。

主要目录

页面模块

• 登录：选择环境、选择业务入口、验证码、登录账户选择和 Token 保存。
• 首页：根据角色展示商户发货、国内仓、海外仓和配送员任务入口。
• 商户发货：查询发货单、查看待发货明细、按明细发货。
• 国内仓：创建或恢复国内仓快速流程，批次扫码、封批、封车、出库。
• 海外仓：车次到仓、入库预查询、正式入库、复核、中转、派送。
• 配送员任务：本人任务列表、任务详情、签收、失败、退仓。

请求约定

环境配置在 src/services/config.ts：

ops-app 通过 service 切换实际入口：

主要接口分组：

仓配和配送员相关接口需要显式使用 service: "admin"。商户发货和商户资料优先使用 client 服务。联调时如果同一路径在两个入口都存在，先按页面身份确认服务前缀，再看权限标识。

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

app 和 ops-app 使用 Expo：

bun install
bun run start
bun run typecheck

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

bun run start

补充说明：

• admin 的脚本来自 package.json，构建会先执行类型检查。
• client 使用微信开发者工具打开 client/project.config.json，依赖变化后执行“构建 npm”。
• ops 使用微信开发者工具打开 ops/project.config.json，依赖变化后执行“构建 npm”。
• app 使用 Expo 启动，发布前需要确认 src/services/trade-api.ts 的 API_BASE_URL。
• ops-app 使用 Expo 启动，开发和预发环境由登录页或上下文选择，服务前缀由 service 控制。
• h5 默认访问 http://localhost:3016/activity/618/，根路径会按默认活动入口跳转。
• 小程序样式优先复用各自 app.wxss 中的公共变量和工具类。

开发约定

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

联调检查清单