@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

package/skills/meritdata-platform-data-access/references/outbound/usage-patterns.md

@@ -1,257 +0,0 @@
-# 平台 Service 典型用法（usage-patterns）
-
-> 同 JVM 场景下，平台 Service 的常见用法模式。
-
----
-
-## 1. 用户查询
-
-### 1.1 单个用户
-
-```java
-@Autowired
-private IUserService userService;
-
-public UserDTO getUser(String userId) {
-    return userService.getById(userId);
-}
-```
-
-### 1.2 批量用户
-
-```java
-public Map<String, UserDTO> getUserMap(List<String> userIds) {
-    List<UserDTO> users = userService.listByIds(userIds);
-    return users.stream().collect(Collectors.toMap(UserDTO::getId, Function.identity()));
-}
-```
-
-### 1.3 按工号查
-
-```java
-public UserDTO getByCode(String code) {
-    return userService.getByCode(code);
-}
-```
-
----
-
-## 2. 组织树查询
-
-### 2.1 整棵组织树
-
-```java
-List<OrgTreeDTO> tree = orgService.getOrgTree(null);  // null = 根
-```
-
-### 2.2 子组织列表
-
-```java
-List<OrgTreeDTO> children = orgService.getOrgTree(parentOrgId);
-```
-
-### 2.3 用户所属组织
-
-```java
-public OrgDTO getUserOrg(String userId) {
-    UserDTO user = userService.getById(userId);
-    return orgService.getById(user.getOrgId());
-}
-```
-
----
-
-## 3. 角色 / 权限校验
-
-### 3.1 单角色校验
-
-```java
-if (!damService.hasRole(userId, "PURCHASE_MANAGER")) {
-    throw new BizException("无采购经理权限");
-}
-```
-
-### 3.2 资源权限校验
-
-```java
-if (!damService.hasPermission(userId, "purchase_order:create")) {
-    throw new BizException("无创建权限");
-}
-```
-
-### 3.3 数据范围过滤
-
-```java
-List<String> authorizedOrgIds = damService.getAuthorizedResourceIds(userId, "org");
-// 在 SQL 里追加：AND org_id IN (authorizedOrgIds)
-```
-
----
-
-## 4. 字典查询
-
-### 4.1 字典列表（按 type）
-
-```java
-List<LookupDTO> orderStatusList = lookupService.listByType("ORDER_STATUS");
-```
-
-### 4.2 单个字典项
-
-```java
-LookupDTO item = lookupService.getByCode("ORDER_STATUS", "PENDING");
-String name = item.getName();  // "审批中"
-```
-
-### 4.3 批量 code → name 映射
-
-```java
-Map<String, String> codeNameMap = lookupService.getCodeNameMap("ORDER_STATUS");
-// {"DRAFT": "草稿", "PENDING": "审批中", ...}
-```
-
----
-
-## 5. 操作日志
-
-### 5.1 记录日志
-
-```java
-operationLogService.log(OperationLogDTO.builder()
-    .module("PURCHASE_ORDER")
-    .action("CREATE")
-    .bizId(order.getId().toString())
-    .userId(SecurityUtils.getCurrentUserId())
-    .content("创建采购订单：" + order.getOrderNo())
-    .build());
-```
-
-### 5.2 注解方式（推荐）
-
-```java
-@OperationLog(module = "PURCHASE_ORDER", action = "CREATE")
-public OrderVO create(OrderCreateParam param) {
-    // 业务逻辑
-    // 切面自动记录日志
-}
-```
-
----
-
-## 6. 附件上传
-
-### 6.1 上传文件
-
-```java
-@PostMapping("/upload")
-public String upload(@RequestParam MultipartFile file,
-                     @RequestParam String bizType,
-                     @RequestParam String bizId) {
-    return attachmentService.upload(file, bizType, bizId);
-}
-```
-
-### 6.2 列出业务附件
-
-```java
-List<AttachmentDTO> attachments = attachmentService.listByBizId("PURCHASE_ORDER_CONTRACT", orderId);
-```
-
----
-
-## 7. 流程启动 / 推进
-
-### 7.1 启动流程
-
-```java
-String processInstanceId = bpmService.startProcess(
-    "purchase_order_approval",
-    order.getId().toString(),         // businessKey
-    variables                          // 流程变量
-);
-```
-
-### 7.2 审批通过
-
-```java
-bpmService.complete(taskId, variables);
-```
-
-### 7.3 审批驳回
-
-```java
-bpmService.reject(taskId, "材料不全");
-```
-
----
-
-## 8. 消息推送
-
-### 8.1 站内信
-
-```java
-messageService.send(MessageDTO.builder()
-    .title("采购订单待审批")
-    .content("订单号：" + order.getOrderNo())
-    .type("NOTIFICATION")
-    .bizId(order.getId().toString())
-    .build());
-```
-
-### 8.2 推送给指定用户
-
-```java
-messageService.sendToUsers(message, List.of(approverUserId));
-```
-
----
-
-## 9. ❌ 反模式
-
-### 9.1 ❌ 循环调单条查询
-
-```java
-// ❌ 错：N+1
-for (String userId : userIds) {
-    UserDTO user = userService.getById(userId);
-}
-```
-
-✅ 用 `listByIds` 一次拉。
-
-### 9.2 ❌ 在 Controller 直接调平台 Service
-
-```java
-// ❌ 错：Controller 应该调自己的 Service
-@PostMapping("/orders")
-public OrderVO create(@RequestBody OrderCreateParam param) {
-    UserDTO user = userService.getById(param.getUserId());  // 不应该
-    return orderService.create(param, user);
-}
-
-// ✅ 正确：业务 Service 封装
-@PostMapping("/orders")
-public OrderVO create(@RequestBody OrderCreateParam param) {
-    return orderService.create(param);
-}
-```
-
-### 9.3 ❌ 缓存键不带用户标识
-
-```java
-// ❌ 错：缓存全局共享 → 数据泄露
-@Cacheable("user")
-public UserDTO getById(String userId) { ... }
-
-// ✅ 正确：缓存键带用户
-@Cacheable(value = "user", key = "#userId + ':' + T(SecurityUtils).getCurrentTenantId()")
-public UserDTO getById(String userId) { ... }
-```
-
----
-
-## 10. 关联阅读
-
-- [service-catalog.md](service-catalog.md) — Service 清单
-- [same-jvm-detection.md](same-jvm-detection.md) — 同 JVM 判定
-- [SKILL.md](../SKILL.md)

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

