增加企业画像

huimv-employment/fe-api/src/main/java/com/huimv/employment/controller/mcp/McpEnterpriseProfileController.java

@@ -0,0 +1,65 @@
+package com.huimv.employment.controller.mcp;
+
+import com.huimv.employment.common.web.R;
+import com.huimv.employment.service.enterprise.McpEnterpriseProfileService;
+import com.huimv.employment.service.enterprise.dto.McpEnterpriseProfileResponse;
+import com.huimv.employment.service.enterprise.dto.McpEnterpriseProfileUpdateRequest;
+import com.huimv.employment.service.enterprise.dto.McpEnterpriseProfileUpdateResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * MCP 企业画像接口（交互规则 v2 §6.2）。
+ * <p>
+ * 通过 {@code X-Session-Id} 自动关联会话与企业，Agent 无需传递 enterprise_id。
+ * 鉴权见 {@code fe.internal.ai-key} 与 {@link com.huimv.employment.security.McpAuthFilter}。
+ * </p>
+ */
+@RestController
+@RequestMapping("/api/mcp/enterprise")
+@Tag(name = "MCP-企业画像", description = "智能体加载/更新企业画像，需 X-Fe-Ai-Key + X-Session-Id")
+public class McpEnterpriseProfileController {
+
+    public static final String HEADER_SESSION_ID = "X-Session-Id";
+
+    private final McpEnterpriseProfileService mcpEnterpriseProfileService;
+
+    public McpEnterpriseProfileController(McpEnterpriseProfileService mcpEnterpriseProfileService) {
+        this.mcpEnterpriseProfileService = mcpEnterpriseProfileService;
+    }
+
+    @GetMapping("/profile")
+    @Operation(summary = "获取企业画像",
+            description = "会话初始化时加载企业基础信息与偏好设置，供 Agent 注入上下文。",
+            parameters = {
+                    @Parameter(name = HEADER_SESSION_ID, in = ParameterIn.HEADER, required = true,
+                            description = "会话标识，与 AI chat session_id / conversation_no 一致"),
+                    @Parameter(name = "X-Fe-Ai-Key", in = ParameterIn.HEADER,
+                            description = "内网服务密钥")
+            })
+    public R<McpEnterpriseProfileResponse> getProfile(@RequestHeader(HEADER_SESSION_ID) String sessionId) {
+        return R.ok(mcpEnterpriseProfileService.getProfile(sessionId));
+    }
+
+    @PutMapping("/profile")
+    @Operation(summary = "增量更新企业画像",
+            description = "捕获对话中的新信息（如地址变更、结算偏好），支持 preferences.xxx 点路径。",
+            parameters = {
+                    @Parameter(name = HEADER_SESSION_ID, in = ParameterIn.HEADER, required = true),
+                    @Parameter(name = "X-Fe-Ai-Key", in = ParameterIn.HEADER)
+            })
+    public R<McpEnterpriseProfileUpdateResponse> updateProfile(
+            @RequestHeader(HEADER_SESSION_ID) String sessionId,
+            @Validated @RequestBody McpEnterpriseProfileUpdateRequest request) {
+        return R.ok(mcpEnterpriseProfileService.updateProfile(sessionId, request));
+    }
+}

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/enterprise/McpEnterpriseProfileService.java

