Ver código fonte

feat(contact.group.import): S-cfc-375 联系人分组/批量导入落地,红契约转绿(11/11)

- 新增 ContactGroup 实体 + ContactGroupMapper + contact_group 表(schema.sql + 迁移488)
- contacts 表补 group_id 列(含索引,迁移488 同步)
- 新增 ContactImportService(CSV 批量导入按 groupId 归组,格式错误行跳过并报告)
- 新增 ContactImportController(/api/contact/group/create、/group/list、/import-batch)
- ContactController 新增 /import-group 分组导入端点
- Contact/ContactDTO/ContactService 透传 groupId
- API_REFERENCE.md 登记新端点并闭环契约缺口 G-3
Sisyphus Agent 4 dias atrás
pai
commit
ac3b56b808

+ 37 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java

@@ -3902,6 +3902,10 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         // 迁移487: task_reminder_config 补日提醒三列(task.reminder.daily,S-cfc-348 / SC-P-65/79;
         //          设计契约 task-daily-reminder-design-2026-11-14.md §3.1)
         migrateTaskReminderDailyColumns();
+
+        // 迁移488: 创建 contact_group 表 + contacts 补 group_id 列
+        //(SC-P-62 建分组 → 导入归组,S-cfc-375 / contact.group.import)
+        migrateContactGroupImportTables();
     }
 
     /**
@@ -13413,6 +13417,39 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
         }
     }
 
+    // 迁移488: 联系人分组载体(SC-P-62 建分组 → 导入归组,S-cfc-375 / contact.group.import)
+    // 1) 创建 contact_group 表(分组归属 userId 隔离,权限流横向越权维度)
+    // 2) contacts 补 group_id 列(导入按 groupId 归组)+ group_id 索引
+    // 幂等:CREATE TABLE IF NOT EXISTS + ensureColumn 自动忽略列已存在。
+    private void migrateContactGroupImportTables() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS contact_group (" +
+                    "id BIGINT AUTO_INCREMENT PRIMARY KEY, " +
+                    "user_id BIGINT NOT NULL COMMENT '用户ID(归属隔离)', " +
+                    "name VARCHAR(50) NOT NULL COMMENT '分组名称', " +
+                    "created_at DATETIME, " +
+                    "updated_at DATETIME, " +
+                    "INDEX idx_cg_user (user_id)" +
+                    ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='联系人分组表'");
+            log.info("迁移488: 已创建contact_group表");
+        } catch (Exception e) {
+            log.warn("迁移488: 创建contact_group表失败: {}", e.getMessage());
+        }
+        try {
+            ensureColumn("contacts", "group_id",
+                    "BIGINT NULL COMMENT '所属分组ID(SC-P-62 联系人分组)'");
+            log.info("迁移488: contacts.group_id 列已就绪");
+        } catch (Exception e) {
+            log.warn("迁移488: contacts 补 group_id 列失败: {}", e.getMessage());
+        }
+        try {
+            jdbcTemplate.execute("ALTER TABLE contacts ADD INDEX idx_contact_group (group_id)");
+            log.info("迁移488: contacts.group_id 索引已就绪");
+        } catch (Exception e) {
+            log.warn("迁移488: contacts.group_id 索引已存在/失败: {}", e.getMessage());
+        }
+    }
+
     // 迁移359: 跨小程序单点登录一次性票据表(cfc ↔ train 双向免登)
     // 详见 schema.sql。此处自愈建表,避免 schema.sql 建表语句因故静默失败导致登录报错。
     private void createSsoTicketTable() {

+ 14 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/ContactController.java

@@ -2,7 +2,9 @@ package com.etotem.cfc.controller;
 
 import com.etotem.cfc.common.Result;
 import com.etotem.cfc.dto.ContactDTO;
+import com.etotem.cfc.dto.ContactImportResultVO;
 import com.etotem.cfc.entity.Contact;
+import com.etotem.cfc.service.ContactImportService;
 import com.etotem.cfc.service.ContactService;
 import org.springframework.web.bind.annotation.*;
 
@@ -18,6 +20,9 @@ public class ContactController {
     @Resource
     private ContactService contactService;
 
+    @Resource
+    private ContactImportService contactImportService;
+
     @PostMapping("/list")
     public Result<List<ContactDTO>> list(@RequestAttribute("userId") Long userId) {
         return contactService.list(userId);
@@ -58,6 +63,15 @@ public class ContactController {
         return contactService.importFromPhone(name, phone, extra, userId);
     }
 
+    /** 分组批量导入(SC-P-62 建分组 → 导入,按 groupId 归组;格式错误行跳过并报告) */
+    @PostMapping("/import-group")
+    public Result<ContactImportResultVO> importGroup(@RequestBody Map<String, Object> params,
+                                                     @RequestAttribute("userId") Long userId) {
+        String csv = (String) params.get("csv");
+        Long groupId = ParamUtils.getLong(params.get("groupId"));
+        return contactImportService.importBatch(csv, groupId, userId);
+    }
+
     @PostMapping("/interaction")
     public Result<ContactDTO> interaction(@RequestBody Map<String, Object> params,
                                           @RequestAttribute("userId") Long userId) {

+ 44 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/ContactImportController.java

@@ -0,0 +1,44 @@
+package com.etotem.cfc.controller;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.dto.ContactImportResultVO;
+import com.etotem.cfc.entity.ContactGroup;
+import com.etotem.cfc.service.ContactImportService;
+import org.springframework.web.bind.annotation.*;
+
+import javax.annotation.Resource;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 联系人导入/分组(SC-P-62 建分组 → 导入,能力键 {@code contact.group.import})。
+ */
+@RestController
+@RequestMapping("/api/contact")
+public class ContactImportController {
+
+    @Resource
+    private ContactImportService contactImportService;
+
+    /** 建分组 */
+    @PostMapping("/group/create")
+    public Result<ContactGroup> createGroup(@RequestBody Map<String, Object> params,
+                                            @RequestAttribute("userId") Long userId) {
+        return contactImportService.createGroup(userId, params);
+    }
+
+    /** 分组列表 */
+    @PostMapping("/group/list")
+    public Result<List<ContactGroup>> listGroups(@RequestAttribute("userId") Long userId) {
+        return contactImportService.listGroups(userId);
+    }
+
+    /** 批量导入(按 groupId 归组;格式错误行跳过并报告) */
+    @PostMapping("/import-batch")
+    public Result<ContactImportResultVO> importBatch(@RequestBody Map<String, Object> params,
+                                                     @RequestAttribute("userId") Long userId) {
+        String csv = (String) params.get("csv");
+        Long groupId = params.get("groupId") == null ? null : Long.valueOf(params.get("groupId").toString());
+        return contactImportService.importBatch(csv, groupId, userId);
+    }
+}

+ 1 - 0
cfc-backend/src/main/java/com/etotem/cfc/dto/ContactDTO.java

@@ -28,4 +28,5 @@ public class ContactDTO {
     private Date updatedAt;
     private Long familyMemberId;
     private String invitedStatus;
+    private Long groupId;
 }

+ 26 - 0
cfc-backend/src/main/java/com/etotem/cfc/dto/ContactImportResultVO.java

@@ -0,0 +1,26 @@
+package com.etotem.cfc.dto;
+
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 联系人批量导入结果载体(SC-P-62 边界「导入格式错误行跳过并报告」,能力键 {@code contact.group.import})。
+ *
+ * <p>导入不整批失败:格式错误行(缺姓名/手机号非法/重复号码)跳过并统计,明细
+ * {@code skippedRows}(行号+原因+原文)供前端报告。</p>
+ */
+@Data
+public class ContactImportResultVO implements Serializable {
+
+    /** 成功导入行数 */
+    private Integer successCount;
+
+    /** 跳过行数(格式错误/重复号码) */
+    private Integer skippedCount;
+
+    /** 被跳过错误行明细:每项 {line: 行号, reason: 原因, raw: 原文} */
+    private List<Map<String, Object>> skippedRows;
+}

+ 3 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/Contact.java

@@ -52,4 +52,7 @@ public class Contact implements Serializable {
 
     /** 邀请加入家庭状态: none/invited/accepted/declined */
     private String invitedStatus;
+
+    /** 所属分组ID(SC-P-62 建分组 → 导入归组,能力键 contact.group.import) */
+    private Long groupId;
 }

+ 33 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/ContactGroup.java

@@ -0,0 +1,33 @@
+package com.etotem.cfc.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * 联系人分组(SC-P-62「建分组 → 导入」,能力键 {@code contact.group.import})。
+ *
+ * <p>承载「建分组 → 导入」的分组载体:分组归属 {@code userId} 隔离(权限流,横向越权维度),
+ * 联系人经 {@code contacts.group_id} 归组。</p>
+ */
+@Data
+@TableName("contact_group")
+public class ContactGroup implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 分组属主(登录用户),userId 隔离 */
+    private Long userId;
+
+    /** 分组名称 */
+    private String name;
+
+    private Date createdAt;
+
+    private Date updatedAt;
+}

