更新记录

1.0.1（2026-09-22）

1.0.1（2026-09-22）

去掉模板遗留的演示组件与文档，工程只保留包月本业务。

删除未使用的地图、条码、聊天、商品、公告等组件及相关代码 文档改为包月本流程与云函数契约（不再写 VaporX / Mock）

1.0.0（2026-09-22）

适用场景

给小区「上门代收 / 代扔垃圾」等包月服务的店主用。店主管客户和上门，住户扫码申请、看套餐、申报付款。

技术栈

• uni-app x（uvue / UTS）
• 微信小程序
• uniCloud（支付宝云）云函数 + 云数据库

功能清单

店主端

• 店铺设置：店名、小区、楼栋数、电话、时段、规则、收款码、强制拍照
• 套餐管理：价格、天数、频次、启用/停用
• 挂牌推广：门口立牌 / 电梯贴 / 楼道告示模板，下载彩印图；生成微信小程序码
• 今日上门：待收/已收/异常，左滑加袋、异常；可强制拍照后标记已收
• 客户：搜索筛选、详情、续费/催付/请假/停用
• 统计：本月账面、今日上门、待确认收款、近七日柱状图

住户端

• 扫码进入申请页，填门牌申请包月
• 今日：今日代收状态、套餐与规则
• 套餐页：店主收款码、申报付款、等待店主确认后生效
• 我的：代收记录、回到店主（同机调试）

交付内容

• 完整前端工程
• uniCloud 云函数 api
• 使用说明（见下方部署步骤）

部署步骤（购买后）

1. 导入 HBuilderX，重新申请自己的 DCloud AppID
2. 绑定自己的 uniCloud 服务空间，上传云函数 api
3. 微信小程序后台配置 AppID；云函数目录 wx.json 填写自己的 AppSecret
4. 开通相册、相机等权限（挂牌下载、强制拍照）
5. 发行到微信开发者工具 / 提交体验版

注意事项

• 不包含你的微信 AppSecret、正式服密钥；需自行填写
• 默认按「单店」场景设计，多租户需自行扩展
• 收款为「出示收款码 + 申报 + 店主确认」，不是微信自动分账

平台兼容性

云端兼容性

uni-app x(5.0)

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

包月本（门口本）

小区代扔垃圾包月台账。店主按楼栋上门收袋，住户查看自己的卡并续费。

演示账号

• 从业者：*** / 123456
• 住户：*** / 123456

请求与 Mock

• config/env.uts 默认 USE_MOCK = true，走本地 Mock。
• 关闭 Mock 且 USE_UNICLOUD = true 时走 uniCloud 云函数 api。

使用流程

• 今日：按楼栋列出应上门客户，拍照标记已收，异常登记，加一袋。
• 客户：按状态筛选（全部 / 包月中 / 试用 / 到期 / 已停用），到期提醒，停用/恢复。
• 店铺：维护 SKU 上下架、强制拍照、服务规则。

VaporX

通用 uni-app x 前端项目模板（蒸汽模式 / vapor）。当前版本 1.1.0（2026-09-17）。

可在 HBuilderX 中作为 uni-app 前端项目模板 免费发布到插件市场。发布步骤见 docs/plugin-publish.md，更新日志见 changelog.md。

后端与 admin 端延后（见 PRD V2.1 附录 A）。

版本时间轴

完整条目见 changelog.md。首页「版本记录」使用同一套节点。

目录结构

uniapp_x_front/
├── main.uts               入口（createSSRApp + Pinia + setupApp）
├── index.html             H5 入口页（Vite 模板，VDOM 模式运行到浏览器必需）
├── App.uvue               应用根组件（引入全局主题样式）
├── manifest.json          uni-app-x 蒸汽模式配置
├── pages.json             页面注册（M0 全主包，分包拆解见模块 README）
├── uni.scss               全局 SCSS 变量与混入（自动注入）
├── config/                应用 / 环境 / 主题 / 模块开关
├── api/                   纯 TS 请求层（types/http/request）
├── utils/                 uni API 触点（storage/platform/toast/setup/share）
├── store/                 Pinia（app/auth/user/message）
├── mock/                  Mock 适配器与聚合入口
├── components/base/       base 基础组件（easycom）
├── components/pro/        pro 复合组件（easycom，与 base 同级）
├── uni_modules/           本地第三方插件（发布包会跳过）
├── modules/<name>/        业务模块（自洽、可拆解）
├── styles/                主题 CSS 变量 + 原子工具类 + SCSS 变量/混入
├── scripts/               Mock 切换脚本（npm run mock:on|off）
├── static/                静态资源
└── docs/                  交付文档（开发/运行/功能清单/后端对接/授权协议）

扩展名约定

• 纯 TypeScript 逻辑用 .uts，页面 / 组件用 .uvue。
• .uvue 内 <script setup> 不写 lang，vue API（ref/computed/watch/onMounted 等）自动引入，不要 import。
• 外部 .uts 文件需显式 import（如 import { ref } from 'vue'、import { defineStore } from 'pinia'）。
• 请求层 header 类型为 UTSJSONObject（api/http.uts / api/request.uts），是 uni-app x 系统边界要求；业务逻辑仍为普通 js/ts。

