diff --git a/README.md b/README.md
index cbdf77a..8642f92 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,136 @@
 # TripLog
 
-家庭旅行记录
\ No newline at end of file
+**家庭旅行日记** —— 把一次旅行的行程、照片、花销、同行人，完整地记录和回看。
+
+以「活动（一次旅行）」为容器，内部按「节点（当天/某一段行程）」串联，
+每个节点可以带时间地点、交通方式、参与人、照片附件与花销分摊；
+首页是一张地图，把去过的家和走过的地方标出来。
+
+技术栈：**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. 取代码与配置
+
+```bash
+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. 数据库
+
+创建库与账号（示例）：
+
+```sql
+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';
+```
+
+执行结构迁移（**幂等，可反复跑**）：
+
+```bash
+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](LICENSE)。