+ 12 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/ContactGroupMapper.java

@@ -0,0 +1,12 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.ContactGroup;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * 联系人分组 Mapper(SC-P-62「建分组」持久化,能力键 {@code contact.group.import})。
+ */
+@Mapper
+public interface ContactGroupMapper extends BaseMapper<ContactGroup> {
+}

+ 147 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ContactImportService.java

@@ -0,0 +1,147 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.dto.ContactImportResultVO;
+import com.etotem.cfc.entity.Contact;
+import com.etotem.cfc.entity.ContactGroup;
+import com.etotem.cfc.mapper.ContactGroupMapper;
+import com.etotem.cfc.mapper.ContactMapper;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 联系人批量导入业务(SC-P-62「建分组 → 导入」,能力键 {@code contact.group.import})。
+ *
+ * <p>CSV 文本逐行解析:格式错误行(缺姓名/手机号非法/重复号码)跳过并报告,不整批失败;
+ * 导入联系人按 groupId 归组,归属当前登录 userId(横向越权:groupId 非本人分组被拒)。
+ */
+@Service
+public class ContactImportService {
+
+    /** 手机号合法正则:1 开头的 11 位数字 */
+    private static final String PHONE_PATTERN = "^1\\d{10}$";
+
+    @Resource
+    private ContactMapper contactMapper;
+
+    @Resource
+    private ContactGroupMapper contactGroupMapper;
+
+    /**
+     * 建分组(分组名称在参数 {@code name})。
+     *
+     * @param userId 当前登录用户
+     */
+    public Result<ContactGroup> createGroup(Long userId, Map<String, Object> params) {
+        Object nameObj = params == null ? null : params.get("name");
+        String name = nameObj == null ? null : nameObj.toString().trim();
+        if (name == null || name.isEmpty()) {
+            return Result.badRequest("分组名称不能为空");
+        }
+        ContactGroup group = new ContactGroup();
+        group.setUserId(userId);
+        group.setName(name);
+        group.setCreatedAt(new Date());
+        group.setUpdatedAt(new Date());
+        contactGroupMapper.insert(group);
+        return Result.success(group);
+    }
+
+    /** 分组列表(按 userId 过滤 + 降序排列) */
+    public Result<List<ContactGroup>> listGroups(Long userId) {
+        LambdaQueryWrapper<ContactGroup> query = new LambdaQueryWrapper<ContactGroup>()
+            .eq(ContactGroup::getUserId, userId)
+            .orderByDesc(ContactGroup::getId);
+        return Result.success(contactGroupMapper.selectList(query));
+    }
+
+    /**
+     * 批量导入(按 groupId 归组;格式错误行跳过并报告)。
+     *
+     * <p>参数承载归属(权限流):{@code csvContent} 为导入源(group 引用),{@code userId}
+     * 为登录用户;{@code groupId} 非空时校验其为当前用户分组,否则拒绝跨用户写入。</p>
+     *
+     * @param csvContent CSV 文本(每行「姓名,手机号」,首行可含表头跳过)
+     * @param groupId    目标分组 ID(可为 null,不归组则归「未分组」)
+     * @param userId     当前登录用户
+     */
+    public Result<ContactImportResultVO> importBatch(String csvContent, Long groupId, Long userId) {
+        if (csvContent == null || csvContent.trim().isEmpty()) {
+            return Result.badRequest("导入内容为空");
+        }
+        if (groupId != null) {
+            ContactGroup group = contactGroupMapper.selectById(groupId);
+            if (group == null || !group.getUserId().equals(userId)) {
+                return Result.forbidden("分组不存在或无权访问");
+            }
+        }
+        ContactImportResultVO result = new ContactImportResultVO();
+        List<Map<String, Object>> skippedRows = new ArrayList<>();
+        int success = 0;
+        int skipped = 0;
+
+        String[] lines = csvContent.replace("\r\n", "\n").split("\n");
+        for (int i = 0; i < lines.length; i++) {
+            String line = lines[i].trim();
+            if (line.isEmpty()) {
+                continue;
+            }
+            // 跳过首行表头
+            if (i == 0 && line.contains("姓名") && line.contains("手机")) {
+                continue;
+            }
+            String[] cols = line.split("[,\\uFF0C]"); // 支持英文/中文逗号
+            String name = cols.length > 0 ? cols[0].trim() : "";
+            String phone = cols.length > 1 ? cols[1].trim() : "";
+            String reason = null;
+            if (name.isEmpty()) {
+                reason = "缺少姓名";
+            } else if (!phone.matches(PHONE_PATTERN)) {
+                reason = "手机号格式非法";
+            } else if (isDuplicate(phone, userId)) {
+                reason = "重复号码";
+            }
+            if (reason != null) {
+                skipped++;
+                Map<String, Object> row = new HashMap<>();
+                row.put("line", i + 1);
+                row.put("reason", reason);
+                row.put("raw", line);
+                skippedRows.add(row);
+                continue;
+            }
+            Contact contact = new Contact();
+            contact.setUserId(userId);
+            contact.setName(name);
+            contact.setPhone(phone);
+            contact.setGroupId(groupId);
+            contact.setContactSource("phone");
+            contact.setIntimacyLevel(30);
+            contact.setContactCount(0);
+            contact.setCreatedAt(new Date());
+            contact.setUpdatedAt(new Date());
+            contactMapper.insert(contact);
+            success++;
+        }
+        result.setSuccessCount(success);
+        result.setSkippedCount(skipped);
+        result.setSkippedRows(skippedRows);
+        return Result.success(result);
+    }
+
+    /** 重复号码检测(同 userId 下手机号已存在) */
+    private boolean isDuplicate(String phone, Long userId) {
+        LambdaQueryWrapper<Contact> query = new LambdaQueryWrapper<Contact>()
+            .eq(Contact::getUserId, userId)
+            .eq(Contact::getPhone, phone);
+        Long count = contactMapper.selectCount(query);
+        return count != null && count > 0;
+    }
+}

