更新记录

1.0.1（2026-10-21）

这个模板解决什么问题

社区团购、驿站代收普及后，「最后一公里到门口」这一段一直是断的：驿站 21:00 关门，上班族 19:00 才到家；老人搬不动大件；下雨天不想下楼。

平台兼容性

云端兼容性

uni-app(5.32)

云函数类插件通用教程

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

邻里代取 · 社区驿站代取互助小程序

一套可直接运行的社区跑腿完整项目模板：同一个小区的邻居互相帮忙，把包裹从驿站捎到门口，发单人付服务费，接单邻居赚劳务费。

uni-app（Vue 3）+ uniCloud 阿里云，只做微信小程序端，全云对象架构，零第三方 UI 库，15 张表（11 在用）、6 个云对象、1 个定时函数、14 个页面。

• 前端 25 个 .vue（约 8500 行）+ 15 个 .js（约 1200 行）
• 云端 20 个 .js（约 2400 行）+ 16 份 schema / 初始化数据
• 不依赖 uni-ui、uView、colorui 等任何 UI 库，所有组件自建（easycom，yd- 前缀）

一、这个模板解决什么问题

社区团购、驿站代收普及后，「最后一公里到门口」这一段一直是断的：驿站 21:00 关门，上班族 19:00 才到家；老人搬不动大件；下雨天不想下楼。

模板把这件事做成了一个双边市场：

• 发单人：选小区 → 选驿站 → 填取件码 → 付服务费 → 等邻居送上门
• 接单邻居：认证 → 上线 → 大厅抢单 → 到驿站取件（上传凭证）→ 送达（上传凭证）→ 拿钱

因为只服务单个小区（communityId 贯穿全表），供需密度足够高，3 分钟内就能匹配到人，这是它和全城跑腿平台的根本区别。

二、功能清单

2.1 已实现（开箱可用，无需改代码）

账号与小区

下单与支付

接单与履约

结算、信用与兜底

工程与体验

2.2 未实现（需要你自己接，代码里已留好位置）

2.3 刻意不做（设计取舍，不是漏了）

• 不做承运：不生成面单、不做干线运输，只做「驿站 → 家门口」这一段
• 不用微信分账：本场景接单方要拿 85%，微信分账上限 30%，因此资金模式是「平台自营 + 众包劳务」
• 不做押金：用信用分替代，避免资金池合规问题
• 不做全城调度：一个小区一个池子，不做跨小区派单
• 不做实时聊天：站内不设 IM，靠备注 + 客服电话
• 文案禁用「快递 / 运费」：统一说「代办服务 / 服务费」，避免被认定为快递经营

三、技术架构

