Resale Master JP - 日本转卖业务财务管理系统

一个面向日本二手转卖业务的私用财务管理 PWA。系统覆盖采购、库存、销售、退货、积分、耗材、买取价对比和税务报表，适合在桌面浏览器和 iPhone 主屏幕 PWA 中使用。

核心功能

交易与库存

• 批量库存管理：一笔采购可记录多个同款商品，支持分批销售、退货和在库统计。
• 混合支付录入：支持信用卡、积分、余额拆分，并自动校验支付合计。
• JAN 录入体验：支持条形码扫描、商品名自动补全（查每日同步的买取X 全量目录，查不到再走 search API 兜底，少量重试应对网络抖动）、Kaitorix 买取价格缓存与对比；店铺报价在日本时间昨天 0 点之前更新的不再作为参考。
• 离线只读：交易列表的数据会按用户缓存到本机（IndexedDB），断网后仍可查看，顶部显示「离线中 · 更新于…」；离线时不能修改数据；登出会清空本机缓存。联网访问过的页面可离线打开（页面缓存保留 30 天），从主屏幕离线启动会进入交易列表。目前交易列表（含平台名）、仪表盘、耗材、数据分析（预设时间范围）、税务报表和买取价格页支持离线数据，设置页与各表单离线时只能打开外壳。
• 出货方案 MCP：任意支持 MCP 的 AI 都能调用的三个工具——库存与利润概况、买取店规则、全局最优出货方案（原 ResaleAssist 的整数规划求解器，部署为 Vercel Python 函数）。
• 仪表盘（复刻买取X）：可按期间 / JAN / 进货来源 / 支付方式筛选的六张指标卡（投资额、回收额、确定利润、利润含预估、已售数量、库存），以及损益走势（ECharts，日线 / 周线 / 月线 K 线）。
• 利润算法与买取X 一致：利润由数据库触发器统一计算（网页与原生 App 同一口径），积分一律计入成本抵减，退货可填损失额，仪表盘 / 分析的确定利润扣除退货损失与经费。
• 导入导出（买取X 格式）：交易页导出 CSV（当前列表）/ XLSX（全部数据：进货・出售・退货・经费），设置页导入买取X 导出的文件或模板；有一处错整份不导入，重复的进货自动跳过。
• AI 分析数据导出：交易详情页 / 列表多选可一键复制 JSON（交易 + 销售 + 退货 + 买取价缓存），结构与原生 App 一致，可直接贴给 AI 或 ResaleAssist 做分析。
• 图片凭证：支持收据图片上传和 iPhone HEIC/HEIF 格式处理。
• 快速编辑：列表页可快速编辑高频字段，完整付款拆分与凭证走完整编辑页。
• 状态标签：交易列表默认显示「未售出」（未到货 + 库存中），并记住上次的选择；深链 ?tab= 优先。搜索落空时提供「在全部交易中查找」。

财务与运营

• 支付方式管理（设置页内）：信用卡与其他支付方式（PayPay、楽天ペイ、银行转账等，可一键添加常用项），配置返点率、卡号后 4 位、返点积分平台、默认支付方式和启用状态；店铺特殊规则可让同一支付方式在某个采购平台用不同返点率（如 Amazon 卡在 Amazon 返 3%），录入交易时自动套用。不管理还款周期。
• 积分平台系统：维护积分平台汇率，并纳入 ROI / 总利润计算。
• 耗材成本：记录包装材料、运输用品等成本，并纳入经营分析。

数据分析与税务

• 仪表盘：展示库存数、总投资额、已回收、确认利润、未回收库存、预期积分 / 本月利润等核心经营指标。
• 数据分析：按时间、平台、状态等维度查看业务表现。
• 税务申报：提供日本报税语境下的交易与利润报表导出能力，支持 Excel/PDF/CSV 相关导出。

技术栈