+ 1 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ContactService.java

@@ -189,6 +189,7 @@ public class ContactService {
         dto.setUpdatedAt(c.getUpdatedAt());
         dto.setFamilyMemberId(c.getFamilyMemberId());
         dto.setInvitedStatus(c.getInvitedStatus());
+        dto.setGroupId(c.getGroupId());
         return dto;
     }
 

+ 13 - 1
cfc-backend/src/main/resources/schema.sql

@@ -5866,9 +5866,21 @@ CREATE TABLE IF NOT EXISTS contacts (
     notes TEXT COMMENT '备注',
     created_at DATETIME,
     updated_at DATETIME,
-    INDEX idx_user_id (user_id)
+    group_id BIGINT NULL COMMENT '所属分组ID(SC-P-62 联系人分组)',
+    INDEX idx_user_id (user_id),
+    INDEX idx_group_id (group_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='联系人表';
 
+-- 联系人分组表(SC-P-62 建分组)
+CREATE TABLE IF NOT EXISTS contact_group (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    user_id BIGINT NOT NULL COMMENT '用户ID(归属隔离)',
+    name VARCHAR(50) NOT NULL COMMENT '分组名称',
+    created_at DATETIME,
+    updated_at DATETIME,
+    INDEX idx_cg_user (user_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='联系人分组表';
+
 -- 联系人帮助记录表(章鱼图数据源)
 CREATE TABLE IF NOT EXISTS contact_help_logs (
     id BIGINT AUTO_INCREMENT PRIMARY KEY,

+ 3 - 2
docs/superpowers/api/API_REFERENCE.md

@@ -3528,7 +3528,8 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 | 路径 | 说明 |
 |------|------|
 | `POST /api/contact/create`、`/list`、`/detail`、`/interaction`、`/invite-to-family` | 联系人添加/详情/互动/邀请入家庭(SC-P-61/63) |
-| `POST /api/contact/import-phone` | 通讯录导入(SC-P-62,候选 `ContactImportController` 不存在;**分组无端点 → 缺口 G-3**) |
+| `POST /api/contact/import-phone` | 通讯录单条导入(SC-P-62,`ContactController.importPhone`) |
+| `POST /api/contact/import-batch`、`/import-group`;`POST /api/contact/group/create`、`/group/list` | 通讯录批量导入 + 建分组/分组列表(SC-P-62「建分组 → 导入」,`ContactImportController`/`ContactImportService`,按 `groupId` 归组、格式错误行跳过并报告 `successCount/skippedCount/skippedRows`;**缺口 G-3 已闭环**,S-cfc-375 / contact.group.import) |
 | `POST /api/family/user/members/visible`、`/members/update-visibility` | 联系人/成员可见性权限(SC-P-63) |
 | `POST /api/health/report/member-permission/list`、`/grant`、`/revoke`、`/visible-members` | 报告查看权限(SC-P-63) |
 #### 4.63.8 设置与通知(SC-P-64/65/66/78/79)
@@ -3553,7 +3554,7 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 |----|------|------|------|
 | SC-P-29 | 食谱收藏/调整 | 「调整」已存在(/api/meal/replace、/api/diet/recommendation/update|regenerate);「收藏」无端点(仅指标收藏 /api/indicator/favorite/* 为异构) | 缺口 G-1,需产品侧确认 |
 | SC-P-51 | 成长里程碑 | `GrowthController /api/growth` 无里程碑端点;关系/邀请里程碑(/api/family/relationship/milestones、/api/invite/milestone/*)非成长;成长页里程碑为前端聚合 | 缺口 G-2,需产品侧确认 |
-| SC-P-62 | 联系人分组/导入 | 导入已存在(/api/contact/import-phone);分组无端点 | 缺口 G-3,需产品侧确认 |
+| SC-P-62 | 联系人分组/导入 | 导入单条存在(/api/contact/import-phone);分组/批量导入原无端点 | ✅ 已闭环:新增 /api/contact/import-batch、/import-group、/group/create、/group/list(S-cfc-375 落地 `contact.group.import`:ContactGroup 实体+contact_group 表+contacts.group_id,格式错误行跳过并报告) |
 | SC-P-83 | 意见反馈/在线客服 | 反馈已存在(/api/health/feedback/*、/api/activity/feedback/*、/api/feedback/*);在线客服无专用端点 | 缺口 G-4,需产品侧确认 |
 | SC-P-85 | 多端登录/会话互斥 | 登录族 + SSO 票据存在;无单端互斥/旧 token 踢出(JWT 无状态) | 缺口 G-5,需产品侧确认 |
 *文档更新:2026-11-07(EVD-13 家长域剩余 30 SC 契约核对增补「家长域剩余」段落 4.63:家庭与成员 / 健康报告上传解析 / 食谱营养 / 测评类型与 AI 对话 / 成长记录 / 商城加购下单 / 联系人与社交 / 设置与通知 / 舌诊情绪·账号·活动·反馈·会话 + 已 GREEN 键复用登记 4 处 + 契约缺口 5 项。完整核验表见 `docs/superpowers/specs/2026-11-07-parent-rest-contract.md`)*