415 lines
15 KiB
Markdown
415 lines
15 KiB
Markdown
# MindScope
|
||
|
||
MindScope 是一个中文心理量表与自我探索测评项目。它专注于答题、浏览器本地计分、加密保存历史记录、导出完整测评档案，不包含广告、营销页、Web3、用户账号系统或内置 AI 分析模块。
|
||
|
||
> 测评结果仅用于自我了解、教育和研究参考，不构成医学诊断、心理诊断或治疗建议。遇到持续、严重或紧急的身心困扰时，请及时联系医生、心理健康专业人员或当地紧急援助服务。
|
||
|
||
## 当前版本
|
||
|
||
**v0.6.0**，更新于 2026-06-23。
|
||
|
||
本版本重点是“计分可信度升级”：
|
||
|
||
- 32 个量表全部接入统一结构化计分摘要。
|
||
- 每个量表记录明确保存：量表版本、计分版本、最低分、最高分、反向题、临界值。
|
||
- 新记录不再依赖结果页面文字抓取，而是在提交时直接保存结构化分数。
|
||
- 历史记录读取时会自动补齐缺失的结构化计分字段。
|
||
- 趋势页会标明“高分代表改善、风险升高、能力更好，还是特质更明显”。
|
||
- Markdown 导出会包含完整计分规则，方便交给 ChatGPT 或其他工具解读。
|
||
- 敏感量表仍保持克制表达，不把筛查结果写成诊断结论。
|
||
|
||
## 版本记录
|
||
|
||
| 版本 | 日期 | 主要变化 |
|
||
| --- | --- | --- |
|
||
| v0.6.0 | 2026-06-23 | 32 个量表统一结构化计分，保存量表版本/计分版本/分数范围/反向题/临界值，趋势页显示高分方向，MD 导出补充计分规则 |
|
||
| v0.5.0 | 2026-06-23 | 本地记录 AES-GCM 加密，旧记录自动迁移，匿名同步端到端加密，首页说明加密与匿名档案 |
|
||
| v0.4.0 | 2026-06-23 | 匿名档案模式、服务器同步接口、远端记录同步、远端档案删除 |
|
||
| v0.3.0 | 2026-06-23 | iOS、手机和平板答题阅读、触控、折叠导航和安全区优化 |
|
||
| v0.2.0 | 2026-06-23 | 多人档案、完整历史、趋势、统一画像、MD/JSON 导出、加密备份和自动测试 |
|
||
| v0.1.0 | 2026-06-22 | 中文量表列表、浏览器答题、本地计分、草稿保存和单次结果导出 |
|
||
|
||
## 项目特点
|
||
|
||
- **中文优先**：界面、题目、结果说明和导出文本均面向中文用户。
|
||
- **32 个测评**：覆盖人格、认知、情绪、职业、价值观、幸福感、心理健康等方向。
|
||
- **本地计分**：答题和计分在浏览器中完成，不依赖外部分析服务。
|
||
- **结构化结果**：每条记录保存分数、版本、范围、反向题、阈值和高分含义。
|
||
- **加密保存**：本地历史记录写入 IndexedDB 前会先加密。
|
||
- **匿名同步**：可使用“代号 + 恢复口令”同步到服务器，服务器只保存密文。
|
||
- **多档案**：可为自己、家人或朋友分别保存独立记录。
|
||
- **完整导出**：支持单次记录或单人全部记录导出为 Markdown，也支持 JSON 备份。
|
||
- **轻量部署**：默认不需要 MySQL、PostgreSQL、Redis 等数据库。
|
||
|
||
## 已收录测评
|
||
|
||
当前共 32 个测评。
|
||
|
||
### 人格与价值观
|
||
|
||
| 测评 | 题数 | 主要内容 |
|
||
| --- | ---: | --- |
|
||
| IPIP Big Five | 50 | 五大人格快速版 |
|
||
| IPIP Big Five 120 | 120 | 五大人格及细分侧面 |
|
||
| IPIP Big Five 300 | 300 | 五大人格完整版及细分侧面 |
|
||
| HEXACO | 60 | 六因素人格结构 |
|
||
| Fisher 气质量表 | 40 | 探索者、建设者、指挥者、协商者倾向 |
|
||
| 开放式九型人格量表 OEPS | 54 | 九型人格倾向 |
|
||
| Short Dark Triad | 27 | 马基雅维利主义、自恋、精神病态倾向 |
|
||
| NPI-16 自恋人格量表 | 16 | 自恋相关人格倾向 |
|
||
| Rosenberg 自尊量表 | 10 | 整体自尊与自我价值感 |
|
||
| Grit-S 坚毅量表 | 8 | 兴趣一致性与努力坚持 |
|
||
| Brief Self-Control | 13 | 自我控制、冲动控制和习惯管理 |
|
||
| ECR-RS 依恋量表 | 9 | 依恋焦虑与依恋回避 |
|
||
| IRI 共情量表 | 28 | 共情、观点采择和个人忧虑 |
|
||
| Schwartz 价值观量表 | 30 | 十类基本价值观和高阶价值维度 |
|
||
| VIA 性格优势量表 | 48 | 24 项性格优势 |
|
||
|
||
### 认知与职业
|
||
|
||
| 测评 | 题数 | 主要内容 |
|
||
| --- | ---: | --- |
|
||
| CRT 认知反思测试 | 7 | 直觉反应与分析性反思 |
|
||
| Need for Cognition | 18 | 主动思考和享受认知活动的倾向 |
|
||
| Maximizer | 13 | 决策中的最大化倾向 |
|
||
| RIASEC 霍兰德职业兴趣 | 48 | 现实型、研究型、艺术型、社会型、企业型、常规型 |
|
||
| Career Anchors 职业锚 | 40 | 八类职业价值与职业定位 |
|
||
| 成人 ADHD 自评量表 ASRS-v1.1 | 18 | 注意力、冲动和执行功能相关表现 |
|
||
|
||
### 情绪、压力与心理健康
|
||
|
||
| 测评 | 题数 | 主要内容 |
|
||
| --- | ---: | --- |
|
||
| DASS-21 | 21 | 抑郁、焦虑与压力 |
|
||
| GAD-7 | 7 | 广泛性焦虑症状筛查 |
|
||
| PHQ-9 | 9 | 抑郁症状筛查 |
|
||
| PSS-10 | 10 | 主观感知压力 |
|
||
| BDI-II | 21 | 抑郁相关症状自评 |
|
||
| SDS | 20 | 抑郁相关症状自评 |
|
||
| WHO-5 幸福感指数 | 5 | 近期主观幸福感 |
|
||
| Yale-Brown 强迫症状量表 | 10 | 强迫观念与强迫行为严重程度 |
|
||
| SCL-90 | 90 | 多维心理症状自评 |
|
||
| ISI 失眠严重程度指数 | 7 | 失眠程度及日间影响 |
|
||
| 游戏障碍问卷 GD | 9 | 游戏相关困扰 |
|
||
| 性别认知障碍问卷 GDQ | 27 | 性别相关体验自评 |
|
||
|
||
## 数据与隐私
|
||
|
||
MindScope 默认没有传统服务端数据库，也不会主动把答案发送给第三方分析服务。
|
||
|
||
| 数据 | 保存位置 | 说明 |
|
||
| --- | --- | --- |
|
||
| 未完成答题草稿 | 浏览器 `localStorage` | 用户清除草稿或站点数据前保留 |
|
||
| 最近完成的答题答案 | 浏览器 `sessionStorage` | 当前标签页会话结束前保留，用于结果页展示 |
|
||
| 档案与历史记录 | 浏览器 `IndexedDB` | 写入前使用 AES-GCM 加密 |
|
||
| 匿名同步记录 | `data/anonymous-store.json` | 浏览器端加密后上传，服务器保存密文 |
|
||
| Markdown 导出 | 用户主动下载的位置 | 由用户自行管理 |
|
||
| JSON / 加密 JSON 备份 | 用户主动下载的位置 | 可用于迁移或恢复 |
|
||
|
||
结果页 URL 不携带答案，因此复制页面链接不会把测评记录放进浏览器历史、代理日志或服务器访问日志。需要保留或交给其他工具分析时，请使用“复制完整记录”或“下载 MD”。
|
||
|
||
## 结构化计分
|
||
|
||
结构化计分元数据位于 `lib/scoring-metadata.ts`。每个量表都会记录：
|
||
|
||
- `questionnaireVersion`：量表题目版本
|
||
- `scoreVersion`：计分逻辑版本
|
||
- `min` / `max`：总分或主要维度分数范围
|
||
- `reverseItems`：反向题编号
|
||
- `thresholds`：临界值或分级阈值
|
||
- `direction`：高分方向，区分风险、保护因素、能力表现、人格特质或混合含义
|
||
- `highScoreMeaning`：人类可读的高分解释
|
||
|
||
新增量表时，除了题目和结果页，还必须补充结构化计分元数据，避免旧记录在题目或计分逻辑更新后被错误解释。
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 15 App Router
|
||
- React 19
|
||
- TypeScript 5
|
||
- Tailwind CSS 4
|
||
- next-international
|
||
- Radix UI
|
||
- Lucide React
|
||
- pnpm
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 20 或更高版本
|
||
- pnpm 9 或更高版本
|
||
|
||
建议开发和生产环境使用相同 Node.js 主版本，避免构建结果不一致。
|
||
|
||
## 获取与更新项目
|
||
|
||
推荐使用 SSH 克隆。如果 Gitea SSH 服务使用 `2222` 端口：
|
||
|
||
```bash
|
||
git clone ssh://git@git.polarisx.net:2222/mikemoi/MindScope.git
|
||
cd MindScope
|
||
```
|
||
|
||
也可以使用 HTTPS：
|
||
|
||
```bash
|
||
git clone https://git.polarisx.net/mikemoi/MindScope.git
|
||
cd MindScope
|
||
```
|
||
|
||
服务器已经部署过项目时，使用以下命令获取最新版本并重新构建：
|
||
|
||
```bash
|
||
cd /opt/mindscope
|
||
git pull --ff-only origin main
|
||
pnpm install --frozen-lockfile
|
||
pnpm build
|
||
|
||
mkdir -p .next/standalone/.next
|
||
rm -rf .next/standalone/.next/static
|
||
cp -r .next/static .next/standalone/.next/static
|
||
|
||
sudo systemctl restart mindscope
|
||
sudo systemctl status mindscope --no-pager
|
||
```
|
||
|
||
如果以后增加 `public` 目录，构建后还需要同步公开静态文件：
|
||
|
||
```bash
|
||
rm -rf .next/standalone/public
|
||
cp -r public .next/standalone/public
|
||
```
|
||
|
||
`.env*`、`.next`、`node_modules`、日志和本地压缩包已被 `.gitignore` 排除。更新前如有未提交的源码修改，先运行 `git status` 检查；`git pull --ff-only` 会在无法安全快进时停止，不会自动创建合并提交。
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
pnpm dev
|
||
```
|
||
|
||
浏览器打开：
|
||
|
||
```text
|
||
http://localhost:3000
|
||
```
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
|
||
# 代码检查
|
||
pnpm lint
|
||
|
||
# TypeScript 类型检查
|
||
pnpm exec tsc --noEmit
|
||
|
||
# 自动化测试
|
||
pnpm test
|
||
|
||
# 生产构建
|
||
pnpm build
|
||
|
||
# 启动 Next.js 生产服务器
|
||
pnpm start
|
||
```
|
||
|
||
## 生产部署
|
||
|
||
### 直接运行
|
||
|
||
适合先验证 VPS 环境：
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
pnpm build
|
||
NODE_ENV=production PORT=3000 pnpm start
|
||
```
|
||
|
||
生产环境建议只监听本机地址，再用 Nginx 提供公网访问和 HTTPS。
|
||
|
||
### Standalone 部署
|
||
|
||
项目在 `next.config.ts` 中启用了 `output: 'standalone'`。构建完成后，可部署更小的运行目录：
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
pnpm build
|
||
|
||
cp -r public .next/standalone/public 2>/dev/null || true
|
||
cp -r .next/static .next/standalone/.next/static
|
||
|
||
cd .next/standalone
|
||
HOSTNAME=127.0.0.1 PORT=3000 NODE_ENV=production node server.js
|
||
```
|
||
|
||
当前项目没有 `public` 目录时，第一条复制命令可以忽略。`.next/static` 必须复制到 standalone 目录，否则静态资源会缺失。
|
||
|
||
### systemd 示例
|
||
|
||
假设项目源码部署到 `/opt/mindscope`，Node.js 位于 `/usr/bin/node`：
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=MindScope
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=mindscope
|
||
Group=mindscope
|
||
WorkingDirectory=/opt/mindscope/.next/standalone
|
||
Environment=NODE_ENV=production
|
||
Environment=HOSTNAME=127.0.0.1
|
||
Environment=PORT=3000
|
||
ExecStart=/usr/bin/node /opt/mindscope/.next/standalone/server.js
|
||
Restart=on-failure
|
||
RestartSec=5
|
||
NoNewPrivileges=true
|
||
PrivateTmp=true
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
保存为 `/etc/systemd/system/mindscope.service` 后：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now mindscope
|
||
sudo systemctl status mindscope
|
||
```
|
||
|
||
不要使用 `root` 用户运行应用。部署目录应只允许部署用户写入。
|
||
|
||
### Nginx 反向代理示例
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name example.com;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
}
|
||
```
|
||
|
||
配置完成后使用 Certbot 或其他证书工具启用 HTTPS。防火墙通常只需要开放 SSH、HTTP 和 HTTPS，应用端口 `3000` 不应直接暴露到公网。
|
||
|
||
## 推荐 VPS 配置
|
||
|
||
- 最低：1 核 CPU、1 GB 内存
|
||
- 建议：1-2 核 CPU、2 GB 内存
|
||
- 系统：Debian 或 Ubuntu LTS
|
||
- 磁盘：预留至少 2 GB 给项目、依赖、构建和日志
|
||
|
||
内存较小的 VPS 可以在构建时临时启用 swap，也可以在本地或 CI 构建后只上传 standalone 运行文件。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
MindScope/
|
||
├── app/ # Next.js 页面、布局和全局样式
|
||
├── components/
|
||
│ ├── questionnaire/
|
||
│ │ ├── test/ # 答题流程和部分量表计分器
|
||
│ │ └── result/ # 结果展示
|
||
│ └── ui/ # 通用界面组件
|
||
├── hooks/ # React Hooks
|
||
├── lib/ # 存储、加密、导出、结构化计分等工具
|
||
├── locales/zh/ # 中文界面文本
|
||
├── questionairies/ # 量表题目、说明和元数据
|
||
│ └── zh.ts # 全部量表注册表
|
||
├── types/ # TypeScript 类型定义
|
||
├── middleware.ts # 中文路由处理
|
||
└── next.config.ts # Next.js 配置
|
||
```
|
||
|
||
目录名 `questionairies` 是项目当前使用的历史命名。新增代码应继续沿用，除非一次性完成全项目重命名，避免导入路径不一致。
|
||
|
||
## 测评流程
|
||
|
||
```text
|
||
量表列表
|
||
-> 量表详情
|
||
-> 浏览器答题
|
||
-> 提交时结构化计分
|
||
-> 加密保存记录
|
||
-> 结果展示
|
||
-> 复制完整记录或下载 Markdown
|
||
```
|
||
|
||
每个量表主要由四部分组成：
|
||
|
||
1. `questionairies/<id>/zh.ts`：题目、选项、说明、分类和参考资料。
|
||
2. `components/questionnaire/test/private/*Calculator.tsx`：复杂量表的答案转换和计分。
|
||
3. `lib/scoring-metadata.ts`：量表版本、计分版本、分数范围、反向题、阈值和高分方向。
|
||
4. `components/questionnaire/result/analysis/*Result.tsx`：结果解释与展示。
|
||
|
||
## 新增量表
|
||
|
||
新增量表时建议按以下顺序进行：
|
||
|
||
1. 在 `questionairies/<id>/zh.ts` 定义量表元数据、题目和选项。
|
||
2. 在 `questionairies/zh.ts` 导入并注册量表。
|
||
3. 创建或复用计分逻辑，处理正向题、反向题和维度得分。
|
||
4. 在 `lib/scoring-metadata.ts` 增加结构化计分元数据。
|
||
5. 创建结果组件，展示总分、维度和必要边界说明。
|
||
6. 在 `ResultAnalysis.tsx` 注册结果组件。
|
||
7. 补充或更新 `lib/score-summary.test.ts`。
|
||
8. 运行 `pnpm lint`、`pnpm exec tsc --noEmit`、`pnpm test` 和 `pnpm build`。
|
||
9. 手动完成一次答题，检查草稿恢复、结果计算、历史记录和 MD 导出。
|
||
|
||
量表数据至少应包含：
|
||
|
||
- 稳定唯一的 `id`
|
||
- 中文标题和简介
|
||
- 一级分类与必要标签
|
||
- 题数、预计时间和作答说明
|
||
- 计分方法和维度说明
|
||
- 最低分、最高分、反向题、临界值和高分含义
|
||
- 学术认可度、是否适合重测和建议重测周期
|
||
- 使用注意事项及参考资料
|
||
|
||
## 质量检查
|
||
|
||
提交代码前执行：
|
||
|
||
```bash
|
||
pnpm lint
|
||
pnpm exec tsc --noEmit
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
涉及计分逻辑时，还应人工核对：
|
||
|
||
- 题目编号是否连续且唯一。
|
||
- 正向题与反向题是否正确。
|
||
- 选项值是否与计分器一致。
|
||
- 维度题目数量是否符合预期。
|
||
- 最低分、最高分和临界值是否可达。
|
||
- 旧记录是否能通过版本号正确解释。
|
||
- 趋势页是否正确解释“高分方向”。
|
||
- 刷新结果页和关闭标签页后的行为是否符合隐私设计。
|
||
|
||
## 使用边界
|
||
|
||
- 筛查量表只能提示风险或症状程度，不能单独用于诊断。
|
||
- 不应根据一次测评结果自行停药、换药或改变治疗方案。
|
||
- 不同翻译版本、计分版本和适用人群可能存在差异。
|
||
- 用于正式研究、机构服务或商业场景前，应再次核实量表版本、常模、授权和当地法规。
|
||
- 项目中的结果解释应保持克制，避免把分数描述为确定的人格或疾病结论。
|
||
|
||
## 授权
|
||
|
||
本仓库未附带通用开源许可证。项目代码、量表文本及相关材料的复制、修改、再发布和商业使用，应取得仓库权利人的明确许可。第三方量表仍受其各自适用的版权、商标、授权条款和使用规范约束。
|