@sunr/dsh-reminder 0.0.0-stage → 0.14.1

package/src/repeat.js

@@ -0,0 +1,171 @@
+/**
+ * 重复规则展开。与 iOS 端 Shared/Models/TodoItem.swift 的 RepeatKind 一一对应：
+ *   none / daily / weekly / monthly / yearly / biweeklyOdd / biweeklyEven / customDays
+ *
+ * 设计取舍：不预生成日程表，而是提供「某一天是否命中」的纯谓词 matchesItem()，
+ * 再按区间逐日扫描。区间通常是「今天起 30 天」，代价可忽略，换来的是
+ * 农历年、闰月、大小月、2/29 这些边界全部退化成同一条判断路径。
+ */
+
+import { solarToLunar, toDate, toISODate } from './lunar.js'
+
+export const REPEAT_KINDS = [
+  'none', 'daily', 'weekly', 'monthly', 'yearly',
+  'biweeklyOdd', 'biweeklyEven', 'customDays',
+]
+
+const DAY_MS = 86_400_000
+
+/** 周几，0=周日（和 Date#getUTCDay 一致） */
+export function weekdayOf(iso) {
+  return toDate(iso).getUTCDay()
+}
+
+/** ISO 8601 周序号，用于单/双周 */
+export function isoWeekOf(iso) {
+  const date = toDate(iso)
+  const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()))
+  const dayNumber = d.getUTCDay() || 7
+  d.setUTCDate(d.getUTCDate() + 4 - dayNumber)
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1))
+  return Math.ceil(((d.getTime() - yearStart.getTime()) / DAY_MS + 1) / 7)
+}
+
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate()
+}
+
+function isLeapYear(year) {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0
+}
+
+function shift(iso, days) {
+  return toISODate(new Date(toDate(iso).getTime() + days * DAY_MS))
+}
+
+function split(iso) {
+  const [year, month, day] = iso.split('-').map(Number)
+  return { year, month, day }
+}
+
+/** 农历某次命中的最后一天：用来处理「腊月三十」落到只有廿九的年份 */
+function isLastDayOfLunarMonth(iso, lunar) {
+  const next = solarToLunar(shift(iso, 1))
+  return next.month !== lunar.month || next.leap !== lunar.leap
+}
+
+function matchGregorianYearly(item, iso) {
+  const anchor = split(item.date)
+  const target = split(iso)
+
+  // 2/29 出生：平年按 feb28 或 mar1 降级（对应 iOS 端的 LeapDayFallback）
+  if (anchor.month === 2 && anchor.day === 29 && !isLeapYear(target.year)) {
+    const fallback = item.leapDayFallback ?? 'feb28'
+    return fallback === 'mar1'
+      ? target.month === 3 && target.day === 1
+      : target.month === 2 && target.day === 28
+  }
+  return target.month === anchor.month && target.day === anchor.day
+}
+
+function matchLunarYearly(item, iso) {
+  const target = solarToLunar(iso)
+  const wanted = item.lunar
+  if (target.month !== wanted.month) return false
+  if (target.leap !== Boolean(wanted.leap)) return false
+  if (target.day === wanted.day) return true
+
+  // 该月只有廿九：要求三十的那年落到月末那一天
+  if (wanted.day === 30 && target.day === 29 && isLastDayOfLunarMonth(iso, target)) return true
+  return false
+}
+
+function matchMonthly(item, iso) {
+  const anchorDay = split(item.date).day
+  const target = split(iso)
+  const lastDay = daysInMonth(target.year, target.month)
+  return target.day === Math.min(anchorDay, lastDay)
+}
+
+function matchBiweekly(item, iso) {
+  if (weekdayOf(iso) !== weekdayOf(item.date)) return false
+  const parity = isoWeekOf(iso) % 2
+  return item.repeat === 'biweeklyOdd' ? parity === 1 : parity === 0
+}
+
+function matchCustomDays(item, iso) {
+  const every = Number(item.every)
+  if (!Number.isFinite(every) || every < 2) return false
+  const diff = Math.round((toDate(iso).getTime() - toDate(item.date).getTime()) / DAY_MS)
+  return diff >= 0 && diff % every === 0
+}
+
+/**
+ * 某一天是否命中这条记录。
+ * @param {object} item 见 README 的数据模型
+ * @param {string} iso  YYYY-MM-DD
+ */
+export function matchesItem(item, iso) {
+  if (!item?.date || iso < item.date) return false
+  if (item.skipped?.includes(iso)) return false
+
+  switch (item.repeat ?? 'none') {
+    case 'none': return iso === item.date
+    case 'daily': return true
+    case 'weekly': return ((item.weekdayMask ?? 0) >> weekdayOf(iso)) & 1 ? true : false
+    case 'monthly': return matchMonthly(item, iso)
+    case 'yearly':
+      return item.calendar === 'lunar'
+        ? matchLunarYearly(item, iso)
+        : matchGregorianYearly(item, iso)
+    case 'biweeklyOdd':
+    case 'biweeklyEven': return matchBiweekly(item, iso)
+    case 'customDays': return matchCustomDays(item, iso)
+    default: return false
+  }
+}
+
+/** [from, to] 闭区间内所有命中日期 */
+export function occurrencesBetween(item, from, to) {
+  if (to < from) return []
+  const out = []
+  for (let cursor = from; cursor <= to; cursor = shift(cursor, 1)) {
+    if (matchesItem(item, cursor)) out.push(cursor)
+  }
+  return out
+}
+
+/** 从 from 起（含当天）往后找最近一次 */
+export function nextOccurrence(item, from, horizonDays = 400) {
+  let cursor = from
+  const end = shift(from, horizonDays)
+  while (cursor <= end) {
+    if (matchesItem(item, cursor)) return cursor
+    cursor = shift(cursor, 1)
+  }
+  return null
+}
+
+/** 距离下一次还有几天（今天 → 0） */
+export function daysUntil(item, from, horizonDays = 400) {
+  const next = nextOccurrence(item, from, horizonDays)
+  if (!next) return null
+  return Math.round((toDate(next).getTime() - toDate(from).getTime()) / DAY_MS)
+}
+
+/** 写入前的基本校验，返回错误信息数组（空数组表示通过） */
+export function validateItem(item) {
+  const errors = []
+  if (!item?.title || typeof item.title !== 'string') errors.push('title 必填')
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(item?.date ?? '')) errors.push('date 必须是 YYYY-MM-DD')
+  if (!REPEAT_KINDS.includes(item?.repeat ?? 'none')) errors.push(`repeat 不支持：${item?.repeat}`)
+  if ((item?.repeat ?? 'none') === 'customDays' && !(Number(item?.every) >= 2)) {
+    errors.push('customDays 需要 every ≥ 2')
+  }
+  if (item?.calendar === 'lunar') {
+    const lunar = item.lunar ?? {}
+    if (!(lunar.month >= 1 && lunar.month <= 12)) errors.push('lunar.month 必须在 1-12')
+    if (!(lunar.day >= 1 && lunar.day <= 30)) errors.push('lunar.day 必须在 1-30')
+  }
+  return errors
+}

