数据库集合说明

本文档说明班级盒子使用的云数据库集合。示例数据均为假数据，仅用于说明字段结构。

notices

用途：存储班级事项，包括通知、考试安排、作业、活动、资料等内容。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`title`	事项标题
`category`	事项分类
`status`	事项状态，例如 `published`
`content`	事项正文说明
`deadline`	截止时间或相关时间
`endTime`	结束时间
`location`	地点或补充说明
`course`	课程、活动或事项名称
`timeLabel`	时间字段显示名称
`images`	图片列表，通常包含 `fileID`、`name` 等字段
`attachments`	附件列表，通常包含 `fileID`、`name`、`size`、`type` 等字段
`links`	相关链接列表
`publisherOpenid`	发布人的 openid
`publisherName`	发布人显示名称
`isImportant`	是否重要
`pinned`	是否置顶
`createdAt`	创建时间
`updatedAt`	更新时间

示例数据：

{
  "title": "示例班会通知",
  "category": "班级通知",
  "status": "published",
  "content": "这是一条示例事项，请替换为真实内容。",
  "deadline": "2026-06-10 19:00",
  "endTime": "",
  "location": "示例教室 A101",
  "course": "班会",
  "timeLabel": "相关时间",
  "images": [],
  "attachments": [],
  "links": [
    {
      "title": "示例链接",
      "url": "https://example.com"
    }
  ],
  "publisherOpenid": "openid_example",
  "publisherName": "示例管理员",
  "isImportant": false,
  "pinned": false,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

users

用途：存储小程序用户身份、认证状态和权限角色。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`openid`	用户 openid
`name`	已认证成员姓名
`studentId`	已认证成员学号
`userType`	身份类型：正式成员为 `member`，访客为 `guest`；旧成员可缺失该字段
`role`	用户角色，支持 `user`、`admin`、`superAdmin`、`guest`
`verified`	是否完成班级成员身份认证
`createdAt`	创建时间
`updatedAt`	更新时间

示例数据：

{
  "openid": "openid_example",
  "name": "示例学生",
  "studentId": "2026000000",
  "userType": "member",
  "role": "user",
  "verified": true,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

兼容规则：任何 verified: true 的旧记录都视为正式成员，不要求迁移 userType。访客必须保持 userType: "guest"、role: "guest"、verified: false，并按各自 OpenID 保存独立记录。

guest_access_codes

用途：保存可供多人长期共用的访客访问码摘要。客户端不得直接读取或写入该集合。

字段	含义
`codeHash`	去除访问码首尾空格后计算的 SHA-256 十六进制摘要
`enabled`	是否允许使用该访问码
`createdAt`	创建时间
`updatedAt`	更新时间

示例记录：

{
  "codeHash": "sha256_hex_example",
  "enabled": true,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

admin_invite_codes

用途：存储一次性管理员邀请码和超级管理员邀请码。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`code`	邀请码
`role`	邀请码授予的角色，支持 `admin`、`superAdmin`
`used`	是否已使用
`usedByOpenid`	使用者 openid
`usedAt`	使用时间
`createdAt`	创建时间
`expiredAt`	过期时间

管理员邀请码示例：

{
  "code": "BW-EXAMPLE-0001",
  "role": "admin",
  "used": false,
  "usedByOpenid": null,
  "usedAt": null,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "expiredAt": "2026-12-31T23:59:59.000Z"
}

超级管理员邀请码示例：

{
  "code": "SUPER-EXAMPLE-0001",
  "role": "superAdmin",
  "used": false,
  "usedByOpenid": null,
  "usedAt": null,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "expiredAt": "2026-12-31T23:59:59.000Z"
}

class_members

用途：存储班级成员基础名单，用于姓名和学号认证。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`name`	成员姓名
`studentId`	成员学号
`boundOpenid`	已绑定的小程序用户 openid
`verified`	是否已完成认证
`verifiedAt`	认证时间
`createdAt`	创建时间
`updatedAt`	更新时间

班级成员示例：

{
  "name": "示例学生",
  "studentId": "2026000000",
  "boundOpenid": null,
  "verified": false,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

subscribers

用途：存储用户对订阅消息的授权记录，用于发送下一次事项提醒。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`openid`	订阅用户 openid
`templateId`	订阅消息模板 ID
`used`	本次订阅授权是否已使用
`enabled`	是否启用
`createdAt`	创建时间
`updatedAt`	更新时间

示例数据：

{
  "openid": "openid_example",
  "templateId": "template_example",
  "used": false,
  "enabled": true,
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

favorites

用途：存储用户收藏事项记录。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`openid`	收藏用户 openid
`noticeId`	被收藏事项 ID
`createdAt`	收藏时间

示例数据：

{
  "openid": "openid_example",
  "noticeId": "notice_example",
  "createdAt": "2026-06-01T00:00:00.000Z"
}

feedbacks

用途：保存已认证用户提交的问题、建议和体验反馈。该功能支持用户提交与超级管理员只读查看，不提供回复、删除、处理流转或导出。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`openid`	提交用户 openid
`userName`	提交用户姓名
`studentId`	提交用户学号
`role`	提交时用户角色，支持 `user`、`admin`、`superAdmin`
`content`	反馈内容
`status`	处理状态，默认值为 `pending`
`createdAt`	反馈提交时间
`updatedAt`	更新时间，创建记录时与 `createdAt` 一致

示例数据：

{
  "openid": "openid_example",
  "userName": "示例学生",
  "studentId": "2026000000",
  "role": "user",
  "content": "希望首页可以支持按课程筛选事项。",
  "status": "pending",
  "createdAt": "2026-07-06T12:00:00.000Z",
  "updatedAt": "2026-07-06T12:00:00.000Z"
}

超级管理员查看反馈页通过 listFeedbacks 云函数读取数据，不开放客户端直接读取 feedbacks。页面只展示以下字段：

字段	含义
`id`	反馈记录 ID，用于列表渲染
`userName`	反馈人姓名
`content`	反馈内容
`createdAt`	反馈提交时间

security_counters

用途：使用固定时间桶记录发布、编辑、邀请码尝试等频率限制计数。该集合应只允许云函数写入，普通用户不应直接写入。

主要字段：

字段	含义
`_id`	由动作、openid 和时间桶组成的确定性记录 ID
`openid`	操作用户 openid
`action`	计数动作，例如 `create_notice`、`update_notice`、`apply_admin_attempt`、`submit_feedback`、`class_assistant_daily`、`class_assistant_minute`
`count`	当前时间桶内的计数值
`windowStart`	当前固定时间桶的开始时间
`windowMs`	时间桶长度，单位毫秒
`expiresAt`	建议清理该计数记录的时间
`createdAt`	创建时间
`updatedAt`	更新时间

示例数据：

{
  "openid": "openid_example",
  "action": "create_notice",
  "count": 1,
  "windowStart": "2026-06-01T00:00:00.000Z",
  "windowMs": 60000,
  "expiresAt": "2026-06-01T00:02:00.000Z",
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

ai_usage_logs

用途：记录 AI 辅助发布的调用情况，方便排查问题、统计使用和定位失败原因。该集合不参与发布逻辑判断，不保存管理员输入原文，也不保存 AI 返回的完整正文。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`openid`	调用用户 openid
`role`	调用时用户角色
`inputLength`	管理员输入文本长度
`success`	AI 草稿生成是否成功
`errorType`	失败类型，例如 `auth`、`permission`、`rate_limit`、`security`、`config`、`network`、`upstream`、`timeout`、`format`、`quota`
`model`	调用的 AI 模型名
`aiProvider`	AI 服务供应商，当前为 `deepseek`
`aiInvoked` / `aiSucceeded`	是否实际发起模型调用，以及模型接口是否成功返回
`latencyMs`	本次调用耗时，单位毫秒
`createdAt`	创建时间

示例数据：

{
  "openid": "openid_example",
  "role": "admin",
  "inputLength": 32,
  "success": true,
  "errorType": "",
  "model": "deepseek-flash",
  "aiProvider": "deepseek",
  "aiInvoked": true,
  "aiSucceeded": true,
  "latencyMs": 1200,
  "createdAt": "2026-07-03T06:30:00.000Z"
}

handbook_versions

用途：记录可供班级助手检索的学生手册版本。生产环境必须且只能有一条 active: true 的记录；多个启用版本会被视为配置错误。

年度升级必须保留历史版本记录和历史切片。当前版本切换只修改 handbook_versions.active：例如启用 2026 时将 2025 设为 false、2026 设为 true。askClassAssistant 先读取唯一 active 版本，再仅查询 handbookVersion 完全相等的切片，因此不得通过同时启用两个年度来做过渡。

字段	含义
`version`	手册版本唯一标识
`name`	对用户展示的手册名称
`active`	是否为当前启用版本
`chunkCount`	对应切片数量
`sourceFileName`	可选的来源文件名，不应在开源示例中使用真实文件名
`createdAt` / `updatedAt`	创建和更新时间

建议为 active 建立升序、非唯一索引，并在切换版本时先关闭旧版本，再启用新版本。不要创建唯一索引，因为多条 active: false 记录同样会触发唯一性冲突。

handbook_chunks

用途：保存学生手册检索切片，仅供 askClassAssistant 云函数读取。

字段	含义
`handbookVersion`	关联的手册版本
`section` / `title` / `article`	章节、标题和条款信息
`pageText`	手册页码
`content`	切片正文
`keywords`	检索关键词数组
`sort`	稳定分页和排序使用的整数
`createdAt`	创建时间

必须建立非唯一复合索引：第一个字段 handbookVersion 升序，第二个字段 sort 升序。单版本最多加载 3000 条候选切片；超过时会返回配置错误，不会静默丢弃尾部数据。同一版本重新导入前必须先删除旧切片，避免重复记录。

class_assistant_logs

用途：记录班级助手各阶段结果和耗时，不保存完整问题、完整回答或完整手册上下文。

字段	含义
`openid` / `role`	调用用户及角色
`handbookVersion`	本次检索使用的版本
`handbookDataVersion`	当前手册数据指纹
`retrievalVersion` / `promptVersion`	检索规则和 Prompt 版本
`questionLength`	问题字符数
`matchedChunkIds`	命中的切片 ID
`matchedChunkSummary`	脱敏后的最终候选标题、页码、条款、分数、概念覆盖和 continuation 标识
`contextLength`	传给模型的手册上下文字符数
`noMatchSource`	无匹配来源，例如 `retrieval_no_match` 或 `model_no_match`
`outcome`	`answered`、`supplemental_answered`、`no_match`、`ai_failed`、`security_rejected`、`security_failed`、`rate_limited`、`permission_denied`、`input_rejected` 或 `config_failed`
`errorType`	细分错误类型
`model`	AI 模型名
`aiProvider`	AI 服务供应商，当前为 `deepseek`
`latencyMs`	端到端耗时
`stageLatencies`	身份、安全、检索、限流和 AI 等阶段耗时
`traceId`	DeepSeek 响应中可用的请求 ID；没有返回时为空字符串
`aiInvoked` / `aiSucceeded`	是否实际调用 AI，以及网关是否返回可解析成功响应
`createdAt`	创建时间

建议为 createdAt、outcome + createdAt 和 errorType + createdAt 建立索引。AI 调用成功率按 aiInvoked: true 的记录统计 aiSucceeded；端到端回答成功率单独按 outcome: answered 统计，不得把未调用 AI 的 no_match 当作 AI 成功。

class_assistant_gaps

用途：保存学生手册未能回答的问题，便于补充别名、手册数据或固定回答。每次无匹配均单独记录，不去重、不归类，也不保存 openid。

字段	含义
`question`	通过内容安全检测的问题原文
`handbookVersion`	产生无匹配结果时使用的手册版本
`source`	`retrieval_no_match` 表示检索无候选，`model_no_match` 表示模型判断现有片段不足以回答
`createdAt`	创建时间
`expiresAt`	创建时间后30天，用于过期清理

建议为 createdAt、source + createdAt 和 expiresAt 建立查询索引。管理员可在数据库控制台按 expiresAt 筛选并手动删除超过30天的记录。该集合必须禁止客户端直接读写。

class_assistant_requests

用途：保存短期请求状态和服务端取消信号。前端停止后，运行中的云函数会读取该记录并终止或忽略后续模型回答流程。

字段	含义
`_id`	前端生成的请求 ID
`openid`	请求所有者
`cancelled`	是否收到取消信号
`status`	`running`、`answered`、`no_match`、`cancelled` 或 `failed`
`expiresAt`	过期清理时间
`createdAt` / `updatedAt`	创建和更新时间

建议为 expiresAt 建立查询索引，并定期在数据库控制台手动删除过期记录。该集合必须禁止客户端直接读写，取消操作只能经过云函数校验 openid。运行中的云函数约每秒检查一次取消状态，因此停止通常不是瞬时完成。

operation_logs

用途：记录身份认证、管理员授权、事项发布、编辑、删除等关键操作日志。日志中不应保存正文原文、完整邀请码、真实敏感配置或完整请求事件。

主要字段：

字段	含义
`_id`	云数据库自动生成的记录 ID
`openid`	操作用户 openid
`role`	操作时用户角色
`action`	操作类型，例如 `verify_member`、`apply_admin`、`create_notice`、`update_notice`、`delete_notice`
`targetType`	操作目标类型
`targetId`	操作目标 ID
`success`	操作是否成功
`detail`	脱敏后的扩展信息，不包含姓名、学号、正文或完整邀请码
`createdAt`	创建时间

示例数据：

{
  "openid": "openid_example",
  "action": "create_notice",
  "role": "admin",
  "success": true,
  "createdAt": "2026-06-01T00:00:00.000Z"
}

FilesExpand file tree

database.md

Latest commit

History

database.md

File metadata and controls

数据库集合说明

notices

users

guest_access_codes

admin_invite_codes

class_members

subscribers

favorites

feedbacks

security_counters

ai_usage_logs

handbook_versions

handbook_chunks

class_assistant_logs

class_assistant_gaps

class_assistant_requests

operation_logs