docs: 管理员分配爱心值给家庭成员设计文档

docs/superpowers/specs/2026-05-23-assign-love-value-to-member-design.md

@@ -0,0 +1,182 @@
+# 管理员分配爱心值给家庭成员 设计文档
+
+**日期：** 2026-05-23
+**版本：** 1.0
+
+---
+
+## 1. 背景
+
+管理员在 PC 管理后台，可以从用户总账号的爱心值余额中，分配一定数量给指定家庭成员。
+
+---
+
+## 2. 业务规则
+
+1. 分配数量必须 > 0
+2. 分配数量不能超过总账号当前余额
+3. 分配成功后：
+   - 总账号 `loveValue` 扣减对应数量
+   - 家庭成员 `loveValue` 增加对应数量
+4. 写两条流水记录（`ht_love_value_record`）：
+   - 总账号支出：`capitalFlow=2`，`transactionType=3`，`memberId=成员id`
+   - 成员收入：`capitalFlow=1`，`transactionType=3`，`userId=总账号id`，`memberId=成员id`
+5. `transactionType=3` 为新增类型，含义：管理员分配
+
+---
+
+## 3. 改动范围
+
+| 端 | 文件 | 改动类型 |
+|----|------|---------|
+| 后端 | `FamilyMemberDTO.java` | 新增 `loveValue` 字段 |
+| 后端 | `FamilyMemberServiceImpl.java` | `page()` 填充 `loveValue`；新增 `assignLoveValue()` |
+| 后端 | `FamilyMemberService.java` | 新增 `assignLoveValue()` 接口声明 |
+| 后端 | `FamilyMemberController.java` | 新增 `POST /core/family/member/assignLoveValue` |
+| 前端 | `familyMember.vue` | 新增「爱心值」列、「分配」按钮、分配弹窗 |
+
+---
+
+## 4. 后端设计
+
+### 4.1 FamilyMemberDTO 新增字段
+
+```java
+@ApiModelProperty(value = "爱心值")
+private BigDecimal loveValue;
+```
+
+### 4.2 FamilyMemberServiceImpl — page() 填充 loveValue
+
+在现有 `page()` 重写方法中，Entity 已通过 `baseDao.selectBatchIds` 批量查出（为填充 channelNames），直接复用，同时填充 `loveValue`：
+
+```
+entity.getLoveValue() → dto.setLoveValue()
+```
+
+### 4.3 新增 assignLoveValue() 方法
+
+**接口声明（FamilyMemberService.java）：**
+
+```java
+void assignLoveValue(Long memberId, Long userId, BigDecimal amount);
+```
+
+**实现逻辑（FamilyMemberServiceImpl.java）：**
+
+```
+1. 查 AppUserEntity（总账号），校验余额 >= amount > 0
+2. 查 FamilyMemberEntity，校验成员属于该用户
+3. 开启事务：
+   a. 总账号 loveValue -= amount，updateById
+   b. 成员 loveValue += amount，updateById
+   c. 插入流水记录（总账号支出）：
+      userId=userId, capitalFlow=2, transactionType=3,
+      memberId=memberId, loveQuantity=amount
+   d. 插入流水记录（成员收入）：
+      userId=userId, capitalFlow=1, transactionType=3,
+      memberId=memberId, loveQuantity=amount
+4. 返回成功
+```
+
+### 4.4 新增接口
+
+**Controller（FamilyMemberController.java）：**
+
+```
+POST /core/family/member/assignLoveValue
+```
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| memberId | Long | 是 | 家庭成员 ID |
+| userId | Long | 是 | 总账号用户 ID |
+| amount | BigDecimal | 是 | 分配数量，必须 > 0 |
+
+响应：统一 `Result` 格式，`code=0` 为成功。
+
+错误场景：
+
+| 场景 | 返回 |
+|------|------|
+| amount <= 0 | `code=500, msg="分配数量必须大于0"` |
+| 余额不足 | `code=500, msg="总账号余额不足"` |
+| 成员不属于该用户 | `code=500, msg="家庭成员不存在"` |
+
+---
+
+## 5. 前端设计
+
+**文件：** `src/views/modules/member/components/familyMember.vue`
+
+### 5.1 列表新增「爱心值」列
+
+在「所属渠道」列后新增：
+
+```html
+<el-table-column label="爱心值">
+  <template slot-scope="scope">{{ scope.row.loveValue || 0 }}</template>
+</el-table-column>
+```
+
+### 5.2 操作列新增「分配」按钮
+
+在列表末尾新增操作列：
+
+```html
+<el-table-column label="操作" width="80">
+  <template slot-scope="scope">
+    <el-button type="text" @click="handleAssign(scope.row)">分配</el-button>
+  </template>
+</el-table-column>
+```
+
+### 5.3 分配弹窗
+
+弹窗字段：
+- 成员姓名（只读展示）
+- 总账号当前余额（只读，从 `detail.vue` 通过 props 传入）
+- 分配数量（数字输入框，最大值 = 总账号余额，最小值 = 1）
+
+提交调用：`POST /core/family/member/assignLoveValue`
+
+成功后：刷新列表（`getList()`）、关闭弹窗。
+
+### 5.4 Props 新增
+
+`familyMember.vue` 新增 prop：
+
+```js
+props: ['userId', 'userLoveValue']
+```
+
+`detail.vue` 传入：
+
+```html
+<family-member :userId="userId" :userLoveValue="assetInfo ? assetInfo.loveValue : 0"></family-member>
+```
+
+---
+
+## 6. 数据流
+
+```
+管理员点击「分配」
+  → 弹窗展示成员姓名 + 总账号余额
+  → 输入分配数量，点击确认
+  → POST /core/family/member/assignLoveValue
+    → 校验余额
+    → 事务：扣总账号 + 加成员 + 写两条流水
+  → 成功：刷新列表，弹窗关闭
+  → 失败：Toast 提示错误信息
+```
+
+---
+
+## 7. 不在本次范围内
+
+- 爱心值分配记录的查询页面
+- 撤销/退回分配
+- 批量分配