feat: 接入积分服务端真实接口并完成隔离联调
新增积分服务端接口封装、积分中心页面，支持登录回跳、签到恢复、积分明细等功能。清理缓存时保留未确认签到键，新增ApiRequestError错误类型区分业务状态，更新开发文档记录积分页面联调完成情况。
This commit is contained in:
hujun
+21
-13
@@ -1,10 +1,18 @@
|
||||
# 积分规则与开发契约
|
||||
|
||||
记录日期：2026-10-01。版本：points-backend-20261001-v2。状态：**后端及真实HTTP隔离开发检查完成，业务规则未定稿，默认不入账，原表未迁移、未部署**。归属既有 POINT-001—004，不新增任务编号。POINT-002保持开发中；DEC-POINT/POINT-001仍待确认，POINT-003未实施，POINT-004页面尚未接真实积分。
|
||||
记录日期：2026-10-02。版本：points-page-20261002-v3。状态：**后端已随5fee3cf部署、积分页面读取与恢复隔离联调通过；业务规则未定稿，正式配置关闭，原表未迁移、前端未发行**。归属既有 POINT-001—004，不新增任务编号。POINT-002/004保持开发中；DEC-POINT/POINT-001仍待确认，POINT-003未实施。
|
||||
|
||||
本文件作为积分实施入口；数据库具体增量见[积分数据库方案](D:/AAdesk/202609/airz/database/points-design.md)。接口源码与真实HTTP隔离检查已完成，未部署；页面仍是本机体验签到。未获规则确认时不填真实奖励，配置默认false/null。
|
||||
本文件作为积分实施入口；数据库具体增量见[积分数据库方案](D:/AAdesk/202609/airz/database/points-design.md)，最新页面状态与证据见[开发进度0.51](开发进度.md)。未获规则确认时不填真实奖励，配置默认false/null；合成联调不代表正式积分可用。
|
||||
|
||||
## 0. 最新协议与隔离开发检查
|
||||
## 0. 最新页面恢复与隔离联调
|
||||
|
||||
页面主流程98项/127次积分请求和补充81项/81次积分请求通过，共201次进入本机真实PHP/MySQL、7次受控故障/网络中断。覆盖真实丢响应后原键确认、跨接口一致性、读取失败时确认入口、确定拒绝弃键、坏回执保键、账户切换及迟到401；登录响应只为合成认证，真机、生产迁移与正式发布仍未完成。
|
||||
|
||||
未知请求由页面会话范围调整为原userId作用域的恢复命令上下文：只含requestId/expectedDate/expectedRuleVersion，不含Token、余额、流水或填写资料；401、会话过期、退出及账户切换仍清资料缓存和会话，但该键保留至确认或明确拒绝。恢复前核验当前账户，POST仍重新鉴权；不会把原请求迁移到别的会员，也不会在登录/刷新后自动发奖。此恢复例外不改变DEC-POINT业务参数。
|
||||
|
||||
共享清理专项35项通过（15真实积分HTTP、2合成密码登录）：真实401清掉会话与该账户的其它资料缓存、保留原命令，同账户重新登录后实际重放且无重复到账。专项未实测本机过期/主动退出/完整账户切换交互；它们共用的清理函数已按上述规则实现。三批共214项/223积分请求，临时环境及私密配置已清理，正式发布/原表迁移状态保持。
|
||||
|
||||
### 0.1 前序：协议与隔离开发检查
|
||||
|
||||
87个真实HTTP请求/1079项检查通过，经过实际ThinkPHP路由、Redis Token鉴权和积分控制器。覆盖匿名/无效/停用/删除/撤销、Cookie/旧Token头拒绝、允许Origin的匿名OPTIONS、JSON/原始query/错误方法、草案/发布/暂停/坏规则、跨日/版本变化、实际丢弃已提交成功响应后的原键确认、本人快照/隐私/旧NULL与0流水、余额边界、坏回执和Redis不可用。
|
||||
|
||||
@@ -14,7 +22,7 @@
|
||||
|
||||
迁移纯110项、独立合成库apply/备份/Windows ACL/恢复89项通过。共享隔离库只复制结构，第一新库合成2会员4流水；apply4增量、重复为0，完整双表schema+NDJSON恢复第二新库并逐列摘要一致。目录3文件ACL及读写probe通过，修正Windows原生绝对路径及父级路径校验，纯路径边界覆盖；两新库、私密INI/备份/probe已清理，源表摘要保持。安全verification保留于C:/Users/JUN/AppData/Local/Temp/airz-points-migration-20261001/apply-20261001-115749-d50a5cd87fd5a84a/verification.json。仅为开发演练，未执行共享原表DDL或生产操作。
|
||||
|
||||
### 0.1 历史：0.48后端基础检查
|
||||
### 0.2 历史：0.48后端基础检查
|
||||
|
||||
已新增 PointsRules、UserPoints、v1 Points 控制器、五条路由、默认未发布配置、显式迁移脚本及测试。通用后台score/level、通用模型更新与旧User::score均已拒绝写入；新服务直接在账户锁内限定更新score并保存完整流水，不重算level。新会员0分、数据库默认0级及Auth注册1级初始化保持。schema.sql和ScoreLog中文注释已同步目标结构，不能据此声称目标库已经增加字段。
|
||||
|
||||
@@ -45,9 +53,9 @@
|
||||
|
||||
| 位置 | 当前能力或风险 | 实施处理 |
|
||||
| --- | --- | --- |
|
||||
| [积分页面](../packages/account/points/points.uvue) | 余额为本机签到日期数乘 10；设备日期；固定体验码 AI2680；没有积分 API | 接真实 API 后移除该余额算法及固定码，清理体验缓存但不换算奖励 |
|
||||
| [账户服务](../packages/account/services/account.uts) | 已有登录、账户变化防护；资料 DTO 无 score/share_code | 新增同分包积分服务，复用会话而不扩充无关资料字段 |
|
||||
| [请求基础](../services/api.uts) | 有 Token 变化及 401 防护；当前错误仅保留 message | 实施时保留现有调用兼容，增加可识别的 HTTP 状态/errorCode，区别确定失败与结果未知 |
|
||||
| [积分页面](../packages/account/points/points.uvue) | 已读取服务端余额、规则、任务和本人流水；按服务端日期/规则恢复签到请求 | 关闭配置时继续显示未发布状态，不伪造奖励；原键确认后重新读取当前余额 |
|
||||
| [账户服务](../packages/account/services/account.uts) | 已有登录、账户变化防护；资料 DTO 无 score/share_code | 积分服务复用会话，不扩充无关资料字段；登录恢复只接受固定 `resumePoints` 白名单 |
|
||||
| [请求基础](../services/api.uts) | 已保留 Token 变化、401 清理、HTTP 状态和业务 `errorCode` | 页面按确定拒绝与结果未知分别清理或保留原签到键，网络/账本故障不误判未入账 |
|
||||
| [数据库结构](D:/AAdesk/202609/airz/database/schema.sql) | fa_user.score 为有符号 INT；流水已具业务键、事件唯一及用户时间索引 | 复用余额和流水；目标库实际结构仍须迁移前只读核实 |
|
||||
| [通用积分方法](D:/AAdesk/202609/airz/application/common/model/User.php) | 旧score()已明确拒绝，通用模型不能更新score/level | 使用UserPoints领域服务，不再吞异常或随积分重算等级 |
|
||||
| [后台会员模型](D:/AAdesk/202609/airz/application/admin/model/User.php) | 模型事件、后台增改/批量及编辑表单已保护score/level | 积分/等级只读；任意SQL仍不经过模型守卫，新增写方须遵守共同账户锁 |
|
||||
@@ -72,7 +80,7 @@ unique = user_id + business_type + business_id
|
||||
|
||||
## 4. 接口源码契约
|
||||
|
||||
统一前缀 `/api/v1`，全部要求显式合法Bearer及当前正常会员，不接受Cookie/旧Token头回退。沿用v1 Base的code/msg/data与data.errorCode、Cache-Control: no-store，v1框架错误亦补该缓存头。由认证身份取得userId；未知参数、客户端余额/奖励/业务完成状态/其他用户ID均拒绝。五条精确白名单路径已实现并通过HTTP开发检查，原表迁移/规则发布/页面尚未完成，不视为线上能力。
|
||||
统一前缀 `/api/v1`，全部要求显式合法Bearer及当前正常会员，不接受Cookie/旧Token头回退。沿用v1 Base的code/msg/data与data.errorCode、Cache-Control: no-store，v1框架错误亦补该缓存头。由认证身份取得userId；未知参数、客户端余额/奖励/业务完成状态/其他用户ID均拒绝。五条精确白名单路径、原键恢复和页面隔离联调已通过开发检查；原表迁移和规则发布仍未完成，不视为线上积分已启用。
|
||||
|
||||
签到要求application/json，可带UTF-8 charset；正文由原生JSON解码及领域校验，必须三个唯一字符串字段，重复键和Unicode等价重复键拒绝。原始QUERY_STRING校验唯一解码键、白名单及PHP解析一致；NUL、坏编码、重复和空片段拒绝。原始/有效HTTP方法须与接口方法一致，覆盖头存在即拒绝；错误方法405，未知路由404。Common既有入口在鉴权前处理允许Origin的匿名OPTIONS，不重复实现CORS。
|
||||
|
||||
@@ -84,11 +92,11 @@ unique = user_id + business_type + business_id
|
||||
| POST /points/check-in | requestId、expectedRuleVersion、expectedDate，必须恰好三个字段 | ledgerId、delta:int、balanceAfter:int、signedDate、ruleVersion、replayed:bool |
|
||||
| GET /points/tasks | 无业务参数 | 首阶段只返回已发布签到任务；未实施资料/邀请奖励明确 unavailable，reward=null |
|
||||
|
||||
流水源码采用与现有消息/内容一致的有界游标，替代旧page/pageSize目标草案；没有已发布积分API，不涉及接口兼容迁移。tasks实际返回serverDate/timezone/items，签到任务按已发布规则和今日状态显示，资料/邀请始终unavailable且reward=null。邀请/invitations和/invitations/bind保留后续阶段目标，不返回固定码或假的奖励进度。
|
||||
流水源码采用与现有消息/内容一致的有界游标，替代旧page/pageSize目标草案；积分 API 已接入页面，但正式原表迁移和规则发布仍未完成。tasks实际返回serverDate/timezone/items，签到任务按已发布规则和今日状态显示，资料/邀请始终unavailable且reward=null。邀请/invitations和/invitations/bind保留后续阶段目标，不返回固定码或假的奖励进度。
|
||||
|
||||
### 4.1 签到请求及回执
|
||||
|
||||
`requestId` 为 `pts_` 加 32 位小写十六进制，客户端用安全随机数生成，同一用户命名空间内唯一。`expectedRuleVersion` 为页面实际读取的已发布版本；`expectedDate` 为同一次读取返回的 serverDate，是操作预期条件，**不是指定奖励日期**。日期须为真实有效的 YYYY-MM-DD，拒绝非法日历日期、空值、数组和宽松类型转换。
|
||||
`requestId` 为 `pts_` 加 32 位小写十六进制，由客户端生成并在同一用户命名空间内作为幂等键；服务端以唯一约束和原请求确认保证不重复入账。正式发布前仍应将生成源替换为跨端可用的安全随机实现。`expectedRuleVersion` 为页面实际读取的已发布版本；`expectedDate` 为同一次读取返回的 serverDate，是操作预期条件，**不是指定奖励日期**。日期须为真实有效的 YYYY-MM-DD，拒绝非法日历日期、空值、数组和宽松类型转换。
|
||||
|
||||
示例仅描述获批发布后的协议形状，当前无这样的运行规则：
|
||||
|
||||
@@ -173,13 +181,13 @@ schema.sql及显式迁移脚本已定义可空request_id/rule_version、唯一(u
|
||||
- 初次/刷新分别处理加载、失败、空流水、未发布规则、已签到；失败清掉不可信旧状态，不显示假的 0 分或成功。
|
||||
- 发送中锁定签到按钮；请求结果未知时保留原 requestId/date/version 和账户身份，只允许原请求确认。不能因刷新、关闭提示或跨日自动生成另一签到请求。
|
||||
- 原回执仅确认原业务日；回执后重新读取当前余额和 serverDate。要签到新一天，必须由用户在刷新后明确点击。
|
||||
- 离页/换账号拒绝迟到响应，未确认请求随账户作用域隔离；未知请求保留范围先按当前页面会话，不跨退出/换账号迁移。
|
||||
- 离页/换账号拒绝迟到响应；未知请求在原userId作用域保留，离页、401、过期、退出和切换账户不会弃键，不能跨账户迁移。只保留三字段恢复命令，其它账户缓存照常清除；重新登录该会员后才能显式确认，仍须服务端鉴权。
|
||||
- 从 API 的 ruleVersion/reward 显示规则与奖励，不再写死 10、AI2680 或本机积分。未接邀请前不显示“真实个人邀请码”或未发生的邀请奖励。
|
||||
- 清理体验签到缓存不产生服务器写入；原匿名/本机记录不影响服务器 signedToday。
|
||||
|
||||
## 8. 后续开发检查清单与顺序
|
||||
|
||||
以下为完整开发检查范围；已覆盖部分见第0节。HTTP后端隔离检查已完成，页面和原表迁移/正式发布仍未完成：
|
||||
以下为完整开发检查范围；已覆盖部分见第0节和开发进度0.51。积分读取/签到恢复隔离页面检查已通过，邀请与资料奖励、原表迁移、正式发布及真机仍未完成：
|
||||
|
||||
| 检查 | 关键反例 |
|
||||
| --- | --- |
|
||||
@@ -194,6 +202,6 @@ schema.sql及显式迁移脚本已定义可空request_id/rule_version、唯一(u
|
||||
| 页面状态 | 实际响应丢失、原键确认、换账号、登录恢复、加载/空/错、迟到回包 |
|
||||
| 迁移和恢复 | 原表只读预检；新合成库apply4增量/重复0、完整备份/ACL/第二库恢复、旧数据摘要一致及精确清理已通过 |
|
||||
|
||||
当前后端可在规则未定稿时保持默认关闭。下一开发子项可实施积分页面真实读取、登录恢复及原键确认流程；规则未发布时签到不可用，不补造奖励。首阶段业务规则定稿、原表迁移和发布另行安排；邀请资格/奖励规则与关系方案留POINT-003，完整POINT-004后续推进。发布参数在确认前保持空值。
|
||||
当前后端可在规则未定稿时保持默认关闭。页面真实读取、登录恢复及原键确认已完成隔离联调；下一步是确认首阶段业务规则，随后执行正式库只读预检、完整备份、4项增量迁移和线上关闭状态烟测。邀请资格/奖励规则与关系方案留POINT-003，完整POINT-004后续推进。发布参数在确认前保持空值。
|
||||
|
||||
正式迁移、上线、真机/多设备、权益运营和真实业务验收后续按实际范围安排，不复用历史生产授权。本轮为源码、纯测试及显式隔离开发检查，不是生产签到到账或积分页面完成证据。
|
||||
|
||||
Reference in New Issue
Block a user