接口占位文档（系统化版）

字数

2574 字

阅读时间

12 分钟

依据功能/页面/数据库/分包/埋点文档与当前代码（miniprogram/services/、cloudfunctions/）梳理。示例均为 JSON，参数字段来自数据库与页面文档。支持运行期切换 Mock：DevTools 控制台执行 wx.setStorageSync('USE_MOCK', true|false)。

接口总览表（REST / 云函数）

名称	路径/函数名	方法	所属服务	分包域
今日情绪	`/api/moods/today`	GET	`services/checkins.js`	主包 pages/today
创建打卡	`/api/checkins`	POST	`services/checkins.js`	主包 pages/today
情绪趋势	`/api/moods/trend`	GET	`services/checkins.js`	主包 pages/journal
微建议列表	`/api/micro-tips`	GET	`services/suggestions.js`	主包 pages/today
建议状态	`/api/micro-tips/{id}`	PATCH	`services/suggestions.js`	主包 pages/today
任务列表	`/api/tasks`	GET	`services/tasks.js`	主包 pages/tasks / packages/tasks
创建任务	`/api/tasks`	POST	`services/tasks.js`	today/journal
更新任务	`/api/tasks/{id}`	PATCH	`services/tasks.js`	主包 pages/tasks
任务复盘	`/api/tasks/review`	POST	`services/tasks.js`	主包 pages/tasks
任务统计	`/api/tasks/summary`	GET	`services/tasks.js`	主包 pages/tasks
随笔列表	`/api/journals`	GET	`services/journals.js`	主包 pages/journal（后续建议分包）
创建随笔	`/api/journals`	POST	`services/journals.js`	主包 pages/journal
随笔详情	`/api/journals/{id}`	GET	`services/journals.js`	主包 pages/journal
更新随笔	`/api/journals/{id}`	PATCH	`services/journals.js`	主包 pages/journal
删除随笔	`/api/journals/{id}`	DELETE	`services/journals.js`	主包 pages/journal
REBT 提取	`/api/journals/{id}/extract-rebt`	POST	`services/journals.js`	主包 pages/journal
生成建议	`/api/journals/{id}/generate-suggestion`	POST	`services/journals.js`	主包 pages/journal
树洞列表	`/api/treehole/posts`	GET	`services/forum.js`	主包 pages/treehole / packages/community
发布帖子	`/api/treehole/posts`	POST	`services/forum.js`	packages/community
帖子详情	`/api/treehole/posts/{id}`	GET	`services/forum.js`	packages/community
互动操作	`/api/treehole/interactions`	POST	`services/forum.js`	packages/community
话题列表	`/api/treehole/topics`	GET	`services/forum.js`	packages/community
搜索帖子	`/api/treehole/search`	GET	`services/forum.js`	packages/community
社区精选	`/api/forum/highlight`	GET	`services/forum.js`	主包 pages/today
用户资料	`/api/user/profile`	GET/PATCH	`services/user.js`	主包 pages/mine / packages/profile
周报	`/api/reports/weekly`	GET/PATCH	`services/reports.js`	packages/profile
周报导出	`/api/reports/export`	POST	`services/reports.js`	packages/profile
徽章	`/api/badges`	GET	`services/badges.js`	packages/profile
通知列表	`/api/notifications`	GET	`services/notifications.js`	主包/消息中心
未读统计	`/api/notifications/unread-count`	GET	`services/notifications.js`	主包/消息中心
资源地图	`/api/resources`	GET	-	packages/profile
隐私授权	`/api/privacy/consents`	GET/PATCH	-	packages/profile
SOS 触发	云函数 `sosRelay`	CALL	cloudfunctions/sosRelay	independent/sos
打卡写入	云函数 `checkinRecorder`	CALL	cloudfunctions/checkinRecorder	主包 pages/today
建议编排	云函数 `suggestionOrchestrator`	CALL	cloudfunctions/suggestionOrchestrator	today/journal
树洞审核	云函数 `treeholeModeration`	CALL	cloudfunctions/treeholeModeration	packages/community
任务闭环	云函数 `taskWorkflow`	CALL	cloudfunctions/taskWorkflow	主包/任务域
周报生成	云函数 `weeklyReport`	CALL	cloudfunctions/weeklyReport	packages/profile
埋点汇聚	云函数 `analyticsIngest`	CALL	cloudfunctions/analyticsIngest	全局

复杂云函数详见：docs/接口/接口-sosRelay.md、docs/接口/接口-treeholeModeration.md、docs/接口/接口-suggestionOrchestrator.md。

