chore: initial commit with CI pipeline, review and tasks docs

specs/003-user-experience/plan.md

@@ -0,0 +1,54 @@
+# 实施计划: 003 - 用户端体验
+
+本文档为“用户端体验”功能规格的技术实施计划。
+
+## 1. 总体思路
+
+用户端体验是转化的关键，需要保证页面的高性能和交互的流畅性。后端需提供快速响应的API，前端则通过无限滚动等技术优化大数据量下的列表展示。
+
+## 2. 后端开发任务 (Backend Tasks)
+
+### 2.1. 新增服务与数据库设计
+
+- **短链接服务 (Short Link Service)**
+    - **数据库**: 创建 `short_links` 表，包含 `id`, `code` (唯一索引), `original_url`, `created_at`。
+    - **内部API**: 创建一个内部 `POST /api/v1/internal/shorten` 接口，用于生成和存储短链接。
+    - **公共重定向**: 创建一个公共 `GET /r/{code}` 接口，用于处理短链接的302重定向。
+
+- **海报生成服务 (Poster Generation Service)**
+    - **技术选型**: 引入图像处理库（如 Node.js 的 `sharp` 或 Python 的 `Pillow`）。
+    - **API设计**: 创建 `GET /api/v1/me/poster` 接口。默认返回 `image/png` 格式的图片文件流。当接收到 `?render=client` 参数时，返回构建海报所需的JSON数据（背景图URL、文案、二维码数据等），以支持客户端渲染的降级方案。
+
+- **数据库更新**
+    - 在 `invitations` 表（或类似表）中增加 `status` 字段 (enum: `clicked`, `registered`, `ordered`)，用于追踪邀请状态。
+
+### 2.2. API Endpoint 设计
+
+- `GET /api/v1/me/invitation-info`: **获取当前用户的邀请信息**
+    - Response: `{ short_link, ... }`，返回已生成的专属短链接。
+
+- `GET /api/v1/me/invited-friends`: **获取邀请好友列表（分页）**
+    - Query Params: `page`, `limit`。
+    - Response: 返回经过隐私处理（昵称、打码手机号、头像）的好友列表及其状态。
+
+- `GET /api/v1/me/rewards`: **获取奖励明细列表（分页）**
+    - Query Params: `page`, `limit`。
+    - Response: 返回当前用户的奖励记录列表。
+
+## 3. 前端开发任务 (Frontend Tasks)
+
+### 3.1. UI 组件设计
+
+- **`UserCenter.vue`**: 用户个人中心的主页面，整合分享和记录查看功能。
+- **`ShareModule.vue`**: 用于展示分享信息的组件，包含：
+    - “一键复制”短链接的按钮。
+    - 展示分享海报，并处理服务端/客户端渲染的逻辑。
+- **`InfiniteScrollList.vue`**: 一个可复用的列表组件，封装“滚动到底部自动加载下一页”的逻辑。
+- **`InvitedFriendItem.vue`**: 用于渲染“邀请记录”列表中的单项，展示好友的隐私保护信息和邀请状态。
+- **`RewardItem.vue`**: 用于渲染“奖励明细”列表中的单项。
+
+### 3.2. API 集成与状态管理
+
+- 在API客户端中新增与用户中心相关的接口请求函数。
+- 使用 `Pinia` 管理用户状态，并可以结合 `useSWRV` 或自定义的 `useFetch` Composable 函数来管理分页数据的获取、缓存和“无限滚动”的状态。
+- 在 `ShareModule.vue` 中实现降级逻辑：当从服务端获取海报图片失败或超时，能自动切换到客户端渲染模式。

specs/003-user-experience/spec.md

