目标：开发一个使用本地存储的微信小程序，用于记录家庭物品的存放位置与数量，强调"好用、直观、低负担"。
本文档用于提供给 Copilot / AI 编程助手，作为统一的产品与技术上下文说明。
This project is a WeChat Mini Program.
- Native Mini Program development (wxml / wxss / js)
- No web frameworks
- Local storage only (wx.setStorageSync)
-
使用场景：家庭内部物品管理
-
目标用户：个人 / 家庭成员（第一版仅限单用户）
-
核心诉求：
- 快速知道「物品在哪」
- 清楚「还剩多少」
- 操作尽量少、学习成本低
- 数据全部保存在用户端（本地存储）
- 不依赖服务器 / 云数据库
- 页面数量尽量少，交互清晰
- 优先满足 80% 高频需求，不追求复杂功能
- 支持浅色/深色主题切换（跟随系统或手动设置）
{
id: "item_170000000001", // 唯一标识（字符串）
name: "5号电池", // 物品名称（必填）
location: "客厅 / 电视柜 / 抽屉", // 存放位置（必填，使用人类语言）
count: 8, // 数量
unit: "节", // 单位（可选）
category: "日用品", // 分类（可选）
note: "遥控器用", // 备注（可选，最多250字符）
createdAt: 1700000000, // 创建时间（时间戳）
updatedAt: 1700000500, // 最近更新时间
// ✨ v1.1 新增：特殊物品到期管理
isSpecial: false, // 是否为特殊物品（有使用期限）
expireAt: null, // 到期时间（时间戳，毫秒），特殊物品时必填
history: [ // 库存变更记录（可选，最多保留20条）
{
delta: -2, // 本次变更数量（+ / -）
after: 6, // 变更后剩余数量
time: 1700000600 // 时间戳（秒）
}
]
}// Storage Key: 'app_settings'
{
theme: 'system', // 主题：'system' | 'light' | 'dark'
locations: ['客厅', '卧室'], // 预设位置列表
categories: ['日用品', '食品'] // 预设分类列表
}- 物品数据：
home_items - 应用设置：
app_settings
pages/
├── index/ // 首页：搜索 + 物品列表
├── add/ // 新增物品页面
├── detail/ // 物品详情 / 编辑页面
├── mine/ // 我的：设置 + 存储管理
- 展示全部物品列表（分类展示）
- 支持搜索
- 跳转新增 / 编辑页面
- ✨ v1.1 新增：区分常规物品和特殊物品（有到期时间）
首页分为两个区块：
-
📦 常规物品
- 显示 isSpecial = false 的物品
- 按原有逻辑展示
-
⏰ 特殊物品（有使用期限）
- 显示 isSpecial = true 的物品
- 显示到期状态标签
- 根据到期时间自动排序（越早到期越靠前）
- 已到期物品自动置底
| 距离到期时间 | 状态 | 颜色 | 提示文案 |
|---|---|---|---|
| > 30天 | 正常 | 默认 | N天后到期 |
| ≤ 30天 且 > 7天 | 警告 | 黄色 | N天后到期 |
| ≤ 7天 | 危险 | 红色 | N天后到期 |
| 已过期 | 已到期 | 灰色（半透明） | 已到期 |
-
根据以下字段模糊匹配：
- name
- location
- note
[ 搜索框 ]
-----------------
📦 常规物品
物品名 位置 数量
-----------------
⏰ 特殊物品（有使用期限）
物品名 位置 数量 [到期状态]
-----------------
[ ＋ 新增物品 ]
- 搜索为实时过滤
- 数量较低（<=2）以橙色高亮显示
- 点击物品进入详情页
- 物品名称（必填）
- 数量（默认 1）
- 单位（可选，默认折叠，点击"添加单位"展开）
- 存放位置（必填，选择器）
- 分类（可选，选择器）
- 备注（可选，最多250字符）
- ✨ v1.1 新增：这是特殊物品（有使用期限）- Switch开关
- ✨ v1.1 新增：到期日期（必填，仅在勾选特殊物品时显示）
- 名称为空 → 不允许保存
- 数量为空 → 自动设为 1
- 位置和分类支持选择器，可添加新选项
- ✨ v1.1：勾选"特殊物品"后，显示日期选择器
- ✨ v1.1：取消勾选后，自动清空已选日期
- 保存后返回首页并提示"已保存"
- 查看物品信息
- 修改数量（加 / 减）
- 编辑位置、备注等字段
- 删除物品
- 查看库存变更记录
[-] 当前数量 [+]
- 单击加减
- 数量不可小于 0
- 修改后立即保存到本地
- 只在详情页展示「最近变更」区域
- 记录时机：用户离开详情页时记录一次（非每次点击）
- 只记录通过 +/- 按钮的数量变化
- 不记录：新增物品初始数量、编辑页面直接修改数量
- 最多保留 20 条记录
- 倒序显示（最新在上）
- 变更数量：+绿色 / -橙色
- 默认显示前5行
- 超过80字符显示"展开"按钮
- 支持长按复制（user-select）
- 点击删除按钮
- 二次确认弹窗
- 主题设置（跟随系统 / 浅色 / 深色）
- 预设位置管理
- 预设分类管理
- 存储空间显示（支持 MB/KB 切换）
- 一键清空数据（双重确认）
- 所有数据变更立即写入本地存储
- 删除操作必须二次确认
- 清空数据需要双重确认
- 空列表状态需显示引导文案
- 存储空间接近上限时提醒用户
🏡 家里还没有记录物品哦～
先加一个吧，让生活更有条理 ✨
- 保存成功：
已保存 - 删除确认：
确定要删除这个物品吗？ - 库存过低：
快用完啦，记得补货～
添加物品✓ 保存到家里🗑️ 删除物品✏️ 编辑信息
- 跟随系统：自动检测系统深浅色模式
- 浅色模式：温馨米色调
- 深色模式：护眼深色调
- 每个页面支持
darkMode状态 - 使用
.theme-dark类名切换样式 - 导航栏、TabBar 颜色同步切换
- 使用微信小程序原生开发
- 使用
wx.setStorageSync / wx.getStorageSync - 本地状态统一从 storage 初始化
- 所有页面通过工具函数读写数据（utils/settings.js）
- 保留结构扩展性，为未来云同步预留接口
- 使用 WXS 处理模板内的数据格式化（如时间）
- 多用户同步
- 云数据库
- 图片长期存储
- 复杂分类 / 标签系统
第一版完成标准：
- ✅ 可新增 / 编辑 / 删除物品
- ✅ 可搜索
- ✅ 数据全部本地保存
- ✅ 支持深浅色主题
- ✅ 轻量级库存变更记录
- ✅ 存储空间管理
- ✅ 日常家庭使用无障碍
做到这里，即为成功版本。
新增功能：
- ✨ 支持特殊物品（有使用期限）管理
- ✨ 新增到期日期设置
- ✨ 首页分类展示（常规物品 / 特殊物品）
- ✨ 智能到期状态提醒（正常/警告/危险/已到期）
- ✨ 特殊物品智能排序（即将到期优先，已到期置底）
数据结构变更：
- 新增
isSpecial字段（是否为特殊物品） - 新增
expireAt字段（到期时间戳）
适用场景：
- 食品保质期管理
- 药品有效期管理
- 化妆品保质期管理
- 其他有时效性的物品
详细文档：
- 查看
docx/SPECIAL_ITEMS_FEATURE.md了解完整实现细节
核心功能：
- ✅ 物品增删改查
- ✅ 搜索功能
- ✅ 本地存储
- ✅ 主题切换
- ✅ 库存变更记录
- ✅ 存储管理