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

package/skills/meritdata-platform-org-user-api/references/masterdata-sync-/346/224/273/347/225/245/INDEX.md

@@ -1,64 +0,0 @@
-# 主数据同步（HR/ERP → 平台）攻略索引
-
-> **来源**：研发版 `meritdata-platform-config-integration`（v2.3.1 拆分整合）
-> **实际内容位置**：[`meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-*.md`](../../../meritdata-dev-docs-file-finder/references/dev-docs/)
-> **策略**：**索引 + 指向**（不复制文件）——所有章节内容均在 dev-docs/ 维护。
-
----
-
-## 一、攻略-09 总览
-
-| 项目 | 值 |
-|------|-----|
-| **攻略名** | 组织人员同步 |
-| **章节数** | 7 |
-| **总览入口** | [攻略-09-组织人员同步-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-00_总览.md) |
-| **典型场景** | HR 系统同步组织/人员 → 美林平台；ERP 同步资源菜单 → 平台；从老系统迁移 |
-
----
-
-## 二、章节清单
-
-| 章节 | 标题 | 路径 |
-|:-:|------|------|
-| 00 | 总览 | [攻略-09-组织人员同步-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-00_总览.md) |
-| 01 | 概述 | [攻略-09-组织人员同步-章节01_概述.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节01_概述.md) |
-| 02 | 组织同步 | [攻略-09-组织人员同步-章节02_组织同步.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节02_组织同步.md) |
-| 03 | 人员同步 | [攻略-09-组织人员同步-章节03_人员同步.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节03_人员同步.md) |
-| 04 | 资源菜单同步 | [攻略-09-组织人员同步-章节04_资源菜单同步.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节04_资源菜单同步.md) |
-| 05 | 角色同步 | [攻略-09-组织人员同步-章节05_角色同步.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节05_角色同步.md) |
-| 06 | 资源权限同步 | [攻略-09-组织人员同步-章节06_资源权限同步.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节06_资源权限同步.md) |
-| 07 | 组织同步配置 | [攻略-09-组织人员同步-章节07_组织同步配置.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-09-组织人员同步-章节07_组织同步配置.md) |
-
----
-
-## 三、按场景快速匹配
-
-| 我想做什么 | 看哪个章节 |
-|-----------|----------|
-| 同步组织（部门）CRUD | 章节02 组织同步 |
-| 同步人员（员工）CRUD | 章节03 人员同步 |
-| 同步资源菜单 | 章节04 资源菜单同步 |
-| 同步角色定义 | 章节05 角色同步 |
-| 同步资源权限（菜单→角色→人）| 章节06 资源权限同步 |
-| 配置文件位置（Nacos / 开关）| 章节07 组织同步配置 |
-| 整体概念与适用边界 | 章节01 概述 |
-
----
-
-## 四、相关外部接口
-
-| 接口 | 文件 | 章节 |
-|------|------|------|
-| WebService 同步接口 | dev-docs/10_三平台服务-3.4多系统集成+3.5数据密级.md | — |
-| 1.16 组织人员同步 HTTP 接口 | dev-docs/22_1.16组织人员同步.md | — |
-| 2.1 组织维护 HTTP 接口 | dev-docs/25-26_2.1组织维护.md | — |
-| 2.2 人员维护 HTTP 接口 | dev-docs/27-28_2.2人员维护.md | — |
-| 资源授权 HTTP 接口 | dev-docs/36-37_3.1-3.10资源授权.md | — |
-
-> **数据访问方式**：同 JVM 走 `IOrgService` / `IUserService`；跨 JVM 走 Feign Client（详见 `meritdata-platform-data-access`）。
-
----
-
-**最后更新**：2026-09-08（v2.3.1 P1 补齐）
-**来源**：研发版 `meritdata-platform-config-integration` 攻略-09

package/skills/meritdata-platform-org-user-api/references/soft-delete-pitfalls.md