@@ -0,0 +1,29 @@
+# 功能规范: 003 - 用户端体验
+
+本文档定义了“蚊子”传播系统中与“用户端体验”相关的功能。
+
+## 1. 用户故事与验收标准 (User Stories & Acceptance Criteria)
+
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为参与者**，我希望能方便地获取专属的邀请链接和海报，以便分享给朋友。 | 1. 页面显著位置提供“一键复制链接”按钮。<br>2. **(澄清)** 复制的链接为短链接形式。<br>3. 可生成带专属二维码的分享海报。<br>4. **(澄清)** 海报内容由管理员在活动中配置，默认在服务端生成，并提供客户端渲染作为高负载降级方案。 | **高** |
+| **作为参与者**，我希望在个人中心看到我的邀请记录和奖励明细，以便了解我的贡献和收益。 | 1. 列表展示我邀请的好友及其状态。<br>2. **(澄清)** 好友信息包含：昵称、头像、部分打码的手机号。<br>3. **(澄清)** 好友状态包含：“已点击但未注册”、“已注册”、“已下单”等。<br>4. 列表展示我获得的每一笔奖励。<br>5. **(澄清)** “邀请记录”和“奖励明细”列表均采用无限滚动方式进行分页加载。 | **高** |
+
+## 2. 澄清与边缘场景 (Clarifications & Edge Cases)
+
+- **海报生成 (Poster Generation)**: 
+    - 默认在服务端生成图片，以保证跨平台显示一致性。
+    - 需监控服务负载，当图片生成请求队列过长或CPU占用过高时，应自动切换到客户端动态渲染模式，作为降级方案。
+
+- **链接形式 (Link Format)**: 
+    - 所有向用户展示的邀请链接，都必须经过短链接服务处理，生成类似 `t.cn/xxxx` 的短格式。
+
+- **好友状态列表 (Friend Statuses)**: 
+    - V1.0阶段，需要明确追踪并展示以下几种状态：`已点击`、`已注册`、`已下单`。
+    - 该状态列表应可扩展，以适应未来更多的转化事件。
+
+- **隐私保护 (Privacy Protection)**: 
+    - 在“邀请的好友”列表中，手机号必须进行打码处理，例如 `138****1234`，仅展示头三位和后四位。
+
+- **列表加载 (List Loading)**: 
+    - 两个列表（邀请记录、奖励明细）在用户滚动到列表底部时，应自动触发加载下一页数据，无需用户点击“加载更多”按钮。

specs/003-user-experience/tasks.md

@@ -0,0 +1,35 @@
+# 开发任务列表: 003 - 用户端体验
+
+基于实施计划，为“用户端体验”功能分解出以下开发任务。
+
+## 后端 (Backend)
+
+### 核心服务与数据库
+
+- [ ] **BE-DB-06**: 创建 `short_links` 表的数据库迁移脚本。
+- [ ] **BE-DB-07**: 为 `invitations` 表增加 `status` 字段的数据库迁移脚本。
+- [ ] **BE-SVC-01**: 实现短链接生成服务，包括 `POST /api/v1/internal/shorten` 内部接口。
+- [ ] **BE-SVC-02**: 实现短链接重定向的公共接口 `GET /r/{code}`。
+- [ ] **BE-SVC-03**: 实现海报生成服务 `GET /api/v1/me/poster`，需支持图片和JSON两种返回模式。
+
+### API & 业务逻辑
+
+- [ ] **BE-API-11**: 实现获取用户专属邀请信息 (`GET /api/v1/me/invitation-info`) 的业务逻辑。
+- [ ] **BE-API-12**: 实现获取邀请好友列表 (`GET /api/v1/me/invited-friends`) 的业务逻辑，包含分页和隐私处理。
+- [ ] **BE-API-13**: 实现获取用户奖励列表 (`GET /api/v1/me/rewards`) 的业务逻辑，包含分页。
+- [ ] **BE-TEST-03**: 为所有用户端相关的API Endpoints 编写单元测试和集成测试。
+
+## 前端 (Frontend)
+
+### UI 组件
+
+- [ ] **FE-UI-12**: 开发 `UserCenter` 页面的主布局组件。
+- [ ] **FE-UI-13**: 开发 `ShareModule` 组件，实现短链接复制、海报展示及客户端渲染降级逻辑。
+- [ ] **FE-UI-14**: 开发一个可复用的 `InfiniteScrollList` 无限滚动列表组件。
+- [ ] **FE-UI-15**: 开发 `InvitedFriendItem` 和 `RewardItem` 列表项组件。
+
+### 状态管理与集成
+
+- [ ] **FE-API-03**: 在API客户端中新增所有用户端相关的请求函数。
+- [ ] **FE-INT-03**: 使用 `React Query` 或类似工具库，将 `InfiniteScrollList` 组件与后端分页接口集成。
+- [ ] **FE-INT-04**: 在 `ShareModule` 组件中，实现对海报生成接口的调用及失败/降级时的客户端渲染逻辑。