HGD Love Record / HGD 恋爱记录

A lightweight relationship journal web app with an affection score, timeline, comments, photo memories, countdown cards, and time capsules.

一个轻量级恋爱记录 Web 应用，包含好感度、时间线、评论、回忆相册、倒数日卡片和时间胶囊等功能。

---

Overview / 项目概览

This project is intentionally simple and easy to deploy.

本项目刻意保持简单，方便部署和二次修改。

• Frontend / 前端： frontend/index.html
• Backend / 后端： backend/app.py
• Storage / 存储： local JSON files under backend/data/ / backend/data/ 下的本地 JSON 文件

---

Features / 功能

• Affection score display and adjustment / 好感度展示与调整
• Per-person cooldown for score changes / 每个人独立的好感度调整冷却时间
• Timeline CRUD / 恋爱时间线增删改查
• Optional AI-generated timeline titles and emojis / 可选 AI 生成时间线标题和 emoji
• Public comments on timeline events / 时间线事件公开评论
• Photo upload with basic image-signature validation / 照片上传与基础图片签名校验
• Countdown cards for birthdays, Qixi, and relationship milestones / 生日、七夕和纪念日倒数卡片
• Time capsules with unlock dates / 带解锁日期的时间胶囊
• HMAC-signed session tokens / HMAC 签名会话 token
• Basic CSRF header check and in-memory rate limiting / 基础 CSRF 请求头检查与内存限流

---

Project Structure / 项目结构

.
├── backend/
│   ├── app.py
│   ├── requirements.txt
│   └── data/
│       └── .gitkeep
├── frontend/
│   └── index.html
├── .env.example
├── .gitignore
├── LICENSE
└── README.md

---

Quick Start / 快速开始

1. Create a virtual environment / 创建虚拟环境

cd backend
python -m venv .venv
source .venv/bin/activate

On Windows PowerShell, use:

Windows PowerShell 可使用：

.venv\Scripts\activate

2. Install dependencies / 安装依赖

pip install -r requirements.txt

3. Configure environment variables / 配置环境变量

Copy .env.example to .env, then replace all example keys before deployment. The three keypad keys must be distinct six-digit numbers. The backend loads this project-root .env file automatically; shell environment variables can override it.

复制 .env.example 为项目根目录的 .env，并在部署前替换所有示例密钥。三个数字键盘密钥必须是互不相同的 6 位数字。后端会自动读取这个 .env 文件；shell 环境变量可覆盖其中的值。

export ADMIN_KEY_1="your-first-admin-key"
export ADMIN_KEY_2="your-second-admin-key"
export PUBLIC_KEY="your-public-key"
export HGD_SECRET="a-long-random-secret"

export PERSON1_NAME="Person One"
export PERSON2_NAME="Person Two"
export PERSON1_SHORT="Person1"
export PERSON2_SHORT="Person2"

export RELATIONSHIP_SINCE="YYYY-MM-DD"

4. Configure birthdays / 配置生日

Each person can choose either the solar calendar or the lunar calendar.

每个人都可以单独选择公历生日或农历生日。

# solar or lunar
# 可选值：solar 或 lunar
export PERSON1_BIRTHDAY_CALENDAR="solar"
export PERSON1_BIRTHDAY_MONTH="1"
export PERSON1_BIRTHDAY_DAY="1"

export PERSON2_BIRTHDAY_CALENDAR="lunar"
export PERSON2_BIRTHDAY_MONTH="1"
export PERSON2_BIRTHDAY_DAY="1"

5. Optional AI configuration / 可选 AI 配置

export DEEPSEEK_API_KEY="your-deepseek-api-key"

If DEEPSEEK_API_KEY is not set, the app uses local fallback scoring.

如果未配置 DEEPSEEK_API_KEY，应用会使用本地默认评分逻辑。

6. Run the backend / 运行后端

python app.py

The backend also serves the bundled frontend for local development. After starting it, open:

后端会在本地开发时一并提供前端页面。启动后打开：

http://127.0.0.1:8767

7. Serve behind a reverse proxy / 使用反向代理部署

For production, Nginx or Caddy may serve frontend/index.html directly and proxy /api to Flask. The built-in route is intended for local development.

生产环境可由 Nginx 或 Caddy 直接托管 frontend/index.html，并把 /api 转发到 Flask；内置首页路由主要用于本地开发。

---

Deployment / 部署

Recommended deployment shape:

推荐部署结构：

Browser / 浏览器
  ↓
Nginx / Caddy
  ├── /      -> frontend/index.html
  └── /api/  -> http://127.0.0.1:8767/api/

The backend stores runtime JSON data in backend/data/. Make sure this directory is writable by the backend process.

后端会把运行时 JSON 数据存储在 backend/data/ 中，请确保后端进程对该目录有写入权限。

---

Environment Variables / 环境变量

Variable / 变量	Description / 说明	Example / 示例
ADMIN_KEY_1	First admin keypad key (six digits) / 第一个管理员 6 位数字密钥	111111
ADMIN_KEY_2	Second admin keypad key (six digits) / 第二个管理员 6 位数字密钥	222222
PUBLIC_KEY	Guest/public keypad key (six digits) / 访客或公开 6 位数字密钥	333333
HGD_SECRET	HMAC token signing secret / HMAC token 签名密钥	a-long-random-secret
PERSON1_NAME	Display name for first person / 第一个人的展示名	Person One
PERSON2_NAME	Display name for second person / 第二个人的展示名	Person Two
PERSON1_SHORT	Short name for score history and cooldown / 第一个人的短名	Person1
PERSON2_SHORT	Short name for score history and cooldown / 第二个人的短名	Person2
RELATIONSHIP_SINCE	Relationship start date / 关系开始日期	YYYY-MM-DD
PERSON1_BIRTHDAY_CALENDAR	Birthday calendar for person 1 / 第一个人的生日历法	solar or lunar
PERSON1_BIRTHDAY_MONTH	Birthday month for person 1 / 第一个人的生日月份	1
PERSON1_BIRTHDAY_DAY	Birthday day for person 1 / 第一个人的生日日期	1
PERSON2_BIRTHDAY_CALENDAR	Birthday calendar for person 2 / 第二个人的生日历法	solar or lunar
PERSON2_BIRTHDAY_MONTH	Birthday month for person 2 / 第二个人的生日月份	1
PERSON2_BIRTHDAY_DAY	Birthday day for person 2 / 第二个人的生日日期	1
DEEPSEEK_API_KEY	Optional DeepSeek API key / 可选 DeepSeek API 密钥	empty / 空

---

License / 许可证

MIT License. See LICENSE for details.

本项目使用 MIT 许可证，详见 LICENSE 文件。