@@ -0,0 +1,243 @@
+package com.huimv.employment.service.enterprise;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.huimv.employment.common.exception.BizException;
+import com.huimv.employment.common.exception.ErrorCode;
+import com.huimv.employment.dao.entity.FeConversation;
+import com.huimv.employment.dao.entity.FeEnterprise;
+import com.huimv.employment.dao.mapper.FeEnterpriseMapper;
+import com.huimv.employment.service.conversation.ConversationService;
+import com.huimv.employment.service.enterprise.dto.McpEnterpriseProfileResponse;
+import com.huimv.employment.service.enterprise.dto.McpEnterpriseProfileUpdateRequest;
+import com.huimv.employment.service.enterprise.dto.McpEnterpriseProfileUpdateResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * MCP 企业画像接口（交互规则 v2 §6.2）。
+ * <p>通过 {@code X-Session-Id} 关联会话与企业，Agent 无需传递 enterprise_id。</p>
+ */
+@Service
+public class McpEnterpriseProfileService {
+
+    private static final Logger log = LoggerFactory.getLogger(McpEnterpriseProfileService.class);
+
+    private static final String STATUS_SUCCESS = "success";
+    private static final String PREF_PREFIX = "preferences.";
+
+    /** 可写入 profile_json.preferences 的偏好键 */
+    private static final Set<String> ALLOWED_PREFERENCE_KEYS = Collections.unmodifiableSet(new HashSet<>(Arrays.asList(
+            "settlement_cycle",
+            "default_region",
+            "default_settlement_mode",
+            "default_work_type",
+            "default_insurance_level"
+    )));
+
+    /** settlement_cycle 合法值 */
+    private static final Set<String> ALLOWED_SETTLEMENT_CYCLES = Collections.unmodifiableSet(new HashSet<>(Arrays.asList(
+            "daily", "weekly", "biweekly", "monthly"
+    )));
+
+    private final FeEnterpriseMapper feEnterpriseMapper;
+    private final ConversationService conversationService;
+    private final EnterpriseService enterpriseService;
+    private final ObjectMapper objectMapper;
+
+    public McpEnterpriseProfileService(FeEnterpriseMapper feEnterpriseMapper,
+                                       ConversationService conversationService,
+                                       EnterpriseService enterpriseService,
+                                       ObjectMapper objectMapper) {
+        this.feEnterpriseMapper = feEnterpriseMapper;
+        this.conversationService = conversationService;
+        this.enterpriseService = enterpriseService;
+        this.objectMapper = objectMapper;
+    }
+
+    public McpEnterpriseProfileResponse getProfile(String sessionId) {
+        FeEnterprise enterprise = requireEnterpriseBySession(sessionId);
+        return toResponse(enterprise);
+    }
+
+    @Transactional(rollbackFor = Exception.class)
+    public McpEnterpriseProfileUpdateResponse updateProfile(String sessionId, McpEnterpriseProfileUpdateRequest request) {
+        FeEnterprise enterprise = requireEnterpriseBySession(sessionId);
+        Map<String, Object> profileRoot = parseProfileJson(enterprise.getProfileJson());
+        Map<String, Object> preferences = extractPreferences(profileRoot);
+
+        int updatedCount = 0;
+        for (Map.Entry<String, Object> entry : request.getUpdates().entrySet()) {
+            if (entry.getKey() == null) {
+                continue;
+            }
+            String key = entry.getKey().trim();
+            if (!StringUtils.hasText(key)) {
+                continue;
+            }
+            Object value = entry.getValue();
+            if (applyUpdate(enterprise, profileRoot, preferences, key, value)) {
+                updatedCount++;
+            }
+        }
+
+        if (updatedCount == 0) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "未识别任何可更新字段");
+        }
+
+        profileRoot.put("preferences", preferences);
+        enterprise.setProfileJson(writeProfileJson(profileRoot));
+        enterprise.setUpdateTime(LocalDateTime.now());
+        feEnterpriseMapper.updateById(enterprise);
+
+        McpEnterpriseProfileUpdateResponse response = new McpEnterpriseProfileUpdateResponse();
+        response.setUpdatedFields(updatedCount);
+        response.setStatus(STATUS_SUCCESS);
+        return response;
+    }
+
+    private FeEnterprise requireEnterpriseBySession(String sessionId) {
+        FeConversation conversation = conversationService.requireBySessionId(sessionId);
+        return enterpriseService.requireById(conversation.getEnterpriseId());
+    }
+
+    private McpEnterpriseProfileResponse toResponse(FeEnterprise enterprise) {
+        Map<String, Object> profileRoot = parseProfileJson(enterprise.getProfileJson());
+        Map<String, Object> preferences = extractPreferences(profileRoot);
+
+        McpEnterpriseProfileResponse response = new McpEnterpriseProfileResponse();
+        response.setCompanyName(enterprise.getName());
+        response.setCompanyAddress(enterprise.getRegisteredAddress());
+        response.setIndustry(enterprise.getIndustry());
+        response.setTaxQualification(readString(profileRoot.get("tax_qualification")));
+        response.setPreferences(preferences);
+        return response;
+    }
+
+    private boolean applyUpdate(FeEnterprise enterprise,
+                                Map<String, Object> profileRoot,
+                                Map<String, Object> preferences,
+                                String key,
+                                Object value) {
+        switch (key) {
+            case "company_name":
+                enterprise.setName(requireNonBlankText(value, key));
+                return true;
+            case "company_address":
+                enterprise.setRegisteredAddress(requireNonBlankText(value, key));
+                return true;
+            case "industry":
+                enterprise.setIndustry(toNullableText(value));
+                return true;
+            case "scale":
+                enterprise.setScale(toNullableText(value));
+                return true;
+            case "tax_qualification":
+                profileRoot.put("tax_qualification", toNullableText(value));
+                return true;
+            default:
+                break;
+        }
+
+        if (key.startsWith(PREF_PREFIX)) {
+            String prefKey = key.substring(PREF_PREFIX.length());
+            if (!StringUtils.hasText(prefKey)) {
+                throw new BizException(ErrorCode.BAD_REQUEST, "偏好键不能为空：" + key);
+            }
+            if (!ALLOWED_PREFERENCE_KEYS.contains(prefKey)) {
+                throw new BizException(ErrorCode.BAD_REQUEST, "不支持的偏好字段：" + prefKey);
+            }
+            String prefValue = toNullableText(value);
+            validatePreferenceValue(prefKey, prefValue);
+            if (prefValue == null) {
+                preferences.remove(prefKey);
+            } else {
+                preferences.put(prefKey, prefValue);
+            }
+            return true;
+        }
+
+        log.debug("忽略未知的企业画像更新字段：{}", key);
+        return false;
+    }
+
+    private void validatePreferenceValue(String prefKey, String value) {
+        if (value == null) {
+            return;
+        }
+        if ("settlement_cycle".equals(prefKey) && !ALLOWED_SETTLEMENT_CYCLES.contains(value)) {
+            throw new BizException(ErrorCode.BAD_REQUEST,
+                    "settlement_cycle 须为 daily/weekly/biweekly/monthly 之一");
+        }
+        if ("default_settlement_mode".equals(prefKey)) {
+            Set<String> modes = new HashSet<>(Arrays.asList("daily", "piece", "monthly"));
+            if (!modes.contains(value)) {
+                throw new BizException(ErrorCode.BAD_REQUEST,
+                        "default_settlement_mode 须为 daily/piece/monthly 之一");
+            }
+        }
+    }
+
+    private Map<String, Object> parseProfileJson(String profileJson) {
+        if (!StringUtils.hasText(profileJson)) {
+            return new LinkedHashMap<>();
+        }
+        try {
+            Map<String, Object> parsed = objectMapper.readValue(profileJson.trim(),
+                    new TypeReference<Map<String, Object>>() {
+                    });
+            return parsed != null ? new LinkedHashMap<>(parsed) : new LinkedHashMap<>();
+        } catch (Exception ex) {
+            log.warn("解析 profile_json 失败，将使用空对象：{}", ex.getMessage());
+            return new LinkedHashMap<>();
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> extractPreferences(Map<String, Object> profileRoot) {
+        Object raw = profileRoot.get("preferences");
+        if (raw instanceof Map) {
+            return new LinkedHashMap<>((Map<String, Object>) raw);
+        }
+        return new LinkedHashMap<>();
+    }
+
+    private String writeProfileJson(Map<String, Object> profileRoot) {
+        try {
+            return objectMapper.writeValueAsString(profileRoot);
+        } catch (Exception ex) {
+            throw new BizException(ErrorCode.INTERNAL_ERROR);
+        }
+    }
+
+    private static String requireNonBlankText(Object value, String key) {
+        String text = toNullableText(value);
+        if (text == null) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "字段 " + key + " 不能为空");
+        }
+        return text;
+    }
+
+    private static String toNullableText(Object value) {
+        if (value == null) {
+            return null;
+        }
+        String text = String.valueOf(value).trim();
+        return text.isEmpty() ? null : text;
+    }
+
+    private static String readString(Object value) {
+        return value != null ? String.valueOf(value) : null;
+    }
+}

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/enterprise/dto/McpEnterpriseProfileResponse.java

