🎭 剧本杀评分系统

基于 Python + Flask + Oracle 的电脑端剧本杀评分、心测匹配与拼车组局平台。

📖 项目简介

本项目是一个面向剧本杀玩家的综合性 Web 平台，提供剧本评分评论、个性化推荐、心理测试匹配（心测）、拼车组局等功能。系统区分普通用户与管理员权限，数据存放在 Oracle 数据库中。

核心功能

模块	功能说明
👤 用户系统	注册 / 登录 / 角色权限（管理员 vs 普通用户）
📜 剧本管理	管理员创建 / 编辑剧本（标题、作者、简介、内容、标签）
⭐ 评分评论	0~10 分评分 + 文字评论，触发器自动维护平均分
🏠 首页推荐	综合「近 7 天点击量 × 0.5 + 平均评分 × 5」排序
🏷️ 分类浏览	按标签筛选剧本（悬疑 / 推理 / 恐怖 / 情感等 16 个标签）
💬 讨论区	按分类发帖 + 回复
🧠 角色心测	嵌入剧本详情页，答题后输出角色适配度排序 + 匹配理由
🌐 全局心测	独立入口，采集题材偏好 / 难度接受度 / 雷点，生成偏好画像并推荐剧本
🚗 拼车车队	创建 / 加入车队，房主可查看成员心测结果辅助分本
🛠️ 管理后台	管理员可管理剧本和用户角色

🛠️ 技术栈

层级	技术
前端	原生 HTML + CSS + JavaScript（SPA 单页应用，无框架依赖）
后端	Python + Flask（RESTful API）
数据库	Oracle（python-oracledb 瘦模式，无需安装 Instant Client）
密码安全	PBKDF2-HMAC-SHA256 加盐哈希（100,000 次迭代）

📁 项目结构

jubensha_rating/
├── app.py                     # 🚀 Flask Web 服务入口（主程序）
├── config.py                  # ⚙️ Oracle 数据库连接配置
├── requirements.txt           # 📦 Python 依赖列表
├── install_deps.bat           # 🔧 环境一键安装脚本
├── 启动.bat                    # 🚀 系统一键启动脚本
│
├── db/                        # 数据库脚本
│   ├── schema.sql             #   主建表脚本（用户/剧本/评分/讨论等）
│   ├── psy_test_schema.sql    #   心测模块建表脚本（角色/心测/拼车）
│   └── connection.py          #   Oracle 连接池管理
│
├── dao/                       # 数据访问层（DAO）
│   ├── user_dao.py            #   用户（注册/登录/角色管理）
│   ├── script_dao.py          #   剧本（增删改查/推荐/搜索）
│   ├── rating_dao.py          #   评分评论
│   ├── category_dao.py        #   标签分类 / 用户兴趣
│   ├── discussion_dao.py      #   讨论区
│   └── psy_test_dao.py        #   心测 + 拼车车队
│
├── models/
│   └── models.py              # 数据模型（dataclass）
│
├── utils/
│   └── security.py            # 密码哈希工具
│
├── static/
│   └── index.html             # 🎨 前端 SPA 页面
│
├── scripts/                   # 数据脚本
│   ├── auto_setup_db.py       #   自动执行主建表脚本
│   ├── seed_data.py           #   填充测试数据（12 剧本 + 8 用户）
│   └── setup_psy_test.py      #   心测建表 + 种子题目
│
├── tools/                     # 辅助工具
│   ├── set_admin.py           #   管理员权限管理（命令行）
│   ├── set_admin.bat          #   管理员权限管理（双击运行）
│   ├── db_diagnose.py         #   数据库连接诊断
│   └── 诊断数据库.bat          #   数据库诊断（双击运行）
│
├── ui/                        # PyQt5 桌面版界面（旧版，已弃用）
│   ├── main_window.py
│   ├── auth_view.py
│   ├── home_view.py
│   └── ... (其他视图)
│
└── main.py                    # PyQt5 桌面版入口（旧版，已弃用）

注意：ui/ 目录和 main.py 是早期的 PyQt5 桌面版代码，当前使用 Web 版（app.py + static/index.html），桌面版保留但不再维护。

🚀 快速开始

前置条件

**Python 3.8+**（已在 3.13 测试）
Oracle 数据库（Oracle 21c 等版本均可），监听端口 1521

三步启动

第 1 步：安装环境

双击运行 install_deps.bat，自动创建虚拟环境并安装所有依赖。

第 2 步：配置数据库

编辑 config.py，填入你的 Oracle 连接信息：

ORACLE_CONFIG = {
    "user":     "system",              # 数据库用户名
    "password": "你的密码",             # 数据库密码
    "dsn":      "localhost:1521/orcl", # 主机:端口/服务名
}

⚠️ 服务名需要与 lsnrctl status 输出中注册的服务名一致，常见的有 orcl、XE、ORCLPDB1 等。

第 3 步：建表 + 填充数据

在命令行执行（任选其一）：

# 方式一：自动建表 + 填充测试数据（推荐）
python scripts/auto_setup_db.py     # 主表
python scripts/seed_data.py         # 测试数据（12 剧本 + 8 用户）
python scripts/setup_psy_test.py    # 心测表 + 种子题目

# 方式二：用 SQL*Plus 手动执行
sqlplus system/密码@localhost:1521/orcl @db/schema.sql
sqlplus system/密码@localhost:1521/orcl @db/psy_test_schema.sql

第 4 步：启动系统

