MovieLog_Server/README.md

# MovieLog_Server · 电影全纪录

一个轻量级的个人/家庭观影记录系统。纯 PHP 编写，使用 SQLite 作为数据库，**无需任何框架、无需 Composer、无需配置数据库服务**，上传到支持 PHP 的空间即可运行。

> 记录每一帧感动 —— 观影记录、影院、同行人、票根与照片，以及属于你的年度观影报告。

---

## 功能特性

### 观影记录管理
- **瀑布流首页**：按观影日期倒序展示所有电影，卡片显示海报、日期、影院（影院专属配色）、同行人头像。
- **添加电影**：支持电影名、剧情简介、观影日期、电影院、同行人、海报、票根、多张观影照片。
- **编辑 / 删除**：编辑页可替换或裁剪已有图片；删除电影时同步清理关联的图片文件。
- **电影详情**：海报大图、基本信息、备注、同行人列表（含头像）、影院信息、影像记录画廊（票根 + 观影照片，点击可查看原图）。

### 图片处理
- **内置裁剪器**：基于 Cropper.js，票根 / 海报 / 观影照片 / 观影人头像均可在浏览器内裁剪后再保存，服务端接收 Base64 图片落盘。
- **多图上传**：观影照片支持一次选择多张。
- **头像兜底**：未上传头像的观影人自动生成"首字母 + 配色"的 SVG 头像，配色由姓名哈希决定，同名同色。
- 上传目录按类型分离：`uploads/posters/`、`uploads/tickets/`、`uploads/photos/`、`uploads/avatars/`。

### 信息辅助
- **OMDb 自动获取**：在添加页输入片名后点击「📡 自动获取」，自动填充年份、类型、片长、导演、主演、IMDb 评分与剧情简介，并预览海报（海报仅供参考，仍需本地上传）。
- **CSV 批量导入**：一次性导入历史数据，自动识别 UTF-8 / GBK / GB2312 编码，自动创建不存在的影院，影院名去重，全程事务保护（出错自动回滚），并输出逐行错误报告。

### 检索与统计
- **首页快捷搜索**：按片名模糊搜索。
- **高级搜索**：片名 + 影院 + 观影人 + 日期区间，多条件组合筛选。
- **统计仪表板**：总览卡片（电影数 / 影院数 / 观影人数 / 观影人次 / 时间跨度），按影院、按观影人、按年份、最近 12 个月的条形图排行。

### 年度报告
- **个性化年度报告**：以「当前登录账号所关联的观影人」为视角生成，而非全站数据。
- **报告内容**：年度观影总数、观影天数、最常去的影院、最常一起观影的人、单场最多人的电影、首末场日期、月均频率、平均间隔天数、备注关键词云、今年共同观影人排行、年末最近观看、年度观影记录墙（含海报与同行人头像）。
- **可视化**：月度观影分布、星期观影偏好（Chart.js 双图），整体为深色"影院感"主题。

### 多用户与权限
- **Session 登录**：`password_hash` / `password_verify` 加盐哈希存储口令，全站页面均需登录。
- **用户管理**：可新增、编辑、删除管理员账号，可修改用户名与密码。
- **账号 ↔ 观影人绑定**：每个管理员账号可关联一个观影人，绑定后即可查看个人年度报告。
- **安全约束**：不允许删除最后一个管理员，也不允许删除自己。
- **个人资料**：修改自己的用户名与密码（需验证旧密码）。

### 基础数据维护
- **影院管理**：增删改查，支持「所在地方 / 影院名称 / 详细地址」三段式信息，内置 50 种预设配色，每个影院可用专属颜色区分；删除已被引用的影院时会给出醒目提示并要求二次确认（关联电影的影院字段将被置空）。
- **观影人管理**：增删改查，支持头像裁剪上传与专属配色；已被电影引用的观影人不允许直接删除。

