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

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

@@ -0,0 +1,64 @@
+# 主数据同步（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

@@ -0,0 +1,200 @@
+# 软删除穿透与唯一性校验（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

@@ -0,0 +1,176 @@
+# 组织树与用户选择器（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

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

@@ -0,0 +1,198 @@
+# 按钮权限与数据权限（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)