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

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

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

@@ -0,0 +1,392 @@
+# 对外 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

@@ -0,0 +1,42 @@
+---
+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)