PunchSettle-Server/doc/技术文档.md

打卡结算

ui设计工具：即时设计

小程序框架：uniapp

后端框架：spring boot + mybatis + tk mybatis+ spring mvc

数据库：mysql

数据库备份工具：gobackup

待增加功能

1. 结算规则要支持节假日补充规则
2. 打卡任务的年视图的统计功能

系统功能

基本概念

打卡结算

• 打卡规则：计时、计数、单次打卡（计数的特例，只需计一次数）

• 计量单位：次数、分钟（自己设置）

• 结算周期：日、周、月、季、半年、年、用户自定义

• 根据有没有结束时间分类：

  • 任务式打卡任务（有结束时间）
  • 普通打卡任务（没有结束时间）

• 奖励规则：

  1. 结算则给予奖励
  2. 完成则给予奖励
     • 在打卡任务结束时，给予奖励
     • 在周期结束时，给予奖励
  3. 按日期不同给予奖励-按照工作日、周末、法定节假日 给予不同的奖励

• 结算规则

  • 普通结算-满足比较条件就给予奖励，比较条件：大于等于、小于等于

  • 额外奖励-满足基本之后，打一次卡就有一次额外奖励

  • 分段式结算

  阶梯区间1-不同区间有不同的结算奖励

  阶梯区间2-不同区间有不同的结算奖励

  以此类推

  • 前置式结算-有一个起步时间，过了这个时间才会真正有结算奖励
  • 完美式结算-在指定时间段范围内，只要有一个没有打卡则全部失败

积分账户

• 基本户：用于结算积分转入，或者兑换奖励

• 一般户：专项专用，只能兑换指定奖励

按页面划分

当前任务视图（主页）

1. 查询当前待使用的积分数、刮刮卡的投入与产出、已消耗积分数与总积分数的比值

2. 查询当前用户待打卡的打卡任务列表

显示内容：任务名称、任务描述、奖励数、全勤奖励标识、周末奖励标识、本周打卡记录，今日打卡情况

说明：今日打卡情况未完成时的状态，根据不同的打卡类型有不同的显示

• 打卡类型：单次打卡，未完成则显示“完成”
• 打卡类型：计数，未完成则显示“计数”，并且显示当前已打卡次数
• 打卡类型：计时，未完成则显示“计时”，并且显示当前已记录的打卡时间

1. 新建打卡任务

任务列表

1. 查询打卡任务列表

2. 新建/编辑打卡任务

   • 需要要任务排序功能
   • 任务显示控制，可以控制过了某个时间点才出现，不要一下子就把当天的都列出来

3. 删除任务

4. 打卡

5. 补打卡

对于不同的打卡类型，都是默认直接完成打卡

如果完全没有打过卡：按照当时的打卡规则，直接生成一条新的打卡记录和结算记录

如果打过卡但是未完成的

• 对于单次打卡：不存在这种情况
• 对于计数打卡：修改打卡记录的数据并记录修改值和对应的状态位，修改结算记录并记录修改值和对应的状态位
• 对于计时打卡：修改打卡记录的数据并记录修改值和对应的状态位，修改结算记录并记录修改值和对应的状态位

1. 误打卡撤销

有两种情况：

1. 当天撤销

   对于单次打卡：直接删除打卡记录即可

   对于计数打卡：直接扣减次数（-1）即可，次数变成0即删除打卡记录

   对于计时打卡：直接删除打卡记录即可，然后重新再打卡即可

2. （这种情况应该不存在，打卡当时应该就能即时处理不会留到结算后）结算后撤销，对于不同的打卡类型，都是默认直接没有打过卡

   删除对应记录，根据对应任务反向计算即可，并记录修改值和对应的状态位

3. 归档

打卡任务详情页

针对单一任务查询时间范围内的打卡信息

显示内容：具体到天是否已打卡、打卡记录、打卡统计（打卡次数、全勤率）

注意：这里在表增加一个状态值辅助判断

数据