### 界面与体验
- 复古票根色系（主色 `#e67e22` 橙）的响应式设计，移动端断点适配（600 / 768px）。
- 导航为下拉菜单，自动高亮当前页；顶部始终显示当前用户头像与用户名。
- 登录页为深色渐变 + 毛玻璃风格。

---

## 技术栈

| 项目 | 说明 |
| --- | --- |
| 语言 | PHP（过程式 + PDO） |
| 数据库 | SQLite（`db/movies.db`，首次运行自动建表） |
| 前端 | 原生 HTML / CSS / JavaScript，无构建步骤 |
| 第三方库 | [Cropper.js 1.5.13](https://github.com/fengyuanchen/cropperjs)（图片裁剪）、[Chart.js 4.4.0](https://www.chartjs.org/)（图表），均由 CDN 引入 |
| 外部 API | [OMDb API](http://www.omdbapi.com/)（电影信息查询，需申请 API Key） |

---

## 目录结构

```
MovieLog_Server/
├── config.php              # 引导入口：错误报告、会话、路径常量、上传目录，并加载 lib/ 各模块
├── lib/                    # 功能模块（被 config.php 统一引入，页面无需单独 require）
│   ├── db.php              #   DB 连接、建表、字段与历史数据迁移、默认管理员
│   ├── helpers.php         #   输出转义、文件名、颜色校验、上传/删除文件、图片 URL
│   ├── auth.php            #   登录校验、管理员账号增删改
│   ├── movies.php          #   电影/影院读取、搜索，以及表单关联数据的解析
│   └── stats.php           #   统计仪表板与年度报告查询
├── index.php               # 首页：观影列表（瀑布流）+ 快捷搜索
├── add.php                 # 添加电影
├── edit.php                # 编辑电影
├── detail.php              # 电影详情
├── delete.php              # 删除电影（连带清理图片文件）
├── search.php              # 高级搜索
├── stats.php               # 统计仪表板
├── annual_report.php       # 年度报告
├── cinemas.php             # 影院管理
├── persons.php             # 观影人管理
├── import.php              # CSV 批量导入
├── users.php               # 用户（管理员）管理
├── change_password.php     # 修改自己的用户名/密码
├── login.php               # 登录
├── logout.php              # 退出
├── nav.php                 # 导航栏组件（被各页面 include）
├── fetch_movie.php         # OMDb 代理接口，返回 JSON
├── test_crop.php           # 开发调试页：验证 Base64 图片落盘是否正常
├── css/style.css           # 全局样式
├── js/main.js              # 公共脚本（含各页面共用的表单联动函数）
├── assets/.gitkeep         # 静态占位资源目录
├── db/movies.db            # SQLite 数据库（运行时自动生成，不纳入版本控制）
└── uploads/                # 上传图片（运行时自动生成，不纳入版本控制）
    ├── posters/            # 海报
    ├── tickets/            # 票根
    ├── photos/             # 观影照片
    └── avatars/            # 观影人头像
```

> 页面只需 `require_once 'config.php'`，`lib/` 下的模块会由引导文件统一加载，并保证依赖顺序（db → helpers → auth → movies → stats）。

---

## 数据库结构

建表逻辑集中在 `config.php` 的 `initDB()`，每次请求都会执行 `CREATE TABLE IF NOT EXISTS` 与幂等的 `ALTER TABLE` 迁移，因此**升级代码无需手动改库**。

| 表 | 作用 | 关键字段 |
| --- | --- | --- |
| `admins` | 管理员账号 | `username`（唯一）、`password`（哈希）、`avatar`、`person_id`（关联观影人） |
| `cinemas` | 电影院 | `place`（所在地方）、`name`、`address`、`color`（专属配色） |
| `movies` | 电影记录 | `title`、`info`、`remark`、`poster_path`、`ticket_path`、`photo_path`（历史遗留单图）、`cinema_id`、`watch_date`、`created_at` |
| `persons` | 观影人 | `name`（唯一）、`color`、`avatar` |
| `viewers` | 电影 ↔ 观影人关联 | `movie_id`、`person_id`、`name`（历史遗留字段） |
| `movie_photos` | 电影多图 | `movie_id`、`photo_path`、`created_at` |

外键约束：`movies.cinema_id → cinemas.id`（`ON DELETE SET NULL`）、`viewers.movie_id → movies.id`（`ON DELETE CASCADE`）、`movie_photos.movie_id → movies.id`（`ON DELETE CASCADE`）。

**历史数据迁移**：`initDB()` 会自动把早期版本存在 `viewers.name` 里的姓名去重后写入 `persons`，并回填 `viewers.person_id`，老库可直接升级。

---

## 安装部署

### 环境要求

- PHP 7.4+（推荐 8.x），需启用扩展：`pdo_sqlite`、`fileinfo`、`mbstring`、`curl`
- Web 服务器：Apache / Nginx / PHP 内置服务器均可

### 步骤

1. **放置代码**：将项目文件放到 Web 根目录或其子目录。

2. **确保可写**：保证项目根目录可写，程序会自动创建 `db/` 与 `uploads/` 及其子目录；或手动创建并授权：
   ```bash
   mkdir -p db uploads/posters uploads/tickets uploads/photos uploads/avatars
   chmod -R 755 db uploads
   ```

3. **配置 OMDb API Key**（可选，仅影响「自动获取」功能）：编辑 `fetch_movie.php`，将 `OMDB_API_KEY` 换成你在 [omdbapi.com](http://www.omdbapi.com/apikey.aspx) 申请的免费 Key。

4. **访问站点**：浏览器打开 `login.php`。

5. **首次登录**：数据库为空时会自动创建默认管理员：
   - 用户名 `admin`
   - 密码 `123456`
   > **登录后请立即在「修改密码」中更换。**

### 本地快速运行

```bash
php -S localhost:8000
# 浏览器访问 http://localhost:8000/login.php
```

> 用 PHP 内置服务器时，`config.php` 中 `posterUrl()` 等函数返回的是以 `/` 开头的根路径，建议直接从项目根目录启动，或通过站点根目录访问。

### Nginx 参考配置

```nginx
server {
    listen 80;
    server_name movielog.local;
    root /path/to/MovieLog_Server;
    index index.php;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }
}
```

---

## 使用说明

### 添加一部电影

1. 顶部导航点击「➕ 添加电影」。
2. 输入片名后点「📡 自动获取」可自动填充影片信息（可选）。
3. 填写观影日期（必填）、选择或新建电影院。
4. 「一起看的人」逐行添加：选择已有观影人，或在下拉框中选「➕ 新增」并输入姓名，新姓名会自动进入观影人库。
5. 上传海报（推荐 2:3）；上传票根会弹出裁剪框，裁剪结果以 Base64 提交。
6. 观影照片支持一次多选。
7. 保存后自动跳转到详情页。

### 生成年度报告

年度报告是**按人**生成的，需要先建立账号与观影人的绑定：

1. 进入「用户管理」，找到自己的账号，在「关联观影人」中选择对应的观影人并保存。
2. 进入「年度报告」，页面顶部切换年份即可查看。
3. 未绑定观影人时报告为空并给出提示。

### CSV 批量导入

CSV **共 9 列，顺序固定**：

```
电影名称, 地点(忽略), 电影院名称, 观影日期, 观影人(空格分隔), 电影票图片路径, 海报图片路径, 备注, 合影图片路径
```

- **观影人**：多个姓名用空格分隔，例如 `张三 李四 王五`。
- **图片路径**：可带目录，系统只取最后一个 `/` 后的文件名；若整段被括号包裹（如 `(电影票/阿甘正传.jpg)`），会先取括号内内容再取文件名。
- **观影日期可为空**，空日期的记录会排在列表最后。
- **导入前**需先把图片文件放入 `uploads/tickets/`、`uploads/posters/`、`uploads/photos/`，文件名与 CSV 中提取出的保持一致。
- 编码支持 UTF-8 / GBK / GB2312，自动识别转换。
- 导入在事务中执行，失败会整体回滚；成功后显示「导入 N 条 / 跳过 M 条」及逐行错误原因。

示例行：

```csv
阿甘正传, , 万达影城, 2024-01-15, 张三 李四, (电影票/阿甘正传.jpg), (海报/阿甘正传.jpg), 经典励志片, (合影/阿甘正传.jpg)
```

### 接口：`fetch_movie.php`

供添加页前端调用，服务端代请求 OMDb 避免浏览器跨域。

- **请求**：`GET fetch_movie.php?q=电影名称`
- **响应**：`Content-Type: application/json`
- **成功**：
  ```json
  {
    "title": "Forrest Gump",
    "year": "1994",
    "rated": "PG-13",
    "released": "06 Jul 1994",
    "runtime": "142 min",
    "genre": "Drama, Romance",
    "director": "Robert Zemeckis",
    "actors": "Tom Hanks, Robin Wright, Gary Sinise",
    "plot": "...",
    "poster": "https://...",
    "imdbRating": "8.8"
  }
  ```
- **失败**：`{"error": "错误说明"}`（如「未找到相关电影，请尝试更准确的关键词」）

---

## 安全注意事项

部署到公网前请务必处理以下事项：

1. **修改默认口令**：默认账号 `admin / 123456` 必须在首次登录后立即更换。
2. **更换 OMDb API Key**：`fetch_movie.php` 中当前硬编码的 Key 为开发期临时使用，请替换为你自己的 Key；若仓库需要公开，建议将该值改为从环境变量读取。
3. **删除或保护 `test_crop.php`**：该文件是开发调试页，**没有登录校验**，仅用于验证 Base64 图片能否落盘，生产环境应直接删除。
4. **关闭调试输出**：`config.php` 顶部当前为 `error_reporting(E_ALL)` + `display_errors=1`，上线前请改为关闭或仅写日志，避免泄露路径与数据库信息。
5. **启用 HTTPS 并校正证书校验**：`fetch_movie.php` 中 `CURLOPT_SSL_VERIFYPEER` 被设为 `false`，生产环境应改为 `true`。
6. **保护数据目录**：`db/`（含 `movies.db`）与 `uploads/` 应禁止直接目录列举；SQLite 文件更应通过 Web 服务器规则**拒绝任何 HTTP 访问**。Nginx 示例：
   ```nginx
   location ~ ^/(db|uploads/.*\.(db|sqlite)) { deny all; }
   ```
7. **限制上传目录执行权限**：确保 `uploads/` 下不允许执行 PHP。

---

## 已知限制与待改进

- `movies.photo_path` 与 `viewers.name` 是历史遗留字段，保留用于兼容旧数据与 CSV 导入，新代码统一使用 `movie_photos` 与 `person_id`。
- 除 `delete.php` 通过 GET 触发（带前端 `confirm`）外，其余写操作均为 POST；删除类接口未做 CSRF Token 校验。
- 暂无分页，数据量增大后首页与统计页需要补充分页或懒加载。
- `config.php` 的 `initDB()` 在每次请求都会跑一遍建表与迁移，数据量或并发上升后可改为一次性迁移脚本。
- 无「回收站」，删除电影与其图片文件不可恢复。
- `assets/placeholder-poster.jpg`、`assets/default-avatar.png` 为代码中的兜底引用，当前仓库未包含这两个文件；由于页面在检测到 placeholder 时会改用 CSS 占位块渲染，正常使用不受影响。

---

## 版本控制说明

以下内容为运行时产物或敏感数据，**不纳入版本控制**（见 `.gitignore`）：

- `db/`（SQLite 数据库文件）
- `uploads/`（用户上传的图片）
- `*.log`、编辑器与系统临时文件

---

## 许可

个人项目，未指定开源许可。