• 框架：Next.js 15 App Router + React 19 + TypeScript
• 样式：Tailwind CSS + app/globals.css 里的 SNUtils 风格 CSS 变量
• 图标：Fluent UI System Icons（@fluentui/react-icons，headless 版）
• 数据库与认证：Supabase Auth + PostgreSQL + Storage
• PWA：Manifest + Workbox Service Worker
• 图表与导出：ECharts（仪表盘）、Recharts（数据分析）、jsPDF、jspdf-autotable、XLSX
• 表格：@tanstack/react-table（headless）
• 数据请求缓存：@tanstack/react-query
• Service Worker：Workbox（InjectManifest，源码 lib/sw/sw-source.ts）
• 图片处理：heic2any
• 买取价：Kaitorix 官方 Open API（进入页面 / 手动刷新）+ 每日全量 CSV 同步（商品目录与价格历史）

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制 .env.local.example 为 .env.local：

cp .env.local.example .env.local

最小必需配置：

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

功能性配置：

KAITORIX_API_TOKENS=your_token1,your_token2
KAITORIX_OPEN_API_KEY=your_open_api_key
KAITORIX_OPEN_API_DAILY_LIMIT=500   # 仅首次响应前的兜底；之后以官方响应头为准
CRON_SECRET=your_random_secret      # /api/kaitorix/catalog-sync 的 Cron 鉴权

买取价与目录同步依赖 Kaitorix 官方 Open API（Premium 每日 500 次，每秒 1 次）；每日 CSV 同步需要「全部买取数据」下载加购。使用范围与出处标注要求见官方文档 https://kaitorix.app/open/docs 。

3. 初始化数据库

在一个全新的 Supabase 项目里，打开 SQL Editor，执行 supabase/schema.sql 即可，一个文件建好所有表、视图、触发器、RLS、Storage bucket 和内置平台数据。

supabase/migrations-archive/ 是历史增量记录，新装不需要执行。

注册第一个用户后，按 schema.sql 文件头的说明把它设为管理员。

4. 启动开发服务器

npm run dev

访问 http://localhost:3000。

项目结构

resale-master-jp/
├── app/
│   ├── layout.tsx                    # 根布局、主题初始化、PWA 注册
│   ├── manifest.ts                   # PWA Manifest
│   ├── globals.css                   # 设计 token 定义源和全局组件样式
│   ├── fluent-tokens.css             # Fluent / Loop 实测 token（浅色 / 深色）
│   ├── api/
│   │   ├── jan-product/[jan]/        # JAN 商品名补全（目录 → 缓存 → search API 兜底）
│   │   ├── kaitorix/                 # 买取价查询（[jan]）、强制刷新、Open API 用量、每日 CSV 同步（catalog-sync）
│   │   ├── thumbnail/enqueue/        # 商品缩略图抓取入队
│   ├── auth/                         # 登录、注册、OAuth 回调
│   ├── dashboard/                    # 仪表盘
│   ├── transactions/                 # 交易列表、新增、详情、编辑
│   ├── supplies/                     # 耗材成本管理
│   ├── analytics/                    # 数据分析
│   ├── tax-report/                   # 税务申报
│   └── settings/                     # 设置与支付方式管理
├── components/                       # 共用 React 组件
├── contexts/                         # AuthContext、PlatformsContext
├── hooks/                            # 自定义 hooks
├── lib/
│   ├── api/                          # 按业务域划分的 Supabase 调用
│   ├── financial/calculator.ts       # ROI 和利润计算
│   ├── supabase/client.ts            # Supabase SSR 客户端
│   ├── theme-mode.ts                 # 深浅色偏好（浅色 / 深色 / 跟随系统）
│   └── theme.ts                      # 共用 Tailwind class 片段
├── public/
│   ├── sw.js                         # Service Worker
│   ├── icons/                        # PWA 图标
│   └── fonts/                        # NotoSansJP（税务 PDF 导出用；界面用系统字体）
├── supabase/schema.sql               # 新装唯一入口（完整库结构）
├── supabase/migrations-archive/              # 历史增量记录（新装不需要）
├── scraper/                          # 独立服务：缩略图 worker；价格 scraper 仅为原生 App 保留
├── types/database.types.ts           # Supabase 类型定义
├── middleware.ts                     # 路由保护
└── tailwind.config.ts

This is the beginning of the README. Read the rest at the original. Read the full README ↗