feat(V0.2): 打卡 / 日历 / 清单模块

- 数据: Habit/CheckIn/CheckList/CheckListItem/CheckListTemplate + 迁移 + 重新生成 client
- 后端: server/checkin/period.js 周期计算(日/周/月/年, 周一起始, Asia/Shanghai)
        /api/checkin/* 打卡项CRUD/打卡/撤销/补打/某日详情/月历
        /api/checklists/* 清单与检查项CRUD/勾选/全选/复制/模板(系统预置出差·回老家)
- 前端: 底部新增「打卡」Tab -> /checkin, 页内三视图
        环形进度 RingProgress + 完成特效(粒子/光晕/触感, 可关闭)
        打卡视图: 待办列表/乐观更新/撤销/新建编辑
        日历视图: 月历网格 + 今天·昨天·明天 + 日期标记/完成率
        清单视图: 场景清单/勾选进度条/模板生成/另存模板/归档
- 文档: docs/V0.2/需求文档.md 补充实现约定(附录B)与接口清单

src/pages/checkin/HabitView.jsx

@@ -0,0 +1,290 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  Button, Dialog, DotLoading, Empty, Input, Popup, Selector, Stepper, Toast,
+} from 'antd-mobile'
+import RingProgress, { Celebrate, effectsEnabled, setEffectsEnabled } from '../../components/RingProgress.jsx'
+import { checkinApi } from '../../api/checkin.js'
+import useRefreshOnVisible from '../../hooks/useRefreshOnVisible.js'
+import { toDateStr, dayLabel } from './date.js'
+
+const PERIOD_OPTIONS = [
+  { label: '每天', value: 'day' },
+  { label: '每周', value: 'week' },
+  { label: '每月', value: 'month' },
+  { label: '每年', value: 'year' },
+]
+
+const COLORS = ['#1677ff', '#00b578', '#ff8f1f', '#ff3141', '#a855f7', '#14b8a6', '#f43f9e']
+
+const EMPTY_FORM = { id: null, name: '', period: 'day', target: 1, color: COLORS[0], note: '' }
+
+// 打卡视图: 今日待办列表 + 环形进度 + 打卡/撤销 + 新建/编辑
+export default function HabitView({ date, onDateChange }) {
+  const [data, setData] = useState(null)          // { today, date, items, summary }
+  const [err, setErr] = useState('')
+  const [bursts, setBursts] = useState({})        // { habitId: 触发计数 }
+  const [form, setForm] = useState(EMPTY_FORM)
+  const [showForm, setShowForm] = useState(false)
+  const [effects, setEffects] = useState(effectsEnabled())
+
+  const load = useCallback((silent) => {
+    if (!silent) setErr('')
+    checkinApi.habits(date)
+      .then((d) => setData(d))
+      .catch((e) => { if (!silent) setErr(e.message) })
+  }, [date])
+
+  useEffect(() => { load(false) }, [load])
+  useRefreshOnVisible(() => load(true))
+
+  const items = useMemo(() => {
+    const list = data?.items || []
+    // 未完成在前, 已完成在后 (F-CK-16 默认排序)
+    return [...list].sort((a, b) => Number(a.completed) - Number(b.completed) || a.id - b.id)
+  }, [data])
+
+  const fireBurst = (id) => setBursts((m) => ({ ...m, [id]: (m[id] || 0) + 1 }))
+
+  // 乐观更新: 先本地 +1, 成功用服务端结果覆盖, 失败回滚 (F-SY-06/E-02)
+  async function doCheck(item) {
+    const before = data
+    const patch = (it) => {
+      const done = it.done + 1
+      return {
+        ...it,
+        done,
+        remaining: Math.max(0, it.target - done),
+        percent: Math.min(1, done / it.target),
+        completed: done >= it.target,
+        over: Math.max(0, done - it.target),
+        countOnDate: (it.countOnDate || 0) + 1,
+        dayDone: (it.countOnDate || 0) + 1 >= it.expectedPerDay,
+      }
+    }
+    setData((d) => ({ ...d, items: d.items.map((x) => (x.id === item.id ? patch(x) : x)) }))
+    try {
+      const res = await checkinApi.check(item.id, date)
+      setData((d) => ({ ...d, items: d.items.map((x) => (x.id === item.id ? res.item : x)) }))
+      if (res.item.completed) fireBurst(item.id)
+    } catch (e) {
+      setData(before)
+      Toast.show({ content: e.message || '打卡失败' })
+    }
+  }
+
+  async function doUncheck(item) {
+    const before = data
+    setData((d) => ({
+      ...d,
+      items: d.items.map((x) => {
+        if (x.id !== item.id) return x
+        const done = Math.max(0, x.done - 1)
+        return {
+          ...x,
+          done,
+          remaining: Math.max(0, x.target - done),
+          percent: Math.min(1, done / x.target),
+          completed: done >= x.target,
+          over: Math.max(0, done - x.target),
+          countOnDate: Math.max(0, (x.countOnDate || 0) - 1),
+        }
+      }),
+    }))
+    try {
+      const res = await checkinApi.uncheck(item.id, date)
+      setData((d) => ({ ...d, items: d.items.map((x) => (x.id === item.id ? res.item : x)) }))
+    } catch (e) {
+      setData(before)
+      Toast.show({ content: e.message || '撤销失败' })
+    }
+  }
+
+  async function submitForm() {
+    const name = String(form.name || '').trim()
+    if (!name) return Toast.show({ content: '请填写名称' })
+    if (name.length > 20) return Toast.show({ content: '名称不能超过 20 个字' })
+    const payload = { name, period: form.period, target: Number(form.target) || 1, color: form.color, note: form.note }
+    try {
+      if (form.id) await checkinApi.updateHabit(form.id, payload)
+      else await checkinApi.createHabit(payload)
+      setShowForm(false)
+      setForm(EMPTY_FORM)
+      load(true)
+    } catch (e) {
+      Toast.show({ content: e.message || '保存失败' })
+    }
+  }
+
+  async function removeHabit(item) {
+    const ok = await Dialog.confirm({
+      content: `归档「${item.name}」？归档后不再出现在待办，历史记录保留。`,
+      confirmText: '归档',
+      cancelText: '取消',
+    })
+    if (!ok) return
+    try {
+      await checkinApi.deleteHabit(item.id)
+      Toast.show({ content: '已归档' })
+      load(true)
+    } catch (e) {
+      Toast.show({ content: e.message || '操作失败' })
+    }
+  }
+
+  const summary = data?.summary || { total: 0, done: 0 }
+  const isToday = data ? data.date === data.today : true
+
+  return (
+    <div className="habit-view">
+      <div className="habit-head">
+        <div className="habit-head-left">
+          <div className="habit-date">{dayLabel(date, data?.today || toDateStr())}</div>
+          <div className="habit-summary">
+            已完成 <strong>{summary.done}</strong> / {summary.total}
+            {!isToday && <span className="habit-badge">非今天</span>}
+          </div>
+        </div>
+        <div className="habit-head-right">
+          <Button size="mini" fill="outline" color="primary" onClick={() => setEffects((v) => {
+            const next = !v
+            setEffectsEnabled(next)
+            return next
+          })}>
+            {effects ? '特效开' : '特效关'}
+          </Button>
+          <Button size="mini" color="primary" onClick={() => { setForm(EMPTY_FORM); setShowForm(true) }}>
+            + 新建
+          </Button>
+        </div>
+      </div>
+
+      {err && (
+        <div className="error-banner">
+          {err}
+          <span className="retry-link" onClick={() => load(false)}>重试</span>
+        </div>
+      )}
+
+      {data === null && !err && <div className="monitor-loading"><DotLoading /> 加载中...</div>}
+
+      {data !== null && !err && items.length === 0 && (
+        <div className="checkin-empty">
+          <Empty description="还没有打卡项" />
+          <Button color="primary" size="small" onClick={() => { setForm(EMPTY_FORM); setShowForm(true) }}>
+            创建第一个打卡项
+          </Button>
+        </div>
+      )}
+
+      <div className="habit-list">
+        {items.map((item) => (
+          <div key={item.id} className={'habit-card' + (item.completed ? ' done' : '')}>
+            <RingProgress
+              percent={item.percent}
+              done={item.done}
+              target={item.target}
+              over={item.over}
+              completed={item.completed}
+              color={item.color}
+              onClick={() => doCheck(item)}
+            />
+            <div className="habit-main">
+              <div className="habit-name">{item.name}</div>
+              <div className="habit-meta">
+                {item.periodLabel} {item.target} 次
+                {item.streak > 0 && <span className="habit-streak">连续 {item.streak}</span>}
+              </div>
+              {item.note && <div className="habit-note">{item.note}</div>}
+              <div className="habit-range">
+                {item.periodStart === item.periodEnd
+                  ? '今日'
+                  : `${item.periodStart.slice(5)} ~ ${item.periodEnd.slice(5)}`}
+                {item.over > 0 && <span className="habit-over">超额 {item.over}</span>}
+              </div>
+            </div>
+            <div className="habit-actions">
+              <Button
+                size="mini"
+                color={item.completed ? 'default' : 'primary'}
+                onClick={() => doCheck(item)}
+              >
+                {item.completed ? '再打一次' : '打卡'}
+              </Button>
+            </div>
+            <div className="habit-foot">
+              {item.done > 0 && (
+                <span className="habit-link" onClick={() => doUncheck(item)}>撤销</span>
+              )}
+              <span
+                className="habit-link"
+                onClick={() => {
+                  setForm({ id: item.id, name: item.name, period: item.period, target: item.target, color: item.color, note: item.note })
+                  setShowForm(true)
+                }}
+              >编辑</span>
+              <span className="habit-link danger" onClick={() => removeHabit(item)}>归档</span>
+            </div>
+            <Celebrate fire={bursts[item.id] || 0} color={item.color} />
+          </div>
+        ))}
+      </div>
+
+      {/* 新建 / 编辑 */}
+      <Popup
+        visible={showForm}
+        onMaskClick={() => setShowForm(false)}
+        bodyStyle={{ borderTopLeftRadius: 12, borderTopRightRadius: 12, paddingBottom: 16 }}
+      >
+        <div className="form-popup">
+          <div className="form-title">{form.id ? '编辑打卡项' : '新建打卡项'}</div>
+          <div className="form-field">
+            <label>名称</label>
+            <Input
+              placeholder="例如：喝水 / 健身 / 读书"
+              value={form.name}
+              maxLength={20}
+              onChange={(v) => setForm((f) => ({ ...f, name: v }))}
+            />
+          </div>
+          <div className="form-field">
+            <label>周期</label>
+            <Selector
+              options={PERIOD_OPTIONS}
+              value={[form.period]}
+              onChange={(v) => setForm((f) => ({ ...f, period: v[0] }))}
+            />
+          </div>
+          <div className="form-field">
+            <label>目标次数（周期内）</label>
+            <Stepper min={1} max={999} value={form.target} onChange={(v) => setForm((f) => ({ ...f, target: v }))} />
+          </div>
+          <div className="form-field">
+            <label>颜色</label>
+            <div className="color-row">
+              {COLORS.map((c) => (
+                <span
+                  key={c}
+                  className={'color-dot' + (form.color === c ? ' active' : '')}
+                  style={{ background: c }}
+                  onClick={() => setForm((f) => ({ ...f, color: c }))}
+                />
+              ))}
+            </div>
+          </div>
+          <div className="form-field">
+            <label>备注（可选）</label>
+            <Input
+              placeholder="补充说明"
+              value={form.note}
+              onChange={(v) => setForm((f) => ({ ...f, note: v }))}
+            />
+          </div>
+          <div className="form-actions">
+            <Button block color="primary" onClick={submitForm}>保存</Button>
+            <Button block fill="outline" onClick={() => setShowForm(false)} style={{ marginTop: 8 }}>取消</Button>
+          </div>
+        </div>
+      </Popup>
+    </div>
+  )
+}