@@ -1,200 +0,0 @@
-# 软删除穿透与唯一性校验（org-user-api）
-
-> 平台用户/组织是软删除实体。二开调用时**必须**注意软删除穿透和唯一性校验陷阱。
-
----
-
-## 1. 软删除机制
-
-平台 User / Org 表使用：
-
-```java
-@Entity
-@SQLDelete(sql = "UPDATE t_user SET deleted = true WHERE id = ?")
-@Where(clause = "deleted = false")
-public class User { ... }
-```
-
-`@Where(clause = "deleted = false")` 让所有 JPQL 查询**自动过滤软删除**。
-
-## 2. 软删除穿透问题
-
-### 2.1 场景
-
-```sql
--- 平台有"工号 = EMP001"的软删除用户（已离职）
-SELECT * FROM t_user WHERE emp_no = 'EMP001' AND deleted = false;
--- 返回空（默认查询）
-```
-
-业务代码做唯一性检查：
-
-```java
-// ❌ 错
-if (userClient.findByEmpNo("EMP001").isPresent()) {
-    throw new EmpNoDuplicateException();
-}
-// 看不到软删除记录 → 校验放行 → 重新创建同名工号 → 数据库约束冲突
-```
-
-### 2.2 解决
-
-平台对外提供穿透查询：
-
-```java
-// ✅ 正确：穿透软删除
-if (userClient.findByEmpNoIncludingDeleted("EMP001").isPresent()) {
-    throw new EmpNoDuplicateException();
-}
-```
-
-## 3. 唯一性校验原则
-
-### 3.1 铁律
-
-> 二开涉及用户/组织字段唯一性校验，**必须**穿透软删除。
-
-### 3.2 业务场景
-
-```java
-@Service
-public class ProjectService {
-
-    public void createProject(ProjectDTO dto) {
-        // 项目有负责人 userId + 业务编号
-        // 负责人 userId 已经在用户表被删除（离职）
-        // 项目创建时，校验 userId 是否有效
-
-        UserDTO user = userClient.getById(dto.getOwnerUserId());
-        if (user == null) {
-            // 用户已被离职软删除 → 业务上算"无效"
-            throw new BizException("负责人已离职");
-        }
-
-        // 项目编号唯一性校验（如果项目编号也是软删除实体）
-        if (projectClient.findByProjectNoIncludingDeleted(dto.getProjectNo()).isPresent()) {
-            throw new ProjectNoDuplicateException();
-        }
-
-        projectRepository.save(dto);
-    }
-}
-```
-
-## 4. 二开软删除穿透
-
-### 4.1 二开业务表软删除
-
-如果二开业务表也用软删除 + 唯一约束（`uk_xxx_no`），**必须**遵循同样的规则：
-
-```java
-// 二开实体
-@Entity
-@TableName("t_project")
-@SQLDelete(sql = "UPDATE t_project SET deleted = true WHERE id = ?")
-@Where(clause = "deleted = false")
-public class Project {
-    @TableField("project_no")
-    private String projectNo;
-    // ...
-}
-```
-
-### 4.2 Repository 写法
-
-```java
-public interface ProjectRepository extends BaseRepository<Project, Long> {
-
-    // 业务查询（受 @Where 过滤）
-    Optional<Project> findByProjectNo(String projectNo);
-
-    // 全量查询（穿透 @Where）
-    @Query(value = "SELECT * FROM t_project WHERE project_no = :projectNo AND deleted = false",
-           nativeQuery = true)
-    Optional<Project> findByProjectNoIncludingDeleted(@Param("projectNo") String projectNo);
-}
-```
-
-### 4.3 业务校验
-
-```java
-// 唯一性校验必须穿透
-public void validateProjectNoUnique(String projectNo) {
-    if (projectRepository.findByProjectNoIncludingDeleted(projectNo).isPresent()) {
-        throw new ProjectNoDuplicateException();
-    }
-}
-```
-
-## 5. 编号生成器穿透
-
-详见 [code-dev-rules §八](../../rules/code-dev-rules.md)。
-
-```java
-// 编号生成器中"查已用编号"必须穿透软删除
-public List<String> findAllUsedNos(String prefix) {
-    return projectRepository.findAllNosStartingWithIncludingDeleted(prefix);
-}
-```
-
-## 6. ❌ 反模式
-
-### 6.1 ❌ 用业务查询做唯一性校验
-
-```java
-// ❌ 错（看得到软删除）
-if (repo.findByXxxNo(no).isPresent()) throw ...;
-```
-
-✅ 用穿透查询。
-
-### 6.2 ❌ 全量查询用于业务展示
-
-```java
-// ❌ 错（业务展示用了穿透查询，会展示软删除数据）
-List<User> users = userClient.listByDeptIncludingDeleted(deptId);
-```
-
-✅ 业务展示用 `listByDept`（受 @Where 过滤）。
-
-## 7. 测试用例
-
-### 7.1 GEN-SOFT-DELETE
-
-```java
-@Test
-public void generateNo_skipSoftDeleted() {
-    // 准备：插入软删除的项目 "P001"
-    Project soft = new Project();
-    soft.setProjectNo("P001");
-    soft.setDeleted(true);
-    repo.save(soft);
-
-    // 业务生成下一个号（应该跳过已软删除的 P001）
-    String next = generator.generateNext("P");
-    assertEquals("P002", next);  // 不是 "P001"
-}
-```
-
-### 7.2 DUP-SOFT-DELETE
-
-```java
-@Test
-public void validate_softDeleted_duplicate() {
-    Project soft = new Project();
-    soft.setProjectNo("P001");
-    soft.setDeleted(true);
-    repo.save(soft);
-
-    // 新建 P001 必须被拒
-    assertThrows(ProjectNoDuplicateException.class, () -> {
-        service.createProject("P001");
-    });
-}
-```
-
-## 8. 关联阅读
-
-- [guide.md](guide.md) — 用户与组织 API 基础
-- [code-dev-rules §八](../../rules/code-dev-rules.md) — 软删除铁律
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-org-user-api/references/tree-and-picker.md

