Skip to content

system_overview.md

Latest commit

 

History

History
182 lines (129 loc) · 4.71 KB

system_overview.md

File metadata and controls

182 lines (129 loc) · 4.71 KB

系统说明文档

一、项目概述

本项目是一个基于 MongoDB 的在线问卷系统。phase1 完成了问卷、答卷、跳转和统计；当前代码已经完成 phase2 的主体迁移，系统从“问卷中心”升级为“题目资产 + 题目版本 + 问卷引用”的双中心结构。

系统当前支持：

  • 用户注册、登录、问卷创建与发布
  • 题目资产创建、版本历史、恢复旧版本
  • 题目共享、题库管理
  • 问卷从题目资产或题库选题
  • 问卷内排序、跳转、切换题目版本
  • 整卷统计与跨问卷单题统计

二、技术栈

层次 技术 说明
Web 框架 FastAPI 页面路由 + API 路由
数据库 MongoDB + PyMongo 文档存储、索引、聚合
模板 Jinja2 服务端渲染
前端 原生 JavaScript + Pico CSS 保持当前技术栈简单直接
认证 Session Cookie + itsdangerous 已登录用户访问受保护资源
测试 pytest + FastAPI TestClient 单元测试与集成测试

三、系统架构

浏览器
  │
  ├── HTML 页面请求
  │     └── pages.py -> Jinja2 模板
  │
  └── API 请求
        └── routes/*
              └── services/*
                    └── MongoDB

关键分层原则：

  • routes/ 负责请求参数、认证依赖、错误码转换
  • services/ 负责业务语义和跨集合逻辑
  • models/ 负责 Pydantic 输入输出模型
  • jump_service.py 与 validation_service.py 保持独立，便于复用和测试

四、核心数据对象

phase2 下的核心对象已经不是只有 survey。

4.1 用户

  • 集合：users
  • 作用：登录认证、拥有问卷/题目/题库

4.2 题目资产

  • 集合：question_roots
  • 含义：同一道题的稳定身份
  • 管理字段：owner_id、visibility、shared_with、latest_version_id、bank_ids

4.3 题目版本

  • 集合：question_versions
  • 含义：题目在某一时刻的具体内容
  • 关键字段：root_id、version、parent_version_id、title、type、options、validation

4.4 题库

  • 集合：question_banks
  • 含义：题目资产的组织容器
  • 关键字段：owner_id、question_root_ids、shared_with

4.5 问卷

  • 集合：surveys
  • 当前 questions[] 存储的是问卷中的题目引用，而不是题目本体
  • 每个问题项包括：
    • qid
    • order
    • question_root_id
    • question_version_id
    • snapshot
    • jump_rules

4.6 答卷

  • 集合：responses
  • 保留 phase1 的 answers
  • 新增 answer_items[]，用于跨问卷按 question_root_id / question_version_id 聚合统计

五、页面结构

页面 URL 作用
登录 /login 用户登录
注册 /register 用户注册
我的问卷 /dashboard 查看本人问卷
创建问卷 /surveys/new 新建问卷并进入编排页
编辑问卷 /surveys/{id}/edit 选题、排序、跳转、切换版本
填写问卷 /survey/{share_code} 公开填写问卷
问卷统计 /surveys/{id}/stats 查看整卷与单题统计
题目资产 /questions 创建题目、筛选、搜索、快捷入库
题目详情 /questions/{root_id} 版本历史、共享、使用情况、跨问卷统计
题库列表 /question-banks 创建题库、筛选、搜索
题库详情 /question-banks/{bank_id} 查看题库成员、加题/移题、只读权限展示

六、问卷状态流转

draft -> published -> closed
状态 可编辑问卷编排 可填写 可看统计
draft 是 否 否
published 否 是 是
closed 否 否 是

补充说明：

  • 已发布问卷冻结，不再因题目资产后续变化而改变
  • 题目内容修改通过“创建新版本”完成，不直接覆盖旧版本

七、前端职责划分

7.1 题目页

负责题目内容和版本：

  • 创建题目
  • 查看版本历史
  • 创建新版本
  • 恢复旧版本
  • 修改共享设置
  • 查看使用情况和跨问卷统计

7.2 题库页

负责题目组织：

  • 创建题库
  • 查看题库成员
  • 管理加题/移题
  • 对共享用户展示只读界面

7.3 问卷编辑页

负责问卷编排：

  • 保存问卷元信息
  • 从题目资产/题库选题
  • 问题排序
  • 配置跳转规则
  • 切换引用版本

问卷页不再是题目内容的主编辑入口。

八、当前实现状态

phase2 代码主链已完成并通过自动化回归，当前测试结果：

93 passed

配套的阶段总结与正式提交报告由本地文档单独维护，不放入仓库。