云函数（后端）

微信云开发后端。原生 + JavaScript（云函数用 JS，小程序端用 TypeScript）。

目录

⚠️ _common 是源目录，改完必须同步

微信云开发在运行时不能跨云函数 import。每个云函数上传时是一个独立代码包， 写 require('../_common/enums') 在本地能跑、一上传就报 MODULE_NOT_FOUND。

所以共享层是靠复制进去的：_common/*.js → 每个云函数的 common/。

python3 _tools/sync_cloud_common.py            # 同步
python3 _tools/sync_cloud_common.py --check    # 只检查，不一致退出码 1

改完 _common 一定要跑一次同步，否则各函数用的还是旧副本， 而且现象很怪（改了 A 函数生效、B 函数没生效）。

云函数里统一写 require('./common/xxx')。

本地测试（不需要开发者工具）

cd _tools/test_cloud && node run.js

它把 wx-server-sdk 换成本地替身（_tools/test_cloud/mock-wx-server-sdk/，内存数据库）， 真执行整条链路：下单 → 确认收款 → 派单 → 开始 → 核销 → 确认 → 结算。

覆盖 48 项断言，包括三类看代码看不出来的问题： - 行为正确性（状态机放不放行、金额算得对不对） - 并发安全（同一档期不能被两个人约走 —— 靠 where({state:OPEN}).update() 的原子性） - 留痕完整性（每一步都有日志、序号连续、顺序正确）

这套测试是验过的，不是摆设

验证方法：故意把状态机改坏，看测试抓不抓得到。

# 在 _common/statemachine.js 里加一条非法转移，例如允许「待服务 → 待确认」
python3 _tools/sync_cloud_common.py && cd _tools/test_cloud && node run.js
# → 报 [FAIL] 「待服务」阶段不能直接核销；还原后恢复 48/0

不做这一步的话，"测试全绿"和"测试根本没在测东西"看起来是一样的。

部署

开发者工具已装在 D:\微信小程序\开发者工具\微信web开发者工具。

前置：工具里 设置 → 安全设置 → 服务端口 打开。 不开的话命令行调不动工具，而且报错信息看起来跟这件事毫无关系。

# 同步共享层（忘了这步部署上去会缺 common/）
python3 _tools/sync_cloud_common.py

cd "D:/微信小程序/开发者工具/微信web开发者工具"
./cli.bat cloud functions deploy --project "D:/微信小程序/05_开发/app" --names order,pay

也可以在工具里右键云函数目录 → 「上传并部署：云端安装依赖」。

两条跨项目经验（踩过才写的）

① 审计日志不能只靠时间排序。 created_at 只到毫秒，状态机一次推进只隔几毫秒，几条日志会落在同一毫秒上， orderBy('created_at') 在并列时顺序不确定 —— 后台时间线会出现"派单"排在 "确认收款"前面。所以 order_logs 每条带一个自增 seq，展示按 seq 排。 测试里专门断言了序号是 1..N 连续。

② 令牌没有有效期 = 一次泄漏就是永久管理员权限。 后台的 session_token 是唯一凭证（bearer 模型），所以必须带过期时间。 guard.requireAdmin 会校验 session_expire_at；退出登录要把 token 清空。

与旧版文档的差异

04_设计/数据库结构.md 是游戏陪练方向的（教练 / 段位 / 战绩截图）， 本项目已改为本地向导陪同服务，差异：

数据库结构文档还没改，仍是旧方向。改它之前先确认甲方对 服务内容与合规路径的答复（见 03_合规与资质/）。