拾光手账 · Trace

用脚步丈量世界，用手账记录时光

一款基于地图的生活手账应用，记录您到访的每一个地点与每一段美好时光

• 项目简介
• 功能特性
• 技术栈
• 支持平台
• 快速开始
  • 环境要求
  • 方式一：HBuilderX（推荐）
  • 方式二：CLI 命令行
  • 项目结构
• 使用指南
  • 地图视图
  • 创建手账
  • 浏览与搜索
  • 数据统计
  • 主题与设置
• 设计规范
• 数据模型
• 配置说明
• 常见问题
• 路线图
• 贡献指南
• 许可证

拾光手账 (Trace) 是一款以地图为核心的生活记录应用。它将您的足迹与手账紧密结合，让每一次出行、每一个到访的地点都能留下可追溯的美好记忆。

无论是��行途中的风景、街角偶然发现的咖啡店，还是每日通勤路上的小确幸，都可以通过拾光手账以图文并茂的方式记录下来，并在地图上直观地呈现您的生活轨迹。

• 🗺️ 地图优先 — 以空间视角组织记忆，让记录有迹可循
• 📔 手账为体 — 丰富的图文表达，还原生活温度
• 🔒 本地优先 — 数据存储在设备本地，隐私安全可控
• 🎨 温暖设计 — 柔和的视觉风格，愉悦的使用体验

• 多维度搜索：支持标题、内容、地点名、标签全字段匹配
• 实时响应：输入即时反馈，搜索结果秒级呈现
• 高亮匹配：搜索结果直观展示匹配位置

• 资料管理：昵称、头像、简介、城市、生日个性化设置
• 数据概览：手账数、地点数、照片数一目了然
• 设置中心：通知开关、主题切换、数据备份与恢复

• 双模式支持：浅色 / 深色模式自由切换
• 统一管理：通过主题 Mixin + CSS 变量统一管控
• 自动适配：文字、图标、背景等 UI 元素智能适配
• 丝滑过渡：模式切换附带平滑过渡动画

💡 提示：地图功能在 App 端体验最佳；H5 端可使用基础手账管理功能。

HBuilderX 是 DCloud 官方 IDE，对 uni-app 项目提供最佳支持，开箱即用。

步骤：

1. 安装 HBuilderX

   • 前往 HBuilderX 官网 下载安装
   • 安装时选择「App 开发版」以获得完整插件支持

2. 获取项目代码

   git clone https://github.com/your-username/trace.git
   cd trace

3. 安装依赖

   npm install

4. 导入项目

   • 打开 HBuilderX
   • 选择「文件」→「导入」→「从本地目录导入」
   • 选择项目根目录 trace/

5. 运行项目

   目标平台	操作路径
   微信小程序	运行 → 运行到小程序模拟器 → 微信开发者工具
   App (Android)	运行 → 运行到手机或模拟器 → 运行到 Android App 基座
   App (iOS)	运行 → 运行到手机或模拟器 → 运行到 iOS App 基座
   H5	运行 → 运行到浏览器 → 选择浏览器
   支付宝小程序	运行 → 运行到小程序模拟器 → 支付宝小程序开发者工具

6. 配置地图 Key（App 端必需）

   首次运行 App 端前，请参考 配置说明 - 地图配置 配置高德地图 Key，否则地图功能无法使用。

如果您习惯使用命令行工具，可以使用 @dcloudio/uni-cli 进行开发。

步骤：

1. 安装 uni-app CLI（全局）

   npm install -g @dcloudio/uni-cli

2. 克隆并安装依赖

   git clone https://github.com/your-username/trace.git
   cd trace
   npm install

3. 开发模式运行

   # 微信小程序
   npm run dev:mp-weixin
   
   # H5
   npm run dev:h5
   
   # App
   npm run dev:app-plus
   
   # 支付宝小程序
   npm run dev:mp-alipay

4. 生产构建

   # 微信小程序
   npm run build:mp-weixin
   
   # H5
   npm run build:h5
   
   # App
   npm run build:app-plus

⚠️ 注意：CLI 方式需要在 package.json 中配置对应的脚本。如使用 HBuilderX 方式可忽略此步骤。

成功运行后，您将看到：

• 首页（地图视图）：显示地图界面与底部 Tab 导航
• 手账页：显示空状态提示，可点击新建手账
• 统计页：显示零数据状态
• 我的页：显示默认用户资料

