Skip to content
zoujindouGithubPublic

About

豆芽待办。简单、好用

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

豆芽待办 · Douya Todo

WeChat MiniProgram Node.js Tests License

轻量、现代、零后端依赖的纯本地存储微信小程序待办工具 A modern, lightweight, and zero-backend-dependency to-do WeChat Mini-Program with offline-first local storage.

中文说明 | English Documentation


📖 中文说明

🌟 项目简介

豆芽待办(Douya Todo) 是一款基于原生微信小程序框架构建的现代化待办管理工具。 项目坚持离线优先(Offline-First)与极简零依赖设计哲学,数据全部持久化存储在手机端微信本地缓存(wx.setStorageSync),不依赖微信云开发、不依赖任何外部服务器或数据库,完全无需服务器费用,点开即用,隐私安全。


✨ 核心功能与交互亮点

  1. 半屏模态抽屉(Bottom-Sheet Modal)
    • 告别传统多页面跳转:点击右下角悬浮按钮(FAB)或点击已有待办卡片,即可在当前页面滑出半屏轻量抽屉;
    • 容器尺寸自适应,坚决零滚动(Zero Scrolling),在方寸之间完成标题、描述、紧急度与日期的快速录入。
  2. 待办截止日期紧迫度分级(越近越醒目)
    • 告别传统千篇一律的红色警示,按自然日天数差($\Delta \text{Days}$)呈现多层次感知:
      • 已逾期:强警示深红(#e5484d / 淡红底加粗),展示具体逾期天数;
      • 今天截止:炽烈橙红(#e03e1a / 暖粉底加粗),今日事今日毕;
      • 明天截止:暖橙黄色(#d97706 / 淡黄底),提前预警;
      • 2~3天内:活力雅致蓝(#2563eb / 浅蓝底),清晰温和;
      • 远期日期:平静中性灰(#6b7280 / 浅灰底),降低视觉噪音;
      • 已完成:极低对比淡灰(#9ca3af),沉静归档。
  3. GTD 智能多维加权排序算法
    • 逾期事项最高优先级置顶:越早逾期越靠前,第一时间火警提醒;
    • 今日与近期待办顺承排列:结合优先级高低(高 > 中 > 低)有序梯队调度;
    • 已完成项优雅沉底:勾选后自动下沉,并按完成时间倒序排列。
  4. 大热区高意会性语义复选框
    • 外框升级为 $48\text{rpx}$ 精致圆角方框,未勾选状态下自带浅灰线稿对勾(✓),明确传达“点此打勾”的视觉意会暗示;
    • 外部包裹 $84\text{rpx} \times 84\text{rpx}$ 独立判定热区,杜绝误触卡片正文;
    • 点击伴随微信马达轻微触感震动(wx.vibrateShort)与回弹微动效,多巴胺反馈感十足。
  5. 卡片左滑操作抽屉(Swipe-Action Drawer)
    • 列表卡片支持指尖向左轻滑,平滑展开宽度为 $280\text{rpx}$ 的操作栏;
    • 内置翠绿「完成 / 恢复」按钮与警示红「删除」按钮;
    • 具备手势正交防冲突判定(不卡纵向滚动)与排他性展开机制(滑动新卡片自动复位旧卡片)。
  6. 手机系统日历强提醒与防重机制(无需云端提醒服务)
    • 保存待办时可通过 wx.addPhoneCalendar 添加系统日程,并请求到时提醒;不申请微信订阅消息。
    • 默认使用设备本地时间的截止日 09:00;若已过该时间,顺延至当前时间十分钟后。
    • TAP 手势失效彻底解决:用户开启日历开关时立即前置触发微信官方隐私保护授权弹窗(利用开关自身的 TAP 手势),避免保存时隐私弹窗打断微信对 wx.addPhoneCalendar 的直接手势约束(彻底规避 can only be invoked by user TAP gesture 报错);授权被拒时自动回退开关并轻提示。
    • 清晰状态标记与防重保护:
      • 待办列表卡片配备浅蓝底高对比度「已加日历」胶囊徽标,状态一目了然;
      • 编辑抽屉展示专属「已添加到手机日历」绿色状态条与系统日历操作指引;
      • 编辑时开关文案智能变更为「再次添加到手机日历」且默认关闭;若用户主动开启,强制弹出二次确认弹窗防误触与重复创建。
    • 日历添加失败不影响本地待办保存;手势丢失时给出贴心重试引导,不再向用户抛出晦涩英文报错。已有日程的修改或删除需在系统日历操作。
  7. Per-Commit 代码质量预提交门禁系统
    • 本地内置 6 道全自动门禁脚本(scripts/quality-gate.js)与 Git pre-commit 钩子:
      • [1/6] JS 语法静态扫描 (node --check)
      • [2/6] 全量 JSON 配置文件有效性校验
      • [3/6] WXML 模板标签闭合完整性校验(彻底杜绝漏写 </view> 等编译崩溃)
      • [4/6] 小程序配置健全性校验(路由存在性、按需注入、打包排除规范)
      • [5/6] 自动化核心数据层与排序算法单元测试套件
      • [6/6] 代码包单文件体积限制($\le 200\text{KB}$)

📂 项目目录结构

.
├── app.js                     # 小程序全局生命周期与断网重试监听
├── app.json                   # 小程序全局页面路由与窗口配置(开启 lazyCodeLoading)
├── app.wxss                   # 全局基础样式与调色板变量
├── project.config.json        # 微信开发者工具工程配置(已配置打包/监听过滤)
├── project.miniapp.json       # 多端框架配置
├── sitemap.json               # 微信索引规则
├── config/                    # 配置文件(模板 ID、云环境解耦配置)
│   ├── subscribe.js
│   └── subscribe.example.js
├── cloudfunctions/           # 轻量云函数(免后端服务器)
│   └── todoReminder/          # 定时下发与发完即焚云函数
├── pages/
│   ├── index/                 # 主页:待办列表、左滑抽屉、半屏编辑模态框
│   │   ├── index.js
│   │   ├── index.json
│   │   ├── index.wxml
│   │   └── index.wxss
│   └── edit/                  # 独立全屏编辑备用页(历史兼容)
├── utils/
│   ├── todo.js                # TodoManager 数据访问层封装(单例、本地缓存 CRUD)
│   ├── date-helper.js         # 日期紧迫度计算、状态分级与智能排序纯函数工具
│   ├── calendar.js            # 手机系统日历强提醒助手(零费用、离线响铃)
│   └── subscribe.js           # 微信订阅消息客户端授权与离线重试同步助手
│   └── quality-gate.js        # 6 道代码质量预提交门禁脚本
├── tests/
│   ├── datastore.test.js      # 本地数据存储与 CRUD 契约单测 (42 项断言)
│   ├── smart-sort.test.js     # 紧迫度分级与 GTD 智能排序算法专项单测
│   ├── calendar.test.js       # 手机系统日历助手专项单测
│   └── subscribe.test.js      # 订阅消息与离线队列容错专项单测
│   └── pre-commit             # Git 提交前自动触发门禁的 Hook
├── LICENSE                    # MIT 开源许可证
└── README.md                  # 本文档

🚀 快速上手与运行

  1. 安装微信开发者工具:前往 微信官方文档 下载对应操作系统的开发者工具。
  2. 导入项目:
    • 打开微信开发者工具,点击「导入」;
    • 目录选择当前仓库根目录;
    • AppID:可填入你自己的微信小程序 AppID(也可以在没有 AppID 时选择「测试号」体验全部功能)。
  3. 本地编译:
    • 点击「编译」,左侧模拟器即可秒级呈现并完整体验全部待办管理功能。

手机日历真机验证

  1. 在微信公众平台的用户隐私保护指引中声明日历写入用途。官方文档说明新增声明约 5 分钟后生效;这不等于用户已授权。
  2. 重新上传修改后的代码并设为体验版,在手机微信中打开。开发者工具和 Node 测试不能证明系统日历实际写入。
  3. 新建一条明天截止的待办,打开「保存时添加到手机日历」(此时将利用点击 switch 的合法 TAP 手势前置拉起微信隐私授权弹窗,点击同意即可成功预授权),点击保存待办。
  4. 以「已保存并加入日历」提示、列表卡片出现「已加日历」蓝色胶囊徽标,以及系统日历中对应日期 09:00 的「待办提醒:标题」事件为写入成功判据。
  5. 再次点击卡片进入编辑抽屉,可看到专属「已添加到手机日历」状态卡片,开关显示为「再次添加到手机日历」(默认关闭)。尝试打开开关时将弹出二次确认弹窗,确认后才允许再次添加,杜绝误触重复创建。
  6. 若失败,待办仍保留:拒绝授权、不支持日历、手势丢失(提示再次点击保存即可加入)、后台声明未生效及系统错误会分别提示。不要通过反复保存猜测是否成功。

日历是单次添加,不与待办双向同步:在小程序完成、删除或改期,不会自动改动手机日历中的既有事件。需要再次添加时请显式打开开关,并在系统日历管理旧事件。添加后的日程也可能按手机的日历账户设置同步到 iCloud 等服务。 参考:日历 API · 隐私协议开发指南

🧪 本地测试与代码门禁运行

本项目内置零第三方依赖的轻量单元测试套件(基于 Node.js 原生 Test Runner):

# 运行全部单元测试
node --test tests/datastore.test.js tests/smart-sort.test.js tests/subscribe.test.js tests/calendar.test.js tests/index-calendar.test.js

# 运行 6 道全量代码质量门禁
node scripts/quality-gate.js

💾 本地数据存储与隔离说明

指标 说明
存储 Key bean_todo_items_v1(保存在微信客户端安全沙箱本地缓存中)
持久性 只要不主动卸载小程序或在微信存储管理中深度清空缓存,数据永久保留在手机上
隐私隔离 微信本地缓存按「小程序 AppID + 手机本地用户」严格物理隔离,外界无法读取
上限容量 单 Key 限制 1MB、总缓存 10MB(纯文本待办即使记录数千条,通常仅占用几十 KB)



🌐 English Documentation

🌟 Overview

Douya Todo is a clean, modern, offline-first To-Do management Mini-Program built with the native WeChat Mini-Program framework. Embracing a zero-backend dependency architecture, all user data is safely persisted within the device's local storage (wx.setStorageSync). It requires no cloud base, no external database, and zero server maintenance cost—completely private, ultra-fast, and works out-of-the-box.


✨ Key Features

  1. Zero-Jump Bottom-Sheet Modal
    • Replaces disruptive page navigations with a sleek, bottom-up half-screen drawer for both creating and editing tasks.
    • Designed with a strict Zero-Scrolling principle to ensure instant form entry and optimal tactile ergonomics.
  2. Due Date Proximity Visual Grading
    • Replaces generic warning labels with an intuitive, multi-level color hierarchy based on days remaining ($\Delta \text{Days}$):
      • Overdue: High-visibility deep red (#e5484d), displaying exact days overdue.
      • Due Today: Urgent orange-red (#e03e1a), prioritizing immediate attention.
      • Due Tomorrow: Warm amber (#d97706), encouraging proactive planning.
      • Within 2~3 Days: Dynamic vibrant blue (#2563eb), clear and reassuring.
      • Later / Future: Calm neutral gray (#6b7280), minimizing visual noise.
      • Completed: Low-contrast muted gray (#9ca3af), clean and archived.
  3. GTD Smart Hybrid Sorting Algorithm
    • Overdue tasks are automatically placed at the very top for urgent resolution.
    • Tasks due today and upcoming deadlines are sequentially prioritized based on urgency and priority tiers (high > normal > low).
    • Completed tasks smoothly sink to the bottom, sorted by completion timestamp.
  4. High-Affordance Semantic Checkbox
    • Upgraded to a $48\text{rpx}$ rounded rectangle with a subtle outline checkmark (✓) in unchecked state, providing unambiguous click affordance.
    • Expanded with an invisible $84\text{rpx} \times 84\text{rpx}$ touch target area to prevent accidental clicks on card titles.
    • Enriched with haptic feedback (wx.vibrateShort) and an elastic bounce animation upon completion.
  5. Swipe-Action Cell (Left-Swipe Drawer)
    • Smooth left-swipe gesture reveals a $280\text{rpx}$ utility drawer.
    • Contains an emerald green Complete / Revert button and an alert red Delete button.
    • Features directional axis-locking to eliminate vertical scrolling interference, along with single-item exclusive expansion.
  6. Phone Calendar Reminders (No Cloud Reminder Service Required)
    • On save, wx.addPhoneCalendar creates a system calendar event with an alarm request; it does not request WeChat subscription messages.
    • Events start at 09:00 on the due date in the device's local timezone. If that time has passed, the reminder is scheduled ten minutes from now.
    • Privacy consent and calendar write permission are required. Actual notifications, sound and vibration depend on calendar settings, notification permissions and Do Not Disturb; a ringing alarm is not guaranteed.
    • Calendar failures do not discard local tasks. Editing does not add another event unless explicitly requested. Existing calendar events must be edited or deleted in the calendar app.
  7. Per-Commit 6-Stage Quality Gate
    • Automated via scripts/quality-gate.js and .githooks/pre-commit:
      • [1/6] JS Syntax Static Verification (node --check)
      • [2/6] Comprehensive JSON Configuration Validation
      • [3/6] WXML Tag Pairing & Closure Verification (prevents missing </view> compile breaks)
      • [4/6] Mini-Program App Configuration Sanity Check
      • [5/6] Full Data-Layer, GTD Sorting & Subscription Unit Test Suites
      • [6/6] Bundle Single-File Size Ceiling ($\le 200\text{KB}$)

📂 Directory Structure

.
├── app.js                     # Global application lifecycle
├── app.json                   # Mini-program pages & window configuration
├── app.wxss                   # Global stylesheet & design tokens
├── project.config.json        # WeChat DevTools project configuration
├── project.miniapp.json       # Multi-platform framework configuration
├── sitemap.json               # Search indexing rules
├── config/                    # Configuration modules
│   ├── subscribe.js
│   └── subscribe.example.js
├── cloudfunctions/           # Lightweight cloud functions
│   └── todoReminder/          # Scheduled notification cloud function
├── pages/
│   ├── index/                 # Main page: task list, swipe cells, bottom-sheet modal
│   │   ├── index.json
│   │   ├── index.wxml
│   │   └── index.wxss
│   └── edit/                  # Dedicated edit page (legacy fallback)
├── utils/
│   ├── todo.js                # TodoManager data access layer (CRUD & local cache)
│   └── date-helper.js         # Functional date difference, urgency grading & GTD sorter
├── scripts/
│   └── quality-gate.js        # 6-Stage Pre-commit Code Quality Gate
├── tests/
│   ├── datastore.test.js      # Storage layer contract tests (42 assertions)
│   └── smart-sort.test.js     # GTD sorting & urgency grading unit tests
├── .githooks/
│   └── pre-commit             # Git pre-commit hook
├── LICENSE                    # MIT License
└── README.md                  # Bilingual documentation

🚀 Getting Started

  1. Download WeChat DevTools: Get the official IDE from the WeChat Developer Portal.
  2. Import Project:
    • Launch WeChat DevTools and select Import.
    • Point the directory to this project root.
    • Enter your own AppID, or choose Test Account (测试号) if you do not have one yet.
  3. Compile & Preview:
    • Click Compile (编译). The simulator will instantly launch with full offline functionality.

Calendar Verification on a Phone

  1. Declare calendar write access in the mini-program's privacy guidelines. The official documentation states that new declarations take about five minutes to become effective; this does not grant user consent.
  2. Upload the updated code as a trial version and open it in WeChat on a phone. DevTools and Node tests cannot verify a real device's calendar.
  3. Create a task due tomorrow, enable the calendar option, and save. Grant privacy consent and calendar permission when prompted; existing grants may skip these prompts.
  4. Confirm both the calendar-success message and the event named 待办提醒:<title> at 09:00 in the phone calendar.
  5. A failure leaves the local task intact and reports the calendar error separately. Keep any original error shown in the failure dialog rather than repeatedly saving.

This is a one-time calendar export, not two-way synchronization. Completing, deleting or rescheduling a task does not update existing calendar events. Manage them in the calendar app. Calendar accounts may sync exported events to services such as iCloud.

References: Calendar API · Privacy authorization guide


🧪 Running Tests & Quality Gate

Run the zero-dependency test suites directly using Node.js built-in test runner:

# Run all unit tests
node --test tests/datastore.test.js tests/smart-sort.test.js tests/subscribe.test.js tests/calendar.test.js tests/index-calendar.test.js

# Execute all 6 stages of the quality gate
node scripts/quality-gate.js

📄 License

This project is licensed under the MIT License. Feel free to use, modify, and distribute it for personal or commercial projects.

About

豆芽待办。简单、好用

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages