墨易 Moyi

English README: README-en.md

墨易是一款偏国风视觉的每日一算应用，用来记录每日卦象、关注事项、结果解读和历史回看。它默认把数据保存在本机，数据文件为 Documents/Moyi/data.json，适合希望保留个人日课记录、又需要移动端体验的用户。

本项目当前以 Next.js 静态应用 + Capacitor Android 封装 为主，目前已完成 Web MVP 和 Android 工程同步。后续正式 APK 以 GitHub Release 为准。

界面与定位

首页概念	背景素材
卡片概念	图标概念

墨易的设计目标不是做复杂玄学系统，也不是高频抽卡工具，而是把“每天取一象、当天留一条记录、以后能回看”做得稳定、清楚、少打扰。界面以宣纸底色、松烟墨绿和朱砂点色为主，保留印章、卦线和纸张边框的视觉感。

下载

最新版本以 GitHub Release 为准：

https://github.com/Cmochance/Moyi/releases/latest

普通用户优先下载 Release 页面中的 Android APK 资产。若某个版本暂未提供 APK，可以按 构建与部署指南 在本机打包。

本次发布的版本更新说明见 CHANGELOG.md，单版本发布说明见 docs/release-notes-v0.1.1.md。

如果这个应用对你有帮助，欢迎 Star 一下。遇到问题、希望补充每日一算流程或需要新的平台适配，可以发到 Issues。

能做什么

• 每天生成一条“今日一算”，并默认复用当天结果。
• 支持填写今日关注事项，也可以留空直接取象。
• 展示本卦、变爻、之卦、关键词和轻量行动建议。
• 历史记录支持主题筛选、查看详情和删除。
• 六十四卦库支持按卦名、上下卦和关键词搜索，并查看卦象详情。
• 支持三套主题配色：墨易、松烟、朱砂。
• 支持本机备份与恢复，固定数据文件为 Documents/Moyi/data.json。
• 支持 Capacitor Android 封装，已生成 Android 工程。

基本用法

1. 打开应用，首页会显示今日状态。
2. 点击“起一卦”。
3. 可填写今日关注事项，并选择主题，例如日常、事业、学习、人际、心绪、财务或身心。
4. 点击“生成今日卦象”，应用会保存当天记录。
5. 在详情页查看本卦、变爻、之卦和今日建议。
6. 在“记录”页面回看历史，在“卦库”页面浏览六十四卦。
7. 在“我的”页面切换主题，或执行本机备份、恢复和清除数据。

数据与备份

应用会维护两份本机数据：

• 应用内部数据：优先使用 Capacitor Preferences，网页预览时兼容 localStorage。
• 本机数据文件：Documents/Moyi/data.json。

每次保存记录或设置后，应用会自动把完整数据写入 Documents/Moyi/data.json。应用启动时会比较内部数据和该文件：

• 如果两边一致，直接进入应用。
• 如果两边不一致，会提示是否导入本机数据。
• 选择导入时，会先把应用内数据备份为 Documents/Moyi/backup-YYYY-MM-DD-HHmmss.json，再用 data.json 覆盖应用内数据。
• 选择不导入时，会先备份现有 data.json，再用应用内数据覆盖该文件。

手动“备份数据”和“恢复数据”使用同一套覆盖前备份逻辑。data.json 和备份文件可能包含用户输入的关注事项、历史卦象和主题设置，请只保存在可信设备上。

本地开发

安装依赖：

npm install

启动开发服务器：

npm run dev

访问：

http://localhost:3000

常用检查命令：

npm run lint
npm run typecheck
npm run verify:divination
npm run build
npm run check

其中 npm run build 会执行 Next.js 静态导出，产物目录为 dist/。如果开发服务器正在运行，请先停止再执行 npm run build 或 npm run check，避免 dist/dev 缓存被生产构建覆盖。

Android 打包

项目使用 Capacitor 将静态站点同步到 Android 工程：

npm run build
npm run sync:android

Debug APK、Release APK、本机 JDK/Android SDK、签名文件和一键脚本的详细说明见 BUILD_GUIDE.md。

仓库只保存源码、Android 工程源码、文档和运行时公共资源；dist/、.next/、*.apk、*.aab、本机工具链和真实签名文件不进入 Git。

Troubleshooting

页面打开后数据为空

请先确认是否刚换了浏览器、设备或安装包。应用启动时会从内部存储和 Documents/Moyi/data.json 读取数据。如果两边不一致，应按弹窗提示选择导入本机数据或保留应用内数据。

备份或恢复失败

请确认应用有访问 Documents/Moyi/ 的权限。Android 上如果系统限制文件写入，备份和恢复会提示失败，需要检查应用权限或重新安装后再试。

本地完整检查失败

在部分受限沙箱环境中，Turbopack/PostCSS 可能因为内部端口绑定受限而失败。请在正常本机终端运行：

npm run check

如果开发服务器正在运行，请先停止开发服务器，再运行完整检查。

安装 APK 时提示未知来源

Android 默认会拦截非应用商店安装包。请只从本仓库 Release 页面下载 APK，并按系统提示允许当前文件管理器或浏览器安装未知来源应用。

构建 APK 失败

请先运行：

npm run check

如果前端检查通过，再按 BUILD_GUIDE.md 检查 JDK、Android SDK、Gradle Wrapper 和签名配置。真实密钥和口令只应放在本机，不要提交到仓库。

技术栈

• 前端框架：Next.js 16, React 19, TypeScript
• 样式方案：Tailwind CSS 4, 全局 CSS 变量主题
• 日期处理：date-fns
• 图标：lucide-react
• 本机能力：Capacitor Preferences, Capacitor Filesystem
• Android 封装：Capacitor Android

项目结构

src/app/                 Next.js 应用入口和全局样式
src/components/          首页、详情、历史、卦库、我的等界面组件
src/components/daily/    每日一算和卦象卡片组件
src/components/history/  历史记录组件
src/components/profile/  主题、关于和设置组件
src/lib/                 起卦算法、卦库、存储、主题、日期和类型
public/                  运行时静态资源
img/                     生成图和设计备用素材
docs/release-notes-*.md  单版本发布说明
android/                 Capacitor Android 工程源码
BUILD_GUIDE.md           Android 构建与签名说明

本机数据说明

• 本项目是个人本机使用的周易日课推演工具，运行时解读按卦象依据直接输出判断。
• 数据默认保存在本机，导出、备份或同步文件时请自行确认保存位置可信。
• Documents/Moyi/data.json 和 backup-*.json 可能包含用户输入的关注事项和历史记录，不建议上传到公开仓库或不可信网盘。

致谢

README 和发布说明结构参考了同作者项目 MoBill 的发布文档风格，并根据墨易的每日一算场景重新整理。

许可证

MIT License。完整文本见 LICENSE。