@@ -0,0 +1,69 @@
+package com.huimv.employment.service.enterprise.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+@Schema(description = "MCP 企业画像响应（v2 §6.2.1）")
+public class McpEnterpriseProfileResponse {
+
+    @JsonProperty("company_name")
+    @Schema(description = "企业全称", example = "XX科技有限公司")
+    private String companyName;
+
+    @JsonProperty("company_address")
+    @Schema(description = "企业地址（注册地址）", example = "南京市玄武区...")
+    private String companyAddress;
+
+    @Schema(description = "所属行业", example = "互联网")
+    private String industry;
+
+    @JsonProperty("tax_qualification")
+    @Schema(description = "纳税人资质", example = "一般纳税人")
+    private String taxQualification;
+
+    @Schema(description = "偏好设置")
+    private Map<String, Object> preferences = new LinkedHashMap<>();
+
+    public String getCompanyName() {
+        return companyName;
+    }
+
+    public void setCompanyName(String companyName) {
+        this.companyName = companyName;
+    }
+
+    public String getCompanyAddress() {
+        return companyAddress;
+    }
+
+    public void setCompanyAddress(String companyAddress) {
+        this.companyAddress = companyAddress;
+    }
+
+    public String getIndustry() {
+        return industry;
+    }
+
+    public void setIndustry(String industry) {
+        this.industry = industry;
+    }
+
+    public String getTaxQualification() {
+        return taxQualification;
+    }
+
+    public void setTaxQualification(String taxQualification) {
+        this.taxQualification = taxQualification;
+    }
+
+    public Map<String, Object> getPreferences() {
+        return preferences;
+    }
+
+    public void setPreferences(Map<String, Object> preferences) {
+        this.preferences = preferences;
+    }
+}

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/enterprise/dto/McpEnterpriseProfileUpdateRequest.java