分组详细说明

一、今天/情绪打卡（checkins）

GET /api/moods/today

用途：今天页状态卡（页面-今天.md）、功能-情绪打卡.md
请求参数：无（可选 date ISO：查询特定日期）
返回：

json

{
  "hasCheckedIn": true,
  "mood": "calm",
  "intensity": 4,
  "tags": ["复盘", "运动"],
  "note": "做了呼吸训练，放松了些",
  "id": "ck_20240406_a",
  "date": "2024-04-06"
}

集合：checkins 读 mood_score, primary_emotion, mood_tags, context_note, checkin_date
错误：401 未登录；404 当日无记录；500 内部错误
埋点：pv_today（页面曝光），成功渲染无特定事件
安全：需鉴权；含 P3 情感数据

POST /api/checkins

用途：提交打卡（页面-今天.md）
请求参数：

json

{
  "mood_score": 72,
  "primary_emotion": "calm",
  "mood_tags": ["校园", "自习室"],
  "scene_tags": ["学业"],
  "context_note": "专注学习但略累",
  "input_type": "mood_card",
  "energy_level": 3
}

返回：与 GET today 类似，附 _id/createdAt
集合：写 checkins；可能回写 suggestion_ids
错误：409 E_DUP_CHECKIN；403 E_FORBIDDEN；500
埋点：mood_checkin_submit
安全：需鉴权；敏感（P3）

GET /api/moods/trend

参数：from、to（ISO 日期）
返回（示例片段）：

json

{
  "points": [
    {"date": "2024-04-01", "mood_score": 60},
    {"date": "2024-04-02", "mood_score": 72}
  ],
  "tags": ["学习", "室友"]
}

集合：读 checkins
错误：400 参数不合法；401；500
埋点：切换粒度与筛选为页面埋点
安全：需鉴权

云函数（落库与风控）：checkinRecorder（写入、幂等校验）、analyticsIngest（埋点）

二、微建议与任务（suggestions, tasks）

GET /api/micro-tips

用途：今天页 Top3 建议（功能-微建议与任务生成.md）
返回：

json

{
  "data": [
    {"id":"sg_001","title":"与室友约定安静时段","category":"relationship","priority_rank":1,"status":"active","source":"model"},
    {"id":"sg_002","title":"午间 10 分钟冥想","category":"emotion","priority_rank":2,"status":"active","source":"model"}
  ]
}

集合：读 suggestions（status='active'）
埋点：列表曝光按卡片 expo_today_suggestion_{id}

PATCH /api/micro-tips/{id}（接受/跳过）

请求：{"status":"accepted"} 或 {"status":"skipped"}
影响：更新 suggestions.status，接受时可回写 accepted_task_id
错误：404 未找到；409 状态冲突；403 越权
埋点：suggestion_task_create（接受时联动任务）

POST /api/tasks

用途：从建议/随笔生成任务或自建
请求（示例-建议转任务）：

json

{
  "title": "和室友约定安静时间",
  "description": "准备三个时段，沟通确认",
  "source": "suggestion",
  "origin_reference_type": "suggestion",
  "origin_reference_id": "sg_001",
  "category": "relationship",
  "estimated_duration_minutes": 20,
  "due_at": "2024-04-08T15:00:00Z"
}

返回：tasks 规范化任务对象
集合：写 tasks
错误：409 E_TASK_DUPLICATE；400 字段不合法；401；500
埋点：suggestion_task_create

GET /api/tasks、PATCH /api/tasks/{id}、POST /api/tasks/review、GET /api/tasks/summary

列表返回：规范化任务数组（见 tasks 集合文档字段）
更新状态：{"status":"in_progress"}/"completed" 等
复盘提交：

json

{
  "task_id": "task_305",
  "review_data": {"mood_before": 45, "mood_after": 72, "review_notes": "放松了"}
}

集合：读写 tasks，复盘可能写 checkins.linked_checkin_id
埋点：task_status_update、task_review_submit

云函数：suggestionOrchestrator（生成建议）、taskWorkflow（闭环、联动回执）

三、心情随笔（journals）

GET/POST /api/journals；GET/PATCH/DELETE /api/journals/{id}

用途：随笔列表/创建/详情/更新/删除（页面-心情随笔.md）
创建示例：

json

{
  "entry_type": "text",
  "title": "与室友调解",
  "body_text": "今天和组员开会比预期顺利……",
  "mood_score": 68,
  "mood_tags": ["室友", "沟通"],
  "media_refs": [],
  "share_scope": "private",
  "source": "journal_page"
}