1. 图表-积分变动表（增加、消耗）
2. 图表-任务完成数
3. 图表-某一天完成的打卡任务（通过日历选中）
4. 图表-新用户，特权用户专属，看一下新用户的增加率
5. 打卡任务的年视图的统计功能
6. 增加刮刮乐刮次数的平均中奖记录、投入与产出比
7. 增加自定义报表，能够自主选择是否显示报表

积分商城

1. 兑换奖励列表（名称、所需积分），

已知奖励：

• 双色球：增加号码自动生成

• 大乐透：增加号码自动生成

• 刮刮乐

1. 创建奖励

2. 删除奖励

3. 兑换奖励

4. 创建一般户

5. 一般户关联指定奖励

6. 删除一般户，删除时要把与指定奖励的关联关系也删除，并且把积分转入一般户

7. 一般户与基本户的积分互转，需要记录对应的转积分日志

用户中心

1. 微信用户登录，简单记录昵称和openId即可

2. 昵称修改

3. 注销

4. 免责声明页面

5. 关于我们页面

6. 结算日志：按时间范围查询当前用户的结算记录

7. 查询当前用户拥有的奖励数

显示内容：总奖励数、已领取奖励数、待领取奖励数

1. 按时间范围查询当前用户的领取奖励记录

2. 查询当前用户的投入刮刮乐信息

显示内容：投入金额、中奖金额

1. 追加投入金额记录/中奖记录

2. 撤销投入金额记录/中奖记录

3. 按时间范围的刮刮乐查询记录

   显示内容：投入金额记录、中奖记录

系统

定时任务

1. 自动结算定时任务
2. 自动打卡定时任务，要考虑怎么分辨没有打卡的问题
3. 自动兑换定时任务
4. 自动归档定时任务

运维接口

1. 清除缓存
2. 调起定时任务
3. 手动结算接口，需要防止重复手动结算

字典

刮刮乐来源

字典名称：刮刮乐来源

字典编码：LOTTERY_SCRATCH_SOURCE

字典项：

字典项编码	字典名称
WELFARE_SCRATCH	福利彩票
SPORTS_SCRATCH	体育彩票

福利彩票刮刮乐种类

字典名称：福利彩票刮刮乐种类

字典编码：WELFARE_SCRATCH

字典项

字典项编码	字典名称
XINGYUN88	幸运88
CHAOGEILI	超给力
XIXIANGFENG	喜相逢

体育彩票刮刮乐种类

字典名称：体育彩票刮刮乐种类

字典编码：SPORTS_SCRATCH

字典项

字典项编码	字典名称

刮刮乐动作类型

字典名称：刮刮乐动作类型

字典编码：SCRATCH_ACTION_TYPE

字典项

字典项编码	字典名称
0	投入
1	中奖

启用状态标志

字典名称：启用状态标志

字典编码：ENABLE_STATUS

字典项

字典项编码	字典名称
0	关闭
1	启用

打卡类型

字典名称：打卡类型

字典编码：PUNCH_IN_CATEGORY

字典项

字典项编码	字典名称
0	单次打卡
1	计数
2	计时

打卡比较规则

字典名称：打卡比较规则

字典编码：PUNCH_IN_RULE

字典项

字典项编码	字典名称
0	大于等于
1	小于等于

表设计

用户表

表名：user

字段	类型	描述
id	bigint	主键
open_id	varchar(128)	微信id
nickname	varchar(100)	微信昵称
avatar	varchar(1000)	微信头像url
total_reward_num	int	总奖励数
unclaimed_reward_num	int	未领取奖励数
claimed_reward_num	int	已领取奖励数
lottery_invest_amount	decimal(10,2)	彩票投入金额(元)
lottery_win_amount	decimal(10,2)	彩票中奖金额(元)
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务表

表名：punch_in

字段	类型	描述
id	bigint	主键
task_name	varchar(128)	任务名称
reward_num	int	奖励倍数
category	int	打卡类型(0-单次打卡，1-计数、2计时)
rule	int	比较规则(0-大于等于，1-小于等于)
count_track	int	次数记录
time_track	time	时间记录
description	varchar(300)	任务描述
weekend_double_flag	tinyint	是否启用周末双倍标志(0-不是，1-是)
full_attendance_flag	tinyint	是否启用全勤奖励标志(0-不是，1-是)
archive_flag	tinyint	是否归档标志(0-不是，1-是)
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务记录表