Trace/
├── components/               # 可复用组件
│   ├── DeleteModal.vue       # 删除确认弹窗
│   ├── EmptyState.vue        # 空状态组件
│   ├── Icon.vue              # SVG 图标组件
│   ├── ImageCropper.vue      # 图片裁剪组件
│   ├── MoodSelect.vue        # 心情选择器
│   ├── PageHero.vue          # 详情页顶部 Hero 区域
│   ├── PhotoUpload.vue       # 照片上传组件
│   ├── StarRating.vue        # 星级评分组件
│   └── TabBar.vue            # 底部导航栏
├── constants/                # 业务常量统一出口
│   ├── cover.js              # 封面色调（5 种色调 + 描边色 + 随机分配）
│   ├── icons.js              # 图标 SVG path 常量（与 Icon 组件 name 对应）
│   ├── index.js              # 统一导出入口（@/constants 即可全量导入）
│   ├── mood.js               # 心情 emoji 列表与色值映射
│   └── rating.js             # 评分维度定义与综合评分计算
├── mixins/                   # Vue Mixin
│   ├── statusbar.js          # 状态栏高度获取（自定义导航栏占位）
│   ├── theme.js              # 主题切换（浅色/深色模式 + 主题色计算属性）
│   └── timers.js             # 定时器统一管理（页面/组件销毁时自动清理）
├── pages/                    # 页面目录
│   ├── index/                # 首页（地图视图）
│   ├── journal/              # 手账列表
│   ├── journal-detail/       # 手账详情
│   ├── journal-edit/         # 编辑/新建手账（含 save-helpers 纯函数 + 单测）
│   ├── location-detail/      # 地点详情
│   ├── profile/              # 个人中心
│   ├── profile-edit/         # 编辑资料
│   ├── search/               # 搜索页
│   └── stats/                # 统计页
├── store/                    # Pinia 状态管理
│   ├── journal.js            # 手账数据 Store
│   ├── location.js           # 地点数据 Store
│   └── profile.js            # 用户资料 Store
├── utils/                    # 工具函数
│   ├── date.js               # 日期处理
│   ├── image.js              # 图片处理
│   ├── nav.js                # 导航工具（safeBack 安全返回上一页）
│   ├── permission.js         # 权限被拒引导（定位/相机/相册跨端处理）
│   └── storage.js            # 本地存储封装（含备份/恢复/数据迁移）
├── static/                   # 静态资源（图片、图标等）
├── androidPrivacy.json       # Android 隐私协议
├── App.vue                   # 应用入口组件（数据迁移 + 草稿自动保存）
├── index.html                # H5 入口模板
├── main.js                   # 主入口文件（Pinia 装配）
├── manifest.json             # 应用配置与平台参数
├── package-lock.json         # 依赖版本锁定
├── package.json              # 项目依赖与脚本
├── pages.json                # 页面路由配置
├── uni.promisify.adaptor.js  # Promise 化适配器
└── uni.scss                  # 全局样式变量

💡 目录职责补充说明

• constants/ — 集中管理业务常量（心情、评分维度、封面色调、图标 SVG），避免在多处硬编码导致不一致。index.js 为统一出口，业务代码可 import { MOODS, RATING_DIMENSIONS, COVER_COLORS } from '@/constants' 一次性导入。
• mixins/ — 抽取跨页面/组件复用的通用逻辑：theme.js 提供主题切换与主题色计算属性、statusbar.js 用于自定义导航栏的状态栏占位、timers.js 用于统一清理 setTimeout 防止内存泄漏。

地图视图是应用的首页，也是您探索记录的入口。

操作说明：

1. 查看地点：在地图上滑动浏览，彩色标记即为您记录过的地点
2. 查看详情：点击地图标记，弹出地点信息卡片，再次点击进入地点详情页
3. 定位当前位置：点击右下角定位按钮，地图将移动到您的当前位置
4. 搜索地点：点击顶部搜索栏，输入关键词搜索已记录的地点
5. 新建手账：点击底部「+」按钮，快速创建一条新的手账记录

💡 小技巧：长按地图上的某个位置，可以快速在该地点创建手账。

操作步骤：

1. 点击底部 Tab 中间的「+」按钮，或在手账列表页点击「新建」
2. 选择地点：
   • 方式一：自动获取当前位置作为记录地点
   • 方式二：在地图上手动选择位置
   • 方式三：从已有地点中选择
3. 填写内容：
   • 输入手账标题
   • 填写详细内容
   • 上传照片（支持多张，可裁剪）
   • 选择心情 emoji
   • 进行四维度评分
   • 添加自定义标签
