Files

T

laoyang 4a5dd19503 docs: 补全 README（功能、结构、部署、使用）

原文只有两行（标题 + 一句话），作为公开仓库的门面信息量不足。
按实际代码补全：功能清单、目录结构、环境要求、数据库初始化与迁移、
Web 服务器与高德配置、后台使用说明。

配置示例统一用 example.com 占位，不含任何开发者个人信息。

2026-09-28 20:18:25 +08:00

4.7 KiB

Raw Blame History

TripLog

家庭旅行日记 —— 把一次旅行的行程、照片、花销、同行人，完整地记录和回看。

以「活动（一次旅行）」为容器，内部按「节点（当天/某一段行程）」串联，每个节点可以带时间地点、交通方式、参与人、照片附件与花销分摊；首页是一张地图，把去过的家和走过的地方标出来。

技术栈：PHP 8 + MySQL，无框架、无 Composer、无前端构建工具。路由自写（index.php?r=控制器/方法），视图为原生 PHP 模板，前端为原生 CSS + JS。

功能

旅行与行程

活动（旅行）的增删改查，支持封面图、起止时间、状态
行程节点：时间、地点（高德选点）、备注，支持「由计划一键成行」
节点交通：出行方式（自驾/高铁/飞机…）+ 车辆，可绑定起终点
一键跳高德导航 / 搜索（服务端与前端共用一处配置，见下文）

记录与协作

照片附件：多图上传、可视化裁剪、当前页灯箱浏览（左右切换）
封面拖拽上传，自动走裁剪
参与人与角色标签（家庭成员角色、当时情绪等）
活动级与节点级评论

花销

只记明细 + 总计，不做预算
分摊到参与人

首页地图

同城活动拥挤时扇形拉出排布，引线带箭头指向真实位置
卡片为「左图右文」方形卡片

存储与基础设施

存储抽象层：本地磁盘 或 阿里云 OSS，后台可切换与自检
媒体代理路由：照片/封面经 media/* 输出，不对外暴露 OSS 地址
站点图标与 PWA 清单（可添加到手机主屏）

目录结构

index.php                入口与路由表（白名单 + 登录拦截）
config.example.php       配置模板（复制为 config.php 使用）
src/
  Database.php           PDO 连接
  Auth.php  Access.php   登录态与权限
  Migrate.php            幂等迁移定义（VERSION 常量）
  Settings.php           站点级键值设置（存储驱动等）
  Storage.php  Oss.php   存储抽象层 / OSS 客户端
  Uploads.php  Attachments.php  Mime.php
  Members.php  Expenses.php  Comments.php
  helpers.php            全局辅助函数（asset()、e()、amap_nav_url() 等）
  Controllers/           各业务控制器
templates/               视图模板（layout.php 为公共骨架）
assets/                  样式、图标、第三方前端库（cropper）
sql/migrations/          SQL 迁移留档
tools/migrate.php        迁移执行入口（仅命令行）
uploads/                 用户上传内容（不入库）

部署

1. 环境要求

PHP 8.x（开发与线上均在 8.1 与 7.4 双版本下做过语法检查与冒烟）
MySQL 5.7+ / 8.0，字符集 utf8mb4
PHP 扩展：pdo_mysql、curl、gd、mbstring、json

2. 取代码与配置

git clone <repo-url> triplog
cd triplog
cp config.example.php config.php

编辑 config.php 填数据库与高德参数。config.php 不入库（含口令），只提交模板。

所有配置项都支持环境变量覆盖（DB_HOST / DB_NAME / AMAP_NAV_SRC 等），便于在不同机器上跑同一份代码。

3. 数据库

创建库与账号（示例）：

CREATE DATABASE trip DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'trip'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON trip.* TO 'trip'@'localhost';

执行结构迁移（幂等，可反复跑）：

php tools/migrate.php            # 执行迁移
php tools/migrate.php --status   # 只看当前版本，不改动

该入口只在命令行可用，被 HTTP 访问时直接返回 404。

4. Web 服务器

把站点根指向项目根目录。Apache 需允许 .htaccess（uploads/ 下有一条禁止执行脚本的规则，不可删除）；Nginx 请自行配置等价规则，并注意 uploads/ 内不得解析 PHP。

确保 uploads/ 对 Web 进程可写。

5. 高德地图

在 config.php 的 amap 段填写：

key —— 服务端接口用
security_js —— 前端 JS API 2.0 的安全密钥
nav_src —— URI API 的调用来源（src）参数，仅用于高德侧来源统计，填任意英数字串都能工作。服务端 amap_nav_url() 与前端表单共用这一个值，只改这一处即可。示例值用 trip.example.com，请替换为你自己的域名。

使用

访问站点根 → 未登录会跳转登录页。首次部署后由管理员在后台创建用户。

后台可维护：用户、活动、节点类型、出行方式、车辆、角色标签、存储设置。

许可

见 LICENSE。

4.7 KiB Raw Blame History Unescape Escape