双击运行 启动.bat，浏览器自动打开 http://localhost:5000。

🔑 测试账号

填充测试数据后，可用以下账号登录（密码统一为 123456）：

角色	用户名	权限
👑 管理员	`剧本达人`	全部功能 + 剧本管理 + 用户管理
👤 普通用户	`推理大师` / `情感玩家` / `恐怖爱好者` 等	浏览 / 评分 / 讨论 / 心测 / 拼车

📊 数据库设计

主表（9 张）

表名	说明
`users`	用户（含 role 字段区分管理员）
`scripts`	剧本（含 avg_rating、total_clicks 等统计字段）
`tags`	标签 / 分类（16 个预置标签）
`script_tags`	剧本-标签多对多关联
`user_interests`	用户兴趣标签
`ratings`	评分 + 评论（每用户每剧本一次）
`clicks`	点击记录（用于 7 天热门统计）
`discussions` / `replies`	讨论帖与回复

心测模块表（9 张）

表名	说明
`script_roles`	剧本角色（性格 / 情感 / 雷点标签）
`role_questions` / `role_options`	角色心测题目 + 选项（含 role_weights 权重 JSON）
`role_test_results`	角色心测结果
`global_questions` / `global_options`	全局心测题目 + 选项（题材 / 难度 / 雷点）
`user_profiles`	用户偏好画像
`carpools` / `carpool_members`	拼车车队 + 成员

触发器

trg_rating_after_insert / update：评分变动时自动更新 scripts.avg_rating 和 rating_count
trg_click_after_insert：点击时自动累加 scripts.total_clicks

🔗 API 接口一览

用户模块

方法	路径	说明
POST	`/api/user/register`	注册
POST	`/api/user/login`	登录（返回 role）
GET	`/api/user/<id>`	获取用户信息
GET	`/api/admin/users`	管理员：获取所有用户
PUT	`/api/admin/users/<id>/role`	管理员：设置用户角色

剧本模块

方法	路径	说明
GET	`/api/scripts/recommendations`	首页推荐
GET	`/api/scripts/search?keyword=`	搜索
GET	`/api/scripts/<id>`	剧本详情
POST	`/api/scripts`	🔒 管理员：创建剧本
PUT	`/api/scripts/<id>`	🔒 管理员：修改剧本
GET	`/api/scripts/category/<tag_id>`	按标签浏览
GET	`/api/scripts/all`	全部剧本（管理用）

评分 / 标签 / 讨论区

方法	路径	说明
POST	`/api/ratings`	提交评分
GET	`/api/ratings/script/<id>`	获取评论列表
GET	`/api/tags`	获取所有标签
GET/PUT	`/api/user/interests/<user_id>`	获取/设置兴趣
GET/POST	`/api/discussions`	帖子列表/发帖
GET/POST	`/api/discussions/<id>/replies`	回复列表/回复

心测模块

方法	路径	说明
GET	`/api/psytest/roles/<script_id>`	获取剧本角色
GET	`/api/psytest/role-questions/<script_id>`	获取角色心测题
POST	`/api/psytest/role-test/<script_id>/<user_id>`	提交角色心测
GET	`/api/psytest/global-questions`	获取全局心测题
POST	`/api/psytest/global-test/<user_id>`	提交全局心测
GET	`/api/psytest/profile/<user_id>`	获取偏好画像

拼车车队

方法	路径	说明
POST	`/api/carpools`	创建车队
GET	`/api/carpools`	车队列表
GET	`/api/carpools/<id>`	车队详情（含成员心测）
POST	`/api/carpools/<id>/join`	加入车队
POST	`/api/carpools/<id>/leave`	退出车队
POST	`/api/carpools/<id>/close`	关闭车队
POST	`/api/carpools/<id>/assign`	房主分配角色

🛠️ 管理员权限管理

提供三种方式赋予管理员权限：

自动生成：数据库为空时，第一个注册的用户自动成为管理员

命令行工具：双击 tools/set_admin.bat，或运行：

python tools/set_admin.py                     # 查看所有用户
python tools/set_admin.py 用户名 admin         # 设为管理员
python tools/set_admin.py 用户名 user          # 降为普通用户

网页端管理：管理员登录后，侧边栏「用户管理」页面可视化切换角色

🔧 常见问题

连接数据库失败？

运行 tools/诊断数据库.bat 自动尝试多种 DSN 格式
检查 Oracle 服务是否启动（services.msc 中 OracleService*）
运行 lsnrctl status 确认监听器注册的服务名
确认 config.py 中的 dsn 与监听器服务名一致

启动后页面空白？

确认 Flask 服务正常运行（终端显示 Running on http://127.0.0.1:5000）
打开浏览器控制台查看是否有 JS 报错
确认已执行建表脚本（scripts/auto_setup_db.py）

管理员看不到「剧本管理」？

确认你的账号 role 为 admin（登录后侧边栏用户名旁有金色「管理员」标签）
用 tools/set_admin.bat 将自己设为管理员

中文乱码？

数据库字符集需为 AL32UTF8
浏览器编码设置为 UTF-8（现代浏览器默认）

📝 开发说明

前端：纯 HTML + CSS + JavaScript，无框架依赖，易于维护
后端：Flask RESTful API，DAO 分层架构
密码安全：PBKDF2-HMAC-SHA256 加盐哈希
CORS 已开启：支持前后端分离部署
连接池：oracledb 瘦模式，无需安装 Oracle Instant Client

📄 许可证

MIT License