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

打卡结算

ui设计工具：即时设计

小程序框架：uniapp

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

数据库：mysql

数据库备份工具：gobackup

待增加功能

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

系统功能

基本概念

打卡

• 打卡规则：计时、计数、单次打卡（计数的特例，只需计一次数）
• 单位：次数、分钟
• 比较规则：大于等于、小于等于
• 比较的目标：用于判断是否完成打卡；一般情况下，只有一个比较目标1；但是启用法定节假日的话，还有一个难度比较低的比较目标2，用于判断比较
• 重复频率：每日、法定工作日、法定节假日（含周末）、自定义（周一至周日）
• 全勤周期：每周、每月
• 打卡任务分类：
  • 普通打卡任务：没有明确的结束时间，任务永远不会结束
  • 任务式打卡任务：有明确的结束时间，任务到期自动结束并进行归档

获取积分奖励的方式

1. 单个任务完成打卡则给予奖励
2. 单个任务法定节假日（含周末）双倍奖励
3. 单个任务全勤双倍奖励，即在一个周期内打卡完成率在容错范围内则给予奖励
4. 单个任务连续完成打卡则给予奖励，按照连续打卡完成天数超过N天进行计算
5. 多个任务完成打卡则给予奖励，按照打卡完成数超过固定值进行计算
6. 多个任务连续完成打卡则给予奖励，按照连续打卡完成数超过固定值的天数进行计算

结算规则

注：在连续完成的时候，需要关注的是完成的天数，其它不用理会

积分计算公式

单个任务积分=基本积分+（可选）额外积分+（可选）连续完成额外积分+法定节假日（含周末）双倍奖励+全勤双倍奖励

多个任务积分=多任务额外积分+连续完成额外积分

总积分=单个任务积分+（可选）多个任务积分

说明：

• 基本积分：满足打卡比较条件就能获得基本积分

• 额外积分：根据新的比较单位（X次，Y分钟，完成数、完成率）进行判断，完成一次就获得一次额外积分

  • 固定积分：额外打一次卡就给一次固定积分，本质是动态积分的特例

  例子：打卡10次，前5次是基本的，后5次是额外的，积分区间：基本积分5；x＞5，奖励积分10；其中的x是打卡次数。共计积分：5+5x5=30积分

  • 动态积分：根据不同的区间，给对应的积分

  例子：打卡10次，前5次是基本的，后5次是额外的，积分区间：基本积分5；6≤x≤8，奖励积分10；9≤x≤10，奖励积分15；其中的x是打卡次数。共计积分：5+10x3+15x2=65积分

（可选）前置判断：

1. 开始前有连续N天，不结算积分

2. 中途没有完成打卡则重新开始

如果没有完成的天数小于等于N天，则有连续Y天不结算积分（等同于一个小的开始，Y自己设置）

如果大于N天，则等同于任务重新开始

注：可以应用在单个任务，也可以应用在多个任务

积分账户

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

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

按页面划分

当前任务视图（主页）

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

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

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

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

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. 查询当前待使用的积分数、刮刮卡的投入与产出、已消耗积分数与总积分数的比值

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

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

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

2. 查询当前用户的投入刮刮乐信息，并允许撤销

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

3. 转账记录

系统

定时任务

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

运维接口

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)	微信小程序openId
nickname	varchar(100)	昵称
total_points	int	总积分
unused_points	int	未使用积分
used_points	int	已使用积分
total_consume_amount	decimal(10,2)	总消费金额(元)
total_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)	任务名称
description	varchar(300)	任务描述
points	int	奖励的积分（基本）
end_date	date	结束日期
archive_status	varchar(10)	是否归档(活跃-ACTIVE，归档-ARCHIVE)
display_order	int	显示顺序
display_time	time	显示时间
category	varchar(10)	打卡类型(单次打卡-SINGLE，计数-COUNT、计时-TIMING)
compare_rule	varchar(10)	比较规则(大于等于-GTE，小于等于-LTE)
count_track	int	次数记录
time_track	time	时间记录
second_count_track	int	次数记录（节假日用）
second_time_track	time	时间记录（节假日用）
holiday_status	varchar(10)	是否启用节假日奖励(ENABLED-启用，DISABLED-关闭)
full_attendance_status	varchar(10)	是否启用全勤奖励(ENABLED-启用，DISABLED-关闭)
full_attendance_period	varchar(10)	全勤周期（周-WEEK，月-MONTH）
full_attendance_fault_tolerance_cnt	int	全勤容错次数
repeat_category	varchar(10)	重复周期类型（每日-EVERYDAY、法定工作日-WORKDAY、法定节假日（含周末）-HOLIADY、自定义（周一至周日）-CUSTOM）
repeat_custom_day	varchar(13)	自定义重复日（周一-1,周二-2,周三-3,周四-4,周五-5,周六-6,周日-7）
grace_status	varchar(10)	是否启用宽限期(ENABLED-启用，DISABLED-关闭)
grace_day	int	宽限期（单位：天）
interrupted_day	int	完成打卡中断天数（单位：天）
penalty_day	int	惩罚天数（单位：天）
created_by	bigint	创建人	普通索引
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务额外结算配置表

表名：punch_in_extra_settlement_config

字段	类型	描述	索引
id	bigint	主键	主键索引
punch_in_id	bigint	打卡任务ID	普通索引
extra_settlement_method	varchar(10)	额外奖励结算方式（无-NONE，固定-FIXED，区间-INTERVAL）
extra_count_step	int	额外的次数间隔
extra_time_step	time	额外的时间间隔
initial_value	int	起始值（单位：次）
extra_points	int	奖励的积分（额外）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务配置表