@@ -1,176 +0,0 @@
-# 组织树与用户选择器（org-user-api）
-
-> 平台提供组织树、用户选择器等组件所需的 API。
-
----
-
-## 1. 组织树
-
-### 1.1 查整棵组织树
-
-```java
-@GetMapping("/orgs/tree")
-public List<OrgTreeDTO> tree() {
-    return orgClient.tree();
-}
-```
-
-### 1.2 OrgTreeDTO 结构
-
-```java
-public class OrgTreeDTO {
-    private String orgId;
-    private String orgName;
-    private String orgCode;
-    private List<OrgTreeDTO> children;   // 子节点（已嵌套）
-}
-```
-
-### 1.3 按用户过滤
-
-```java
-// 查某用户可见的组织（基于数据权限）
-List<OrgTreeDTO> userOrgTree = orgClient.userTree(userId);
-```
-
-### 1.4 查祖先链
-
-```java
-// 给一个 orgId，查祖先链（如：D003 → [D001, D002, D003]）
-List<OrgDTO> ancestors = orgClient.listAncestors(orgId);
-```
-
-### 1.5 缓存
-
-组织树数据量大，建议二开缓存：
-
-```java
-@Cacheable(value = "orgTree", key = "#tenantId")
-public List<OrgTreeDTO> tree(String tenantId) {
-    return orgClient.tree();
-}
-```
-
-## 2. 用户选择器
-
-### 2.1 按组织查用户
-
-```java
-List<UserDTO> users = userClient.listByOrg(orgId);
-```
-
-### 2.2 按角色查用户
-
-```java
-// 查所有订单审批人
-List<UserDTO> approvers = userClient.listByRole("ORDER_APPROVER");
-```
-
-### 2.3 按组织 + 角色
-
-```java
-// 查财务部 + 财务角色的用户
-List<UserDTO> users = userClient.listByOrgAndRole(orgId, roleCode);
-```
-
-### 2.4 关键字搜索
-
-```java
-@GetMapping("/users/search")
-public List<UserDTO> search(@RequestParam String keyword) {
-    return userClient.search(keyword, 10);  // limit 10
-}
-```
-
-搜索字段：用户名 / 真实姓名 / 工号 / 手机号。
-
-## 3. 典型场景
-
-### 3.1 审批人下拉框
-
-```java
-@GetMapping("/approval/candidates")
-public List<UserDTO> approvalCandidates(@RequestParam String orgId) {
-    // 同部门 + 审批角色
-    return userClient.listByOrgAndRole(orgId, "ORDER_APPROVER");
-}
-```
-
-### 3.2 部门主管查询
-
-```java
-public UserDTO getDeptManager(String orgId) {
-    OrgDTO org = orgClient.getById(orgId);
-    if (org.getManagerUserId() != null) {
-        return userClient.getById(org.getManagerUserId());
-    }
-    return null;
-}
-```
-
-### 3.3 组织 + 人员混合树
-
-```java
-@Data
-public class OrgUserTreeDTO {
-    private String id;
-    private String label;
-    private String type;        // "ORG" / "USER"
-    private List<OrgUserTreeDTO> children;
-}
-
-// 构建
-public OrgUserTreeDTO buildTree(String orgId) {
-    OrgDTO org = orgClient.getById(orgId);
-    OrgUserTreeDTO node = new OrgUserTreeDTO();
-    node.setId("ORG:" + org.getOrgId());
-    node.setLabel(org.getOrgName());
-    node.setType("ORG");
-
-    // 子部门
-    List<OrgDTO> children = orgClient.listChildren(orgId);
-    for (OrgDTO child : children) {
-        node.getChildren().add(buildTree(child.getOrgId()));
-    }
-
-    // 当前部门用户
-    List<UserDTO> users = userClient.listByOrg(orgId);
-    for (UserDTO user : users) {
-        OrgUserTreeDTO userNode = new OrgUserTreeDTO();
-        userNode.setId("USER:" + user.getUserId());
-        userNode.setLabel(user.getRealName());
-        userNode.setType("USER");
-        node.getChildren().add(userNode);
-    }
-
-    return node;
-}
-```
-
-## 4. ❌ 反模式
-
-### 4.1 ❌ 循环查组织树
-
-```java
-// ❌ 错
-for (OrgDTO org : orgs) {
-    org.setChildren(orgClient.listChildren(org.getOrgId()));
-}
-```
-
-✅ 一次性查全量 + 内存构树。
-
-### 4.2 ❌ 用户选择器返回全表
-
-```java
-// ❌ 错：返回所有用户（几万条）
-List<UserDTO> users = userClient.listAll();
-```
-
-✅ 加关键字/分页/按组织过滤。
-
-## 5. 关联阅读
-
-- [guide.md](guide.md) — 用户与组织 API 基础
-- [soft-delete-pitfalls.md](soft-delete-pitfalls.md) — 软删除穿透
-- [SKILL.md](../SKILL.md)

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

