Open edX LMS Survey Report为平台收集并上报匿名化聚合数据的调研报告功能【免费下载链接】openedx-platformThe Open edX LMS Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platformSurvey Report 是 Open edXopenedx-platform内置于 LMS 中的一个 Django Appopenedx.features.survey_report用于以聚合、匿名的方式收集平台上课程规模化的关键运营指标课程数、活跃学习者、注册量、选课量、证书数并支持将这些指标定期上报给外部 API为年度 Open edX Impact Report 提供数据来源。阅读本文后你将掌握如何理解它上报的五类核心指标口径、如何通过 Django Admin 或命令行generate_report命令生成与发送报告、如何配置SURVEY_REPORT_ENDPOINT等设置项将报告改发到自己指定的端点以及管理后台提醒 Banner 的触发机制。一、功能定位收集哪些聚合、匿名数据Survey Report 的设计目标见 README.rst收集aggregated, anonymized的平台级数据以便跟踪 Open edX 使用量的增长与趋势。它收集的核心指标与数据来源如下指标名称来自 README.rst 与 models.py 中的模型字段注释指标字段含义底层统计口径来自 queries.pycourses_offered平台当前提供的活跃课程总数get_unique_courses_offered()课程已开start 当前时间、未结束end为空或晚于当前时间、且报名数大于MIN_ENROLLS_ACTIVE_COURSE常量值为 5从源码结构看这是用来过滤测试/废弃课程的最小报名量阈值learners近 4 周内有登录的活跃用户数get_recently_active_users(weeks)按last_login 当前时间 - weeks统计调用方固定传入 4 周见下文MAX_WEEKS_SINCE_LAST_LOGINregistered_learners平台历史注册用户总数get_registered_learners()User中is_activeTrue的记录数enrollments平台活跃选课总数get_course_enrollments()is_activeTrue的CourseEnrollment且排除超级用户与 staff 用户generated_certificates已生成证书总数get_generated_certificates()PersistentCourseGrade中passed_timestamp非空的记录数extra_data附加信息如 site_name、openedx-release 版本号直接取设置项SURVEY_REPORT_EXTRA_DATAstate异步生成流程所处状态取值为processing/generated/error三态SURVEY_REPORT_STATES所有查询都通过.using(read_replica_or_default())走只读副本若配置了读副本避免大表统计对主库产生压力见 queries.py。二、数据模型三个核心 Model模型定义在 models.pySurveyReport存储一份报告快照。除上表各指标均为BigIntegerField默认 0外还有created_atauto_nowTrue——报告生成时间Meta.ordering [-created_at]保证列表按时间倒序stateCharFieldmax_length24——异步生成流程状态默认processing完成后置为generated出错置为error。SurveyReportUpload记录发送报告到外部 API这一动作的结果字段包括sent_at发送时间、report外键指向SurveyReport级联删除、status_codeHTTP 状态码、request_details请求响应体max_length255。其中is_uploaded()方法以200 status_code 300判定是否发送成功。SurveyReportAnonymousSiteID当启用匿名上报时持久化一个随机 UUID主键、uuid.uuid4默认值作为站点身份标识。从源码结构看其作用是让同一站点在多次匿名上报中使用同一个 UUID便于接收方做去重与趋势关联。这三个模型对应了 migrations/ 目录下 6 个版本的迁移演进初始模型、state字段、SurveyReportUpload、匿名 UUID 等。三、报告数据是如何生成的api.py调用链核心业务逻辑集中在 api.pyget_report_data()依次调用queries.py的五个统计函数并将settings.SURVEY_REPORT_EXTRA_DATA作为extra_data一并返回。注意活跃学习者的窗口固定为MAX_WEEKS_SINCE_LAST_LOGIN 4周api.py#L23。generate_report()生成流程的状态机入口——若SURVEY_REPORT_ENABLE为False直接抛出异常拒绝生成先落库一条空记录state默认processing调用get_report_data()取数成功后把state更新为generated并紧接着调用send_report_to_external_api()任一步骤异常时把state置为error并向外抛出异常。get_id()决定上报 payload 中的站点身份。ANONYMOUS_SURVEY_REPORT为False默认时返回settings.LMS_BASE即你的 LMS 域名为True时返回SurveyReportAnonymousSiteID中 get-or-create 的 UUID实现匿名但可识别的上报。四、生成并发送报告的两种操作方式方式一Django Admin按 README.rst 的步骤打开你的 LMS 域名/admin/survey_report/surveyreport/进入Survey Report管理页点击Generate Report按钮该按钮来自自定义的 change_list.html 模板勾选想发送的报告使用批量操作admin actionSend report to external API将其发送到外部 API。Admin 端的定制逻辑在 admin.py 中值得注意的几个约束has_add_permission返回False报告不允许手工新建只能由生成流程产生has_delete_permission返回False且移除了delete_selected默认操作报告是历史数据快照不可删除所有字段均设为readonly_fields并隐藏保存按钮changeform_view注入show_saveFalse等上下文管理页对报告只读唯一可执行的动作就是发送report_state列会在报告存在成功上传记录时显示Sent否则显示state本身Processing/Generated/Error。整个 Admin 只在settings.SURVEY_REPORT_ENABLE为真时注册admin.py#L98-L99配合该开关可以完全关闭功能入口。方式二命令行进入 LMS 容器的 Bash shell例如使用tutor dev run lms bash执行./manage.py lms generate_report命令实现位于 management/commands/generate_report.py默认行为是生成 发送先调用generate_report()其内部在取数成功后即会发送一次报告随后若未加--no-send标志命令会再显式调用一次send_report_to_external_api(report_id)如果只想生成、不上报加--no-send参数./manage.py lms generate_report --no-send任意环节失败会抛出CommandError并带上原始错误信息如An error has occurred while survey report was generating. ...参数详情可通过./manage.py lms generate_report --help查看。附Celery 异步任务除了手动触发仓库还提供了 Celery 任务 tasks.pygenerate_survey_report任务名openedx.features.survey_report.tasks.generate_survey_report内部调用generate_report()。从源码结构看这为由外部定时任务如 cron/beat 或 Tutor 插件周期性触发报告生成与上报预留了入口README.rst 中也注明了通过 Tutor 插件可自动化执行该流程相关章节在原文档中标注为 TODO。五、报告如何被发送到外部 API发送逻辑即 api.py 中的send_report_to_external_api(report_id)按report_id取出SurveyReport记录用model_to_dict提取五个指标字段再组装完整 payloadid站点身份LMS_BASE域名或匿名 UUID见get_id()extra_data报告中保存的附加字典created_at格式化为%m-%d-%Y %H:%M:%S的生成时间以 JSON 格式requests.post(settings.SURVEY_REPORT_ENDPOINT, jsondata)发送raise_for_status()对非 2xx 响应抛出异常成功后创建一条SurveyReportUpload记录保存状态码与响应体。也就是说你的SURVEY_REPORT_ENDPOINT端点只需要能接收包含上述字段的 JSON POST 请求即可接收报告。六、配置项全解各设置项在 lms/envs/common.py 中给出默认值.. setting_name注释表明它们是通过paver设置框架暴露给 LMS 的正式配置项设置项类型默认值说明SURVEY_REPORT_ENABLEboolTrue总开关。设为False时Admin 不再注册入口、Banner 消失、generate_report()拒绝生成抛 Survey report generation is not enabledSURVEY_REPORT_ENDPOINTstringhttps://hooks.zapier.com/hooks/catch/11595998/3ouwv7m/报告发送目标 URL需支持 JSON POST。默认为 Open edX 组织的接收端点用于年度 Impact Report 协作可自行覆盖ANONYMOUS_SURVEY_REPORTboolFalseFalse时 payload 中的站点 ID 为LMS_BASE你的 LMS 域名True时改用持久化的随机 UUID 匿名上报SURVEY_REPORT_EXTRA_DATAdict{}附加字典会原样写入报告的extra_data字段并随 payload 上报例如{site_name: ..., openedx-release: ...}SURVEY_REPORT_CHECK_THRESHOLDint6Banner 检查阈值单位月。距最近一次报告超过该月数时提醒见下节前四项的语义描述来自 README.rst 的 Settings for Survey Report 一节默认值取自当前仓库的实际配置。七、Admin Banner 的触发机制为了让 Open edX 运营者不会忘记定期上报该 App 实现了一个管理后台提醒 Banner模板 admin_banner.html配套前端脚本 admin_banner.js。判定逻辑在 context_processors.pyadmin_extra_context(request)作为 context processor 向所有 admin 页面注入show_survey_report_banner上下文仅当SURVEY_REPORT_ENABLE为真且当前请求路径属于 admin 首页reverse(admin:index)前缀匹配时才进行判断should_show_survey_report_banner()取出created_at最新的SurveyReport若其日期早于阈值日期今天 - SURVEY_REPORT_CHECK_THRESHOLD个月由get_months_threshold()基于dateutil.relativedelta计算则显示 Banner若从未生成过任何报告SurveyReport.DoesNotExist同样显示 Banner因此默认行为是距上次生成报告超过 6 个月SURVEY_REPORT_CHECK_THRESHOLD 6时在 admin 首页出现提醒可调整该阈值改变提醒频率。八、小结与相关入口Survey Report 提供了一条统计查询 → 快照落库 → 外部上报 → 结果留痕的完整链路queries.py 负责只读统计api.py 负责生成与发送的状态机admin.py 与 management/commands/generate_report.py 提供两个操作入口context_processors.py 负责周期性提醒。测试方面可参考 tests/test_query_methods.py 与 management/commands/tests/test_generate_report.py其中覆盖了各统计口径与命令的行为验证。若你只想在自己的部署中本地留存报告而不向 Open edX 官方端点上报最简做法是把SURVEY_REPORT_ENDPOINT指向自己的接收端点或配合--no-send仅生成并可通过SURVEY_REPORT_EXTRA_DATA附加站点标识信息。【免费下载链接】openedx-platformThe Open edX LMS Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Open edX LMS Survey Report为平台收集并上报匿名化聚合数据的调研报告功能【免费下载链接】openedx-platformThe Open edX LMS Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platformSurvey Report 是 Open edXopenedx-platform内置于 LMS 中的一个 Django Appopenedx.features.survey_report用于以聚合、匿名的方式收集平台上课程规模化的关键运营指标课程数、活跃学习者、注册量、选课量、证书数并支持将这些指标定期上报给外部 API为年度 Open edX Impact Report 提供数据来源。阅读本文后你将掌握如何理解它上报的五类核心指标口径、如何通过 Django Admin 或命令行generate_report命令生成与发送报告、如何配置SURVEY_REPORT_ENDPOINT等设置项将报告改发到自己指定的端点以及管理后台提醒 Banner 的触发机制。一、功能定位收集哪些聚合、匿名数据Survey Report 的设计目标见 README.rst收集aggregated, anonymized的平台级数据以便跟踪 Open edX 使用量的增长与趋势。它收集的核心指标与数据来源如下指标名称来自 README.rst 与 models.py 中的模型字段注释指标字段含义底层统计口径来自 queries.pycourses_offered平台当前提供的活跃课程总数get_unique_courses_offered()课程已开start 当前时间、未结束end为空或晚于当前时间、且报名数大于MIN_ENROLLS_ACTIVE_COURSE常量值为 5从源码结构看这是用来过滤测试/废弃课程的最小报名量阈值learners近 4 周内有登录的活跃用户数get_recently_active_users(weeks)按last_login 当前时间 - weeks统计调用方固定传入 4 周见下文MAX_WEEKS_SINCE_LAST_LOGINregistered_learners平台历史注册用户总数get_registered_learners()User中is_activeTrue的记录数enrollments平台活跃选课总数get_course_enrollments()is_activeTrue的CourseEnrollment且排除超级用户与 staff 用户generated_certificates已生成证书总数get_generated_certificates()PersistentCourseGrade中passed_timestamp非空的记录数extra_data附加信息如 site_name、openedx-release 版本号直接取设置项SURVEY_REPORT_EXTRA_DATAstate异步生成流程所处状态取值为processing/generated/error三态SURVEY_REPORT_STATES所有查询都通过.using(read_replica_or_default())走只读副本若配置了读副本避免大表统计对主库产生压力见 queries.py。二、数据模型三个核心 Model模型定义在 models.pySurveyReport存储一份报告快照。除上表各指标均为BigIntegerField默认 0外还有created_atauto_nowTrue——报告生成时间Meta.ordering [-created_at]保证列表按时间倒序stateCharFieldmax_length24——异步生成流程状态默认processing完成后置为generated出错置为error。SurveyReportUpload记录发送报告到外部 API这一动作的结果字段包括sent_at发送时间、report外键指向SurveyReport级联删除、status_codeHTTP 状态码、request_details请求响应体max_length255。其中is_uploaded()方法以200 status_code 300判定是否发送成功。SurveyReportAnonymousSiteID当启用匿名上报时持久化一个随机 UUID主键、uuid.uuid4默认值作为站点身份标识。从源码结构看其作用是让同一站点在多次匿名上报中使用同一个 UUID便于接收方做去重与趋势关联。这三个模型对应了 migrations/ 目录下 6 个版本的迁移演进初始模型、state字段、SurveyReportUpload、匿名 UUID 等。三、报告数据是如何生成的api.py调用链核心业务逻辑集中在 api.pyget_report_data()依次调用queries.py的五个统计函数并将settings.SURVEY_REPORT_EXTRA_DATA作为extra_data一并返回。注意活跃学习者的窗口固定为MAX_WEEKS_SINCE_LAST_LOGIN 4周api.py#L23。generate_report()生成流程的状态机入口——若SURVEY_REPORT_ENABLE为False直接抛出异常拒绝生成先落库一条空记录state默认processing调用get_report_data()取数成功后把state更新为generated并紧接着调用send_report_to_external_api()任一步骤异常时把state置为error并向外抛出异常。get_id()决定上报 payload 中的站点身份。ANONYMOUS_SURVEY_REPORT为False默认时返回settings.LMS_BASE即你的 LMS 域名为True时返回SurveyReportAnonymousSiteID中 get-or-create 的 UUID实现匿名但可识别的上报。四、生成并发送报告的两种操作方式方式一Django Admin按 README.rst 的步骤打开你的 LMS 域名/admin/survey_report/surveyreport/进入Survey Report管理页点击Generate Report按钮该按钮来自自定义的 change_list.html 模板勾选想发送的报告使用批量操作admin actionSend report to external API将其发送到外部 API。Admin 端的定制逻辑在 admin.py 中值得注意的几个约束has_add_permission返回False报告不允许手工新建只能由生成流程产生has_delete_permission返回False且移除了delete_selected默认操作报告是历史数据快照不可删除所有字段均设为readonly_fields并隐藏保存按钮changeform_view注入show_saveFalse等上下文管理页对报告只读唯一可执行的动作就是发送report_state列会在报告存在成功上传记录时显示Sent否则显示state本身Processing/Generated/Error。整个 Admin 只在settings.SURVEY_REPORT_ENABLE为真时注册admin.py#L98-L99配合该开关可以完全关闭功能入口。方式二命令行进入 LMS 容器的 Bash shell例如使用tutor dev run lms bash执行./manage.py lms generate_report命令实现位于 management/commands/generate_report.py默认行为是生成 发送先调用generate_report()其内部在取数成功后即会发送一次报告随后若未加--no-send标志命令会再显式调用一次send_report_to_external_api(report_id)如果只想生成、不上报加--no-send参数./manage.py lms generate_report --no-send任意环节失败会抛出CommandError并带上原始错误信息如An error has occurred while survey report was generating. ...参数详情可通过./manage.py lms generate_report --help查看。附Celery 异步任务除了手动触发仓库还提供了 Celery 任务 tasks.pygenerate_survey_report任务名openedx.features.survey_report.tasks.generate_survey_report内部调用generate_report()。从源码结构看这为由外部定时任务如 cron/beat 或 Tutor 插件周期性触发报告生成与上报预留了入口README.rst 中也注明了通过 Tutor 插件可自动化执行该流程相关章节在原文档中标注为 TODO。五、报告如何被发送到外部 API发送逻辑即 api.py 中的send_report_to_external_api(report_id)按report_id取出SurveyReport记录用model_to_dict提取五个指标字段再组装完整 payloadid站点身份LMS_BASE域名或匿名 UUID见get_id()extra_data报告中保存的附加字典created_at格式化为%m-%d-%Y %H:%M:%S的生成时间以 JSON 格式requests.post(settings.SURVEY_REPORT_ENDPOINT, jsondata)发送raise_for_status()对非 2xx 响应抛出异常成功后创建一条SurveyReportUpload记录保存状态码与响应体。也就是说你的SURVEY_REPORT_ENDPOINT端点只需要能接收包含上述字段的 JSON POST 请求即可接收报告。六、配置项全解各设置项在 lms/envs/common.py 中给出默认值.. setting_name注释表明它们是通过paver设置框架暴露给 LMS 的正式配置项设置项类型默认值说明SURVEY_REPORT_ENABLEboolTrue总开关。设为False时Admin 不再注册入口、Banner 消失、generate_report()拒绝生成抛 Survey report generation is not enabledSURVEY_REPORT_ENDPOINTstringhttps://hooks.zapier.com/hooks/catch/11595998/3ouwv7m/报告发送目标 URL需支持 JSON POST。默认为 Open edX 组织的接收端点用于年度 Impact Report 协作可自行覆盖ANONYMOUS_SURVEY_REPORTboolFalseFalse时 payload 中的站点 ID 为LMS_BASE你的 LMS 域名True时改用持久化的随机 UUID 匿名上报SURVEY_REPORT_EXTRA_DATAdict{}附加字典会原样写入报告的extra_data字段并随 payload 上报例如{site_name: ..., openedx-release: ...}SURVEY_REPORT_CHECK_THRESHOLDint6Banner 检查阈值单位月。距最近一次报告超过该月数时提醒见下节前四项的语义描述来自 README.rst 的 Settings for Survey Report 一节默认值取自当前仓库的实际配置。七、Admin Banner 的触发机制为了让 Open edX 运营者不会忘记定期上报该 App 实现了一个管理后台提醒 Banner模板 admin_banner.html配套前端脚本 admin_banner.js。判定逻辑在 context_processors.pyadmin_extra_context(request)作为 context processor 向所有 admin 页面注入show_survey_report_banner上下文仅当SURVEY_REPORT_ENABLE为真且当前请求路径属于 admin 首页reverse(admin:index)前缀匹配时才进行判断should_show_survey_report_banner()取出created_at最新的SurveyReport若其日期早于阈值日期今天 - SURVEY_REPORT_CHECK_THRESHOLD个月由get_months_threshold()基于dateutil.relativedelta计算则显示 Banner若从未生成过任何报告SurveyReport.DoesNotExist同样显示 Banner因此默认行为是距上次生成报告超过 6 个月SURVEY_REPORT_CHECK_THRESHOLD 6时在 admin 首页出现提醒可调整该阈值改变提醒频率。八、小结与相关入口Survey Report 提供了一条统计查询 → 快照落库 → 外部上报 → 结果留痕的完整链路queries.py 负责只读统计api.py 负责生成与发送的状态机admin.py 与 management/commands/generate_report.py 提供两个操作入口context_processors.py 负责周期性提醒。测试方面可参考 tests/test_query_methods.py 与 management/commands/tests/test_generate_report.py其中覆盖了各统计口径与命令的行为验证。若你只想在自己的部署中本地留存报告而不向 Open edX 官方端点上报最简做法是把SURVEY_REPORT_ENDPOINT指向自己的接收端点或配合--no-send仅生成并可通过SURVEY_REPORT_EXTRA_DATA附加站点标识信息。【免费下载链接】openedx-platformThe Open edX LMS Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