【微信小程序端】uni-app Vue3 + Pinia
  pages/*.vue        14 个页面 —— 只调 api/*，不直接 importObject
       ↓
  api/*.js           5 个文件，薄封装
       ↓
  utils/request.js   统一错误 toast / token 失效清本地态 / 防抖跳转
       ↓  uniCloud.callFunction
────────────────────────────────────────────
【uniCloud 阿里云】
  云对象 6 个    yd-base  yd-user  yd-address  yd-order  yd-rider  yd-pay
  云函数 1 个    yd-task（定时触发器，每 5 分钟）
  公共模块 2 个  yd-common（业务内核）、uni-config-center（配置中心）
       ↓
  云数据库 15 张表（permission 全 false，只有云端能读写）
  云存储（存证照片、头像）

3.1 为什么全走云对象

不用 clientDB / JQL，所有读写都在云对象里：

• schema 的 permission 全部写 false，客户端无法直连数据库，越权面为零
• 金额、状态机、抽佣、加密全部在服务端，客户端拿不到密文和手机号
• 代价是每个业务方法都要写一遍参数校验，换来的是不会被前端改价

3.2 目录结构

├── App.vue                     全局事件监听（登录失效、小区失效）
├── main.js                     Pinia 挂载
├── manifest.json               ⚠️ 本模板已清空 appid，导入后请填自己的
├── pages.json                  14 个页面 + 4 个 tabBar
├── uni.scss                    设计令牌（颜色/字号/间距/圆角）唯一来源
├── api/                        接口层：address common order rider user
├── common/constants.js         前端常量镜像（订单状态、错误码、事件名、时限默认值）
├── components/                 10 个自建组件，全部 yd- 前缀
│   ├── yd-icon/icons.js        内联 SVG 图标表
│   ├── yd-privacy/             隐私授权弹窗
│   └── yd-order-card/          接单大厅订单卡
├── pages/
│   ├── index/                  首页：进行中订单 + 服务入口
│   ├── login/                  登录 + 手机号（支持 forcePhone 改号）
│   ├── order/{create,list,detail}/
│   ├── rider/{hall,task,wallet}/
│   ├── user/{mine,address,cert,community}/
│   └── common/webview/         协议 / 隐私政策
├── static/                     logo + 4 组 tabBar 图标
├── store/                      user.js（登录态）config.js（服务目录/计价/时限）
├── utils/
│   ├── request.js              云对象调用 + 错误处理 + 401 回登录
│   ├── privacy.js              隐私授权（主动询问 + 拦截兜底）
│   ├── format.js               金额/时间/距离/时长格式化
│   ├── order.js                状态文案、颜色、步骤条
│   ├── pickup.js               取件码解析与校验
│   └── auth.js                 登录态判断
├── scripts/pack-market.py      打包到插件市场（清 appid、清密钥、去 unpackage）
└── uniCloud-aliyun/
    ├── cloudfunctions/
    │   ├── common/yd-common/   业务内核（11 个文件）
    │   │   ├── token.js        自签 HS256
    │   │   ├── auth.js         验签 + 读用户 + 角色判断
    │   │   ├── crypto.js       AES-256-GCM
    │   │   ├── pricing.js      计价
    │   │   ├── timeout.js      时限解析（读 service_catalog）
    │   │   ├── wallet.js       钱包（乐观锁 + 流水）
    │   │   ├── payment.js      支付流水
    │   │   ├── sweep.js        四条超时兜底
    │   │   ├── resp.js         统一响应
    │   │   ├── geo.js          地理工具
    │   │   └── constants.js    状态机与业务常量
    │   ├── common/uni-config-center/  配置中心（yd/config.json）
    │   ├── yd-base/  yd-user/  yd-address/  yd-order/  yd-rider/  yd-pay/
    │   └── yd-task/            定时任务
    └── database/               15 张表 schema + 索引 + db_init.json（种子数据）

3.3 分层铁律

1. 页面只调 api/*，绝不直接 uniCloud.importObject
2. 云对象只通过 yd-common 共享逻辑，彼此不互相调用
3. 每个云对象都在自己的 package.json 里平铺声明 file:../common/xxx 依赖（uniCloud 不递归解析）
4. 金额一律用「分」存整数；时间一律用时间戳
5. 云端与前端的常量两份（common/constants.js ↔ yd-common/constants.js），改动必须同步

四、数据模型

4.1 15 张表（11 张在用 + 4 张仅 schema）

db_init.json 覆盖 12 张表（withdraws / complaints / audit_logs 无种子数据）（含 3 个小区 + 3 个驿站 + 1 条服务目录种子数据）。

4.2 订单状态机

PENDING_PAY ──支付──> PENDING_ACCEPT ──抢单──> ACCEPTED ──取件──> PICKED ──送达──> DELIVERED ──确认/自动──> COMPLETED
     │                      │                    │
     └──取消/超时关单──> CANCELLED <──取消(扣30%补偿)┘
                            │
                    无人接单超时 ──> CANCELLED + 退款
                            ↓
                        REFUNDED（资金态）

DELIVERING 为预留中间态（当前不写入）、DISPUTED 为申诉态（未实现）。

取消规则：PENDING_PAY / PENDING_ACCEPT 全额退；ACCEPTED 扣 riderIncome × 30% 补偿接单方；PICKED 之后不可取消。

4.3 订单上的四个截止时间

设计要点：截止时间写死在订单上，不是每次现算。这样后台调整时限只影响新订单，不会把已经挂在厅里的订单的承诺时间改掉。

五、计价与分账

阶段一只有一个服务：FETCH（驿站代取）。规则在 service_catalog.pricingRule：

{
  "base": 250,          // 基础服务费 2.50 元
  "weightStep1": 100,   // 5–10kg 加 1.00 元
  "weightStep2": 300,   // >10kg 再加 3.00 元（叠加 step1）
  "urgent": 200,        // 加急加 2.00 元
  "night": 200          // 夜间(21:00–08:00)加 2.00 元
}

计算（全部整数分）：

总额   total        = base + weightSurcharge + urgentSurcharge + nightSurcharge + tip
平台费 platformFee  = round(total × commissionRate)     // commissionRate 默认 0.15
骑手收入 riderIncome = total − platformFee

例：基础单、非夜间、不加急、无悬赏 → total=250，platformFee=38，riderIncome=212（骑手拿 84.8%）。

⚠️ 注意：当前实现里 platformFee 是按含悬赏的总额计提的，而下单页文案写的是「悬赏全额给到接单邻居，平台不抽成」。若要让悬赏不抽佣，把 pricing.js 第 49 行改成 Math.round((total - tip) * rate) 即可。这是产品决策，模板保留原样未改。

六、时限与超时兜底

6.1 可调时限

全部在 service_catalog 的 timeout 字段，改数据库即生效，不用发版、不用重启：

"timeout": {
  "payMinutes": 5,        // 待支付关单
  "acceptMinutes": 1440,  // 无人接单自动退款 = 1 天
  "pickupMinutes": 120,   // 接单后取件时限 = 2 小时
  "confirmMinutes": 120   // 送达后自动确认 = 2 小时
}

字段缺失、填 0、填非数字都会回落到默认值（yd-common/constants.js 的 TIMEOUT_DEFAULT）。

6.2 四条兜底规则

yd-task 每 5 分钟跑一次 yd-common/sweep.js：

四条都用「条件更新 + 带原状态」写库，与用户/骑手操作并发时以数据库结果为准，重复扫描不会重复结算。

七、安全与隐私

八、快速开始（7 步跑通）

前置

• HBuilderX 3.8+（建议最新版）
• 已实名认证的 DCloud 账号
• 阿里云 uniCloud 服务空间（免费版即可跑通）
• 微信小程序 AppID（个人主体也可，但手机号快捷登录 / 位置类目受限时需企业主体）

1. 导入项目并关联云空间

HBuilderX → 文件 → 导入 → 从本地目录导入 → 选中本项目 → 右键 uniCloud-aliyun → 关联云服务空间或项目 → 选一个阿里云空间。

2. 填配置

编辑 uniCloud-aliyun/cloudfunctions/common/uni-config-center/yd/config.json：

{
  "wxAppId": "你自己的微信小程序 AppID",
  "wxAppSecret": "你自己的 AppSecret",
  "cryptoKey": "64 位十六进制随机串（AES-256 密钥）",
  "tokenSecret": "64 位十六进制随机串（JWT 密钥）",
  "tokenExpiresIn": 2592000,
  "mockPay": true,
  "serviceHotline": "客服电话，可留空",
  "ruleText": "服务保障文案，展示在首页"
}

生成两个随机串：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. 上传公共模块（必须先做）

右键 uniCloud-aliyun/cloudfunctions/common/uni-config-center → 上传公共模块 右键 uniCloud-aliyun/cloudfunctions/common/yd-common → 上传公共模块

4. 初始化数据库

右键 uniCloud-aliyun/database/db_init.json → 初始化云数据库。 会建表、建索引，并写入 3 个测试小区 + 3 个驿站 + 1 条服务目录。

已有数据会被覆盖，生产库请在控制台手工建。

5. 上传云函数

依次右键上传（顺序不能反，函数打包时会把公共模块复制进自己的 node_modules）：

yd-base → yd-user → yd-address → yd-order → yd-rider → yd-pay → yd-task

上传 yd-task 后到控制台确认「定时触发器」已创建（0 */5 * * * * *，每 5 分钟）。没自动创建就手动加一条。