package/src/retrograde.js

@@ -0,0 +1,67 @@
+/**
+ * 水星逆行区间：用星历算水星的地心视黄经，黄经在减小就是逆行。
+ *
+ * 采样 12 小时一格，区间端点精确到天（±12h）。结果按「起止日期」缓存，
+ * 月历切页不会重复计算。
+ */
+
+import * as A from 'astronomy-engine'
+
+const DAY = 86_400_000
+const STEP = 12 * 3600 * 1000
+const cache = new Map()
+
+function longitude(date) {
+  const vector = A.GeoVector(A.Body.Mercury, date, true)
+  return A.Ecliptic(vector).elon
+}
+
+function unwrap(delta) {
+  if (delta > 180) return delta - 360
+  if (delta < -180) return delta + 360
+  return delta
+}
+
+const isoOf = (ms) => new Date(ms).toISOString().slice(0, 10)
+
+/**
+ * @param {string} startISO YYYY-MM-DD
+ * @param {string} endISO   YYYY-MM-DD
+ * @returns {{ start: string, end: string }[]} 起止都含当天
+ */
+export function mercuryRetrogradeRanges(startISO, endISO) {
+  const key = `${startISO}..${endISO}`
+  if (cache.has(key)) return cache.get(key)
+
+  const from = Date.parse(`${startISO}T00:00:00Z`) - STEP
+  const to = Date.parse(`${endISO}T00:00:00Z`) + STEP
+  const ranges = []
+  let current = null
+  let previous = null
+
+  for (let time = from; time <= to; time += STEP) {
+    const lon = longitude(new Date(time))
+    if (previous !== null) {
+      const retrograde = unwrap(lon - previous) < 0
+      const day = isoOf(time)
+      if (retrograde) {
+        if (current === null) current = { start: isoOf(time - STEP), end: day }
+        else current.end = day
+      } else if (current !== null) {
+        ranges.push(current)
+        current = null
+      }
+    }
+    previous = lon
+  }
+  if (current !== null) ranges.push(current)
+
+  if (cache.size > 24) cache.clear()
+  cache.set(key, ranges)
+  return ranges
+}
+
+/** 某天是否在水逆区间内 */
+export function isRetrograde(iso, ranges) {
+  return ranges.some((range) => iso >= range.start && iso <= range.end)
+}

package/src/service.js

