@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

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

@@ -1,232 +0,0 @@
-# 平台 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

@@ -1,278 +0,0 @@
-# 第三方接口接入（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)