kdletters
9f3e34e81a
- Add invite code starts/expires fields across contracts, API, Spacetime bindings, and admin UI - Enforce pending/expired invite code redemption behavior and expose admin status - Add admin write-operation confirmation guard and documentation - Add invite code contract/runtime tests
272 lines
9.4 KiB
Markdown
272 lines
9.4 KiB
Markdown
# 邀请码有效期与后台二次确认实施计划
|
||
|
||
> **For Hermes:** 按 plan 模式，仅输出并保存实施计划，不直接改业务代码。
|
||
|
||
**Goal:** 为邀请码新增开始日期与截止日期，并让后台所有会修改数据的操作在提交前增加二次确认，降低误操作风险。
|
||
|
||
**Architecture:**
|
||
邀请码仍作为“用户稳定邀请身份码”保留，不做停用删除；在数据层增加 `starts_at` / `expires_at`，前台填写邀请码时按时间窗校验，后台列表与编辑页展示状态。后台所有写操作统一先弹二次确认，再真正调用 API，避免对兑换码、邀请码、任务配置等管理动作误触发。
|
||
|
||
**Tech Stack:**
|
||
Rust / SpacetimeDB / Axum / shared-contracts / TS + React 的 admin-web。
|
||
|
||
---
|
||
|
||
## 当前上下文
|
||
|
||
- 邀请码当前只有 `user_id`、`invite_code`、`metadata_json`、`created_at`、`updated_at`，没有状态字段。
|
||
- 目前后台存在邀请码管理入口，但没有停用能力，也没有有效期概念。
|
||
- 邀请码用于 `redeem_profile_referral_invite_code` 时的实时校验，适合增加“时间窗”而不是“禁用删除”。
|
||
- 后台已存在兑换码、任务配置等可写操作；本次要求把所有后台操作统一加二次确认，包括新增、编辑、禁用、删除等写入口。
|
||
|
||
---
|
||
|
||
## 设计原则
|
||
|
||
1. **邀请码不做软删除**：保留历史记录和邀请链路。
|
||
2. **有效期由时间窗推导**：
|
||
- `starts_at` 为空表示立即生效。
|
||
- `expires_at` 为空表示长期有效。
|
||
3. **前台只拒绝新绑定**：已绑定关系不回溯修改。
|
||
4. **后台写操作统一确认**：所有会触发 POST / PATCH / DELETE 的管理动作，在真正提交前必须弹出二次确认。
|
||
5. **尽量少改接口语义**：优先在现有 admin upsert/list 体系内扩展字段，而不是新增一套并行 API。
|
||
|
||
---
|
||
|
||
## 方案概要
|
||
|
||
### 邀请码时间窗
|
||
|
||
新增字段：
|
||
- `starts_at: Option<Timestamp>`
|
||
- `expires_at: Option<Timestamp>`
|
||
|
||
校验规则：
|
||
- 当前时间 `< starts_at`：返回“邀请码未生效”
|
||
- 当前时间 `>= expires_at`：返回“邀请码已过期”
|
||
- 其他情况允许填写
|
||
|
||
建议把状态展示为：
|
||
- 未生效
|
||
- 有效
|
||
- 已过期
|
||
- 长期有效（两个字段都为空或仅无截止）
|
||
|
||
### 后台二次确认
|
||
|
||
对 admin-web 所有管理动作统一加确认弹窗/对话框，至少覆盖：
|
||
- 兑换码新增/更新
|
||
- 兑换码停用
|
||
- 邀请码新增/更新
|
||
- 任务配置新增/更新
|
||
- 任务配置停用
|
||
- 其他后续新增的后台写操作
|
||
|
||
确认文案要求：
|
||
- 显示对象标识（如 code / inviteCode / taskId）
|
||
- 显示操作类型（新增 / 更新 / 停用）
|
||
- 明确提醒“该操作会立即影响线上数据”
|
||
- 允许取消返回，不调用 API
|
||
|
||
---
|
||
|
||
## 预期修改文件
|
||
|
||
### 1. 服务端领域与契约
|
||
- `server-rs/crates/spacetime-module/src/runtime/profile.rs`
|
||
- `ProfileInviteCode` 表结构新增开始/截止字段
|
||
- 邀请码 upsert 逻辑写入时间窗
|
||
- 邀请码 redeem 逻辑增加时间窗校验
|
||
- 邀请中心快照补充时间窗/状态
|
||
- `server-rs/crates/spacetime-module/src/migration.rs`
|
||
- 兼容旧表数据，给旧邀请码补默认空值
|
||
- `server-rs/crates/shared-contracts/src/runtime*.rs` 或对应生成/手写契约文件
|
||
- `AdminUpsertProfileInviteCodeRequest` 扩展字段
|
||
- `ProfileInviteCodeAdminResponse` 扩展字段
|
||
- 如需要，增加时间窗相关状态枚举或派生字段
|
||
- `server-rs/crates/spacetime-client/src/module_bindings/*`
|
||
- 重新生成 bindings
|
||
- mapper 补齐新字段
|
||
|
||
### 2. API Server
|
||
- `server-rs/crates/api-server/src/runtime_profile.rs`
|
||
- 接收/转发邀请码时间窗参数
|
||
- 返回新增字段给后台
|
||
- 如需要，调整校验错误文案
|
||
- `server-rs/crates/api-server/src/app.rs`
|
||
- 若有新路由或错误码需挂接，在此统一登记
|
||
|
||
### 3. Admin Web
|
||
- `apps/admin-web/src/api/adminApiTypes.ts`
|
||
- 增加邀请码时间窗字段
|
||
- 如有需要，增加后台操作请求结构字段
|
||
- `apps/admin-web/src/api/adminApiClient.ts`
|
||
- 透传新的请求/响应字段
|
||
- `apps/admin-web/src/app/adminRoutes.ts`
|
||
- 不一定需要改，但如果新增独立页面/子面板，需要在此登记
|
||
- `apps/admin-web/src/styles/admin.css`
|
||
- 确认弹窗与时间窗展示样式
|
||
- `apps/admin-web/src/**` 实际管理页面组件
|
||
- 邀请码编辑表单
|
||
- 邀请码列表状态展示
|
||
- 所有写操作前的二次确认弹窗
|
||
|
||
### 4. 文档
|
||
- `docs/technical/` 或 `docs/design/`
|
||
- 补一份邀请码时间窗与后台确认交互说明
|
||
- 如现有文档已经覆盖后台管理规范，则优先补充现有文档，不重复造新说明页
|
||
|
||
---
|
||
|
||
## 分步实施计划
|
||
|
||
### Task 1: 明确数据模型与契约扩展
|
||
**Objective:** 定义邀请码开始/截止日期字段及其在响应中的展示方式。
|
||
|
||
**要点：**
|
||
- 确认字段名采用 `starts_at` / `expires_at`，避免与现有字段语义冲突。
|
||
- 确认时间类型统一用 `Timestamp` / 毫秒微秒整数转换策略。
|
||
- 明确返回给后台的字段是否需要附带派生状态（如 `status`）。
|
||
|
||
**产出：**
|
||
- 契约字段定义
|
||
- 状态枚举/派生规则
|
||
|
||
---
|
||
|
||
### Task 2: 更新 SpacetimeDB 表与迁移
|
||
**Objective:** 让邀请码表可保存有效期，并兼容旧数据。
|
||
|
||
**要点：**
|
||
- 修改 `ProfileInviteCode` 表结构。
|
||
- 更新迁移逻辑，旧记录默认无开始/截止。
|
||
- 检查是否需要补充索引或查询辅助字段。
|
||
|
||
**验证：**
|
||
- 旧数据能正常读取。
|
||
- 新数据能写入开始/截止。
|
||
|
||
---
|
||
|
||
### Task 3: 实现邀请填写时的时间窗校验
|
||
**Objective:** 在邀请码被填写时正确拒绝未生效或已过期的邀请码。
|
||
|
||
**要点：**
|
||
- 在 `redeem_profile_referral_invite_code_record` 内增加开始/截止校验。
|
||
- 保持“自己的邀请码不能填”“邀请码不存在”等原有错误优先级清晰。
|
||
- 保留历史绑定关系不受影响。
|
||
|
||
**验证：**
|
||
- 未到开始时间时返回明确错误。
|
||
- 超过截止时间时返回明确错误。
|
||
- 正常区间可绑定成功。
|
||
|
||
---
|
||
|
||
### Task 4: 扩展后台邀请码管理接口
|
||
**Objective:** 让后台可以创建/修改邀请码时间窗，并在列表中查看状态。
|
||
|
||
**要点：**
|
||
- 扩展 `AdminUpsertProfileInviteCodeRequest`。
|
||
- 扩展 `ProfileInviteCodeAdminResponse`。
|
||
- `api-server` 接口负责接收新字段并转发。
|
||
- 列表接口返回可读时间字段与状态。
|
||
|
||
**验证：**
|
||
- 后台表单提交后，返回结果包含时间窗信息。
|
||
- 列表页能看到状态与时间。
|
||
|
||
---
|
||
|
||
### Task 5: 给后台所有写操作加二次确认
|
||
**Objective:** 统一拦截所有后台写动作，避免误点直接生效。
|
||
|
||
**覆盖范围建议：**
|
||
- 邀请码新增/更新
|
||
- 兑换码新增/更新/停用
|
||
- 任务配置新增/更新/停用
|
||
- 后续新增的管理写操作
|
||
|
||
**实现要求：**
|
||
- 在真正调用 API 之前弹出确认框。
|
||
- 确认框需要展示对象名、操作类型、影响范围。
|
||
- 取消后不发送请求。
|
||
- 尽量抽象出通用确认组件/通用 action 包装函数，避免每个页面重复写。
|
||
|
||
**验证：**
|
||
- 点击“保存”不会直接提交，需先确认。
|
||
- 点击“取消”不会发请求。
|
||
- 所有后台写入口行为一致。
|
||
|
||
---
|
||
|
||
### Task 6: 补充文档与交互说明
|
||
**Objective:** 把新规则写进项目文档，避免后续实现偏差。
|
||
|
||
**要点：**
|
||
- 记录邀请码时间窗语义。
|
||
- 记录后台二次确认规范。
|
||
- 说明哪些动作属于“必须确认”的写操作。
|
||
|
||
---
|
||
|
||
## 测试与验证
|
||
|
||
### 服务端
|
||
- 邀请码时间窗单测 / 集成测试
|
||
- 邀请码 redeem 流程回归测试
|
||
- 旧数据兼容测试
|
||
|
||
### API / 前端
|
||
- 管理后台列表展示正确
|
||
- 表单提交能回传新字段
|
||
- 二次确认取消后不请求接口
|
||
- 二次确认确认后正常提交
|
||
|
||
### 推荐验证命令
|
||
- 视项目现有脚本执行对应后端测试
|
||
- 前端按 admin-web 构建/测试脚本验证
|
||
- 如涉及生成绑定，先确认生成产物无漏字段
|
||
|
||
---
|
||
|
||
## 风险与权衡
|
||
|
||
1. **时间字段格式不统一**
|
||
- 风险：前后端对时间单位理解不一致。
|
||
- 处理：在契约层明确是 ISO 字符串还是微秒整数，并全链路统一。
|
||
|
||
2. **后台“所有操作”范围过大**
|
||
- 风险：遗漏某些写入口。
|
||
- 处理：先枚举现有写 API，再做统一确认封装。
|
||
|
||
3. **邀请码过期后历史链接解释成本**
|
||
- 风险：用户误以为历史邀请码失效影响已绑定关系。
|
||
- 处理：文案明确“仅影响新填写，不影响已绑定记录”。
|
||
|
||
4. **契约与生成绑定联动较多**
|
||
- 风险：字段变更后生成文件数量较多。
|
||
- 处理：先改源契约与服务端，再统一重生成 bindings。
|
||
|
||
---
|
||
|
||
## 待确认问题
|
||
|
||
1. `starts_at` / `expires_at` 在接口里要返回 **ISO 字符串** 还是 **微秒整数**？
|
||
2. 后台二次确认是否统一用一个全局弹窗组件，还是页面级本地实现？
|
||
3. 邀请码列表是否需要直接展示“状态标签”还是只展示时间字段由前端推导？
|
||
4. 现有后台所有写操作里，是否还要覆盖调试类接口，还是仅覆盖业务管理接口？
|
||
|
||
---
|
||
|
||
## 建议执行顺序
|
||
|
||
1. 先确认时间字段格式与确认弹窗范围。
|
||
2. 再改服务端契约与迁移。
|
||
3. 再改 redeem 校验与后台接口。
|
||
4. 最后统一改 admin-web 的二次确认与表单展示。
|
||
|
||
---
|
||
|
||
**结论：** 这是一个适合分阶段落地的改动，建议先做“邀请码时间窗 + 后台统一二次确认”的基础能力，再补交互细节。
|