# 🍽️ Tipping Study - 小费研究实验 基于 **oTree** 框架构建的多轮服务小费行为研究实验平台，用于研究顾客与服务员之间的小费决策机制。 --- ## 📋 项目概述 本项目是一个行为经济学实验，旨在研究不同**薪酬模式**下顾客对服务员的小费行为差异。实验采用"餐厅服务场景"模拟，参与者被随机分配为 **Worker（服务员）** 或 **Customer（顾客）** 角色，通过多轮交互完成实验。 ### 核心研究问题 - 服务员固定工资 vs 绩效工资如何影响顾客给小费的意愿？ - 事前小费（Pre-tip） vs 事后小费（Post-tip）的行为差异？ - 社会规范（tipping norms）对小费行为的影响？ --- ## 🧪 实验设计 ### 薪酬类型（Treatment Conditions） | 条件名称 | 描述 | |---------|------| | **Fixed_wage** | 服务员获得高于行业标准的固定工资（200 tokens），顾客无需支付额外费用 | | **Service_charge** | 服务员获得标准工资（160 tokens）+ 固定服务费（40 tokens） | | **Pre_tip** | 服务员获得标准工资，顾客在服务开始前决定小费金额 | | **Post_tip** | 服务员获得标准工资，顾客在服务结束后决定小费金额 | ### 小费规范变体 - `present`：明确告知参与者小费社会规范 - `absent`：不告知小费规范 --- ## 🏗️ 项目结构 ``` tipping_study_FirstDraft/ ├── settings.py # oTree 全局配置与会话定义 ├── requirements.txt # Python 依赖 ├── Procfile # Heroku 部署配置 ├── db.sqlite3 # 本地开发数据库 │ ├── consent_intro/ # 知情同意与实验介绍模块 │ ├── __init__.py # 页面逻辑与角色分配 │ ├── ret_functions.py # 解码任务函数 │ └── *.html # 页面模板（Screen1 - Screen13） │ ├── practice_rounds2/ # 练习轮模块 │ ├── __init__.py # 练习任务逻辑 │ ├── ret_functions.py # 解码任务函数 │ └── *.html # 练习页面模板 │ ├── main_tasks/ # 主任务模块（核心实验） │ ├── __init__.py # 小费决策与解码任务逻辑 │ ├── ret_functions.py # 解码任务函数 │ └── *.html # 主任务页面模板（Screen20 - Screen32） │ ├── post_experiment/ # 实验后调查问卷 │ ├── __init__.py # 问卷逻辑与人口统计 │ └── *.html # 问卷页面模板 │ ├── _static/ # 静态资源（CSS、JS、图片） ├── _templates/ # 共享页面模板 └── ret_modules/ # 共享函数模块 ``` --- ## 🚀 快速开始 ### 1. 环境准备 ```bash # 创建虚拟环境 python -m venv .venv # 激活虚拟环境 source .venv/bin/activate # macOS/Linux # 或 .venv\Scripts\activate # Windows # 安装依赖 pip install -r requirements.txt ``` ### 2. 本地运行 ```bash # 启动开发服务器 otree devserver # 访问 http://localhost:8000 ``` ### 3. 重置数据库 ```bash otree resetdb # ⚠️ 警告：这将清空所有实验数据 ``` --- ## 🎮 实验流程 ### 完整会话流程 ``` consent_intro → practice_rounds2 → main_tasks → post_experiment ``` ### 各模块功能 | 模块 | 功能 | 关键页面 | |------|------|---------| | `consent_intro` | 知情同意、实验介绍、角色分配、理解检测 | 13 个页面 | | `practice_rounds2` | 解码任务练习 | 3 个页面 | | `main_tasks` | 主实验（2轮）：小费决策、解码任务、收益反馈 | 13 个页面 | | `post_experiment` | 实验后问卷与人口统计 | 10 个页面 | ### 实验参数（Constants） | 参数 | 值 | 描述 | |------|-----|------| | `FixedWage` | 200 | 固定工资（高于标准） | | `WageStandard` | 160 | 标准工资 | | `ServiceCharge` | 40 | 服务费 | | `SatisfactionRate` | 200 | 满意度系数（每完成一个任务） | | `CustomerBase` | 60 | 顾客基础收益 | | `task_time` | 20秒 | 解码任务时间 | | `NUM_ROUNDS` | 2 | 主任务轮数 | --- ## 📊 数据导出 主任务模块提供自定义数据导出功能，包含以下字段： ``` session_code, participant_code, round_number, role, effort, satisfaction, tip_amount, payoff, cumulative_payoff ``` --- ## ⚙️ 配置说明 ### 会话配置示例 (`settings.py`) ```python dict( name='Pre_tip_present', display_name='Pre_tip_present', num_demo_participants=2, app_sequence=['consent_intro', 'practice_rounds2', 'main_tasks', 'post_experiment'], compensation_type='Pre_tip', tipping_norms='present' ) ``` ### 环境变量 | 变量 | 描述 | |------|------| | `OTREE_ADMIN_PASSWORD` | 管理员密码（生产环境必须设置） | --- ## 🧪 测试 ```bash # 运行所有 App 的测试 otree test consent_intro practice_rounds2 main_tasks post_experiment # 功能测试：本地开两个浏览器窗口，模拟双人参与 ``` --- ## 🚢 生产部署 ```bash # Heroku 部署流程参考 Procfile otree prodserver1of2 otree prodserver2of2 ``` > ⚠️ **安全提醒**： > - 生产环境必须设置 `OTREE_ADMIN_PASSWORD` 环境变量 > - 使用 PostgreSQL 替代 SQLite > - `db.sqlite3` 不应作为生产数据库 > - 敏感配置通过环境变量注入，勿写入代码仓库 --- ## 📝 代码规范 - **Python**：遵循 PEP 8，4 空格缩进，`snake_case` 命名 - **模板**：文件名小写加下划线 - **注释**：使用中文注释解释业务规则 - **提交**：格式 `type(scope): summary`，如 `feat(main_tasks): 调整小费展示` --- ## 📚 技术栈 - **框架**：[oTree](https://www.otree.org/) (≥5.0.0) - **数据库**：SQLite（开发） / PostgreSQL（生产） - **部署**：Heroku / 自建服务器 --- ## 📄 许可证 本项目为学术研究实验，仅供研究使用。 --- ## 🤝 贡献指南 1. Fork 本项目 2. 创建特性分支 (`git checkout -b feature/xxx`) 3. 提交变更 (`git commit -m 'feat(scope): 描述'`) 4. 推送分支 (`git push origin feature/xxx`) 5. 创建 Pull Request --- > 💡 **提示**：如需了解更多开发规范，请参阅 [AGENTS.md](./AGENTS.md)