@@ -1,42 +0,0 @@
----
-name: meritdata-platform-permission
-description: |
-  权限点。按钮权限 / API 权限 / 数据权限入口 / @PreAuthorize 用法 / 自定义权限注解。
-  触发场景：按钮级别权限校验（新增/删除/审批按钮）/ API 权限拦截 / 自定义权限规则 / 角色授权权限点。
-  何时不用：菜单显隐 → 用 menu-config；数据行级/列级权限 → 用 data-classification。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: high
-  layer: L3
-  sub-layer: L3-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 权限点（permission）
-
-## 触发
-- 按钮级别权限校验（新增/删除/审批按钮是否显示）
-- API 接口权限拦截（@PreAuthorize）
-- 自定义权限规则（如"金额大于 1 万需要审批"）
-- 角色授权权限点（管理员给角色分配权限）
-
-## 不触发
-- 菜单显示/隐藏 → 用 `meritdata-platform-menu-config`
-- 数据行级/列级权限 → 用 `meritdata-platform-data-classification`
-- 资源路径匹配 → 用 `meritdata-platform-menu-resource`
-
-## 前置约束
-- 权限定义**统一**在 DAM 平台（不散落在代码）
-- 权限名**禁止**用通配符全开（如 `*:*:*`）
-- 关键操作（删除、配置变更）必须**显式**校验权限
-
-## 路由
-- 权限定义 + @PreAuthorize → [references/guide.md](references/guide.md)
-- 按钮权限 + 数据权限 → [references/button-and-data.md](references/button-and-data.md)
-- 自定义权限规则 → [references/custom-rule.md](references/custom-rule.md)
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-permission/references/button-and-data.md

