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

package/skills/meritdata-platform-permission/references/custom-rule.md

@@ -0,0 +1,207 @@
+# 自定义权限规则（permission）
+
+> 复杂业务规则：金额阈值 / 时间窗口 / 业务对象状态等。
+
+---
+
+## 1. 场景
+
+### 1.1 典型场景
+
+| 规则 | 说明 |
+|------|------|
+| 金额阈值 | 金额 > 10 万需总监审批 |
+| 时间窗口 | 工作时间才能审批 |
+| 业务状态 | 只有"待审批"状态能审批 |
+| 数据归属 | 只能审批自己创建的订单 |
+
+## 2. SpEL 表达式（推荐）
+
+### 2.1 内置 SpEL 变量
+
+```java
+@PreAuthorize("hasAuthority('order:approve') and #order.amount <= 10000")
+public Result approve(@RequestBody OrderDTO order) { ... }
+```
+
+可用变量：
+
+| 变量 | 含义 |
+|------|------|
+| `#paramName` | 方法参数 |
+| `#root.methodName` | 当前方法 |
+| `#authentication.name` | 当前用户 |
+
+### 2.2 多条件组合
+
+```java
+@PreAuthorize("hasAuthority('order:approve') and " +
+              "#order.amount <= 10000 and " +
+              "#order.status == 'PENDING'")
+public Result approve(@RequestBody OrderDTO order) { ... }
+```
+
+### 2.3 自定义函数
+
+```java
+@Component("customAuth")
+public class CustomAuthorization {
+
+    public boolean isOwner(String userId) {
+        return userId.equals(SecurityUtils.getCurrentUserId());
+    }
+}
+
+@PreAuthorize("@customAuth.isOwner(#order.createBy)")
+public Result approve(@RequestBody OrderDTO order) { ... }
+```
+
+## 3. 自定义注解
+
+### 3.1 @AmountLimit
+
+```java
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface AmountLimit {
+    String permission();
+    double maxAmount();
+}
+```
+
+### 3.2 实现 AOP
+
+```java
+@Aspect
+@Component
+public class AmountLimitAspect {
+
+    @Autowired
+    private PermissionService permissionService;
+
+    @Before("@annotation(amountLimit)")
+    public void check(JoinPoint joinPoint, AmountLimit amountLimit) {
+        // 1. 校验权限
+        if (!permissionService.hasPermission(amountLimit.permission())) {
+            throw new ForbiddenException("无权限");
+        }
+
+        // 2. 校验金额
+        OrderDTO order = (OrderDTO) joinPoint.getArgs()[0];
+        if (order.getAmount() > amountLimit.maxAmount()) {
+            throw new BizException("金额超过限制，需要更高级别审批");
+        }
+    }
+}
+```
+
+### 3.3 使用
+
+```java
+@PostMapping("/{id}/approve")
+@AmountLimit(permission = "order:approve", maxAmount = 10000)
+public Result approve(@PathVariable String id, @RequestBody OrderDTO order) { ... }
+```
+
+## 4. 业务校验 vs 权限校验
+
+| 维度 | 权限校验 | 业务校验 |
+|------|---------|---------|
+| 关注点 | "能不能做" | "做得对不对" |
+| 失败 | 403 Forbidden | 400 Bad Request |
+| 责任 | DAM 平台 | 业务 Service |
+
+```java
+// 权限校验
+@PreAuthorize("hasAuthority('order:approve')")
+public Result approve(@RequestBody OrderDTO order) {
+    // 业务校验（金额、状态等）
+    if (order.getAmount() > 100000) {
+        throw new BizException("金额超过 10 万，需总监审批");
+    }
+    if (!"PENDING".equals(order.getStatus())) {
+        throw new BizException("订单状态非待审批");
+    }
+    return orderService.approve(order);
+}
+```
+
+## 5. 复杂场景
+
+### 5.1 多级审批
+
+```java
+@PostMapping("/{id}/approve")
+public Result approve(@PathVariable String id) {
+    Order order = orderRepository.findById(id).orElseThrow();
+    UserDTO user = SecurityUtils.getCurrentUser();
+
+    if (order.getAmount() <= 10000) {
+        // 1 万以下：部门经理可审批
+        requireRole("ROLE_DEPT_MANAGER");
+    } else if (order.getAmount() <= 100000) {
+        // 1 万 ~ 10 万：总监审批
+        requireRole("ROLE_DIRECTOR");
+    } else {
+        // 10 万以上：VP 审批
+        requireRole("ROLE_VP");
+    }
+
+    return orderService.approve(id);
+}
+
+private void requireRole(String role) {
+    if (!SecurityUtils.hasRole(role)) {
+        throw new ForbiddenException("无权限");
+    }
+}
+```
+
+### 5.2 工作流集成
+
+详见 [meritdata-platform-bpm](../meritdata-platform-bpm/references/guide.md)。
+
+```java
+@PostMapping("/{id}/approve")
+public Result approve(@PathVariable String id, @RequestBody ApproveRequest req) {
+    // BPM 自动判断当前节点审批人
+    bpmService.approve(id, req);
+    return Result.success();
+}
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 权限校验混入业务逻辑
+
+```java
+// ❌ 错：业务逻辑里硬编码权限判断
+public Result approve(String id) {
+    UserDTO user = SecurityUtils.getCurrentUser();
+    if (user.getLevel() < 3) {  // 业务逻辑混入了权限
+        throw new ForbiddenException();
+    }
+    // 业务逻辑
+}
+```
+
+✅ 用 @PreAuthorize 分离关注点。
+
+### 6.2 ❌ 复杂规则写在 SpEL 里（难维护）
+
+```java
+// ❌ 错：超长 SpEL
+@PreAuthorize("@customAuth.isOwner(#order.createBy) and " +
+              "#order.amount <= #config.maxApproveAmount and " +
+              "T(DateUtils).isBusinessHour() and " +
+              "#order.status == 'PENDING' and " +
+              "@customAuth.notInBlackList(authentication.name)")
+```
+
+✅ 抽到 @AmountLimit 自定义注解。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 权限基础
+- [button-and-data.md](button-and-data.md) — 按钮权限 + 数据权限
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-permission/references/guide.md

@@ -0,0 +1,196 @@
+# 权限点基础指南（permission）
+
+> 权限点 = 业务可执行的最小操作单元。
+
+---
+
+## 1. 权限点模型
+
+```
+Permission (权限点)
+├── code           -- 权限编码（如 "order:create"）
+├── name           -- 权限名称
+├── module         -- 所属模块
+├── type           -- 类型（API / BUTTON / DATA）
+└── description
+```
+
+类型说明：
+- `API`：API 接口权限（后端拦截）
+- `BUTTON`：按钮权限（前端显隐）
+- `DATA`：数据权限（行级/列级）
+
+## 2. 权限定义
+
+### 2.1 在 DAM 平台定义
+
+平台提供权限管理界面：
+- 权限点新增/修改
+- 权限点授权给角色
+- 权限点分类管理
+
+### 2.2 命名规范
+
+```
+{模块}:{动作}
+```
+
+例：
+- `order:create` / `order:update` / `order:delete` / `order:list`
+- `user:create` / `user:assignRole`
+- `project:approve` / `project:reject`
+
+### 2.3 二开自定义权限
+
+```java
+@Permission(code = "order:bulkApprove", name = "批量审批", module = "ORDER")
+public class BulkApprovePermission { ... }
+```
+
+## 3. 权限校验
+
+### 3.1 @PreAuthorize 注解（API）
+
+```java
+@PostMapping
+@PreAuthorize("hasAuthority('order:create')")
+public Result create(@RequestBody OrderDTO order) { ... }
+```
+
+### 3.2 @PermissionRequired 自定义注解
+
+```java
+@PostMapping
+@PermissionRequired("order:bulkApprove")
+public Result bulkApprove(@RequestBody List<String> orderIds) { ... }
+```
+
+### 3.3 编程式校验
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private PermissionService permissionService;
+
+    public void approve(String orderId) {
+        if (!permissionService.hasPermission("order:approve")) {
+            throw new ForbiddenException("无审批权限");
+        }
+        // 业务逻辑
+    }
+}
+```
+
+## 4. 按钮权限（前端）
+
+### 4.1 后端返回权限列表
+
+```java
+@GetMapping("/auth/current/permissions")
+public List<String> currentPermissions() {
+    return permissionService.userPermissions(SecurityUtils.getCurrentUserId());
+}
+```
+
+### 4.2 前端判断
+
+```typescript
+import { useAuth } from '@/hooks/useAuth';
+
+const { permissions } = useAuth();
+
+const canCreate = permissions.includes('order:create');
+const canDelete = permissions.includes('order:delete');
+
+return (
+  <div>
+    {canCreate && <Button onClick={handleCreate}>新建</Button>}
+    {canDelete && <Button onClick={handleDelete}>删除</Button>}
+  </div>
+);
+```
+
+### 4.3 组件封装
+
+```typescript
+<AuthButton permission="order:create" onClick={handleCreate}>
+  新建订单
+</AuthButton>
+```
+
+## 5. 角色授权
+
+### 5.1 给角色分配权限
+
+```java
+@PostMapping("/admin/roles/{roleCode}/permissions")
+public Result assignPermissions(@PathVariable String roleCode, @RequestBody List<String> permissionCodes) {
+    permissionService.assignToRole(roleCode, permissionCodes);
+    return Result.success();
+}
+```
+
+### 5.2 权限继承
+
+```
+ROLE_SUPER_ADMIN
+   ↓ 继承所有
+ROLE_ADMIN
+   ↓ 继承
+ROLE_ORDER_ADMIN
+```
+
+平台支持角色继承（需在 DAM 配置）。
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 权限硬编码字符串
+
+```java
+// ❌ 错
+@PreAuthorize("hasAuthority('order_create')")  // 命名不一致
+
+// ✅ 正确
+@PreAuthorize("hasAuthority('order:create')")  // 统一规范
+```
+
+### 6.2 ❌ 用通配符全开
+
+```java
+// ❌ 错
+@PreAuthorize("hasAuthority('*:*:*')")  // 超管权限代码散落业务
+```
+
+✅ 用超管角色单独判断。
+
+### 6.3 ❌ 权限判断在客户端
+
+```javascript
+// ❌ 错：前端判断是否显示按钮
+if (user.role === 'admin') {
+    showDeleteButton();
+}
+```
+
+✅ 后端校验 + 返回权限列表。
+
+### 6.4 ❌ 关键操作无权限校验
+
+```java
+// ❌ 错：删除操作无权限校验
+@DeleteMapping("/{id}")
+public Result delete(@PathVariable String id) {
+    orderService.delete(id);  // 谁都能删
+    return Result.success();
+}
+```
+
+✅ 加 @PreAuthorize 或 @PermissionRequired。
+
+## 7. 关联阅读
+
+- [button-and-data.md](button-and-data.md) — 按钮权限 + 数据权限
+- [custom-rule.md](custom-rule.md) — 自定义权限规则
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-platform-config/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: meritdata-platform-platform-config
+description: |
+  平台配置。系统参数 / 业务参数 / 租户配置 / 配置变更审计 / 配置缓存。
+  触发场景：业务需要动态配置（阈值、开关、白名单）/ 多租户差异化配置 / 配置变更需要审计 / 配置热更新。
+  何时不用：基础设施配置（数据库/Redis）→ 用 Nacos；一次性配置 → 用 application.yml。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: medium
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 平台配置（platform-config）
+
+## 触发
+- 业务参数（订单金额阈值、审批人白名单）
+- 多租户差异化配置（不同租户不同规则）
+- 配置需要审计（谁改了什么）
+- 配置需要热更新（不重启生效）
+
+## 不触发
+- 基础设施配置（数据库连接、Redis）→ 用 `meritdata-platform-nacos-config`
+- 字典（订单状态、用户类型）→ 用 `meritdata-platform-lookup-api`
+- 一次性配置（端口、日志级别）→ 用 application.yml
+
+## 前置约束
+- 平台配置**必须有审计**
+- 平台配置**必须支持热更新**
+- 多租户配置**必须**租户隔离
+
+## 路由
+- 平台配置接口 + 热更新 → [references/guide.md](references/guide.md)
+- 平台基础配置外部接口（15+ 端点）→ [references/basic-config-api.md](references/basic-config-api.md)
+- 多租户配置 + 审计 → [references/multi-tenant-and-audit.md](references/multi-tenant-and-audit.md)
+- 配置缓存策略 → [references/cache-and-persist.md](references/cache-and-persist.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-platform-config/references/basic-config-api.md

@@ -0,0 +1,221 @@
+# 平台基础配置外部接口（basic-config-api）
+
+> **目的**：补齐 v2.4.0 复核发现的覆盖缺口——研发版 `meritdata-platform-basic-config-api` 的 15+ 端点 + Feign Client 模板。
+> **场景**：首页加载 / 登录页定制 / Logo / 平台名称 / 密级展示 / 角色跳转。
+> **来源**：研发版 `meritdata-platform-basic-config-api` v1.0.0 + dev-docs 外部接口清单 1.1-1.15。
+
+---
+
+## 一、15+ 外部接口速查
+
+### 1.1-1.6 平台信息类（GET）
+
+| # | 接口 | 路径 | 用途 |
+|:-:|------|------|------|
+| 1.1 | 平台基本信息 | `/api/base/info` | 获取产品名称、版本、版权 |
+| 1.2 | 产品基本信息 | `/api/base/productInfo` | 产品描述、技术栈 |
+| 1.3 | 是否可左侧拖动 | `/api/base/ui/draggable` | UI 渲染（首页布局）|
+| 1.4 | 初始密码策略 | `/api/base/pwd/init` | 新建用户默认密码规则 |
+| 1.5 | 平台密级信息 | `/api/base/secret/info` | 密级标签（公开/内部/秘密/机密）|
+| 1.6 | 是否自定义平台信息 | `/api/base/custom/info` | 平台定制标识 |
+
+### 1.7-1.10 页面与消息类（GET/POST）
+
+| # | 接口 | 方法 | 路径 | 用途 |
+|:-:|------|:--:|------|------|
+| 1.7 | tagimage 获取和 | GET | `/api/base/tagimage/sum` | 标签图片聚合 |
+| 1.8 | 登录页超链接名称和地址 | GET | `/api/base/login/link` | 登录页底部链接配置 |
+| 1.9 | tempo 授权信息首页加载 | GET | `/api/base/tempo/auth` | 第三方授权跳转 |
+| 1.10 | 保存和发送消息 | POST | `/api/base/message/save` | 消息中心发消息 |
+
+### 1.11-1.15 消息与配置类
+
+| # | 接口 | 方法 | 路径 | 用途 |
+|:-:|------|:--:|------|------|
+| 1.11 | 管理页面已读未读消息 | GET | `/api/base/message/read-state` | 消息中心红点 |
+| 1.12 | 发送信息详情 | GET | `/api/base/message/detail` | 消息详情查询 |
+| 1.13 | 保存信息 | POST | `/api/base/message/draft` | 草稿保存 |
+| 1.14 | 首页框架配置 | GET | `/api/base/frame/config` | 首页布局配置 |
+| 1.15 | 角色跳转地址 | GET | `/api/base/role/router` | 不同角色登录后跳不同页 |
+
+> **完整 API**：详见 dev-docs 外部接口清单 `19-21_1.1-1.15基础配置-*.md`。
+
+---
+
+## 二、Feign Client 模板
+
+### 2.1 客户端接口定义
+
+```java
+@FeignClient(
+    name = "cloud-system-manage",
+    fallback = BaseConfigFeignClientFallback.class
+)
+public interface BaseConfigFeignClient {
+
+    @GetMapping("/api/base/info")
+    ResultBody<PlatformInfoVO> getPlatformInfo();
+
+    @GetMapping("/api/base/productInfo")
+    ResultBody<ProductInfoVO> getProductInfo();
+
+    @GetMapping("/api/base/ui/draggable")
+    ResultBody<Boolean> getUiDraggable();
+
+    @GetMapping("/api/base/pwd/init")
+    ResultBody<PasswordPolicyVO> getInitPassword();
+
+    @GetMapping("/api/base/img/logo")
+    ResultBody<String> getLogoUrl();
+
+    @GetMapping("/api/base/secret/info")
+    ResultBody<SecretLevelVO> getSecretInfo();
+
+    @GetMapping("/api/base/login/link")
+    ResultBody<List<LoginLinkVO>> getLoginLinks();
+
+    @GetMapping("/api/base/frame/config")
+    ResultBody<FrameConfigVO> getFrameConfig();
+}
+```
+
+### 2.2 服务层封装（带缓存）
+
+```java
+@Service
+public class BaseConfigService {
+
+    @Autowired
+    private BaseConfigFeignClient baseConfigClient;
+
+    /**
+     * 平台信息：缓存 1 天（极少变化）
+     */
+    @Cacheable(value = "platform:info", ttl = 86400)
+    public PlatformInfoVO getPlatformInfo() {
+        ResultBody<PlatformInfoVO> result = baseConfigClient.getPlatformInfo();
+        if (!result.isSuccess()) {
+            throw new ServiceException("ERR_PLATFORM_INFO", "获取平台信息失败");
+        }
+        return result.getData();
+    }
+
+    /**
+     * 平台密级：缓存 1 小时（可能调整）
+     */
+    @Cacheable(value = "platform:secret", ttl = 3600)
+    public SecretLevelVO getSecretInfo() {
+        return baseConfigClient.getSecretInfo().getData();
+    }
+}
+```
+
+### 2.3 降级类（fallback）
+
+```java
+@Component
+public class BaseConfigFeignClientFallback implements BaseConfigFeignClient {
+
+    @Override
+    public ResultBody<PlatformInfoVO> getPlatformInfo() {
+        // 返回默认平台信息（保证前端可渲染）
+        return ResultBody.success(PlatformInfoVO.defaultInstance());
+    }
+
+    // 其他方法同理返回默认值
+}
+```
+
+---
+
+## 三、缓存策略
+
+| 接口 | 缓存 TTL | 理由 |
+|------|:--------:|------|
+| `getPlatformInfo` | 86400 (1天) | 极少变化 |
+| `getProductInfo` | 86400 (1天) | 极少变化 |
+| `getSecretInfo` | 3600 (1小时) | 可能调整密级策略 |
+| `getLoginLinks` | 3600 (1小时) | 可能调整登录页链接 |
+| `getFrameConfig` | 1800 (30分钟) | 可能调整首页布局 |
+| `getMessageReadState` | 60 (1分钟) | 实时性要求高 |
+
+**关键原则**：
+- 缓存 key 必须包含用户标识：`userId:platformInfo`（按需）
+- 缓存**不存敏感字段**（密级密码、token）
+- 平台名称/Logo 变更走 Nacos 配置 + 自动刷新，**不走缓存失效**（避免重启）
+
+---
+
+## 四、典型使用场景
+
+### 4.1 首页加载（并发获取）
+
+```java
+@GetMapping("/home")
+public HomeVO loadHome() {
+    // 并发获取（CompletableFuture）
+    CompletableFuture<PlatformInfoVO> info = CompletableFuture
+        .supplyAsync(() -> baseConfigService.getPlatformInfo());
+    CompletableFuture<FrameConfigVO> frame = CompletableFuture
+        .supplyAsync(() -> baseConfigService.getFrameConfig());
+
+    CompletableFuture.allOf(info, frame).join();
+
+    return HomeVO.builder()
+        .platformInfo(info.join())
+        .frameConfig(frame.join())
+        .build();
+}
+```
+
+### 4.2 Logo 动态加载
+
+```java
+@GetMapping("/logo")
+public ResponseEntity<byte[]> getLogo() {
+    String logoUrl = baseConfigService.getPlatformInfo().getLogoUrl();
+    // 下载 logo 并返回（注意：URL 必须白名单）
+    return restTemplate.execute(logoUrl, ...);
+}
+```
+
+### 4.3 登录页定制
+
+```java
+@GetMapping("/login-page")
+public LoginPageVO loadLoginPage() {
+    return LoginPageVO.builder()
+        .links(baseConfigService.getLoginLinks())     // 底部链接
+        .draggable(baseConfigService.getUiDraggable())  // 是否可拖动
+        .build();
+}
+```
+
+---
+
+## 五、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| Feign Client 写法 + 超时 + 批量装配 | `meritdata-platform-data-access/references/feign-guide.md` |
+| 多租户差异化配置 | `meritdata-platform-platform-config/references/multi-tenant-and-audit.md` |
+| 平台密级 → 数据密级 | `meritdata-platform-data-classification/references/guide.md` |
+| 消息发送（1.10）| `meritdata-platform-message-center/references/message-攻略/INDEX.md` |
+
+---
+
+## 六、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| Logo/平台名硬编码到前端 | 改平台名要发版 | 走 `/api/base/info` 接口 |
+| 不缓存平台信息 | 每次请求慢 | `@Cacheable` 1 天 |
+| Feign 无 fallback | 平台宕机 → 前端空白 | 提供默认值 |
+| 缓存敏感字段（密码/密级）| 数据泄露 | 只缓存公开字段 |
+| 不做并发获取 | 首页加载慢 | CompletableFuture 并发 |
+
+---
+
+**最后更新**：2026-09-08（v2.4.0 P1 补齐）
+**来源**：研发版 `meritdata-platform-basic-config-api` v1.0.0 + dev-docs 外部接口 19-21
+**整合位置**：`meritdata-platform-platform-config/references/basic-config-api.md`