@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-data-access/references/outbound/service-catalog.md

@@ -0,0 +1,232 @@
+# 平台 Service 清单（services）
+
+> 仅适用于**同 JVM** 场景（pom 引入 `cloud-system-manage-module` 且同 Spring Boot 应用部署）。非同 JVM 必须 Feign，用 `meritdata-platform-integration`。
+
+---
+
+## 1. 用户 / 组织
+
+### 1.1 IUserService
+
+```java
+public interface IUserService {
+    UserDTO getById(String userId);
+    List<UserDTO> listByIds(List<String> userIds);
+    UserDTO getByCode(String code);
+    PageResult<UserDTO> page(UserQuery query);
+}
+```
+
+### 1.2 IOrgService
+
+```java
+public interface IOrgService {
+    OrgDTO getById(String orgId);
+    List<OrgDTO> listByIds(List<String> orgIds);
+    List<OrgTreeDTO> getOrgTree(String parentId);
+    OrgDTO getByCode(String code);
+}
+```
+
+### 1.3 IDeptService
+
+```java
+public interface IDeptService {
+    DeptDTO getById(String deptId);
+    List<DeptDTO> listByDeptIds(List<String> deptIds);
+    List<DeptDTO> listByOrgId(String orgId);
+}
+```
+
+---
+
+## 2. 角色 / 权限
+
+### 2.1 IRoleService
+
+```java
+public interface IRoleService {
+    RoleDTO getById(String roleId);
+    RoleDTO getByCode(String roleCode);
+    List<RoleDTO> listByUserId(String userId);
+    List<RoleDTO> listByOrgId(String orgId);
+}
+```
+
+### 2.2 IAssignService（用户角色分配）
+
+```java
+public interface IAssignService {
+    void assignRoles(String userId, List<String> roleCodes);
+    void revokeRoles(String userId, List<String> roleCodes);
+    List<String> getUserRoleCodes(String userId);
+}
+```
+
+### 2.3 IDamService（数据访问管理）
+
+```java
+public interface IDamService {
+    boolean hasPermission(String userId, String resourceCode);
+    boolean hasRole(String userId, String roleCode);
+    List<String> getAuthorizedResourceIds(String userId, String resourceType);
+}
+```
+
+---
+
+## 3. 字典 / 查找
+
+### 3.1 ILookupService
+
+```java
+public interface ILookupService {
+    List<LookupDTO> listByType(String type);
+    LookupDTO getByCode(String type, String code);
+    String getName(String type, String code);  // 常用：code 转 name
+    Map<String, String> getCodeNameMap(String type);
+}
+```
+
+### 3.2 IConfigService
+
+```java
+public interface IConfigService {
+    String getConfig(String key);
+    <T> T getConfig(String key, Class<T> clazz);
+    void refresh(String key);  // 手动刷新配置缓存
+}
+```
+
+---
+
+## 4. 审计 / 日志
+
+### 4.1 IOperationLogService
+
+```java
+public interface IOperationLogService {
+    void log(OperationLogDTO log);
+    PageResult<OperationLogDTO> page(LogQuery query);
+}
+```
+
+### 4.2 IAuditService
+
+```java
+public interface IAuditService {
+    void record(AuditDTO audit);
+}
+```
+
+---
+
+## 5. 文件 / 附件
+
+### 5.1 IAttachmentService
+
+```java
+public interface IAttachmentService {
+    AttachmentDTO getById(String id);
+    List<AttachmentDTO> listByBizId(String bizType, String bizId);
+    String upload(MultipartFile file, String bizType, String bizId);
+    void delete(String id);
+}
+```
+
+---
+
+## 6. 消息
+
+### 6.1 IMessageService
+
+```java
+public interface IMessageService {
+    void send(MessageDTO message);
+    void sendToUsers(MessageDTO message, List<String> userIds);
+}
+```
+
+---
+
+## 7. 流程 / 任务
+
+### 7.1 IBpmService
+
+```java
+public interface IBpmService {
+    String startProcess(String processKey, String businessKey, Map<String, Object> variables);
+    void complete(String taskId, Map<String, Object> variables);
+    void reject(String taskId, String reason);
+    void withdraw(String processInstanceId, String reason);
+}
+```
+
+---
+
+## 8. 注入使用示例
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private IUserService userService;
+
+    @Autowired
+    private ILookupService lookupService;
+
+    public OrderVO getOrderDetail(Long id) {
+        Order order = orderRepository.findById(id).orElseThrow();
+
+        // ✅ 同 JVM：直接注入平台 Service
+        UserDTO user = userService.getById(order.getApplicantUserId());
+
+        // ✅ 字典：code 转 name
+        String statusName = lookupService.getName("ORDER_STATUS", order.getStatus());
+
+        OrderVO vo = OrderConverter.toVO(order);
+        vo.setApplicantName(user.getName());
+        vo.setStatusName(statusName);
+        return vo;
+    }
+}
+```
+
+---
+
+## 9. ❌ 反模式
+
+### 9.1 ❌ 非同 JVM 用同 JVM Service
+
+```java
+// ❌ 错：二开服务独立部署，却注入 IUserService
+// 运行时找不到 Bean → 启动失败
+// 即使能注入，也是错的（违反服务边界）
+```
+
+### 9.2 ❌ 同 JVM 直连平台数据库
+
+```java
+// ❌ 错：用 JdbcTemplate 查平台表
+jdbcTemplate.queryForObject("SELECT * FROM PF_USER WHERE id = ?", ...);
+```
+
+即使同 JVM，也禁止直连平台库（仍走 Service）。
+
+### 9.3 ❌ 同 JVM 复制平台 Entity
+
+```java
+// ❌ 错：把 UserDTO 复制到二开模块
+public class User extends UserDTO { ... }
+```
+
+DTO 是平台公共契约，复制定义会破坏升级。
+
+---
+
+## 10. 关联阅读
+
+- [same-jvm-detection.md](same-jvm-detection.md) — 同 JVM 判定
+- [usage-patterns.md](usage-patterns.md) — 典型用法
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-access/references/outbound/third-party.md

@@ -0,0 +1,278 @@
+# 第三方接口接入（third-party）
+
+> HR / 邮件 / 短信 / 支付 / 物流等外部系统的接入模式。
+
+---
+
+## 1. 通用模式
+
+### 1.1 接口封装层
+
+```
+Controller (二开)
+    ↓
+Service (二开业务)
+    ↓
+Client (封装第三方)     ← 这里处理第三方差异
+    ↓
+HttpUtil / Feign / SDK
+```
+
+**关键**：第三方差异（鉴权/重试/超时）封装在 Client 层，业务 Service 不感知。
+
+---
+
+## 2. HR 同步
+
+### 2.1 同步策略
+
+| 策略 | 触发 | 频率 |
+|------|------|------|
+| 全量同步 | 首次接入 | 一次性 |
+| 增量同步 | 定时任务 | 每天凌晨 |
+| 实时同步 | HR 回调 | 实时 |
+
+### 2.2 定时同步 Job
+
+```java
+@JobHandler("hrUserSyncJob")
+@Component
+public class HrUserSyncJob extends IJobHandler {
+
+    @Autowired
+    private HrClient hrClient;
+
+    @Autowired
+    private IUserService userService;
+
+    @Override
+    public ReturnT<String> execute(String param) {
+        // 1. 获取增量变更时间
+        LocalDateTime lastSyncTime = syncTimeService.getLastSyncTime("HR_USER");
+        List<HrUserChange> changes = hrClient.getUserChanges(lastSyncTime);
+
+        // 2. 批量处理
+        for (List<HrUserChange> batch : Lists.partition(changes, 100)) {
+            // 幂等：先查后写
+            for (HrUserChange change : batch) {
+                if (change.getAction().equals("DELETE")) {
+                    userService.disable(change.getUserId());
+                } else {
+                    userService.upsert(convertToUser(change));
+                }
+            }
+        }
+
+        // 3. 记录同步时间
+        syncTimeService.updateLastSyncTime("HR_USER", LocalDateTime.now());
+        return SUCCESS;
+    }
+}
+```
+
+### 2.3 ❌ 反例
+
+- ❌ 同步逻辑写在 Controller
+- ❌ 不做幂等（重复同步产生脏数据）
+- ❌ 同步失败不告警（悄悄漏数据）
+- ❌ 同步阻塞主流程（HR 接口慢导致业务卡顿）
+
+---
+
+## 3. 短信发送
+
+### 3.1 短信网关（阿里云 / 腾讯云 / 华为云）
+
+```java
+@Component
+public class SmsClient {
+
+    @Value("${sms.access-key}")
+    private String accessKey;
+
+    @Value("${sms.access-secret}")
+    private String accessSecret;
+
+    @Value("${sms.signature}")
+    private String signature;
+
+    public void send(String phone, String templateCode, Map<String, String> params) {
+        // 调用短信网关 SDK
+        SmsSendResult result = smsGateway.send(
+            accessKey, accessSecret,
+            phone, signature, templateCode, params
+        );
+
+        if (!result.isSuccess()) {
+            throw new SmsSendException("短信发送失败：" + result.getMessage());
+        }
+    }
+}
+```
+
+### 3.2 Service 封装
+
+```java
+@Service
+public class SmsService {
+
+    @Autowired
+    private SmsClient smsClient;
+
+    public void sendVerificationCode(String phone, String code) {
+        Map<String, String> params = new HashMap<>();
+        params.put("code", code);
+        params.put("minutes", "5");
+
+        smsClient.send(phone, "SMS_VERIFICATION_CODE", params);
+    }
+}
+```
+
+### 3.3 ❌ 反例
+
+- ❌ 业务代码直接调 SDK（换短信厂商要改业务代码）
+- ❌ 短信模板硬编码在代码里
+- ❌ 不限流（被刷爆）
+
+---
+
+## 4. 邮件发送
+
+### 4.1 Spring Mail
+
+```java
+@Service
+public class EmailService {
+
+    @Autowired
+    private JavaMailSender mailSender;
+
+    @Value("${spring.mail.username}")
+    private String from;
+
+    public void send(String to, String subject, String content) {
+        SimpleMailMessage message = new SimpleMailMessage();
+        message.setFrom(from);
+        message.setTo(to);
+        message.setSubject(subject);
+        message.setText(content);
+
+        mailSender.send(message);
+    }
+
+    public void sendHtml(String to, String subject, String htmlContent) {
+        MimeMessage message = mailSender.createMimeMessage();
+        try {
+            MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
+            helper.setFrom(from);
+            helper.setTo(to);
+            helper.setSubject(subject);
+            helper.setText(htmlContent, true);  // true = HTML
+            mailSender.send(message);
+        } catch (MessagingException e) {
+            throw new EmailSendException("邮件发送失败", e);
+        }
+    }
+}
+```
+
+### 4.2 ❌ 反例
+
+- ❌ 用户输入直接拼接 HTML（XSS 风险）
+- ❌ 邮件内容含敏感信息（密码 / token）明文
+- ❌ 不限流（被刷爆）
+
+---
+
+## 5. 支付接入
+
+### 5.1 异步通知 vs 同步回调
+
+| 类型 | 时机 | 用途 |
+|------|------|------|
+| 同步回调 | 用户支付完成跳转回来 | 仅展示"支付中"页面 |
+| 异步通知 | 支付平台后台调用 | **唯一可信**的支付成功依据 |
+
+### 5.2 异步通知处理（关键）
+
+```java
+@PostMapping("/payment/notify")
+public String handlePaymentNotify(@RequestBody PaymentNotifyRequest request) {
+    // 1. 验签（必须）
+    if !paymentClient.verifySignature(request) {
+        return "FAIL";
+    }
+
+    // 2. 幂等处理（必须）
+    if (paymentNotifyLogRepository.existsByNotifyId(request.getNotifyId())) {
+        return "SUCCESS";  // 已处理过，直接返回成功
+    }
+
+    // 3. 业务处理（事务）
+    orderService.markPaid(
+        request.getOrderNo(),
+        request.getPayTime(),
+        request.getAmount()
+    );
+
+    // 4. 记录通知日志
+    paymentNotifyLogRepository.save(request);
+
+    return "SUCCESS";
+}
+```
+
+### 5.3 ❌ 反例
+
+- ❌ 不验签（伪造通知）
+- ❌ 不幂等（重复通知导致重复发货）
+- ❌ 直接依赖同步回调（用户关浏览器就丢了）
+
+---
+
+## 6. 物流查询
+
+### 6.1 缓存策略
+
+```java
+public TrackingInfo track(String expressNo, String companyCode) {
+    String cacheKey = "tracking:" + companyCode + ":" + expressNo;
+    TrackingInfo cached = redisTemplate.opsForValue().get(cacheKey);
+    if (cached != null) {
+        return cached;
+    }
+
+    // 调物流公司 API
+    TrackingInfo info = logisticsClient.track(companyCode, expressNo);
+
+    // 缓存 30 分钟
+    redisTemplate.opsForValue().set(cacheKey, info, Duration.ofMinutes(30));
+    return info;
+}
+```
+
+### 6.2 ❌ 反例
+
+- ❌ 每次都调物流 API（被限流 / 收费）
+- ❌ 不缓存物流状态（用户刷新一次查一次）
+
+---
+
+## 7. 通用规范
+
+| 规范 | 说明 |
+|------|------|
+| 超时 | 必须设（5-15s）|
+| 重试 | 幂等接口可重试，非幂等不重试 |
+| 限流 | 避免被刷爆（短信 / 邮件）|
+| 监控 | 失败告警（短信发送失败要通知运维）|
+| 日志 | 脱敏（手机号 / 邮箱 / 卡号）|
+
+---
+
+## 8. 关联阅读
+
+- [feign-guide.md](feign-guide.md) — Feign 写法
+- [batch-assembly.md](batch-assembly.md) — 批量装配
+- [SKILL.md](../SKILL.md)