86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# 实施计划: 001 - 活动管理
|
||
|
||
本文档为“活动管理”功能规格的技术实施计划。
|
||
|
||
## 1. 总体思路
|
||
|
||
采用前后端分离的架构。后端负责提供RESTful API，处理所有业务逻辑和数据持久化。前端负责提供一个响应式的、用户友好的管理界面，供管理员创建和配置活动。
|
||
|
||
## 2. 后端开发任务 (Backend Tasks)
|
||
|
||
### 2.1. 数据库 Schema 设计
|
||
|
||
需要设计以下数据表来支持活动管理功能：
|
||
|
||
- **`activities` (活动表)**
|
||
- `id` (主键)
|
||
- `name` (活动名称, string)
|
||
- `start_time_utc` (开始时间, datetime)
|
||
- `end_time_utc` (结束时间, datetime)
|
||
- `target_users_config` (目标用户配置, json) - 存储用户ID列表或标签
|
||
- `page_content_config` (页面内容配置, json) - 存储文案和图片URL
|
||
- `reward_calculation_mode` (奖励计算模式, enum: `delta`, `cumulative`)
|
||
- `status` (活动状态, enum: `draft`, `active`, `ended`)
|
||
|
||
- **`activity_rewards` (阶梯奖励规则表)**
|
||
- `id` (主键)
|
||
- `activity_id` (外键, 关联 `activities`)
|
||
- `invite_threshold` (邀请人数阈值, integer)
|
||
- `reward_type` (奖励类型, enum: `points`, `coupon`)
|
||
- `reward_value` (奖励值, string) - 积分数量或优惠券批次ID
|
||
- `skip_validation` (跳过校验, boolean)
|
||
|
||
- **`multi_level_reward_rules` (多级奖励规则表)**
|
||
- `id` (主键)
|
||
- `activity_id` (外键, 关联 `activities`)
|
||
- `level` (奖励层级, integer, e.g., 2, 3)
|
||
- `coefficient_percent` (衰减系数-百分比, integer)
|
||
|
||
- **`api_keys` (API密钥表)**
|
||
- `id` (主键)
|
||
- `key_hash` (密钥的哈希值, string) - **绝不存储明文密钥**
|
||
- `scope_type` (范围类型, enum: `account`, `activity`)
|
||
- `scope_id` (范围ID, integer) - 对应账户ID或活动ID
|
||
- `created_at` (创建时间, datetime)
|
||
- `last_used_at` (最后使用时间, datetime, 可选)
|
||
|
||
### 2.2. API Endpoint 设计
|
||
|
||
设计以下RESTful API接口：
|
||
|
||
- `POST /api/v1/activities`: **创建新活动**
|
||
- Request Body: 包含活动所有配置信息。
|
||
- Response: 返回创建成功的活动详情。
|
||
|
||
- `PUT /api/v1/activities/{id}`: **更新活动**
|
||
- Request Body: 包含需要更新的活动配置。
|
||
- Response: 返回更新后的活动详情。
|
||
|
||
- `GET /api/v1/activities/{id}`: **获取活动详情**
|
||
- Response: 返回指定ID的活动完整配置。
|
||
|
||
- `POST /api/v1/api-keys`: **创建API密钥**
|
||
- Request Body: `{ scope_type, scope_id }`
|
||
- Response: 返回新生成的API Key (仅此一次)。
|
||
|
||
- `DELETE /api/v1/api-keys/{id}`: **吊销API密钥**
|
||
- Response: 成功状态码。
|
||
|
||
## 3. 前端开发任务 (Frontend Tasks)
|
||
|
||
### 3.1. UI 组件设计
|
||
|
||
需要开发一系列Vue组件来构建活动创建/编辑表单：
|
||
|
||
- **`ActivityEditor.vue`**: 主表单容器，管理整个活动配置的状态。
|
||
- **`GeneralSettings.vue`**: 用于配置活动名称、时间（需处理UTC与本地时间的转换）。
|
||
- **`TargetingEditor.vue`**: 用于配置目标用户，支持文本输入或文件上传。
|
||
- **`PageContentEditor.vue`**: 富文本编辑器及图片上传/链接组件（处理30MB大小限制和格式校验）。
|
||
- **`RewardRuleEditor.vue`**: 核心组件，用于配置阶梯奖励和多级奖励，包含奖励模式切换和计算示例的实时预览。
|
||
- **`ApiKeyManager.vue`**: 用于展示API密钥列表（不显示密钥本身）、生成新密钥（弹窗显示一次）、吊销密钥。
|
||
|
||
### 3.2. 状态管理与API集成
|
||
|
||
- 使用 `Pinia` 等状态管理库来管理复杂的表单数据。
|
||
- 创建一个API客户端模块 (`apiClient.js`)，封装所有对后端API的请求。
|
||
- 在组件中调用API，并处理加载（loading）和错误（error）状态，提供流畅的用户体验。 |