运行

1. 在 uniapp_x_front/ 执行 npm install（安装 pinia@3.0.4，与 HBuilderX 5.25+ 内置版本对齐；vue 由 HBuilderX 提供，不要另装）。
2. 用 HBuilderX（Pinia 集成建议 5.25+，最低 5.21+）打开 uniapp_x_front/ 目录。
3. 首次打开会重新生成 appid；mp-weixin.appid 需自行填入微信小程序 AppID。
4. 运行到 H5 / 微信开发者工具 / App 模拟器验证。

请求与 Mock

• config/env.uts 的 USE_MOCK = true 时走本地 Mock，false 时走 uni.request 真实接口；也可用脚本一键切换：npm run mock:on / npm run mock:off（切换后需重新编译）。
• api/request.uts 统一处理 loading、错误提示、鉴权头、401 单飞刷新并重放原请求。

文档索引（docs/）

模块化

• 新增业务模块：在 modules/<name>/ 放 types/api/mock/pages，注册 pages.json 页面，并在 mock/index.uts 聚合 Mock 路由。
• 禁用模块：config/modules.uts 中 enabled: false，并同步移除 pages.json 页面注册与 mock/index.uts 聚合。
• 分包注意：微信小程序主包不能引用分包模块，M0 全部页面注册在主包；后续拆分包时保持「模块代码在主包、子包只放页面壳」。

M0 范围

工程骨架 + 请求封装 + Mock + Pinia + 双主题 + base 组件（loading/empty/navbar）+ 公告 Demo 页面。

M1 范围（已落地骨架）

• 登录 / 注册 / 忘记密码 + Mock（验证码 123456，密码 123456）。
• 路由守卫：config/auth.uts 的 NEED_LOGIN_PAGES（uni-app x 的 pages.json 不支持 needLogin）。
• Token 刷新、登出清会话、登录成功回跳。
• 自定义 Tabbar（首页 / 消息 / 我的），图标在 static/svg/。
• 我的：资料、通知开关、清缓存、关于、退出登录。

M2 范围（已落地）

• 公告：列表关键字搜索 + 详情（富文本）。
• 消息中心：列表分页、未读红点、全部已读、详情自动已读、Tabbar 未读角标。
• 意见反馈：文字 + 图片（最多 4 张）提交、我的反馈列表、详情与官方回复卡片。
• 文件浏览：PDF / 图片在线预览（H5 web-view / App 与小程序 downloadFile + openDocument），统一封装 utils/file.uts。
• 组件补齐：base 原子件（skeleton / error / upload / input）+ pro 复合件（form / load-more）。
• 新增页面：modules/notice/pages/detail/detail、modules/message/pages/detail/detail、modules/feedback/pages/{list,submit,detail}。

M3 范围（已落地）

• base 组件补齐：base-dialog（声明式弹窗，v-model + 自动关闭/异步 loading）、base-share（底部分享面板，App 系统分享 / 全端复制链接），分享逻辑集中在 utils/share.uts。
• 商品展示（goods）：分类筛选 + 列表 + 详情（图集 / 参数 / 富文本），仅展示不做交易，游客可浏览。
• 服务预约（reservation）：选商品 + 填信息提交，生成预约记录，状态流转「待处理 / 已联系 / 已完成 / 已取消」，支持取消待处理预约。
• 收藏（favorite）：商品 / 公告可收藏，我的收藏列表 + 取消收藏，通用 targetType/targetId 结构。
• 支付占位（api/pay.uts）：统一支付签名，当前抛「未接入」，附 docs/payment.md 微信/支付宝接入步骤。
• 双主题 + 深色模式：styles/theme/{default,business,dark}.scss 三套变量，config/theme.uts 编译期默认值 + store/app 运行时切换 + 「我的」页入口（主题风格 / 深色模式），深色默认跟随系统（prefers-color-scheme）。附 docs/theme.md 换主题指南。
• App 版本检查与更新引导：utils/version.uts 版本比较 + api/version.uts 拉取最新版本 + mock/version.uts 演示数据 + utils/update.uts 检查/下载引导（仅 App 端生效），「关于我们」页「检查更新」弹「发现新版本」对话框。下载先复制链接 + 引导（真实对接再换各平台商店 open API）。

M4 范围（已落地，待真机验证）

• 文档全套：开发文档 / 运行文档 / 功能清单 / 后端对接指南 / 授权协议模板，见上方「文档索引」。
• Mock 切换脚本：scripts/toggle-mock.js（npm run mock:on|off），已实测往返切换。

已知待验证（需 HBuilderX 三端真机）

• rich-text 在 App 端的渲染表现。
• 微信小程序分享已接入（首页 / 商品详情 / 公告详情实现 onShareAppMessage），需在开发者工具验证右上角分享与卡片内容。
• 主题运行时切换已覆盖全部页面（根视图统一绑 appStore.pageClass），三端实际换肤表现需对照验证。
• App 端更新引导需真机核对剪贴板与商店跳转。
• 文件浏览 PDF 预览三端差异：H5 web-view、App/小程序 openDocument，小程序需配置 downloadFile 合法域名（见 docs/compatibility-checklist.md）。