@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

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

@@ -1,290 +0,0 @@
-# 第三方 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

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

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