@@ -0,0 +1,170 @@
+/**
+ * 写入服务：工具（模型调用）和页面（人工操作）共用同一套校验与落库逻辑，
+ * 避免两边口径不一致。
+ */
+
+import { nextOccurrence, validateItem } from './repeat.js'
+import { nextLunarOccurrence } from './lunar.js'
+import { newId } from './store.js'
+import { normalizeTime } from './remind.js'
+
+export const KINDS = ['todo', 'anniversary', 'memo']
+
+/**
+ * 提前提醒天数：支持 0 / 数字 / 数组 / "7,1" 字符串，统一成去重升序的数组。
+ * 兼容旧数据（advance 是单个数字）。
+ */
+export function normalizeAdvance(value) {
+  const raw = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(/[,，\s]+/).filter(Boolean)
+      : value === undefined || value === null || value === ''
+        ? []
+        : [value]
+
+  const points = new Set()
+  for (const entry of raw) {
+    const days = Math.trunc(Number(entry))
+    if (!Number.isFinite(days)) continue
+    if (days <= 0) continue
+    points.add(Math.min(30, days))
+  }
+  return [...points].sort((left, right) => left - right)
+}
+
+export const REPEATS = [
+  'none', 'daily', 'weekly', 'monthly', 'yearly',
+  'biweeklyOdd', 'biweeklyEven', 'customDays',
+]
+
+function splitTags(value) {
+  if (Array.isArray(value)) return value.map((tag) => String(tag).trim()).filter(Boolean)
+  if (!value) return []
+  return String(value).split(/[,，\s]+/).map((tag) => tag.trim()).filter(Boolean)
+}
+
+/** 把「页面表单 / 工具参数」归一成一条完整记录（不含 id），失败时抛错 */
+export function draftFrom(input, { timeZone = 'Asia/Shanghai', today } = {}) {
+  const calendar = input.calendar === 'lunar' ? 'lunar' : 'gregorian'
+  const kind = KINDS.includes(input.kind) ? input.kind : 'todo'
+  const repeat = REPEATS.includes(input.repeat)
+    ? input.repeat
+    : (kind === 'anniversary' ? 'yearly' : 'none')
+
+  let date = input.date?.trim() || null
+  if (calendar === 'lunar') {
+    const month = Number(input.lunarMonth)
+    const day = Number(input.lunarDay)
+    if (!(month >= 1 && month <= 12) || !(day >= 1 && day <= 30)) {
+      throw new Error('农历日期需要月份 1-12、日 1-30')
+    }
+    if (!date) {
+      const hit = nextLunarOccurrence({ month, day, leap: Boolean(input.lunarLeap) }, today, { timeZone })
+      if (!hit) throw new Error('这个农历日期在未来一年内没有出现，请补一个公历锚点')
+      date = hit.date
+    }
+  }
+  date ??= today
+
+  const item = {
+    id: newId(),
+    kind,
+    title: String(input.title ?? '').trim(),
+    calendar,
+    date,
+    repeat,
+    every: input.every ?? null,
+    weekdayMask: Number(input.weekdayMask ?? 0),
+    leapDayFallback: input.leapDayFallback ?? 'feb28',
+    advance: normalizeAdvance(input.advance),
+    remindAt: normalizeTime(input.remindAt),
+    tags: splitTags(input.tags),
+    note: input.note ?? '',
+    skipped: [],
+    done: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  }
+  if (calendar === 'lunar') {
+    item.lunar = {
+      month: Number(input.lunarMonth),
+      day: Number(input.lunarDay),
+      leap: Boolean(input.lunarLeap),
+    }
+  }
+
+  const errors = validateItem(item)
+  if (errors.length) throw new Error(errors.join('；'))
+  return item
+}
+
+export async function addItem(store, input, context) {
+  const item = draftFrom(input, context)
+  await store.insert(item)
+  return item
+}
+
+const EDITABLE = ['title', 'date', 'repeat', 'every', 'weekdayMask', 'tags', 'note', 'kind', 'advance', 'remindAt']
+
+export async function updateItem(store, id, fields) {
+  const current = await store.get(id)
+  if (!current) throw new Error(`找不到记录：${id}`)
+
+  const patch = {}
+  for (const key of EDITABLE) {
+    if (fields[key] === undefined) continue
+    if (key === 'tags') patch[key] = splitTags(fields[key])
+    else if (key === 'advance') patch[key] = normalizeAdvance(fields[key])
+    else if (key === 'remindAt') patch[key] = normalizeTime(fields[key])
+    else patch[key] = fields[key]
+  }
+
+  // 页面可以改历法与农历分量，工具不必改，所以单独处理
+  if (fields.calendar !== undefined) {
+    patch.calendar = fields.calendar === 'lunar' ? 'lunar' : 'gregorian'
+  }
+  const calendar = patch.calendar ?? current.calendar
+  if (calendar === 'lunar') {
+    if (fields.lunarMonth !== undefined || fields.lunarDay !== undefined || fields.lunarLeap !== undefined) {
+      patch.lunar = {
+        month: Number(fields.lunarMonth ?? current.lunar?.month ?? 1),
+        day: Number(fields.lunarDay ?? current.lunar?.day ?? 1),
+        leap: Boolean(fields.lunarLeap ?? current.lunar?.leap),
+      }
+    }
+  } else if (patch.calendar === 'gregorian') {
+    patch.lunar = undefined
+  }
+
+  if (!Object.keys(patch).length) throw new Error('没有要修改的字段')
+
+  const merged = { ...current, ...patch }
+  const errors = validateItem(merged)
+  if (errors.length) throw new Error(errors.join('；'))
+
+  return store.patch(id, patch)
+}
+
+export async function removeItem(store, id) {
+  const removed = await store.remove(id)
+  if (!removed) throw new Error(`找不到记录：${id}`)
+  return removed
+}
+
+export async function markDone(store, id, occurrence, today) {
+  const item = await store.get(id)
+  if (!item) throw new Error(`找不到记录：${id}`)
+  const target = occurrence || (item.repeat === 'none' ? item.date : nextOccurrence(item, today) || today)
+  const done = new Set(item.done ?? [])
+  done.add(target)
+  const updated = await store.patch(id, { done: [...done].sort() })
+  return { item: updated, occurrence: target }
+}
+
+export async function undoDone(store, id, occurrence) {
+  const item = await store.get(id)
+  if (!item) throw new Error(`找不到记录：${id}`)
+  const done = (item.done ?? []).filter((entry) => entry !== occurrence)
+  return store.patch(id, { done })
+}