4. 点击「保存」完成创建

评分系统说明：

手账列表：

• 按时间倒序展示所有手账
• 顶部可切换筛选条件（全部 / 最近 / 有照片）
• 点击手账卡片进入详情页
• 在手账详情页可编辑或删除

搜索功能：

1. 点击首页顶部搜索栏或 Tab 中的「搜索」
2. 输入关键词，实时显示匹配结果
3. 搜索范围包括：标题、内容、地点名称、标签
4. 点击搜索结果直接跳转到对应详情

在「统计」页面，您可以查看：

• 本月数据：本月新增的手账数、地点数、照片数
• 月度趋势图：最近 12 个月的记录数量变化
• 心情分布：各种心情的占比统计
• 连续记录：最长连续打卡天数
• 累计数据：手账总数、地点总数、照片总数

💡 建议：坚持记录，连续打卡天数会给您意想���到的成就感！

切换主题：

1. 进入「我的」页面
2. 找到「设置」→「主题模式」
3. 选择「浅色」或「深色」模式
4. 切换即时生效

数据备份与恢复：

1. 进入「我的」→「设置」→「数据备份」
2. 点击「创建备份」，系统将打包所有数据
3. 需要恢复时，点击「恢复备份」即可还原数据

⚠️ 重要：备份数据存储在本地，卸载应用会一并清除。建议定期导出备份文件。

⚠️ SCSS 与 CSS 变量命名遗留说明

项目中存在 SCSS 变量（uni.scss）与 CSS 变量（App.vue）两套体系，二者主/辅色命名不一致，使用时请以颜色值为准，避免混淆：

颜色值	SCSS 变量	CSS 变量	含义
#E09080（橙红）	$accent / $seed-primary	--primary	主色
#7FA3C8（蓝）	$accent-secondary / $seed-accent	--accent	辅色

关键差异：SCSS 的 $accent 指主色（橙红），而 CSS 的 --accent 指辅色（蓝），两者同名但含义不同，属历史命名遗留。新增样式时建议直接使用 $seed-primary / $seed-accent，避免歧义。

共 5 种色调，用于照片加载前的占位展示，按地点随机分配：

• 🎯 温暖的卡片式设计风格，亲和力强
• 🔶 柔和的圆角体系（24-36rpx），圆润舒适
• ✨ 丰富的视觉反馈与微动效
• 🌓 浅色 / 深色模式完整支持
• 📱 自定义导航栏（navigationStyle: custom），沉浸式体验

Store 位置：store/journal.js

interface Journal {
  id: string              // 唯一标识，格式: jour_xxxxx
  locationId: string      // 关联地点 ID
  locationName: string    // 地点名称（冗余存储，便于列表展示）
  title: string           // 手账标题
  content: string         // 手账正文内容
  photos: string[]        // 照片路径数组（本地临时路径）
  mood: string            // 心情 emoji
  ratings: {
    environment: number   // 环境评分 1-5
    scenery: number       // 景色评分 1-5
    transport: number     // 交通评分 1-5
    experience: number    // 体验评分 1-5
  }
  overallRating: number   // 综合评分（四维度平均值，保留一位小数）
  tags: string[]          // 自定义标签数组
  createdAt: string       // ���建时间（ISO 格式字符串）
  updatedAt: string       // 更新时间（ISO 格式字符串）
}

主要 Getter：

注：getJournal / getJournalsByLocation / photosByLocation / search 采用 curried getter 形式声明（store.fn(arg) 调用语法与 action 一致，但语义为只读、不触发 mutation）。

主要 Action：

Store 位置：store/location.js

interface Location {
  id: string              // 唯一标识，格式: loc_xxxxx
  name: string            // 地点名称
  address: string         // 详细地址
  latitude: number        // 纬度
  longitude: number       // 经度
  coverColor: CoverColor  // 封面色调（warm/blue/lavender/green/gold）
  visitCount: number      // 访问次数
  lastVisitDate: string   // 最近访问日期
  journalCount: number    // 关联手账数量
  photoCount: number      // 关联照片数量
  createdAt: string       // 创建时间
}

type CoverColor = 'warm' | 'blue' | 'lavender' | 'green' | 'gold'

主要 Getter：

注：getLocation / search 采用 curried getter 形式声明。

主要 Action：

Store 位置：store/profile.js

interface Profile {
  nickname: string        // 昵称，默认 "小鹿同学"
  bio: string             // 个人简介
  city: string            // 所在城市
  birthday: string        // 生日
  avatar: string          // 头像路径
}