@@ -0,0 +1,23 @@
+package com.huimv.employment.service.enterprise.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import javax.validation.constraints.NotEmpty;
+import java.util.Map;
+
+@Schema(description = "MCP 企业画像增量更新请求（v2 §6.2.2）")
+public class McpEnterpriseProfileUpdateRequest {
+
+    @NotEmpty(message = "updates 不能为空")
+    @Schema(description = "增量更新字段，支持点路径如 preferences.settlement_cycle",
+            example = "{\"preferences.settlement_cycle\":\"monthly\",\"company_address\":\"上海市浦东新区...\"}")
+    private Map<String, Object> updates;
+
+    public Map<String, Object> getUpdates() {
+        return updates;
+    }
+
+    public void setUpdates(Map<String, Object> updates) {
+        this.updates = updates;
+    }
+}

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/enterprise/dto/McpEnterpriseProfileUpdateResponse.java

@@ -0,0 +1,31 @@
+package com.huimv.employment.service.enterprise.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "MCP 企业画像更新响应（v2 §6.2.2）")
+public class McpEnterpriseProfileUpdateResponse {
+
+    @JsonProperty("updated_fields")
+    @Schema(description = "成功更新的字段数", example = "2")
+    private int updatedFields;
+
+    @Schema(description = "更新结果", example = "success")
+    private String status;
+
+    public int getUpdatedFields() {
+        return updatedFields;
+    }
+
+    public void setUpdatedFields(int updatedFields) {
+        this.updatedFields = updatedFields;
+    }
+
+    public String getStatus() {
+        return status;
+    }
+
+    public void setStatus(String status) {
+        this.status = status;
+    }
+}