@@ -1,392 +0,0 @@
-# 对外 WebApi 发布与授权（webapi）
-
-> **目的**：把 MeritData Cloud 平台能力安全地发布给外部系统（供应商系统、合作伙伴系统等），不复制平台拦截器内部算法或密钥。
-> **来源**：石油 `merit-cloud-dev/modules/merit-cloud-webapi/`（v2.6.0 P1-B 整合）
-> **平台版本**：MeritData Cloud（仅 `/webapi/**` 路径生效）
-
----
-
-## 触发场景
-
-- 外部系统要调用平台能力（如供应商系统拉采购订单、银行系统拉对账单）
-- 新增 `/webapi/**` 接口供外部系统调用
-- 建立应用（App）+ 接口编目 + IP 黑白名单 + 接口授权
-- 处理 App-Key / App-Token 认证（vs 内部 Cookie session）
-- 处理重放攻击防护、调用审计、密钥轮换
-- 内部微服务调用（**不**适用）→ 用 `meritdata-platform-data-access/references/outbound/feign-guide.md`
-
-## 不适用
-
-- 内部 Feign / 同 JVM Bean → 用 `feign-guide.md` / `service-catalog.md`
-- 网关路由部署 / 证书签发 / License 破解 → 不属于本 skill 范围
-- 前端多服务 axios → 用 `meritdata-platform-frontend/references/http-client/`
-- 外部组织人员同步 → 用 `meritdata-platform-data-access/references/inbound/masterdata-sync`
-
----
-
-## 前置约束
-
-- **服务端路径必须** `/webapi/**`（非 `/api/**` / `/open/**` 等）
-- **必须先完成 WebApiInfo 登记**（不登记 = 平台不认）
-- **必须 AppAuth 授权**（App → 一组允许的接口 + IP 规则）
-- **不复制平台拦截器内部算法**（不自行实现 `WebApiInterceptor`）
-- **Secret/App-Token 不进**源码 / 日志 / 示例 / 异常 / 留痕
-- **写接口必须**声明幂等键 + 重放防护 + 业务授权
-
----
-
-## 一、调用方向判定（首要）
-
-```mermaid
-flowchart TD
-    A{调用方是谁？}
-    A -->|外部系统<br>供应商/银行/合作伙伴| B[WebApi 本 skill]
-    A -->|公司内部微服务<br>同集群| C[Feign 走 feign-guide]
-    A -->|同 JVM 平台模块| D[直接注入 Service]
-
-    B --> E[App-Key + App-Token 认证]
-    C --> F[Cookie session 或免认证]
-    D --> F
-
-    E --> G[/webapi/** 路径]
-    F --> H[/api/** 路径]
-```
-
-| 调用方 | 走什么 | 路径前缀 | 认证 |
-|--------|-------|---------|------|
-| 外部系统（供应商）| **WebApi**（本 skill）| `/webapi/**` | App-Key + App-Token |
-| 公司内部微服务（异 JVM）| Feign | `/api/**` | Cookie session 或内部免认证 |
-| 同 JVM 平台模块 | 直接注入 Service | （不走 HTTP）| JVM 内调用 |
-
----
-
-## 二、平台四类服务（public-contracts）
-
-按 V6.13.2 平台约定，WebApi 涉及 4 类服务：
-
-| 服务 | 作用 |
-|------|------|
-| **App** 服务 | 管理外部应用（创建 App、分配 App-Key、查看调用方）|
-| **Category** 服务 | 管理接口分类（按业务模块划分）|
-| **Info** 服务 | 管理接口编目（每个 `/webapi/**` 必须登记）|
-| **Auth** 服务 | 管理应用授权（App → 一组 Info + IP 规则）|
-
----
-
-## 三、接口编目（5 要素）
-
-每个对外接口必须登记到 WebApiInfo，包含：
-
-| 要素 | 含义 | 示例 |
-|------|------|------|
-| **稳定 URL** | 不随版本变化 | `/webapi/purchaseOrder/queryBySupplier` |
-| **HTTP 方法** | GET / POST | POST |
-| **请求/响应 schema** | 严格 DTO + Jakarta Validation | `WebApiPurchaseOrderQueryRequest` / `ResultBody<...>` |
-| **责任人 + 密级** | 谁负责 + 数据敏感度 | 张三 / 密级 3 |
-| **幂等键 + 超时 + 版本** | 防重放 + SLA | bizKey=`{supplierId}:{orderNo}` / 5s / v1 |
-
-### 3.1 反模式
-
-```java
-// ❌ 错误 1：把 Controller 路径当成未经登记的 WebApi
-@RestController
-@RequestMapping("/api/open/purchaseOrder")  // ❌ 不是 /webapi/**
-public class OpenPurchaseOrderController { ... }
-
-// ❌ 错误 2：响应直接返回实体（不遵循统一响应）
-@GetMapping("/list")
-public List<PurchaseOrder> list() { ... }  // ❌ 应返回 ResultBody
-
-// ❌ 错误 3：写接口不声明幂等键
-@PostMapping("/approve")
-public ResultBody<Void> approve(@RequestBody ApproveRequest req) {
-    // ❌ 无幂等键 → 重放攻击风险
-}
-
-// ❌ 错误 4：暴露堆栈或内部实体
-catch (Exception e) {
-    return ResultBody.fail(500, e.getStackTrace().toString());  // ❌ 泄露内部
-}
-```
-
-### 3.2 正模式
-
-```java
-@RestController
-@RequestMapping("/webapi/purchaseOrder")  // ✅ /webapi/**
-@WebApi(
-    code = "purchaseOrder.queryBySupplier",
-    name = "供应商查询采购订单",
-    category = "purchase",
-    secretLevel = 3,
-    idempotentKey = "#{bizKey}",  // ✅ SpEL 取 bizKey 字段
-    timeout = 5000,
-    version = "v1",
-    owner = "zhangsan"
-)
-public class WebApiPurchaseOrderController {
-
-    @PostMapping("/queryBySupplier")
-    public ResultBody<PurchaseOrderPageVO> queryBySupplier(
-        @Valid @RequestBody WebApiPurchaseOrderQueryRequest req,
-        @RequestHeader("App-Key") String appKey,
-        @RequestHeader("App-Token") String appToken,
-        @RequestHeader("bizKey") String bizKey  // ✅ 幂等键
-    ) {
-        // 1. 业务授权（不只是 App-Token）
-        if (!permissionService.canAccessSupplier(currentSupplierId(), req.getSupplierId())) {
-            return ResultBody.fail(403, "无该供应商权限");
-        }
-
-        // 2. 业务逻辑
-        Page<PurchaseOrder> page = purchaseOrderService.queryBySupplier(req);
-
-        // 3. 审计
-        auditService.log(currentApp(), "purchaseOrder.queryBySupplier", req);
-
-        // 4. 统一响应
-        return ResultBody.ok(PurchaseOrderPageVO.from(page));
-    }
-}
-```
-
----
-
-## 四、App 注册与授权
-
-### 4.1 创建 App
-
-每个外部系统（供应商、银行、合作伙伴）对应一个 App：
-
-```java
-// App 创建请求
-WebApiAppCreateRequest req = new WebApiAppCreateRequest();
-req.setAppCode("SUPPLIER_ACME");
-req.setAppName("ACME 供应商对接系统");
-req.setSecretLevel(2);
-req.setIpWhitelist(Arrays.asList("10.0.5.0/24", "192.168.1.100"));
-req.setAllowedCategories(Arrays.asList("purchase", "inquiry"));
-req.setAllowedApis(Arrays.asList(
-    "purchaseOrder.queryBySupplier",
-    "inquiry.query"
-));
-req.setRateLimit(100);  // QPS 上限
-
-WebApiAppVO app = webApiAppService.create(req);
-//  → 返回 appKey + appSecret（只返回一次）
-//  → 业务方必须安全存储
-```
-
-### 4.2 App 鉴权流程
-
-```
-外部系统                                  平台 WebApi 拦截器
-   │                                          │
-   │  1. POST /webapi/purchaseOrder/queryBySupplier
-   │     Headers:
-   │       App-Key: SUPPLIER_ACME
-   │       App-Token: <短时 token>
-   │       bizKey: SUP001:ORD20260908001
-   │     Body: {"supplierId":"SUP001", ...}
-   │ ─────────────────────────────────────────►
-   │                                          │
-   │                          2. 校验 App-Key 存在
-   │                          3. 校验 IP 白名单
-   │                          4. 校验 App-Token（短时 + 签名）
-   │                          5. 校验接口授权（allowedApis）
-   │                          6. 校验幂等键（重放检测）
-   │                          7. 进入 Controller
-   │                                          │
-   │  8. ResultBody<PurchaseOrderPageVO>      │
-   │ ◄─────────────────────────────────────────
-```
-
-### 4.3 App-Token 生成（短时）
-
-外部系统调用前必须生成短时 token（**不是**长期 secret）：
-
-```java
-// 外部系统（伪代码）
-public String generateAppToken(String appKey, String appSecret, long timestamp) {
-    // 1. 拼字符串
-    String raw = appKey + appSecret + timestamp;
-
-    // 2. 按平台文档算法签名（不复制内部算法）
-    String sign = PlatformSignatureUtil.sign(raw);
-
-    // 3. 返回 token
-    return appKey + ":" + timestamp + ":" + sign;
-}
-
-// 调用方使用
-String token = generateAppToken(appKey, appSecret, System.currentTimeMillis());
-httpPost("/webapi/purchaseOrder/queryBySupplier",
-    headers: {
-      "App-Key": appKey,
-      "App-Token": token,
-      "bizKey": "SUP001:ORD20260908001"
-    },
-    body: {...}
-);
-```
-
-**关键约束**：
-- 时钟偏差容忍：±5 分钟
-- App-Token 一次性（重放检测由 bizKey 保证）
-- Secret 不进日志 / 示例 / 异常
-
----
-
-## 五、错误码（431-437 认证类 + 业务 ResultBody）
-
-### 5.1 认证错误
-
-| 状态码 | 含义 | 处置 |
-|:------:|------|------|
-| 431 | App-Key 不存在 | 检查 appKey 拼写 |
-| 432 | App-Token 无效 | 重新生成 token |
-| 433 | App-Token 过期 | 用新 timestamp 重生成 |
-| 434 | IP 不在白名单 | 联系平台管理员加白 |
-| 435 | 接口未授权 | 在 allowedApis 中添加 |
-| 436 | 签名错误 | 检查平台签名算法版本 |
-| 437 | 重放检测命中（bizKey 重复）| 业务方确认是否真的重复 |
-
-### 5.2 业务错误
-
-```json
-{
-  "code": "SUPPLIER_NOT_FOUND",
-  "message": "供应商不存在",
-  "data": null
-}
-```
-
----
-
-## 六、生成规则（必须遵守）
-
-### 6.1 服务端路径
-
-- ✅ 必须位于 `/webapi/**`
-- ✅ 必须先完成 WebApiInfo 登记
-- ✅ 必须 AppAuth 授权
-- ❌ 不在 `/api/open/**` / `/external/**` / `/public/**` 等其他前缀
-
-### 6.2 请求/响应
-
-- ✅ 请求体使用 DTO + Jakarta Validation（`@NotNull` / `@Size` / `@Pattern`）
-- ✅ 响应遵循平台统一 `ResultBody<T>`，不暴露堆栈或内部实体
-- ✅ 错误码使用稳定 code（`SUPPLIER_NOT_FOUND`），不要直接用 HTTP 状态码代替
-
-### 6.3 写接口
-
-- ✅ 必须声明幂等键（`@Idempotent(key = "#{bizKey}")`）
-- ✅ 重复请求结果一致（幂等）
-- ✅ 部分成功语义明确（哪个成功 / 哪个失败）
-- ✅ 高风险操作增加业务授权（不能只依赖 App-Token）
-
-### 6.4 不做的事
-
-- ❌ 不自行实现或覆盖 `WebApiInterceptor`
-- ❌ 不把平台内部或未公开常量写进业务代码
-- ❌ 不暴露 `appSecret` / `appToken` 到日志 / 异常 / 响应体
-- ❌ 不绕过 WebApiInfo 登记
-
----
-
-## 七、外部组织人员同步（不在本 skill）
-
-> 外部组织/人员数据同步到平台 → 用 `meritdata-platform-data-access/references/inbound/masterdata-sync`
-
-| 场景 | 用什么 |
-|------|--------|
-| 外部供应商查询平台采购数据 | **本 skill**（WebApi，平台 → 外部） |
-| 外部 HR 系统同步组织人员到平台 | inbound/masterdata-sync（外部 → 平台） |
-| 平台内部微服务调用 | feign-guide（同集群）|
-
----
-
-## 八、安全清单
-
-### 8.1 必须做
-
-- ✅ WebApiInfo 登记
-- ✅ AppAuth 授权（最小 API 集）
-- ✅ IP 白名单
-- ✅ 幂等键（写接口）
-- ✅ 业务授权（L3，不仅 App-Token）
-- ✅ 调用审计
-- ✅ 限流（QPS）
-- ✅ 密钥轮换（定期换 appSecret）
-
-### 8.2 必须不做
-
-- ❌ 暴露 appSecret
-- ❌ 暴露 stack trace
-- ❌ 共享 appKey（每个外部系统独立）
-- ❌ 永久 appToken（必须短时）
-- ❌ 跳过权限校验（仅靠 App-Token 鉴权）
-
----
-
-## 九、WA-01 ~ WA-07 验收清单
-
-| ID | 标准 | 测试方法 |
-|----|------|---------|
-| WA-01 | 服务端路径在 `/webapi/**` | 单元测试 + CI 扫描 |
-| WA-02 | WebApiInfo 已登记 | 注册表比对 |
-| WA-03 | AppAuth 已授权（最小 API 集）| 权限测试 |
-| WA-04 | IP 白名单生效 | 跨 IP 测试 |
-| WA-05 | 写接口有幂等键 + 重放检测 | 重放测试 |
-| WA-06 | appSecret 不出现在日志 / 异常 / 响应 | 扫描 + 故障注入 |
-| WA-07 | 密钥轮换 + 撤权 + 审计 + 限流演练 | E2E 演练 |
-
-详见验收文档（v2.6.0 后续补 references/acceptance.md）。
-
----
-
-## 十、与其他 skill 的协作
-
-| 场景 | 协作 skill |
-|------|----------|
-| 同集群内部微服务调用 | `meritdata-platform-data-access/references/outbound/feign-guide.md` |
-| 同 JVM Service 直接注入 | `meritdata-platform-data-access/references/outbound/service-catalog.md` |
-| 外部主数据反向同步到平台 | `meritdata-platform-data-access/references/inbound/masterdata-sync` |
-| 前端多服务 axios | `meritdata-platform-frontend/references/http-client/` |
-| 平台密钥管理 | `meritdata-platform-sm-crypto/` |
-| 限流配置 | `meritdata-platform-nacos-config/references/configuration-properties.md` |
-
----
-
-## 十一、典型攻击与防御
-
-| 攻击 | 防护 |
-|------|------|
-| 重放攻击 | 幂等键 + App-Token 时效 |
-| IP 伪造 | IP 白名单 |
-| Secret 泄露 | Secret 不进任何可观测位置 |
-| 越权调用 | AppAuth 最小 API 集 + 业务授权 L3 |
-| DDoS | QPS 限流 |
-| 中间人 | HTTPS |
-| 内部常量泄露 | 不复制平台拦截器内部实现 |
-
----
-
-## 十二、常见错误
-
-| 错误 | 后果 | 正确做法 |
-|------|------|---------|
-| 路径用 `/api/open/**` | 平台不认 | 必须 `/webapi/**` |
-| 没登记 WebApiInfo | 调用 403 | 先登记再写 Controller |
-| AppAuth 给过大权限 | 越权风险 | 最小 API 集 |
-| 写接口无幂等键 | 重放攻击 | `@Idempotent(key = "#{bizKey}")` |
-| Secret 打印到日志 | 完全无安全 | 全链路脱敏 |
-| 自己实现 `WebApiInterceptor` | 算法不一致 | 用平台拦截器 |
-| 时钟偏差 > 5 分钟 | 认证失败 | NTP 同步 |
-| 共享 appKey | 撤权困难 | 每个外部系统独立 |
-
----
-
-**最后更新**：2026-09-08（v2.6.0 P1-B 整合）
-**来源**：石油 `merit-cloud-webapi/`（public-contracts.md / replay-and-e2e.md / acceptance.md）
-**整合位置**：`meritdata-platform-data-access/references/outbound/webapi.md`