interface Settings {
  notifications: boolean  // 通知开关
  theme: 'light' | 'dark' // 主题模式
  backup: boolean         // 自动备份开关
  onboarded: boolean      // 首启引导是否已完成（首次启动后置 true，后续不再展示）
}

主要 Action：

💡 跨 Store 协作说明：profile 页面展示的「手账数 / 地���数 / 照片数」并非 profile store 的 getter，而是页面层直接调用 journalStore.totalCount / locationStore.totalCount / journalStore.totalPhotos 组合得到。

在 manifest.json 中配置应用基础信息：

本项目使用高德地图（Amap）SDK，App 端必须配置 Key 才能使用地图功能。

获取高德 Key：

1. 前往 高德开放平��� 注册并创建应用
2. 添加「Android 平台」和「iOS 平台」的 Key
3. 分别获取两个平台的 AppKey

配置位置：manifest.json → app-plus → distribute → sdkConfigs

{
  "app-plus": {
    "modules": {
      "Maps": {}
    },
    "distribute": {
      "sdkConfigs": {
        "maps": {
          "amap": {
            "appkey_ios": "your-ios-amap-key",
            "appkey_android": "your-android-amap-key"
          }
        },
        "geolocation": {
          "amap": {
            "__platform__": ["ios", "android"],
            "appkey_ios": "your-ios-amap-key",
            "appkey_android": "your-android-amap-key"
          }
        }
      }
    }
  }
}

Android 权限（已内置配置）：

在 manifest.json → mp-weixin 中配置：

示例：

{
  "mp-weixin": {
    "appid": "your-wechat-appid",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "minified": true
    },
    "usingComponents": true,
    "permission": {
      "scope.userLocation": {
        "desc": "你的位置信息将用于地图显示和地点记录"
      }
    }
  }
}

在 pages.json 中配置页面路由与全局样式。完整页面列表请参考 项目结构。

全局样式配置：

可能原因及解决方案：

1. 未配置高德地图 Key

   • 检查 manifest.json 中 sdkConfigs.maps.amap 是否正确配置
   • 确认 Key 与应用包名/签名匹配

2. 网络问题

   • 检查设备网络连接
   • 确认高德地图服务是否可用

3. 定位权限未开启

   • 在系统设置中检查应用定位权限
   • 确认已授权「始终允许」或「使用时允许」

4. H5 端限制

   • H5 端地图功能有限，建议使用 App 端或小程序端

• 本应用数据存储在设备本地（uni.setStorageSync）
• 卸载应用、清除缓存会导致数据丢失
• 建议定期使用「数据备份」功能
• 未来版本将支持云端同步

目前版本暂不支持直接导出文件。您可以：

1. 使用「数据备份」功能在本地保存一份副本
2. 如需迁移数据，可通过手机备份 / 还原功能操作
3. 后续版本将支持 JSON / CSV 格式导出

支持的格式：JPG、PNG、WEBP（取决于平台支持）

• 单张图片建议控制在 5MB 以内
• 最多支持 9 张图片 / 手账
• 图片支持裁剪后上传

路径：「我的」→「设置」→「主题模式」→ 选择「深色」

切换后即时生效，所有页面自动适配深色配色。

每个手账最多添加 10 个标签，标签总数量没有限制。 建议标签简洁明了，便于搜索和分类。

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库

   git clone https://github.com/your-username/trace.git
   cd trace

2. 创建特性分支

   git checkout -b feature/AmazingFeature

3. 提交更改

   git commit -m "Add some AmazingFeature"

4. 推送到分支

   git push origin feature/AmazingFeature

5. 提交 Pull Request

• 使用 ES6+ 语法，遵循 Vue 3 风格指南
• ���件命名使用 PascalCase
• 文件名使用 kebab-case（组件除外）
• 提交信息遵循 Conventional Commits 规范

提交 Issue 时请包含：

• 运行平台（微信小程序 / App / H5 等）
• 系统版本与设备型号
• 详细的复现步骤
• 预期行为与实际行为
• 截图或录屏（如有）

本项目采用 GPL-3.0 许可证 - 详见 LICENSE 文件。

• UniApp - 优秀的跨平台开发框架
• Vue.js - 渐进式 JavaScript 框架
• Pinia - 直观的 Vue 状态管理
• 高德地图 - 专业的地图服务平台
• Sass - 强大的 CSS 扩展语言