6. 填 appid 并运行

manifest.json → 基础配置 → 重新获取 uni-app 应用标识（或填自己的） manifest.json → 微信小程序配置 → 填自己的微信 AppID

HBuilderX → 运行 → 运行到小程序模拟器 → 微信开发者工具。

7. 小程序后台配置

• 开发管理 → 服务器域名：uniCloud 会自动加白，无需手工填
• 设置 → 服务内容声明 → 用户隐私保护指引：必须声明
  • 手机号（若用手机号登录/展示）
  • 相册（仅写入）+ 摄像头（上传取件/送达存证照片，不声明会 errno 112，上传按钮直接无反应）
  • 位置信息（识别所在小区） 提交后约 5 分钟生效
• 设置 → 基本设置 → 服务类目：选「生活服务 > 跑腿代购」或当地可用类目

九、配置说明

9.1 uni-config-center/yd/config.json

改了 config.json 必须重新上传公共模块 uni-config-center，再重传依赖它的云函数，否则云端读到的还是旧值。

9.2 service_catalog（业务参数，改库即生效）

9.3 小区与驿站

communities 与 stations 两张表，一对一小区下有多个驿站。

⚠️ 小区没有驿站会导致下单报「驿站不存在」，新增小区时记得同步加驿站。

十、常见问题