表名：punch_in_record

字段	类型	描述
id	bigint	主键
punch_in_id	bigint	打卡任务表主键
punch_in_date	varchar(10)	打卡日期
count_track	int	次数记录
time_track	time	时间记录
settle_reward_num	int	结算时任务上的奖励倍数
settle_category	int	结算时任务上的打卡类型(0-单次打卡，1-计数、2计时)
settle_rule	int	结算时任务上的比较规则(0-大于，1-大于等于，2-小于，3-小于等于)
settle_count_track	int	结算时任务上的次数记录
settle_time_track	time	结算时任务上的时间记录
punch_in_status	int	打卡状态(0-进行中，1-完成，2-未完成) ，结算后修改状态，单次打卡除外
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务结算表

表名：punch_in_settlement

字段	类型	描述
id	bigint	主键
user_id	bigint	用户表主键
settle_reward_num	int	结算奖励数
before_settle_reward_num	int	结算前用户拥有的奖励数
after_settle_reward_num	int	结算后用户拥有的奖励数
settlement_task_id	bigint	结算任务表id
settlement_time	timestamp	结算时间
notify_id	bigint	通知表ID
notify_status	varchar(20)	结算通知状态(fail-通知失败，success-成功通知，pending-待通知)
notify_time	timestamp	结算通知时间
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务记录与结算关联表

表名：punch_in_record_settlement_rela

字段	类型	描述
id	bigint	主键
record_id	bigint	打卡任务记录表ID
settlement_id	bigint	打卡任务结算表ID
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

领取奖励记录表

表名：user_claim_reward_record

字段	类型	描述
id	bigint	主键
claim_reward_num	int	本次领取奖励数
claim_reward_time	timestamp	领取奖励时间
before_claim_reward_num	int	领取前用户拥有的奖励数
after_claim_reward_num	int	领取后用户拥有的奖励数
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

奖励结算定时任务执行记录表

表名：settlement_task

字段	类型	描述
id	bigint	主键
settle_date	varchar(10)	结算日期
start_time	timestamp	任务开始时间
end_time	timestamp	任务结束时间
processed_num	int	待处理结算数量
processed_settle_num	int	处理已结算数量
processed_unsettle_num	int	处理没结算数量
error_message	text	失败异常信息
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

通知定时任务执行记录表（暂时无用）

表名：settlement_notify_task

字段	类型	描述
id	bigint	主键
start_time	timestamp	任务开始时间
end_time	timestamp	任务结束时间
notify_num	int	通知数量
notify_success_num	int	通知成功数量
notify_fail_num	int	通知失败数量
error_message	text	失败异常信息
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

彩票刮刮乐记录

表名：lottery_scratch_record

字段	类型	描述
id	bigint	主键
action_type	int	动作类型(0-投入/购买，1-中奖，2-撤销投入，3-撤销中奖)
source	varchar(100)	彩票来源
category	varchar(100)	彩票种类
amount	decimal(10,2)	金额（元）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

系统字典表

表名：sys_dict

字段	类型	描述
id	bigint	主键
dict_code	varchar(100)	字典编码
dict_name	varchar(100)	字典名称
description	varchar(200)	描述
status	int	状态(1-启用，0-失效)
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

系统字典项表

表名：sys_dict_item

字段	类型	描述
id	bigint	主键
dict_id	bigint	字典表主键
data_type	int	数据类型（0-String，1-Number）
item_code	varchar(100)	字典项编码
item_name	varchar(100)	字典项名称
description	varchar(200)	描述
status	int	状态(1-启用，0-失效)
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更信人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

开发参考

• 两种优雅的获取当前登录用户ID的方式
• 学会自己编写Mybatis插件（拦截器）实现自定义需求
• Mybatis拦截器教程及几个实用自定义拦截器分享
• tk.mybatis 2.1.15 如何将枚举类型在类中进行自动转换