package/src/store.js

@@ -0,0 +1,116 @@
+/**
+ * 存储层：一个 JSON 文件，原子写（临时文件 + rename），进程内串行化。
+ *
+ * 为什么不用 DSH 的 storage-domain：第一版要能脱离宿主单测，
+ * 也要能让人直接打开文件看数据。等形态稳定了再迁到 ctx.storage。
+ */
+
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { randomBytes } from 'node:crypto'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+
+export const SCHEMA_VERSION = 1
+
+export function defaultStorePath() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  return join(home, 'storages', 'dsh-reminder', 'items.json')
+}
+
+export function emptyState() {
+  return { version: SCHEMA_VERSION, items: [] }
+}
+
+export function newId() {
+  return `jiri_${randomBytes(5).toString('hex')}`
+}
+
+/** 串行化读-改-写，避免并发工具调用互相覆盖 */
+function createQueue() {
+  let tail = Promise.resolve()
+  return (task) => {
+    const run = tail.then(task, task)
+    tail = run.then(() => undefined, () => undefined)
+    return run
+  }
+}
+
+export async function readState(file) {
+  try {
+    const raw = await readFile(file, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (!Array.isArray(parsed?.items)) throw new Error(`存储格式不对：${file}`)
+    return { version: parsed.version ?? SCHEMA_VERSION, items: parsed.items }
+  } catch (error) {
+    if (error.code === 'ENOENT') return emptyState()
+    throw error
+  }
+}
+
+export async function writeState(file, state) {
+  await mkdir(dirname(file), { recursive: true })
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`
+  // 记录里有生日、家庭关系，只给当前用户读
+  await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+  await rename(temp, file)
+  await chmod(file, 0o600).catch(() => {})
+}
+
+export function createStore(file = defaultStorePath()) {
+  const enqueue = createQueue()
+
+  return {
+    file,
+
+    async list() {
+      return (await readState(file)).items
+    },
+
+    async get(id) {
+      const items = await readState(file)
+      return items.items.find((item) => item.id === id) ?? null
+    },
+
+    async insert(item) {
+      return enqueue(async () => {
+        const state = await readState(file)
+        state.items.push(item)
+        await writeState(file, state)
+        return item
+      })
+    },
+
+    async patch(id, fields) {
+      return enqueue(async () => {
+        const state = await readState(file)
+        const index = state.items.findIndex((item) => item.id === id)
+        if (index === -1) return null
+        const merged = { ...state.items[index], ...fields, id, updatedAt: new Date().toISOString() }
+        state.items[index] = merged
+        await writeState(file, state)
+        return merged
+      })
+    },
+
+    async remove(id) {
+      return enqueue(async () => {
+        const state = await readState(file)
+        const index = state.items.findIndex((item) => item.id === id)
+        if (index === -1) return null
+        const [removed] = state.items.splice(index, 1)
+        await writeState(file, state)
+        return removed
+      })
+    },
+
+    /** 直接改整个 state 的逃生门：导入、迁移用 */
+    async mutate(mutator) {
+      return enqueue(async () => {
+        const state = await readState(file)
+        const result = await mutator(state)
+        await writeState(file, state)
+        return result
+      })
+    },
+  }
+}