Q：登录成功但页面不跳转？ A：多半是拿到空 token。本模板用 yd-common/token.js 自签，不碰 uni-id-users 集合，store.user.login() 里还有硬校验——拿不到 token 直接抛错，不会再静默失败。

Q：一直提示「请先绑定小区」，但已经选过了？ A：鉴权读的是数据库里的 users.communityId，不是本地缓存。若云端确实没写进去，request.js 收到 COMMUNITY_REQUIRED 会同时清本地缓存并跳选小区页，不会卡死。

Q：接自己的单提示「已被抢走」？ A：大厅已排除自己发的单，且 accept 失败时会回查真实原因（OWN_ORDER 会明确告诉你「不能接自己的单」）。要测完整流程请用**第二个*****（开发者工具 → 工具 → 多账号调试）。

Q：点「拍照上传」没反应？ A：隐私声明缺失（errno 112）或用户未同意。本模板已加 ensurePrivacyAuthorized 前置询问，并且失败必定有提示——看到「未声明相册/摄像头」就去小程序后台补声明。

Q：云函数报 resource exhausted？ A：不一定是额度用完。阿里云按「函数 × 小时」有最低消费，httpclient 默认 60 秒超时特别吃 GBs。本模板的 jscode2session 已显式设 timeout: 5000 并 try/catch。若仍报错，先看是不是空间被限制并发。

Q：改时限后旧订单没变？ A：这是设计如此。时限在订单创建/支付/接单/送达时写死，改配置只影响新订单。

Q：mockPay=true 时为什么下单就显示已支付？ A：这是为了方便你先打通业务闭环。接真实支付时把 mockPay 置 false，yd-pay.create 会走虚拟支付分支（需你实现 v3 下单）。

十一、合规提示

1. 文案禁用「快递」「运费」，统一叫「代办服务」「服务费」——本模板所有文案已按此约束
2. 不做承运：不生成面单、不做分拣运输，只做同城末端捎带
3. 资金模式：平台自营 + 众包劳务，不走微信分账（上限 30%，本场景要 85%）
4. 不收押金：用信用分替代，避免资金池
5. 上线前请按当地法规确认「跑腿/代取」类目的经营要求，以及是否需要为接单方投保

十二、源码加密（发布为付费插件时）

本模板是项目型插件（uniCloud 前后一体项目模板），加密配置放在项目根目录 package.json：

{
    "uni_modules": {
        "encrypt": ["uniCloud-aliyun/cloudfunctions/yd-order/index.obj.js", "utils/request.js"]
    }
}

路径是相对项目根的真实文件路径。注意与 uni_modules 插件不同：项目根下的 uniCloud 目录带 -aliyun 后缀，写成 uniCloud/... 会静默失效。

已纳入加密的 33 个 js

不加密（平台限制或刻意保留）

三件必须知道的事

1. 加密只在付费插件生效：上传时普通授权版价格必须 > 0。免费发布的插件 encrypt 配置会被忽略，源码照旧公开。
2. 买家侧效果：普通授权版看不到加密文件，云函数试用期（一般 7 天）后才在买家空间上失效；授权绑定 appid + 包名，换一个就要重买；只有源码授权版拿到全部源码。
3. 加密文件不能单独对外导出，所以不要把「准备给别的项目复用的库」放进 encrypt。

列表由脚本维护，别手抄：

python3 scripts/gen-encrypt.py          # 重新生成（新增云对象/工具函数后跑一次）
python3 scripts/gen-encrypt.py --check  # 只校验，不一致退出码非 0
python3 scripts/gen-encrypt.py --cloud-only  # 降级：只加密云端，前端 js 恢复明文

pack-market.py 打包时会校验清单里每个路径在包内真实存在——路径写错不会报错，只会静默失效，这道检查就是防这个。

若买家反馈导入后编译失败（前端 js 加密依赖 HBuilderX 云端编译），用 --cloud-only 重新出包即可：云函数照样加密，前端 js 退回明文。业务核心全在云对象里，前端开源不影响商业模式。

十三、版本

v1.0.1（versionCode 101）

• 完整业务闭环：登录 → 绑定小区 → 下单 → 支付（记账）→ 抢单 → 取件 → 送达 → 确认 → 结算 → 评价
• 四类超时兜底定时任务
• 隐私授权适配（主动询问 + 拦截兜底）
• 自签 token 取代 uni-id，零 uniCloud 官方依赖

后续计划（需要你自己实现，或看下一版）：真实微信支付、退款、提现、订阅消息、认证审核、申诉仲裁、管理后台。

十四、许可

MIT。二次开发、商用均可，请自行承担合规与资金安全责任。