package/skills/meritdata-platform-data-access-review/SKILL.md

@@ -1,42 +0,0 @@
----
-name: meritdata-platform-data-access-review
-description: |
-  数据访问审查。data-boundary 4 铁律的审查清单与自动化检测；PR 评审必查；CI 扫描脚本。
-  触发场景：审查数据访问代码 / 二开跨库访问 / Feign 调用合规性 / 平台 Entity 引用 / 空集合掩盖异常。
-  何时不用：纯业务代码审查 → 用 code-review；测试用例 → 用 test-case。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: high
-  layer: L2
-  sub-layer: L2-M
-  stack: methodology
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 数据访问审查（data-access-review）
-
-## 触发
-- 审查二开数据访问层代码（Controller/Service/Repository/Feign）
-- PR review 时发现数据访问反模式
-- CI 扫描集成 data-boundary 铁律
-- 排查数据访问性能/正确性问题
-
-## 不触发
-- 纯业务逻辑审查 → 用 `meritdata-platform-code-review`
-- 测试用例审查 → 用 `meritdata-platform-test-case`
-- 平台模块代码（同 JVM 例外）→ 不在本 skill 范围
-
-## 前置约束
-- data-boundary §1.1-1.4 4 条铁律**强制**检查（违反即阻断）
-- 自动化扫描（CI）**必须**集成 validate-rules.md
-- 严重反模式（如 PF_ 映射、catch + emptyList）**零容忍**
-
-## 路由
-- 4 铁律逐条审查清单 → [references/guide.md](references/guide.md)
-- 自动化扫描脚本（CI 集成）→ [references/ci-scan.md](references/ci-scan.md)
-- 反模式库（含真实案例） → [references/anti-patterns.md](references/anti-patterns.md)
-- [SKILL.md](../SKILL.md)