# 实施计划: 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）状态，提供流畅的用户体验。