root保质期提醒小程序 - 开发文档
项目概述
保质期提醒小程序是一款帮助用户管理家庭物品保质期的工具，支持食品、药品、化妆品等多种物品的记录和提醒。
文档索引
- PRD.md - 产品需求文档（功能范围、页面设计、数据模型）
- API.md - 接口文档（完整的 API 定义和示例）
- DEVELOPMENT.md - 开发指南（技术实现细节）
- ISSUES.md - 开发任务清单（按优先级拆分的 Issues）
快速开始
1. 数据库初始化
-- 创建物品表
CREATE TABLE expiry_items (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
user_id BIGINT UNSIGNED NOT NULL,
mini_program_id BIGINT UNSIGNED NOT NULL,
name VARCHAR(100) NOT NULL,
category VARCHAR(20) NOT NULL,
production_date DATE,
expiry_date DATE NOT NULL,
shelf_life_days INT,
quantity INT DEFAULT 1,
location VARCHAR(50),
remark VARCHAR(255),
status VARCHAR(20) DEFAULT 'normal',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
deleted_at TIMESTAMP NULL,
INDEX idx_user_expiry (user_id, expiry_date),
INDEX idx_user_category (user_id, category),
INDEX idx_user_status (user_id, status),
INDEX idx_deleted_at (deleted_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 创建用户设置表
CREATE TABLE expiry_user_settings (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
user_id BIGINT UNSIGNED NOT NULL UNIQUE,
remind_days JSON DEFAULT '[7,3,1]',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
2. 后端开发
参考现有模块结构（如 internal/smoke），创建 internal/expiry 目录：
internal/expiry/
├── handler.go # HTTP 处理器
├── service.go # 业务逻辑
├── model.go # 数据模型
└── repository.go # 数据访问层
3. 路由注册
在 internal/routes/routes.go 中注册路由：
expiry := r.Group("/api/expiry")
expiry.Use(middleware.AuthMiddleware())
{
expiry.GET("/summary", expiryHandler.GetSummary)
expiry.GET("/items", expiryHandler.GetItems)
expiry.POST("/items", expiryHandler.CreateItem)
expiry.PUT("/items/:id", expiryHandler.UpdateItem)
expiry.DELETE("/items/:id", expiryHandler.DeleteItem)
expiry.POST("/items/:id/status", expiryHandler.UpdateStatus)
expiry.GET("/settings", expiryHandler.GetSettings)
expiry.POST("/settings", expiryHandler.UpdateSettings)
}
4. 小程序端开发
参考 API 文档进行前端开发，主要页面：
pages/expiry/home- 首页pages/expiry/add- 添加/编辑物品pages/expiry/list- 全部物品列表pages/expiry/profile- 个人中心
MVP 功能清单
Phase 1: 核心功能（2-3天）
- 数据库表设计
- 后端 API 实现
- 物品 CRUD
- 汇总统计
- 用户设置
- 前端页面开发
- 首页（列表 + 统计）
- 添加/编辑页
- 全部物品页
Phase 2: 优化完善（1-2天）
- 状态计算逻辑优化
- 列表分页加载
- 左滑操作
- 空状态提示
- 错误处理
Phase 3: 测试上线（1天）
- 单元测试
- 接口测试
- 小程序端测试
- 部署上线
技术栈
后端:
- Go 1.23+
- Gin Web Framework
- GORM (MySQL)
- JWT 认证
前端:
- 微信小程序原生开发
- WeUI 组件库（可选）
数据库:
- MySQL 8.0+
开发规范
1. 代码风格
遵循项目现有代码风格：
- Go: 使用
gofmt格式化 - 变量命名：驼峰命名法
- 错误处理：统一使用
common.ErrorResponse
2. 提交规范
feat: 添加物品管理接口
fix: 修复过期日期计算错误
docs: 更新 API 文档
test: 添加物品服务单元测试
3. 分支管理
main: 生产环境develop: 开发环境feature/expiry-*: 功能分支
测试数据
测试物品
[
{
"name": "伊利纯牛奶",
"category": "food",
"expiry_date": "2026-03-10",
"quantity": 6,
"location": "冰箱"
},
{
"name": "感冒灵颗粒",
"category": "medicine",
"expiry_date": "2027-12-31",
"quantity": 1,
"location": "药箱"
},
{
"name": "雅诗兰黛面霜",
"category": "cosmetic",
"production_date": "2025-06-01",
"shelf_life_days": 1095,
"quantity": 1,
"location": "梳妆台"
}
]
常见问题
Q1: 如何计算过期状态？
后端统一计算 days_left = expiry_date - today，前端根据 days_left 显示颜色：
< 0: 红色（已过期）0-3: 橙色（即将过期）4-7: 黄色（临期）> 7: 绿色（正常）
Q2: 如何处理时区问题？
统一使用 UTC 时间存储，前端根据用户时区显示。
Q3: 软删除如何实现？
使用 GORM 的 deleted_at 字段，查询时自动过滤已删除数据。
联系方式
如有问题，请查看：