# K-Return-Book

**Repository Path**: Pridejoy/k-return-book

## Basic Information

- **Project Name**: K-Return-Book
- **Description**: > 记录你买过的每一件物品，算算它们每天花掉你多少钱。

一个纯本地存储的物品资产管理小程序：添加物品、自动计算使用天数与日均成本，让你直观看到"回本了没有"。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 归物本 return-book

> 记录你买过的每一件物品，算算它们每天花掉你多少钱。

一个纯本地存储的物品资产管理小程序：添加物品、自动计算使用天数与日均成本，让你直观看到"回本了没有"。

## ✨ 特性

- 📊 **统计看板**：物品件数、总消费、日均消费、使用天数，增删改实时刷新
- 📦 **物品管理**：名称、分类、购买日期、价格（赠品可留空）、保修日期、备注、图片（最多 3 张）
- 🏷️ **分类管理**：内置 8 个预置分类，支持自定义增删改；有物品的分类禁止删除
- 🔍 **筛选搜索**：分类横向筛选 + 名称搜索 + 按时间 / 价格 / 使用天数排序
- 💾 **数据备份**：一键导出 JSON 备份文件到微信聊天，支持覆盖 / 合并两种导入模式
- 🔒 **隐私优先**：数据仅存微信本地缓存，不上传任何服务器，无账号无登录
- 🧮 **精度保证**：金额全程以「分」为整数计算存储，杜绝浮点累加误差

## 🛠 技术栈

| 项 | 选择 |
|---|---|
| 框架 | Taro 4 + React 18 |
| 语言 | TypeScript |
| 状态管理 | Zustand（含 storage 持久化） |
| 样式 | SCSS + CSS Modules |
| 目标平台 | 微信小程序（可扩展至支付宝 / H5） |

## 🚀 快速开始

```bash
# 安装依赖
npm install

# 开发模式（文件变更自动重编译）
npm run dev:weapp

# 生产构建
npm run build:weapp
```

构建产物输出至 `dist/`，用微信开发者工具导入 `dist` 目录即可预览。

## 📁 目录结构

```
src/
├── app.tsx / app.config.ts     # 入口与全局配置（页面路由、TabBar）
├── types/index.ts              # Item / Category / Meta / BackupData 类型
├── utils/
│   ├── storage.ts              # storage 封装 + 首次启动初始化（幂等）
│   ├── calc.ts                 # 使用天数 / 日均成本等统计公式
│   ├── money.ts               # 元 ↔ 分换算与格式化
│   └── backup.ts               # 备份导出 / 导入 / 白名单校验
├── store/useAppStore.ts        # Zustand 全局状态 + 持久化
├── components/                 # StatPanel / ItemCard / EmptyState
└── pages/
    ├── index/                  # 首页（Tab）：看板 + 筛选 + 列表
    ├── settings/               # 设置（Tab）：备份导入导出
    ├── item-form/              # 添加 / 编辑物品（复用）
    ├── item-detail/            # 物品详情
    └── category/               # 分类管理
scripts/
└── gen-tabbar-icons.js         # 纯 Node 生成 tabBar PNG 图标
```

## 🧮 计算规则

```
使用天数   = 今天 − 首次使用日期 + 1（当天记 1 天）
日均消费   = 总消费金额 ÷ 使用天数
物品已用   = 今天 − 购买日期 + 1
日均成本   = 购买价格 ÷ 已使用天数（未填价格显示 --）
```

- 首次使用日期在应用首次启动时写入本地存储
- 未填写价格的物品不计入总消费
- 备份导入（合并模式）时，首次使用日期取更早者，保证天数不被缩短

## 💾 数据与备份

数据保存在微信本地缓存（`Taro.setStorageSync`），key 约定：

| Key | 内容 |
|---|---|
| `returnbook_items` | 物品列表 |
| `returnbook_categories` | 分类列表 |
| `returnbook_meta` | 首次使用日期等元信息 |

备份文件为 JSON，结构如下：

```jsonc
{
  "version": 1,
  "exportedAt": 1735689600000,
  "categories": [{ "id": "cat_xxx", "name": "电子产品", "createdAt": 1630972800000 }],
  "items": [
    {
      "id": "1776749042764",
      "name": "手机-GT8Pro",
      "categoryId": "cat_xxx",
      "purchaseDate": "2025-12-06",
      "price": 400000,          // 单位：分
      "remark": "",
      "images": [],
      "createdAt": 1776749042764,
      "updatedAt": 1776749042764
    }
  ],
  "meta": { "firstOpenDate": "2021-09-07" }
}
```

导入时执行字段白名单校验，损坏文件不会污染现有数据。

## ⚠️ 已知限制

- 数据仅存本地：清微信缓存 / 换机 / 卸载小程序会丢数据，请定期导出备份
- 图片保存在本地文件目录，清理缓存后显示占位图（文字数据不受影响）

## 🗺 Roadmap

- [ ] 物品状态流转（在用 / 出售 / 报废）
- [ ] 月度消费报表
- [ ] 多端适配（支付宝小程序 / H5）

## 🤝 贡献

欢迎 Issue 与 PR。提交前请确保 `npm run build:weapp` 编译通过。

## 📄 License

[MIT](./LICENSE)