表名：punch_in_task_config

字段	类型	描述	索引
id	bigint	主键	主键索引
punch_in_id	bigint	打卡任务ID	普通索引
grace_status	varchar(10)	是否启用宽限期(ENABLED-启用，DISABLED-关闭)
grace_day	int	宽限期（单位：天）
interrupted_day	int	打卡中断天数（单位：天）
penalty_day	int	惩罚天数（单位：天）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

打卡任务额外结算配置表

表名：punch_in_task_extra_config

字段	类型	描述	索引
id	bigint	主键	主键索引
punch_in_id	bigint	打卡任务ID	普通索引
extra_settlement_method	varchar(10)	额外奖励结算方式（无-NONE，固定-FIXED，区间-INTERVAL）
initial_value	int	起始值（单位：天）
extra_points	int	奖励的积分（额外）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

多打卡任务配置表（单次）

表名：punch_in_task_config

字段	类型	描述	索引
id	bigint	主键	主键索引
category	varchar(10)	计算方式（次数-COUNT，比率-RATE）
punch_in_count	int	完成打卡次数
punch_in_rate	decimal(5,2)	完成率
points	int	奖励的积分（基本）
grace_status	varchar(10)	是否启用宽限期(ENABLED-启用，DISABLED-关闭)
grace_day	int	宽限期（单位：天）
interrupted_day	int	打卡中断天数（单位：天）
penalty_day	int	惩罚天数（单位：天）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

多打卡任务额外结算配置表（单次）

表名：punch_in_task_extra_config

字段	类型	描述	索引
id	bigint	主键	主键索引
punch_in_id	bigint	打卡任务ID	普通索引
extra_settlement_method	varchar(10)	额外奖励结算方式（无-NONE，固定-FIXED，区间-INTERVAL）
initial_value	int	起始值（单位：天）
extra_points	int	奖励的积分（额外）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

多打卡任务配置表（连续）

表名：punch_in_task_config

字段	类型	描述	索引
id	bigint	主键	主键索引
points	int	奖励的积分（基本）
grace_status	varchar(10)	是否启用宽限期(ENABLED-启用，DISABLED-关闭)
grace_day	int	宽限期（单位：天）
interrupted_day	int	打卡中断天数（单位：天）
penalty_day	int	惩罚天数（单位：天）
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

多打卡任务额外结算配置表（连续）

表名：punch_in_task_extra_config

字段	类型	描述	索引
id	bigint	主键	主键索引
			普通索引
extra_settlement_method	varchar(10)	额外奖励结算方式（无-NONE，固定-FIXED，区间-INTERVAL）
initial_value	int	起始值（单位：天）
extra_points	int	奖励的积分（额外）
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-已删除）

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

表名：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-已删除）

消费与中奖记录

表名：consume_win_history

字段	类型	描述	索引
id	bigint	主键	主键索引
action	varchar(30)	动作（消费-CONSUME，中奖-WIN，撤销消费-REVERSE_CONSUME，撤销中奖-REVERSE_WIN）
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	varchar(10)	状态(ENABLED-启用，DISABLED-失效)
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	数据类型（STRING-字符串，INTEGER-整型数值）
item_code	varchar(100)	字典项编码	普通索引
item_name	varchar(100)	字典项名称
description	varchar(200)	描述
status	varchar(10)	状态(ENABLED-启用，DISABLED-失效)
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

账户

表名：account

字段	类型	描述	索引
id	bigint	主键	主键索引
user_id	bigint	用户id	普通索引
account_name	varchar(100)	账户名称
account_type	varchar(30)	账户类型（BASIC-基本户，GENERAL-一般户）
points	int	奖励积分
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

账户转账记录

表名：account_transfer_history

字段	类型	描述	索引
id	bigint	主键	主键索引
user_id	bigint	用户id	普通索引
sender_account_id	bigint	转出账户id
recipient_account_id	bigint	转入账户id
transfer_points	int	转账积分
sa_points_before_transfer	int	转出账户转出前积分
sa_points_after_transfer	int	转出账户转出后积分
ra_points_before_transfer	int	转入账户转入前积分
ra_points_after_transfer	int	转入账户转入后积分
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

奖励

表名：rewards

字段	类型	描述	索引
id	bigint	主键	主键索引
user_id	bigint	用户id	普通索引
reward_name	varchar(100)	奖励名称
exchange_points	int	兑换所需积分
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

奖励与账户关联表

表名：rewards_account_rela

字段	类型	描述	索引
id	bigint	主键	主键索引
user_id	bigint	用户id	普通索引
rewards_id	bigint	奖励id
account_id	bigint	账户id
created_by	bigint	创建人
creation_time	timestamp	创建时间
last_updated_by	bigint	最后更新人
last_update_time	timestamp	最后更新时间
version	bigint	版本号
delete_flag	tinyint	逻辑删除标志（0-未删除，1-已删除）

奖励兑换记录

表名：rewards_account_rela

字段	类型	描述	索引
id	bigint	主键	主键索引
user_id	bigint	用户id	普通索引
rewards_id	bigint	奖励id
reward_name	varchar(100)	奖励名称
exchange_points	int	兑换所需积分
account_id	bigint	兑换使用的账户id
account_name	varchar(100)	账户名称
account_points_before_exchange	int	兑换前账户中的积分
account_points_after_exchange	int	兑换后账户中的积分
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 如何将枚举类型在类中进行自动转换