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

package/skills/meritdata-platform-sso/references/oauth-providers.md

@@ -0,0 +1,290 @@
+# 第三方 OAuth 接入（oauth-providers）
+
+> 接入微信 / 钉钉 / 企业微信 / 飞书等第三方 OAuth 登录。
+
+---
+
+## 1. 通用流程
+
+```
+用户点击"微信登录"
+  ↓
+跳转到微信授权页
+  ↓
+用户确认授权
+  ↓
+微信回调（带 code）
+  ↓
+应用用 code 换 access_token
+  ↓
+用 access_token 拉用户信息
+  ↓
+建立本地会话
+```
+
+---
+
+## 2. 微信 OAuth
+
+### 2.1 申请配置
+
+1. 微信开放平台注册应用：https://open.weixin.qq.com
+2. 获取：`appId`、`appSecret`
+3. 配置回调域名
+
+### 2.2 配置文件
+
+```yaml
+oauth:
+  wechat:
+    enabled: true
+    app-id: ${WECHAT_APP_ID}
+    app-secret: ${WECHAT_APP_SECRET}
+    redirect-uri: https://your-app.example.com/oauth/wechat/callback
+    scope: snsapi_login
+```
+
+### 2.3 Controller
+
+```java
+@GetMapping("/oauth/wechat/login")
+public void wechatLogin(HttpServletResponse response) throws IOException {
+    String url = "https://open.weixin.qq.com/connect/qrconnect" +
+        "?appid=" + wechatConfig.getAppId() +
+        "&redirect_uri=" + URLEncoder.encode(wechatConfig.getRedirectUri()) +
+        "&response_type=code" +
+        "&scope=" + wechatConfig.getScope() +
+        "&state=random_state";
+    response.sendRedirect(url);
+}
+
+@GetMapping("/oauth/wechat/callback")
+public ApiResponse<LoginResult> wechatCallback(@RequestParam String code, @RequestParam String state) {
+    // 1. 用 code 换 access_token
+    WechatTokenResponse tokenResp = wechatClient.exchangeToken(code);
+
+    // 2. 用 access_token 拉用户信息
+    WechatUserInfo userInfo = wechatClient.getUserInfo(tokenResp.getAccessToken(), tokenResp.getOpenId());
+
+    // 3. 查找或创建本地用户
+    UserDTO user = userService.findOrCreateByWechat(userInfo);
+
+    // 4. 建立会话
+    return ApiResponse.success(loginService.createSession(user));
+}
+```
+
+---
+
+## 3. 钉钉 OAuth
+
+### 3.1 申请配置
+
+1. 钉钉开放平台：https://open-dev.dingtalk.com
+2. 创建应用：获取 `appKey`、`appSecret`
+3. 配置回调域名
+
+### 3.2 扫码登录（前端）
+
+```vue
+<template>
+  <div id="dingtalk-login-container"></div>
+</template>
+
+<script setup>
+import { onMounted } from 'vue';
+
+onMounted(() => {
+  // 引入钉钉 JS SDK
+  const script = document.createElement('script');
+  script.src = 'https://g.alicdn.com/dingding/dinglogin/0.0.5/ddLogin.js';
+  script.onload = () => {
+    window.DTFrameLogin(
+      {
+        id: 'dingtalk-login-container',
+        width: 300,
+        height: 300
+      },
+      {
+        redirect_uri: encodeURIComponent('https://your-app.example.com/oauth/dingtalk/callback'),
+        client_id: 'YOUR_APP_KEY',
+        scope: 'snsapi_login',
+        response_type: 'code',
+        state: 'random_state'
+      },
+      (loginUrl) => {
+        window.location.href = loginUrl;
+      }
+    );
+  };
+  document.body.appendChild(script);
+});
+</script>
+```
+
+### 3.3 后端回调处理
+
+```java
+@GetMapping("/oauth/dingtalk/callback")
+public ApiResponse<LoginResult> dingtalkCallback(@RequestParam String code, @RequestParam String state) {
+    // 1. 用 code 换取用户信息（钉钉一步到位）
+    DingtalkUserResponse userResp = dingtalkClient.getUserByCode(code, appKey, appSecret);
+
+    // 2. 查找或创建本地用户
+    UserDTO user = userService.findOrCreateByDingtalk(userResp);
+
+    // 3. 建立会话
+    return ApiResponse.success(loginService.createSession(user));
+}
+```
+
+---
+
+## 4. 企业微信 OAuth
+
+### 4.1 配置
+
+```yaml
+oauth:
+  wechat-work:
+    enabled: true
+    corp-id: ${WXWORK_CORP_ID}
+    agent-id: ${WXWORK_AGENT_ID}
+    secret: ${WXWORK_SECRET}
+    redirect-uri: https://your-app.example.com/oauth/wxwork/callback
+```
+
+### 4.2 实现
+
+```java
+@GetMapping("/oauth/wxwork/callback")
+public ApiResponse<LoginResult> wxworkCallback(@RequestParam String code) {
+    // 1. 用 code 换 userId（企业微信一步到位）
+    String userId = wxworkClient.getUserIdByCode(code);
+
+    // 2. 用 userId 拉用户详情
+    WxworkUserDetail detail = wxworkClient.getUserDetail(userId);
+
+    // 3. 查找或创建本地用户
+    UserDTO user = userService.findOrCreateByWxwork(detail);
+
+    // 4. 建立会话
+    return ApiResponse.success(loginService.createSession(user));
+}
+```
+
+---
+
+## 5. 飞书 OAuth
+
+### 5.1 配置
+
+```yaml
+oauth:
+  feishu:
+    enabled: true
+    app-id: ${FEISHU_APP_ID}
+    app-secret: ${FEISHU_APP_SECRET}
+    redirect-uri: https://your-app.example.com/oauth/feishu/callback
+```
+
+### 5.2 实现
+
+```java
+@GetMapping("/oauth/feishu/callback")
+public ApiResponse<LoginResult> feishuCallback(@RequestParam String code) {
+    // 1. 用 code 换 user_access_token
+    FeishuTokenResponse tokenResp = feishuClient.exchangeToken(code);
+
+    // 2. 拉用户信息
+    FeishuUserInfo userInfo = feishuClient.getUserInfo(tokenResp.getAccessToken());
+
+    // 3. 查找或创建本地用户
+    UserDTO user = userService.findOrCreateByFeishu(userInfo);
+
+    // 4. 建立会话
+    return ApiResponse.success(loginService.createSession(user));
+}
+```
+
+---
+
+## 6. 账号绑定
+
+### 6.1 场景
+
+用户用微信登录后，需要绑定工号才能进入业务系统。
+
+### 6.2 实现
+
+```java
+@PostMapping("/oauth/bind")
+public ApiResponse<Void> bindAccount(@RequestBody BindParam param) {
+    // 1. 验证当前 session（必须是已登录用户）
+    UserDTO currentUser = SecurityUtils.getCurrentUser();
+
+    // 2. 验证工号 + 密码（防止账号接管）
+    UserDTO targetUser = userService.authenticate(param.getCode(), param.getPassword());
+
+    // 3. 合并账号
+    userMergeService.merge(currentUser.getId(), targetUser.getId());
+
+    return ApiResponse.success();
+}
+```
+
+### 6.3 ❌ 反例：直接绑定无验证
+
+```java
+// ❌ 错：拿到微信 userInfo 就直接绑定本地账号
+@PostMapping("/oauth/bind")
+public ApiResponse<Void> bindAccount(@RequestBody BindParam param) {
+    userMergeService.merge(param.getWechatOpenId(), param.getLocalUserId());
+    return ApiResponse.success();
+}
+```
+
+攻击者可以用自己微信绑定他人账号。
+
+---
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ appSecret 硬编码
+
+```java
+// ❌ 错
+private static final String APP_SECRET = "abc123def456";
+```
+
+✅ 从环境变量读取（详见 [rules/security-rules.md](../../rules/security-rules.md)）。
+
+### 7.2 ❌ 不验证 state
+
+```java
+// ❌ 错：不验证 state → CSRF 攻击
+@GetMapping("/oauth/wechat/callback")
+public void callback(@RequestParam String code) {
+    // 直接处理，没有校验 state
+}
+```
+
+✅ 必须校验 state（防 CSRF）。
+
+### 7.3 ❌ 第三方用户信息直接当业务用户
+
+```java
+// ❌ 错：用微信昵称当工号
+UserDTO user = new UserDTO();
+user.setCode(wechatUserInfo.getNickname());  // 昵称可能重复/变化
+```
+
+✅ 第三方 userId 只作为关联，本地必须有独立业务用户。
+
+---
+
+## 8. 关联阅读
+
+- [sso-guide.md](sso-guide.md) — SSO 主流程
+- [filter-config.md](filter-config.md) — 过滤器配置
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,319 @@
+# SSO 单点登录接入指南（sso-guide）
+
+> 平台统一 SSO 接入流程、Token 管理、过滤器配置。
+
+---
+
+## 1. SSO 整体流程
+
+```
+用户访问应用
+  ↓ (未登录)
+跳转 SSO 登录页
+  ↓
+用户输入账号密码 (或扫码)
+  ↓
+SSO 认证服务器验证
+  ↓
+颁发 Token (JWT / SessionId)
+  ↓
+回调应用 (带 Token)
+  ↓
+应用验证 Token + 获取用户信息
+  ↓
+建立本地会话 + 跳转首页
+```
+
+---
+
+## 2. 接入步骤
+
+### 2.1 引入 SSO SDK
+
+```xml
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-sso-client</artifactId>
+    <version>${platform.version}</version>
+</dependency>
+```
+
+### 2.2 application.yml
+
+```yaml
+sso:
+  enabled: true
+  server-url: https://sso.example.com
+  client-id: your-2nd-app
+  client-secret: ${SSO_CLIENT_SECRET}     # 从环境变量读取
+  redirect-uri: https://your-app.example.com/sso/callback
+  logout-uri: https://your-app.example.com/sso/logout
+```
+
+### 2.3 启动类加配置
+
+```java
+@SpringBootApplication
+@EnableSsoClient
+public class YourApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(YourApplication.class, args);
+    }
+}
+```
+
+---
+
+## 3. Token 管理
+
+### 3.1 Token 存储
+
+**推荐**：httpOnly cookie（防 XSS 盗取）
+
+```java
+@PostMapping("/sso/callback")
+public ApiResponse<Void> callback(@RequestParam String code, HttpServletResponse response) {
+    // 1. 用 code 换 token
+    SsoToken token = ssoClient.exchangeToken(code);
+
+    // 2. 设置 httpOnly cookie
+    Cookie cookie = new Cookie("sso_token", token.getAccessToken());
+    cookie.setHttpOnly(true);
+    cookie.setSecure(true);                    // 仅 HTTPS
+    cookie.setPath("/");
+    cookie.setMaxAge(token.getExpiresIn());
+    response.addCookie(cookie);
+
+    return ApiResponse.success();
+}
+```
+
+### 3.2 Token 验证
+
+```java
+public class SsoTokenValidator {
+
+    @Autowired
+    private SsoClient ssoClient;
+
+    public UserDTO validateAndGetUser(String token) {
+        // 1. 本地 JWT 验签（快）
+        if (JwtUtils.verify(token)) {
+            return JwtUtils.extractUser(token);
+        }
+
+        // 2. 调 SSO 服务器验证（慢但权威）
+        return ssoClient.getUserByToken(token);
+    }
+}
+```
+
+### 3.3 Token 刷新
+
+```java
+public class SsoTokenRefresher {
+
+    public String refresh(String refreshToken) {
+        SsoToken newToken = ssoClient.refresh(refreshToken);
+        return newToken.getAccessToken();
+    }
+}
+```
+
+---
+
+## 4. 登录拦截器
+
+### 4.1 拦截器
+
+```java
+@Component
+public class SsoAuthInterceptor implements HandlerInterceptor {
+
+    @Autowired
+    private SsoTokenValidator validator;
+
+    @Override
+    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
+        // 1. 白名单放行
+        if (isWhiteListed(request.getRequestURI())) {
+            return true;
+        }
+
+        // 2. 提取 token
+        String token = extractToken(request);
+        if (StringUtils.isBlank(token)) {
+            throw new UnauthorizedException("未登录");
+        }
+
+        // 3. 验证 token
+        try {
+            UserDTO user = validator.validateAndGetUser(token);
+            // 4. 放入上下文
+            SecurityUtils.setCurrentUser(user);
+            return true;
+        } catch (TokenExpiredException e) {
+            throw new UnauthorizedException("Token 已过期");
+        } catch (TokenInvalidException e) {
+            throw new UnauthorizedException("Token 无效");
+        }
+    }
+}
+```
+
+### 4.2 注册拦截器
+
+```java
+@Configuration
+public class WebConfig implements WebMvcConfigurer {
+
+    @Autowired
+    private SsoAuthInterceptor ssoAuthInterceptor;
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        registry.addInterceptor(ssoAuthInterceptor)
+            .addPathPatterns("/api/**")
+            .excludePathPatterns(
+                "/api/v1/auth/login",
+                "/api/v1/auth/callback",
+                "/api/v1/public/**"
+            );
+    }
+}
+```
+
+---
+
+## 5. 退出登录
+
+### 5.1 本地退出
+
+```java
+@PostMapping("/sso/logout")
+public ApiResponse<Void> logout(HttpServletRequest request, HttpServletResponse response) {
+    // 1. 清除本地 cookie
+    Cookie cookie = new Cookie("sso_token", null);
+    cookie.setMaxAge(0);
+    cookie.setPath("/");
+    response.addCookie(cookie);
+
+    // 2. 通知 SSO 服务器销毁 token
+    String token = extractToken(request);
+    if (StringUtils.isNotBlank(token)) {
+        ssoClient.logout(token);
+    }
+
+    return ApiResponse.success();
+}
+```
+
+### 5.2 SSO 端退出
+
+浏览器跳转到 SSO 退出页（清除 SSO 服务器会话）：
+
+```java
+@GetMapping("/sso/logout-redirect")
+public void logoutRedirect(HttpServletResponse response) throws IOException {
+    String ssoLogoutUrl = ssoClient.getLogoutRedirectUrl();
+    response.sendRedirect(ssoLogoutUrl);
+}
+```
+
+---
+
+## 6. 多端登录互踢
+
+### 6.1 场景
+
+用户在 A 电脑登录，又在 B 电脑登录 → A 电脑被踢下线。
+
+### 6.2 实现
+
+```java
+public class LoginService {
+
+    @Autowired
+    private StringRedisTemplate redis;
+
+    public LoginResult login(String username, String password) {
+        // 1. 验证账号密码
+        UserDTO user = userService.authenticate(username, password);
+
+        // 2. 生成 sessionId
+        String sessionId = UUID.randomUUID().toString();
+
+        // 3. 存储 sessionId → userId
+        redis.opsForValue().set(
+            "session:" + user.getId(),
+            sessionId,
+            Duration.ofHours(8)
+        );
+
+        // 4. 返回 token（含 sessionId）
+        return new LoginResult(JwtUtils.generate(user.getId(), sessionId));
+    }
+}
+```
+
+---
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ Token 写入 URL
+
+```java
+// ❌ 错：URL 传 token → 日志泄露 + Referer 泄露
+@GetMapping("/api/orders")
+public List<Order> list(@RequestParam String token) { ... }
+```
+
+✅ 用 Header：`Authorization: Bearer <token>`
+
+### 7.2 ❌ 自定义 Token 校验逻辑
+
+```java
+// ❌ 错：业务代码自己解析 token
+String token = request.getHeader("X-Token");
+String userId = JwtUtils.extractUserId(token);  // 业务代码依赖 JWT 库
+```
+
+✅ 用统一的 `SecurityUtils.getCurrentUser()`，业务不感知 Token 细节。
+
+### 7.3 ❌ 认证失败提示过细
+
+```java
+// ❌ 错：泄露用户存在性
+if (!userExists) throw new BizException("用户不存在");
+if (!passwordMatch) throw new BizException("密码错误");
+
+// ✅ 正确：统一提示
+throw new BizException("账号或密码错误");
+```
+
+### 7.4 ❌ Cookie 没 httpOnly
+
+```javascript
+// ❌ 错：JS 可读 → XSS 攻击可盗
+document.cookie;  // 能读到 sso_token
+```
+
+✅ `Set-Cookie: sso_token=xxx; HttpOnly; Secure; SameSite=Strict`
+
+### 7.5 ❌ Token 不过期
+
+```java
+// ❌ 错：永不过期
+jwtToken = JwtUtils.generate(userId, expiresIn = -1);
+```
+
+✅ 必须有过期时间（建议 8-24 小时）+ Refresh Token 机制。
+
+---
+
+## 8. 关联阅读
+
+- [oauth-providers.md](oauth-providers.md) — 第三方 OAuth 接入
+- [filter-config.md](filter-config.md) — 过滤器配置
+- [rules/security-rules.md](../../rules/security-rules.md) — 安全规范
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-test-case/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: meritdata-platform-test-case
+description: |
+  测试用例。单元测试 / 集成测试模板；覆盖率要求；边界值 / 空值 / 安全 / 性能维度。
+  触发场景：编写单元测试 / 设计集成测试 / 测试用例评审 / 提升覆盖率。
+  何时不用：自动化 E2E → 用 e2e skill；性能压测 → 用 perf skill。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: low
+  layer: L2
+  sub-layer: L2-M
+  stack: methodology
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 测试用例（test-case）
+
+## 触发
+- 编写单元测试（Service / Util）
+- 编写集成测试（Controller / Repository）
+- 业务用例测试（基于 test-case-dev-rules）
+- 提升测试覆盖率
+
+## 不触发
+- E2E 测试 → 用 e2e skill
+- 性能压测 → 用 perf skill
+- 安全渗透测试 → 用 security skill
+
+## 前置约束
+- 业务方法**必须**有单元测试（覆盖率 ≥ 80%）
+- Controller **必须**有集成测试
+- 软删除实体**必须**含 GEN-SOFT-DELETE / DUP-SOFT-DELETE 回归用例（详见 data-access-review）
+- 边界值 / 空值 / 安全 / 并发**必须**覆盖
+
+## 路由
+- 测试用例模板 + 覆盖率 → [references/guide.md](references/guide.md)
+- 单元测试（Service / Util）→ [references/unit-test.md](references/unit-test.md)
+- 集成测试（Controller / Feign / Repository）→ [references/integration-test.md](references/integration-test.md)
+- [SKILL.md](../SKILL.md)