@@ -1,198 +0,0 @@
-# 按钮权限与数据权限（permission）
-
-> 按钮权限是 UI 显隐；数据权限是行/列过滤。两者结合实现完整权限体系。
-
----
-
-## 1. 按钮权限
-
-### 1.1 三种粒度
-
-| 粒度 | 示例 | 实现 |
-|------|------|------|
-| 页面级 | 整个订单管理页可见 | 菜单权限（menu-config）|
-| 模块级 | 订单列表页内某模块 | 按钮权限 |
-| 操作级 | 新建/编辑/删除按钮 | 按钮权限 |
-
-### 1.2 后端实现
-
-```java
-@GetMapping("/auth/current/permissions")
-public List<String> currentPermissions() {
-    return permissionService.userPermissions(userId);
-}
-```
-
-返回用户所有权限编码。
-
-### 1.3 前端实现
-
-#### Hook 方式
-
-```typescript
-function usePermission(code: string) {
-    const { permissions } = useAuth();
-    return permissions.includes(code);
-}
-
-const canApprove = usePermission('order:approve');
-const canDelete = usePermission('order:delete');
-```
-
-#### 组件方式
-
-```typescript
-<AuthButton permission="order:approve" onClick={handleApprove}>
-  审批
-</AuthButton>
-
-// 内部
-function AuthButton({ permission, children, ...rest }) {
-    const hasPermission = usePermission(permission);
-    return hasPermission ? <Button {...rest}>{children}</Button> : null;
-}
-```
-
-#### 路由守卫
-
-```typescript
-const RequireAuth = ({ permission, children }) => {
-    const hasPermission = usePermission(permission);
-    return hasPermission ? children : <Navigate to="/forbidden" />;
-};
-
-<Route path="/orders/approve" element={
-    <RequireAuth permission="order:approve">
-        <ApprovePage />
-    </RequireAuth>
-} />
-```
-
-## 2. 数据权限
-
-详见 [meritdata-platform-data-classification](../meritdata-platform-data-classification/references/guide.md)。
-
-### 2.1 行级权限
-
-员工只能看本部门订单：
-
-```java
-@GetMapping("/orders")
-public List<OrderVO> list() {
-    // 平台自动注入 org_id 过滤条件
-    return orderService.list();
-}
-```
-
-### 2.2 列级权限
-
-```java
-@Data
-public class OrderVO {
-    @SensitiveField("order.cost:view")  // 仅财务可见
-    private BigDecimal cost;
-}
-```
-
-### 2.3 数据权限与按钮权限组合
-
-```
-按钮权限：用户有"order:view" → 列表可见
-   +
-数据权限：用户能看本部门订单 → 列表过滤后只剩本部门
-```
-
-## 3. 综合案例
-
-### 3.1 需求
-
-```
-订单列表页：
-  - 所有员工可见列表（菜单权限 order:list）
-  - 员工只看到本部门订单（数据权限）
-  - 部门经理有"审批"按钮（按钮权限 order:approve）
-  - 财务看到"成本"字段（列级权限）
-```
-
-### 3.2 实现
-
-```java
-@RestController
-@RequestMapping("/api/v1/orders")
-@MenuResource(module = "ORDER")
-public class OrderController {
-
-    // 列表（行级过滤由 DAM 自动）
-    @GetMapping
-    @PreAuthorize("hasAuthority('order:list')")
-    public List<OrderVO> list() {
-        return orderService.list();
-    }
-
-    // 审批（按钮权限 + API 权限）
-    @PostMapping("/{id}/approve")
-    @PreAuthorize("hasAuthority('order:approve')")
-    public Result approve(@PathVariable String id, @RequestBody ApproveRequest req) {
-        return orderService.approve(id, req);
-    }
-}
-```
-
-```java
-@Data
-public class OrderVO {
-    private String orderNo;
-    private BigDecimal amount;
-
-    @SensitiveField("order.cost:view")  // 财务角色可见
-    private BigDecimal cost;
-}
-```
-
-```typescript
-const { permissions } = useAuth();
-
-return (
-    <Table dataSource={orders}>
-        <Column title="订单号" dataIndex="orderNo" />
-        <Column title="金额" dataIndex="amount" />
-        {permissions.includes('order.cost:view') &&
-            <Column title="成本" dataIndex="cost" />}
-        {permissions.includes('order:approve') &&
-            <Column title="操作" render={(o) =>
-                <Button onClick={() => approve(o)}>审批</Button>
-            } />}
-    </Table>
-);
-```
-
-## 4. ❌ 反模式
-
-### 4.1 ❌ 只做菜单权限不做按钮权限
-
-```java
-// ❌ 错：菜单可见 = 按钮可用 → 任意员工都能"审批"
-@PreAuthorize("hasAuthority('order:list')")  // 只校验菜单权限
-public Result approve(...) { ... }
-```
-
-✅ 审批接口独立校验 `order:approve`。
-
-### 4.2 ❌ 数据权限靠业务代码
-
-```java
-// ❌ 错：业务代码自己实现行级过滤
-@GetMapping("/orders")
-public List<Order> list() {
-    String orgId = SecurityUtils.getCurrentUser().getOrgId();
-    return orderRepository.findByOrgId(orgId);  // 自己过滤
-}
-```
-
-✅ 用 DAM 自动注入。
-
-## 5. 关联阅读
-
-- [guide.md](guide.md) — 权限基础
-- [custom-rule.md](custom-rule.md) — 自定义权限规则
-- [SKILL.md](../SKILL.md)