外部服务 Mock 指南
模板本地体验使用虚构 Maker 场景和本机替代服务。所有状态默认只在当前 Mock API 进程内存中变化，重启或重置后恢复基线，不会连接真实用户、商户、邮箱或云资源。
1. 启动与能力清单
在解压后的源码根目录执行：
pnpm install --frozen-lockfile
pnpm dev:community-template- 社区 Web：
http://localhost:3002 - 模板指南：
http://localhost:4173 - Mock API：
http://localhost:3999
查看可执行的本地替代能力：
curl http://localhost:3999/__mock/providersready: true 只代表本地替代链路可用，不代表生产云服务已经配置。
2. 覆盖矩阵
| 外部依赖 | 本地模式 | 覆盖 | 明确不覆盖 |
|---|---|---|---|
| 登录与用户状态 | 真实本地 Auth + 业务场景 viewer | 注册、登录、退出、Session、OAuth/OIDC、本地授权页与订阅场景 | 真实第三方 OAuth 与 SMTP 投递 |
| 数据库与缓存 | 进程内存 | 内容浏览、部分通用写操作、订单变化和重置 | SQL 并发、缓存故障、备份恢复与持久化性能 |
| 对象存储 | 原字节内存存储 | 头像、帖子图片和通用附件上传/读取 | CDN、bucket ACL、签名校验和生命周期策略 |
| 支付 | 确定性确认 | 订阅与积分订单从待支付变为已支付 | 支付网络、回调验签、清结算和退款到账 |
| 视频 | local_http | 原始文件直传、原生播放、播放进度 | 转码、截图、DRM、CDN 和云 VOD 回调 |
| 外链预览 | 本地 fixture | 安全预览卡片 | 自动加载第三方 iframe、播放器或脚本 |
| AI | 固定规则 | 可复现的内容草稿 | 模型质量、Token、费用、限流和供应商网络 |
| 邮件 | 本地 outbox | 文本/HTML payload、查看与清空 | SMTP 投递、退信和真实收件箱 |
| GitHub | 独立只读任务 | 显式配置仓库的公开元数据 | 私有仓库、自动发现、写操作和隐藏抓取策略 |
3. 图片与附件
Web 会先请求 /v1/uploads/post-image-token 或 /v1/uploads/asset-token，再把 multipart 原始字节上传到 /__mock/uploads，最后从 /__mock/assets/* 读回。上传数据只保存在当前 Mock API 进程内存中，不会提交到仓库，也不应当作备份。
4. 视频上传与播放
本地视频链路保持生产 contract 的状态结构：
/v1/video-assets/upload-plans创建local_http直传计划。- 浏览器把原始字节写入
/v1/video-assets/:id/provider-upload。 /upload-complete确认视频已经就绪。/playback-grants返回短时本地播放源。/progress保存当前进程内的播放进度。
本地实现不会伪装成云端转码。文件必须使用浏览器本身可以播放的编码。
5. 订阅与积分模拟支付
从会员页创建订阅订单后，页面可调用 /v1/subscriptions/orders/:id/mock-paid 完成明确的本地确认；积分充值使用 /v1/points/topup-orders/:id/mock-paid。确认只修改内存状态，不连接支付宝、微信或任何真实支付网络。
生产验收必须单独验证商户配置、回调签名、金额一致性、幂等、退款和对账。Mock 成功不能证明生产支付可用。
6. AI 规则结果与邮件 outbox
生成一份稳定的 Maker 内容草稿：
curl -X POST http://localhost:3999/__mock/ai/draft \
-H 'content-type: application/json' \
-d '{"topic":"如何公开记录一个 Maker 项目"}'写入并查看本地邮件：
curl -X POST http://localhost:3999/__mock/email/send \
-H 'content-type: application/json' \
-d '{"to":"demo@example.com","subject":"本地邮件演示","text":"这是一封不会真实投递的邮件。"}'
curl http://localhost:3999/__mock/email/outbox
curl -X DELETE http://localhost:3999/__mock/email/outbox7. 通用自动化与 GitHub 示例
pnpm dev:automation 启动通用自动化服务。默认任务只做健康摘要与预览，不发送邮件、不写生产数据。GitHub 示例只有在你显式填写 owner/repo 后，才会通过官方 API 读取该仓库的公开元数据；它不会自动发现仓库，也不会执行写操作。
8. 重置与生产边界
curl -X POST http://localhost:3999/__mock/reset重置会恢复 fixture，并清空上传字节、视频会话、播放进度与邮件 outbox。
生产环境必须使用真实 Space API，关闭 Mock 支付与本地视频模式，并且不能暴露 3999 端口或任何 /__mock/* 路由。需要接入新 Provider 时，先阅读包含内容与使用边界与Provider 扩展。