集合：读写 journals
错误：404 不存在；401；500
埋点：journal_entry_submit、journal_to_task

POST /api/journals/{id}/extract-rebt、/generate-suggestion

json

{
  "A": "触发事件…",
  "B": "信念…",
  "C": "情绪…",
  "D": "质疑…",
  "E": "新信念…"
}

集合：只读/写 journals.rebt_struct；生成建议联动 suggestions

云函数：suggestionOrchestrator（基于随笔生成建议）

四、树洞社区（posts/comments）

GET/POST /api/treehole/posts、GET /api/treehole/posts/{id}、GET /api/forum/highlight

列表/详情用 fields 见 posts 集合文档
发布示例：

json

{
  "content": "最近准备考研，和室友节奏不同有点焦虑…",
  "tags": ["考研", "室友"],
  "topic": "study",
  "mood_thermometer": 38,
  "anonymity_mode": "anon",
  "self_check_result": {"etiquette_confirmed": true, "anonymity_choice": "anon", "risk_aware": true}
}

集合：写 posts；高风险需审核
错误：E_POST_TOO_LONG、E_POST_DUPLICATE_CONTENT、E_POST_RISK_HIGH
埋点：treehole_post_publish、exp_treehole_feed

POST /api/treehole/interactions、GET /api/treehole/posts/{id}/comments、GET /api/treehole/topics、GET /api/treehole/search

互动示例（抱抱/评论）：

json

{
  "post_id": "post_900",
  "action_type": "hug",
  "is_add": true
}

集合：读写 comments
错误：E_HUG_DUPLICATE、E_COMMENT_BLOCKED
埋点：treehole_care_action

云函数：treeholeModeration（内容审核/风险识别，R3/R4 升级触发 sosRelay）

五、我的/资料/周报/通知（users/reports/badges/notifications）

/api/user/profile GET/PATCH

字段：见 users 集合；PATCH 支持 nickname, avatar_url, campus_affiliation, emergency_contacts
埋点：资料页曝光/更新可上报 privacy_setting_update

/api/reports/weekly GET/PATCH，/api/reports/export POST

GET 返回：

json

{
  "id": "rep_week_2024w14_usr001",
  "headline": "情绪平衡度提升 12%",
  "periodLabel": "04.01 - 04.07",
  "moodScore": 67,
  "metrics": [
    {"label": "建议接受率", "value": "82%"},
    {"label": "任务完成率", "value": "74%"}
  ],
  "recommendations": [{"title": "继续保持晚安呼吸练习，睡前 10 分钟即可"}]
}

导出返回：{"id":"...","url":"https://.../report-<id>.pdf"}
集合：读写 reports
埋点：weekly_report_view

/api/badges GET，/api/notifications GET，/api/notifications/unread-count GET

集合：badges（来源服务）、notifications

/api/privacy/consents GET/PATCH

集合：users（guardian_ids, counselor_id, consent_version）

六、SOS 与分析（sosRelay/analyticsIngest）

云函数 sosRelay

用途：紧急流程与值班转接（independent/sos）
事件（示例）：

json

{
  "trigger": "fab_long_press",
  "risk_level": "L4",
  "consent_scopes": ["share_minimal"],
  "preferred_channel": "phone"
}

返回：{"ok": true, "ticket_id": "sos_20240406_01"}
集合：写 sos_events（规划中）、reports（risk_alert）
埋点：sos_fab_trigger, risk_signal_escalate

云函数 analyticsIngest

用途：埋点聚合（见 docs/埋点与数据分析.md 事件表）

接口-页面映射表（页面 → 接口）

