# 13 积分（心愿值）体系（for AI Agents）

> 关联代码：internal/service/points/（含 EventBus）、internal/model/points.go
> 管理端页面：web/src/views/points/；小程序页面：pages/points/*、pages/recharge/*
> 用户侧营销名：积分 = 心愿值；充值所得 = 好运币（points_recharge 100:1 入账）

====================================================================
1. 功能概述
====================================================================

积分（UserPoints，营销名「心愿值」）是用户行为激励通货：签到、做任务、参与玩法获得；消耗于幸运抽奖、心愿兑换助力（见 04）、商城积分兑换（见 12）、优惠券兑换。账本设计与现金钱包同构（幂等流水）。

积分来源/去向全景：
- 获得：每日签到（规则可配）、任务完成、签到抽奖每日签到积分、新用户赠 points.newuser_grant、充值转换（好运币 100:1）、后台手动调整。
- 消耗：幸运抽奖（见 07）、心愿兑换助力值（见 04）、商城积分兑换商品/券（见 12）。

====================================================================
2. 底层逻辑
====================================================================

2.1 模型
- UserPoints：余额 + 累计获得/消耗。
- PointsTransaction：流水；类型 earn/spend/admin_adjust；业务标识（checkin/task/admin/order + Code 任务码）；幂等键设计同 MoneyLog。
- 等级展示：用户等级 Level = floor(心愿值余额/100)+1（小程序「我的」页 Lv 展示）。

2.2 签到与任务
- 签到规则：按连续天数阶梯发分（后台行内编辑「第 N 天/奖励积分/启用」）。
- 任务：后台完整 CRUD（code 唯一标识/标题/类型/奖励/阈值/事件触发/跳转路径/排序/启用）；小程序按 link_path 跳转承载页完成。
- EventBus：中奖/待填地址等业务事件 → 通知服务与任务服务消费（常驻进程）。

2.3 充值（好运币）
- pages/recharge/index/index：档位选择 → 微信支付（订单 ProductType=points_recharge）→ 回调按档位 points 字段入账积分。
- 充值配置（KV 键 "recharge"）：enabled 开关 + tiers 数组（每档 amount_fen/points）。默认 4 档（1/5/10/30 元），赠送好运币按最低档位基准汇率动态计算（BaseTier→BonusFor），超出基准汇率的部分即为赠送。后台「充值配置」页可编辑档位与开关；功能开关总览页可一键关闭充值入口。

====================================================================
3. 后台操作（积分管理菜单）
====================================================================

3.1 签到规则 /points/checkin（CheckinRules.vue）
- 表格列：第N天/奖励积分/操作。
- 行内编辑 + 「保存」「删除」「新增一行」。

3.2 任务配置 /points/tasks（TaskConfigs.vue）
- 表格列：标题/描述/奖励/阈值/事件触发/跳转路径/排序/启用/操作。
- 完整 CRUD：「新增任务」弹窗（Code 唯一标识/标题/类型 一次性|每日|累计/描述/图标/奖励积分/阈值/事件触发下拉/跳转路径/排序/启用）；行内编辑所有字段 + 行保存（PATCH）；行删除（确认弹窗）。
- 事件触发选项：share.created / order.paid / invite.bound / prize.won / order.shipped / prize.await_address / assist.done / lottery.cancelled。

3.3 用户积分 /points/users（UserPoints.vue）
- 筛选：搜索用户；表格列：用户/积分余额/累计获得/累计消耗。
- 行操作：「调整积分」弹窗（正负变动 + 原因必填）。
- 也可从小程序用户列表「更多→积分」进入同一能力。

3.4 积分流水 /points/transactions（Transactions.vue）
- 筛选：搜索用户、类型（earn/spend/admin_adjust/...）、业务（checkin/task/admin/order）。
- 表格列：用户/变动/余额/类型/业务/备注/创建时间；只读分页。

3.5 积分排行 /points/leaderboard（Leaderboard.vue）
- 表格列：排名/用户/积分余额；按余额排名只读分页。

3.6 后台操作逻辑备注（隐藏约束，UI 不直接体现）
- 手动调整积分：POST /points/adjust 要求 delta≠0 且 reason 必填；admin_adjust 流水不纳入 total_earned/total_spent 统计（这两个字段仅记录业务路径的累计，人工调整直接改余额但不影响累计值）。
- 签到连签逻辑：每日签到判断「昨天是否签到」→ 连签天数 +1；若昨天未签则连签重置为 1（非累计）。同一天重复签到返回 2152「今日已签到」。
- 任务 code 唯一标识：后台支持新增任务（POST /admin/tasks，需指定唯一 code），也可编辑和删除已有任务；code 是主键，创建后不可修改。
- 等级计算：Level = floor(心愿值余额/100)+1，仅在 earn 路径（签到/任务/充值/管理员调整正数）时重新计算并写入；spend 路径不触发等级重算。调整积分会立即影响「我的」页等级展示。
- 签到规则变更不追溯：修改签到规则（如第 N 天奖励积分）对已发生的签到记录不生效；只影响后续签到。

====================================================================
4. 小程序端操作
====================================================================

- pages/points/index/index：心愿值中心（余额+流水+签到/任务/幸运抽奖入口）。
- pages/points/checkin/index：签到日历、签到按钮、任务列表、兑换记录/流水入口。
- pages/points/tasks/index：任务列表（link_path 跳转承载页，如首页停留类任务）。
- pages/points/transactions/index：流水分页。
- pages/points/exchange-records/index：积分兑换记录（商城兑换单）。
- pages/recharge/index/index：好运币充值（档位+微信支付）。
- 首页签到卡片（文案后台「签到卡片文案」配置）快捷入口。

====================================================================
5. API 速查
====================================================================

小程序端（/api/mp）：
GET  /api/mp/points/me                  我的积分
GET  /api/mp/points/transactions        我的流水
GET  /api/mp/points/checkin/status      签到状态（连签/今日是否已签）
POST /api/mp/points/checkin             每日签到
GET  /api/mp/points/tasks               任务列表
GET  /api/mp/recharge/tiers；POST /api/mp/recharge   好运币充值档位/下单

管理端（/api/admin，权限 points:*）：
GET  /api/admin/points/users/:id        用户积分
GET  /api/admin/points/transactions     全站流水
GET  /api/admin/points/rank             排行
GET|POST|DELETE /api/admin/checkin/rules(:id)   签到规则（PUT 经 POST 列表接口）
GET  /api/admin/tasks；POST /api/admin/tasks；PATCH /api/admin/tasks/:code；DELETE /api/admin/tasks/:code   任务配置 CRUD
POST /api/admin/points/adjust           手动调整（正负+原因）

====================================================================
6. 注意事项
====================================================================

- 积分与现金是两个账本：积分不可提现、不可转余额；处理客诉退款时现金走钱包 adjust、积分走 points/adjust，别混。
- 任务支持后台完整 CRUD：可新增（指定唯一 code）、编辑、删除任务类型；code 是主键创建后不可改。
- 充值档位与赠送可在后台编辑：默认 4 档（1/5/10/30 元），赠送按最低档位基准汇率动态计算；充值入口可通过功能开关总览一键关闭。充值订单退款退积分（见 11）。
- 签到规则变更对已发生的签到不追溯；阶梯按「连续签到天数」解释口径先核对实现。
- 小程序「我的」页等级 Level 由余额实时计算，调整积分会立即影响等级展示。
