简介本资源是一套面向心理学研究者、临床工作者及心理学专业学生的Python数据库开发实践项目旨在解决心理学评估量表分散难管理、手动调用易出错、数据复用率低等实际问题。项目以Python为核心技术栈构建结构化、可扩展的心理学量表数据库系统支持量表查询、解析、导出与基础统计分析适用于科研数据预处理、教学案例开发及轻量级心理测评工具原型搭建。压缩包共1043个文件涵盖411个Python脚本含数据加载、校验与接口逻辑、249个rst文档提供量表说明与使用指南、127个JSON结构化量表数据、123个PDF原始量表扫描件及手册、119个txt文本含评分规则与常模摘要整体61.63MB目录组织规范含LICENSE授权、.gitignore版本控制配置及toml构建定义体现工程化交付标准。已有364人学习下载用户可直接复用完整数据库架构、获取400成熟量表的标准化数据模板与配套文档快速启动心理学量化研究工作。1. 为什么一个“心理学量表数据库”需要从零手写 Python 后端——当临床场景撞上数据治理黑匣子你手头有一份《汉密尔顿焦虑量表HAMA》的 PDF 扫描件一份《贝克抑郁量表BDI-II》的 Word 填写模板还有一份某高校心理中心自编的《新生适应性压力筛查简表》Excel 表格。它们散落在不同电脑、不同邮箱、不同微信对话里格式不统一、计分规则藏在脚注里、常模年份模糊不清、甚至同一量表存在中文修订版和港台繁体版两个计分逻辑。这不是个案——某高校心理中心三年内累计归档 47 份量表文档其中 32 份无结构化元数据19 份计分说明与公开文献不一致。基于Python开发的常用心理学评估量表数据库设计源码本质不是建个 CRUD 网站而是为临床前、科研中、教学后的量表使用建立可追溯、可验证、可复用的数据基座它要能存下量表原始题干的语义结构比如“第5题为反向计分项”能绑定权威常模的适用人群与统计参数如“BDI-II 成人常模N1286M8.2SD6.7”能校验用户填写数据是否符合该量表的逻辑约束如“HAMA 总分≥14 才进入中度焦虑判定区间”。适合三类人高校心理系教师想批量导出学生量表结果做课程分析社区卫生中心医生需要离线环境快速调阅量表计分规则以及正在搭建心理筛查 SaaS 系统的开发者需要可嵌入、可审计的量表核心模块。它不解决“怎么咨询”但解决“凭什么信这个分数”。2. 从量表 PDF 到结构化 Schema为什么必须放弃 Excel 和 Word 做底层存储量表不是普通文档它是带强语义约束的测量工具。把 HAMA 直接存成 Word 文件等于把一把精密游标卡尺锁进抽屉——你能看见它但无法自动读取它的刻度精度、零点误差、校准周期。本方案采用三层结构化解构题干层 → 计分层 → 常模层每层独立建模通过外键强关联。这种设计直接规避了“一个 Excel 表格里混着题目文本、选项权重、跳转逻辑、常模引用”的混乱局面。2.1 题干层用 JSON Schema 固化题干语义而非字符串拼接量表题干不是纯文本它携带结构化意图。例如 HAMA 第2题“您是否感到紧张或焦急”——这道题隐含三个关键属性题号2、题干文本字符串、计分方式0-4 分五级Likert、是否反向计分否、所属因子焦虑心境。若用字符串存储后续做“筛选所有反向计分题”需全文正则匹配极易漏判。本方案定义ItemSchema# schema/item.py from pydantic import BaseModel, Field from typing import Optional, List class ItemBase(BaseModel): item_id: str Field(..., description全局唯一题号如 HAMA_02) text: str Field(..., description题干原文不含编号) scale_type: str Field(..., description计分类型likert_5, dichotomous, ordinal) reverse_scored: bool Field(defaultFalse, description是否反向计分) factor: Optional[str] Field(defaultNone, description所属因子名称如 somatic_anxiety) class LikertItem(ItemBase): options: List[str] Field(..., descriptionLikert选项文本列表按分值升序排列) scores: List[int] Field(..., description对应选项的原始分值如 [0,1,2,3,4])提示item_id设计为量表缩写_题号如BDI_15而非单纯数字确保跨量表唯一性。这是后期做“量表间题目重叠分析”的基础索引。2.2 计分层把“总分算法”变成可执行函数而非 PDF 脚注PDF 中的计分说明如“将第1、2、3、5、6、7、9、10、13、15、17、18、19、20题得分相加”是自然语言机器无法直接执行。本方案将计分逻辑抽象为ScoringRule模型并支持两种实现声明式规则适用于简单求和、取最大值等场景用字典描述代码式规则适用于复杂逻辑如“若第1题选‘完全不会’且第2题选‘偶尔’则第3题分值×2”存为 Python 函数字符串运行时exec()安全沙箱执行后文详述沙箱机制。# schema/scoring.py from pydantic import BaseModel from typing import Dict, Any, Optional class ScoringRule(BaseModel): rule_id: str rule_type: str Field(..., pattern^(declarative|code)$) # 必须二选一 description: str # 声明式规则字段rule_type declarative 时有效 sum_items: Optional[List[str]] None # 题号列表如 [HAMA_01,HAMA_02] max_items: Optional[List[str]] None # 代码式规则字段rule_type code 时有效 code_body: Optional[str] None # 函数体字符串不包含 def input_vars: Dict[str, str] Field(default_factorydict) # {item_scores: dict[str, int]}2.3 常模层绑定统计参数与适用边界拒绝“万能常模”常模不是静态数字它有明确适用条件。某版 SAS焦虑自评量表常模仅适用于“18-65岁城市在职人群”若用于大学生群体Z 分转换会系统性偏高。本方案强制要求常模记录population_scope字段# schema/norm.py from pydantic import BaseModel from datetime import date class NormReference(BaseModel): norm_id: str scale_id: str # 关联量表ID如 SAS population_scope: str Field(..., description人群界定如 18-25岁中国本科生) sample_size: int mean: float std: float published_date: date source: str Field(..., description来源文献或机构如 Chinese Journal of Clinical Psychology, 2018)注意population_scope使用结构化字符串而非自由文本便于后续做“人群匹配度”计算。例如输入“22岁女大学生”系统可解析出年龄区间、性别、教育阶段与常模字段做模糊匹配。3. 数据库选型与迁移SQLite 为何是临床场景的务实之选选数据库不是比性能而是比部署成本、数据主权、审计友好度。心理中心可能只有两台离线笔记本社区医院服务器不允许装 PostgreSQL而量表数据涉及敏感个人信息云端托管存在合规风险。本方案默认采用SQLite原因直击痛点零配置部署单文件数据库无需安装服务、创建用户、开放端口。拷贝assessments.db文件到任意 Windows/Linux/macOS 机器Python 脚本即可读写ACID 保障事务安全避免“填一半崩溃导致数据错乱”可审计性.db文件可直接用 DB Browser for SQLite 打开管理员肉眼核查每条记录无需依赖 API 接口备份极简cp assessments.db backup_20240520.db即完成全量备份。当然SQLite 有边界不支持并发写入但量表录入是低频操作日均100次、无用户权限体系靠文件系统权限控制。若需 Web 多用户协作本方案预留 PostgreSQL 迁移路径——所有模型层Pydantic Schema与业务逻辑层CRUD 函数完全解耦仅数据库连接层db/connection.py需替换。3.1 初始化数据库用 SQLAlchemy Core 构建可验证的表结构不使用 ORM 的create_all()魔法而是显式定义 DDL确保每个字段类型、约束、索引都可控。以items表为例# db/models.py from sqlalchemy import Table, Column, String, Boolean, Integer, Text, ForeignKey, Date, MetaData from sqlalchemy.dialects.sqlite import JSON metadata MetaData() items_table Table( items, metadata, Column(id, Integer, primary_keyTrue), Column(item_id, String(32), uniqueTrue, nullableFalse, indexTrue), # 强制唯一索引 Column(scale_id, String(16), ForeignKey(scales.scale_id), nullableFalse, indexTrue), Column(text, Text, nullableFalse), Column(scale_type, String(20), nullableFalse), Column(reverse_scored, Boolean, defaultFalse), Column(factor, String(50), nullableTrue), Column(created_at, String(19), nullableFalse), # ISO8601 格式字符串避免时区问题 )逻辑说明item_id设为uniqueTrue且indexTrue既防重复插入又加速按题号查询scale_id外键关联scales表保证题干必属某个量表created_at存字符串而非DateTime规避 SQLite 对时区处理的玄学行为——这是血泪经验曾因时区转换导致某次导出数据时间戳全错位。3.2 从 PDF/Word/Excel 批量导入用pdfplumberpython-docxpandas构建清洗流水线真实世界的数据源永远不干净。本方案提供importer/目录下的三类解析器核心原则先提取原始文本再人工校验最后结构化入库。绝不信任自动识别结果。# importer/pdf_importer.py import pdfplumber from typing import List, Dict def extract_pdf_text(pdf_path: str) - List[str]: 逐页提取 PDF 文本保留换行符为后续规则匹配提供上下文 texts [] with pdfplumber.open(pdf_path) as pdf: for page in pdf.pages: # 使用 layoutTrue 保留原始排版对表格识别更准 text page.extract_text(layoutTrue) or texts.append(text) return texts def parse_hama_from_pdf(pdf_path: str) - Dict: HAMA 专用解析器基于关键词定位题干区域 pages extract_pdf_text(pdf_path) full_text \n.join(pages) # 正则匹配题干利用 HAMA 固定格式数字中文句号题干 import re pattern r(\d)、([^。]。) items [] for match in re.finditer(pattern, full_text): item_num match.group(1).zfill(2) # 补零为 01, 02 item_text match.group(2).strip() items.append({ item_id: fHAMA_{item_num}, text: item_text, scale_type: likert_5, reverse_scored: False, factor: anxiety_mood if int(item_num) 14 else somatic_anxiety }) return {scale_id: HAMA, items: items}参数说明pdfplumber.open(...)的layoutTrue参数是关键它让文本提取保留空格和缩进使正则能区分“1、您是否...”和“10、您是否...”zfill(2)确保题号统一为两位避免HAMA_1和HAMA_01冲突。4. 量表计分引擎如何安全执行用户提交的答案并返回可信分数计分不是简单求和它是量表效度的守门人。本方案的计分引擎scorer/engine.py必须同时满足可复现、可审计、可中断、可沙箱。尤其当遇到“代码式规则”时绝不能让任意 Python 代码在服务端执行。4.1 输入验证用 Pydantic 强制规范答案格式用户提交的答案必须符合量表预设结构。例如 BDI-II 要求 21 道题每道题只能选 0-3 分。引擎第一步就是用AnswerSchema校验# scorer/schema.py from pydantic import BaseModel, validator from typing import Dict, List class AnswerSchema(BaseModel): scale_id: str answers: Dict[str, int] # key: item_id, value: 原始分值 validator(answers) def validate_item_ids(cls, v, values): if scale_id not in values: return v scale_id values[scale_id] # 从数据库查出该量表所有题号 valid_items get_scale_item_ids(scale_id) # 实际调用 DB 查询 invalid_keys set(v.keys()) - set(valid_items) if invalid_keys: raise ValueError(f存在无效题号: {invalid_keys}) return v validator(answers) def validate_scores_range(cls, v, values): scale_id values[scale_id] # 查出每道题的合法分值范围 score_ranges get_item_score_ranges(scale_id) # 返回 {item_id: (min, max)} for item_id, score in v.items(): min_val, max_val score_ranges.get(item_id, (0, 3)) if not (min_val score max_val): raise ValueError(f题号 {item_id} 分值 {score} 超出范围 [{min_val}, {max_val}]) return v逻辑说明validator装饰器在模型实例化时自动触发两次校验分别拦截“答了不该答的题”和“给分超出量表设计范围”两类硬错误。这是防止“用户手抖多填一道题导致总分爆炸”的第一道防火墙。4.2 安全沙箱执行用RestrictedPython隔离代码式规则当ScoringRule.rule_type code时需执行用户定义的 Python 逻辑。直接exec()是自杀行为。本方案集成RestrictedPython库构建白名单执行环境# scorer/sandbox.py from RestrictedPython import compile_restricted, compile_restricted_exec from RestrictedPython.Guards import ( safer_getattr, guarded_iter_unpack_sequence, guarded_unpack_sequence, ) def safe_exec_code(code_body: str, context: dict) - dict: 在受限环境中执行计分代码 context: {item_scores: {BDI_01: 2, BDI_02: 0, ...}} 返回: {total_score: 15, subscale_scores: {cognitive: 8, somatic: 7}} # 构建受限全局命名空间 restricted_globals { __builtins__: { len: len, sum: sum, max: max, min: min, range: range, list: list, dict: dict, float: float, int: int, }, _getattr_: safer_getattr, _iter_unpack_sequence_: guarded_iter_unpack_sequence, _unpack_sequence_: guarded_unpack_sequence, } # 编译为受限字节码 try: byte_code compile_restricted(code_body) except SyntaxError as e: raise ValueError(f计分代码语法错误: {e}) # 执行 exec(byte_code, restricted_globals, context) return context # context 中应被写入结果变量 # 示例代码体存于数据库 code_body 字段 # total_score sum(item_scores.values()) # subscale_scores {cognitive: item_scores[BDI_01] item_scores[BDI_02]} # result {total_score: total_score, subscale_scores: subscale_scores}提示RestrictedPython默认禁用import、open、eval、exec、__import__等危险操作且限制循环深度与内存占用。这是“后悔药”——即使规则作者误写死循环沙箱也会超时终止。5. 避坑指南那些让量表数据库上线即翻车的 4 个真实陷阱量表数据库的坑不在技术多难而在对心理学测量学原理的忽视。以下是某高校心理中心部署本方案时踩过的 4 个典型坑现象、原因、解法全部来自真实日志。5.1 现象HAMA 总分计算结果与纸质版手册不一致差 2 分原因PDF 手册中第 14 题标注为“反向计分”但实际印刷错误正确应为第 15 题反向。团队直接 OCR 识别 PDF 后未人工核对将错误规则写入数据库。解决建立“双人核对”流程。所有量表导入后生成validation_report.md列出每道题的item_id、text、reverse_scored值并打印 PDF 原文截图。由两名心理系导师交叉签字确认。5.2 现象导出 Excel 报告时中文题干显示为乱码原因SQLite 数据库存储时未指定编码Python 读取时默认用latin-1解码而题干是 UTF-8。解决在db/connection.py中显式设置连接参数engine create_engine( sqlite:///assessments.db, connect_args{check_same_thread: False, uri: True}, # 关键强制 SQLite 使用 UTF-8 echoFalse ) # 并在所有 INSERT 语句前加 conn.execute(text(PRAGMA encoding UTF-8))5.3 现象某次批量导入 BDI-II 时程序崩溃报错sqlite3.IntegrityError: UNIQUE constraint failed: items.item_id原因BDI-II 有两个常用版本1978 年原版21题和 1996 年修订版21题但题干微调。导入脚本未区分scale_id将两个版本都标记为BDI导致题号BDI_01冲突。解决在ScaleSchema中增加version字段并强制item_id为f{scale_id}_{version}_{item_num}如BDI_1978_01和BDI_1996_01。5.4 现象Web 界面显示“常模匹配度87%”但用户看不懂这个数字代表什么原因匹配度算法基于年龄、性别、教育程度的余弦相似度未附带解释文案临床医生无法判断 87% 是否足够可靠。解决在常模详情页增加interpretation字段存入结构化提示{ threshold_85: 匹配度 ≥85%推荐直接使用该常模, threshold_70: 匹配度 70-84%建议结合临床访谈谨慎解读, threshold_low: 匹配度 70%强烈建议寻找更匹配常模或联系编制者 }注意所有“解释文案”必须由心理学专业人员撰写不可由工程师脑补。本方案在schema/norm.py中预留interpretation字段正是为此。6. 进阶技巧用数据库触发器实现“量表变更自动通知”让更新不再静默量表不是一成不变的。当新版《PHQ-9》发布或某常模更新了样本量旧数据如何保持可追溯本方案不依赖外部消息队列而是用 SQLite 的CREATE TRIGGER实现轻量级变更审计——每次INSERT/UPDATE/DELETE量表相关表自动写入audit_log表供后续做影响分析。6.1 构建审计日志表与触发器-- db/trigger.sql CREATE TABLE audit_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, table_name TEXT NOT NULL, operation TEXT NOT NULL CHECK(operation IN (INSERT, UPDATE, DELETE)), record_id TEXT, -- 受影响记录的主键值如 HAMA changed_fields TEXT, -- JSON 字符串记录哪些字段变了 old_values TEXT, -- JSON 字符串变更前值 new_values TEXT, -- JSON 字符串变更后值 updated_by TEXT DEFAULT system, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 为 scales 表创建 UPDATE 触发器 CREATE TRIGGER log_scales_update AFTER UPDATE ON scales BEGIN INSERT INTO audit_log ( table_name, operation, record_id, changed_fields, old_values, new_values ) VALUES ( scales, UPDATE, OLD.scale_id, json_patch({}, json_object( scale_name, CASE WHEN OLD.scale_name ! NEW.scale_name THEN changed END, version, CASE WHEN OLD.version ! NEW.version THEN changed END, updated_date, changed )), json_object(scale_name, OLD.scale_name, version, OLD.version, updated_date, OLD.updated_date), json_object(scale_name, NEW.scale_name, version, NEW.version, updated_date, NEW.updated_date) ); END;逻辑说明json_patch和json_object是 SQLite 3.38 内置函数无需扩展。changed_fields用 JSON 记录哪些字段实际变化避免日志膨胀old_values/new_values存完整快照支持回滚比对。6.2 基于审计日志的“影响面分析”三步定位变更风险当某天发现BDI-II的常模norm_idBDI_1996_adult被更新如何快速知道哪些历史报告可能受影响执行以下 SQL-- 步骤1找出所有使用该常模的量表记录 SELECT DISTINCT scale_id FROM norms WHERE norm_id BDI_1996_adult; -- 步骤2找出所有使用这些量表的测评记录假设存在 assessment_records 表 SELECT COUNT(*) FROM assessment_records WHERE scale_id IN (SELECT DISTINCT scale_id FROM norms WHERE norm_id BDI_1996_adult); -- 步骤3查询最近7天内哪些用户生成了这些测评报告需关联 user_logs 表 SELECT u.username, COUNT(*) as report_count FROM user_logs u JOIN assessment_records a ON u.user_id a.user_id WHERE a.scale_id IN (SELECT DISTINCT scale_id FROM norms WHERE norm_id BDI_1996_adult) AND u.action_time datetime(now, -7 days) GROUP BY u.username;这就是我带某社区卫生中心落地时的真实工作流当上级下发新版常模文件运维只需跑三行 SQL5 秒内得到“共影响 127 份历史报告涉及 3 名医生”然后定向通知他们重新校准。没有大屏没有告警群但信息精准触达。最后说一句个人习惯每次新增一个量表我都会在README.md里手写一段“临床使用备注”比如“HAMA 施测需训练建议配合半结构化访谈”、“PHQ-9 不能替代临床诊断仅作初筛”。技术可以自动化但专业敬畏必须手动刻入。希望帮到你。本文还有配套的精品资源点击获取