Imported from HDNRAY/down-and-up (AGENTS.md). Install upstream with npx skills add HDNRAY/down-and-up. Copyright stays with the author.

解压计数器 · 项目开发指南

本项目是 AGENTS.md 驱动的 AI 辅助开发。此文件是所有开发行为的参考原点。 开始新任务前先读此文件，确保架构一致性。

一、项目概述

产品：解压计数器 — 一款极简无文字界面的微信小程序。 核心理念：不是"会发声的计数器"，而是"有数字的指尖解压玩具"。 技术栈：微信小程序原生框架（WXML + WXSS + JS）+ Canvas 2D。

二、架构决策

三、文件组织约定

miniapp/
├── AGENTS.md                       # 本文件 — 设计指南
├── app.js                          # 小程序入口
├── app.json                        # 全局配置
├── app.wxss                        # CSS 变量 + 全局 reset
├── project.config.json             # 开发者工具配置
├── pages/
│   └── index/                      # 唯一主页面
│       ├── index.js                # 页面逻辑（状态机、触摸、计数）
│       ├── index.wxml              # WXML 布局（零内联样式）
│       ├── index.wxss              # 页面样式（全 class 选择器）
│       └── index.json              # 页面配置
├── components/
│   ├── reset-button/               # 归零按钮组件
│   │   ├── reset-button.js/wxml/wxss/json
│   └── stats-panel/                # 统计面板组件
│       ├── stats-panel.js/wxml/wxss/json
├── utils/
│   ├── renderer.js                 # Canvas 2D 绘制工具库
│   ├── spring.js                   # 弹簧物理 / 惯性引擎
│   ├── audio.js                    # 程序化音效生成
│   ├── haptics.js                  # 震动封装
│   └── storage.js                  # 本地存储
└── assets/
    └── audio/                      # 预录音效（备用，优先程序化生成）

命名规则

四、组件树

Page (pages/index)
├── .page-wrapper                  # 全屏容器，暗色背景 + safe-area
│   ├── .top-bar                   # 顶部信息区（fixed）
│   │   ├── .count-number          # 居中巨大数字 (<text>)
│   │   ├── reset-button (custom)  # 归零按钮组件
│   │   └── .calendar-icon         # 日历图标入口
│   ├── #interaction-canvas        # Canvas 交互区 (flex:1)
│   │   ├── PressMode              # 按压模式渲染（绿色圆形按钮）
│   │   ├── ScrollMode             # 滚动模式渲染（金属滚轮）
│   │   └── PullMode               # 拉拽模式渲染（橡胶带）
│   ├── .bottom-bar                # 底部固定区
│   │   └── .mode-indicators       # 三圆点（● ⌇ ↕）
│   └── stats-panel (custom)       # 统计面板（条件渲染，遮罩+滑入）

五、数据流

用户触摸 (touchstart/touchmove/touchend)
  │
  ▼
TouchDispatcher (index.js)
  ├── 命中 Canvas 区域 → currentMode.handleTouch(event)
  │     ├── 更新 modeCount (+1 / 按刻度增加)
  │     ├── 触发 FeedbackSystem：
  │     │     ├── AudioEngine.play(soundName)
  │     │     └── HapticEngine.trigger(type)
  │     └── 返回 { count, feedback }
  │
  ├── 命中归零按钮 → resetAll()
  │     ├── 播放归零音效（沙沙消散）
  │     ├── heavy 震动
  │     ├── 数字归零动画（缩→消→弹）
  │     └── Storage.resetToday()
  │
  └── 命中底部指示器 → switchMode(index)
        └── 切换 currentMode + 更新 UI 选中态

count 变更 → setData({ displayCount }) → WXML 绑定更新
每天首次操作 → Storage.initDay() → 创建今日记录
每次变更 → Storage.append(count)

六、反馈系统规格

音效表（程序化生成）

震动表

七、编码规范

WXML

• 零内联样式：禁止 style="..." 属性，所有样式走 class
• 语义化 class：.count-number, .mode-indicator, .reset-btn
• 条件渲染用 wx:if：<view wx:if="{{showStats}}">
• 列表用 wx:for：<view wx:for="{{modes}}" wx:key="id">

WXSS

• 全 class 选择器：禁止标签选择器（除 page {} reset 外）
• CSS 变量集中管理：所有颜色/尺寸在 app.wxss 定义 --* 变量
• rpx 单位：尺寸用 rpx 适配屏幕，Canvas 内用 px（通过 DPR 换算）
• BEM 风格 class：.component__element--modifier

JavaScript

• ES6+ 语法：const/let, arrow function, class, destructuring
• 无大量重复代码：三种模式共享 renderer.js 工具函数
• Canvas 绘制函数收归 utils/renderer.js，模式类只做组合和交互逻辑
• setData 最小化：只 set 变化的数据，不 set 整个对象

注释规范

• 每个 class 前 JSDoc 说明职责
• 复杂物理公式旁加注释
• WXML 中关键 block 前加 HTML 注释 <!-- 计数数字 -->

八、微信小程序限制备忘

九、颜色系统

--bg-primary:    #1A1A2E    /* 深色背景 */
--bg-secondary:  #16213E    /* 次级背景 */
--text-primary:  #EAEAEA    /* 主文字/数字 */
--green-main:    #4CAF50    /* 绿色按钮主色 */
--green-light:   #81C784    /* 绿色按钮高光 */
--orange-reset:  #FF7043    /* 归零按钮暖橙红 */
--orange-light:  #FFAB91    /* 归零按钮高光 */
--metal-base:    #78909C    /* 滚轮金属基底 */
--metal-highlight:#B0BEC5   /* 滚轮金属高光 */
--strap-yellow:  #FFC107    /* 拉带黄色 */
--strap-coral:   #FF6B6B    /* 拉带极限红 */
--mode-off:      #555555    /* 模式指示器未选中 */
--mode-on:       #EAEAEA    /* 模式指示器选中 */
--overlay:       rgba(0,0,0,0.6)  /* 遮罩层 */

十、开发顺序（已计划）