pages/today/index
- GET /api/moods/today，POST /api/checkins
- GET /api/micro-tips，PATCH /api/micro-tips/{id}（accept/skip）
- GET /api/tasks，POST /api/tasks
- GET /api/forum/highlight
pages/treehole/index
- GET /api/treehole/posts、GET /api/treehole/topics、GET /api/treehole/search
- POST /api/treehole/interactions
pages/journal/index
- GET/POST /api/journals，GET /api/journals/{id}，PATCH/DELETE /api/journals/{id}
- POST /api/journals/{id}/extract-rebt，/generate-suggestion
pages/tasks/index + packages/tasks/*
- GET /api/tasks，PATCH /api/tasks/{id}，POST /api/tasks/review，GET /api/tasks/summary
pages/mine/index + packages/profile/*
- GET/PATCH /api/user/profile
- GET/PATCH /api/reports/weekly，POST /api/reports/export
- GET /api/badges，GET /api/notifications，GET /api/notifications/unread-count
independent/sos/*
- CALL sosRelay

接口-集合映射表（接口 → 数据库集合）

/api/moods/today、/api/checkins、/api/moods/trend → checkins
/api/micro-tips、/api/micro-tips/{id} → suggestions
/api/tasks* → tasks（复盘联动 checkins）
/api/journals* → journals
/api/treehole/posts* → posts，互动读取/写入 comments
/api/user/profile、/api/privacy/consents → users
/api/reports/* → reports
/api/notifications* → notifications
sosRelay → sos_events（规划）、reports（risk_alert）
treeholeModeration → posts、comments（状态/风控写回）
suggestionOrchestrator → suggestions（生成/排序写入）

差异与补充建议（文档 ↔ 代码）

命名不一致：
- 社区接口在文档使用 /api/treehole/*，代码服务名为 forum.js，且今日页引用了 /api/forum/highlight 概念。建议统一 REST 前缀为 /api/treehole/*，将“高亮”定义为 /api/treehole/highlight。
- 文档部分表述 recommendations，数据库与代码为 suggestions。建议统一为 suggestions。
未实现/Mock：
- miniprogram/services/* 当前均为 Mock。上线前需替换为 wx.request/云函数调用，并对照本文件字段对齐。
- /api/tasks/bulk、/api/tasks/summary、/api/resources、/api/privacy/consents 在代码侧暂无封装，建议补充 service 包装。
代码问题（建议修复）：
- miniprogram/services/forum.js 中 calculateRiskScore 引用了未定义变量 params（应以 content 计算）。
- miniprogram/services/checkins.js 中 intensityFromScore 使用了未定义变量 mood_score（应为 moodScore）。
分包域差异：
- 文档建议存在 packages/journal，当前工程未建。若继续沿用分包规划，建议新增分包并迁移日记详情/编辑页。
安全与合规：
- checkins/posts/comments 字段含 P3 情感/隐私内容，需在 API 层默认脱敏日志并最小化返回字段（特别是 context_note）。
埋点对齐：
- 各接口成功/失败时机请接入 analyticsIngest 或 telemetry，映射 docs/埋点与数据分析.md 所列事件。

版本与变更记录

2025-09-22 v1.0 系统化补齐（来源：功能/页面/数据库/分包/埋点文档与现有代码），新增复杂模块子文档；统一 REST/函数清单与映射表；补充差异与修复建议。

贡献者

Cai Hongyu

文件历史

最后编辑于 5 个月前查看完整历史

architecture

prd

svg

样式规范

心语精灵

ai

approvals

core

crm

finance

goals

hr

integrations

knowledge

manufacturing

oms

personalization

projects

security

shared-assets

support

api

database

deployment

development

接口占位文档（系统化版）

接口总览表（REST / 云函数）

分组详细说明

一、今天/情绪打卡（checkins）

二、微建议与任务（suggestions, tasks）

三、心情随笔（journals）

四、树洞社区（posts/comments）

五、我的/资料/周报/通知（users/reports/badges/notifications）

六、SOS 与分析（sosRelay/analyticsIngest）

接口-页面映射表（页面 → 接口）

接口-集合映射表（接口 → 数据库集合）

差异与补充建议（文档 ↔ 代码）

版本与变更记录

贡献者

文件历史

接口占位文档（系统化版） ​

接口总览表（REST / 云函数） ​

分组详细说明 ​

一、今天/情绪打卡（checkins） ​

二、微建议与任务（suggestions, tasks） ​

三、心情随笔（journals） ​

四、树洞社区（posts/comments） ​

五、我的/资料/周报/通知（users/reports/badges/notifications） ​

六、SOS 与分析（sosRelay/analyticsIngest） ​

接口-页面映射表（页面 → 接口） ​

接口-集合映射表（接口 → 数据库集合） ​

差异与补充建议（文档 ↔ 代码） ​

版本与变更记录 ​

贡献者 ​

文件历史 ​

接口占位文档（系统化版）

接口总览表（REST / 云函数）

分组详细说明

一、今天/情绪打卡（checkins）

二、微建议与任务（suggestions, tasks）

三、心情随笔（journals）

四、树洞社区（posts/comments）

五、我的/资料/周报/通知（users/reports/badges/notifications）

六、SOS 与分析（sosRelay/analyticsIngest）

接口-页面映射表（页面 → 接口）

接口-集合映射表（接口 → 数据库集合）

差异与补充建议（文档 ↔ 代码）

版本与变更记录

贡献者

文件历史