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

package/skills/README.md

@@ -1,118 +0,0 @@
-# pfsuite skills 索引
-
-> **抽取日期**：2026-09-07  
-> **目标**：三方整合 44 → **31 个 skill**，按 4 层架构分层（详见 `MeritData_Skill整合重构方案_20260904.md`）
-
----
-
-## 一、双轨制原则（skill ↔ rules 边界）
-
-| 角色 | 内容 | 文件 | 加载方式 |
-|------|------|------|---------|
-| **rules** | 铁律摘要（一句话一段）| `../rules/*.md` | CLAUDE.md 自动注入 |
-| **skill SKILL.md** | 路由器（触发 + 不触发 + 路由）| `skills/<name>/SKILL.md` | Skill 工具按需触发 |
-| **skill references/** | 详细文档（代码对比 + 案例 + CI 命令）| `skills/<name>/references/*.md` | skill 触发后按需加载 |
-
-**关键约束**：
-- SKILL.md **不重复** rules 的铁律正文——只引用章节号
-- references/ **承载** rules 容纳不下的内容：完整代码、真实案例、bash/Python 脚本、YAML
-- 任何铁律变更**先改 rules**，再同步 references（保持两边一致）
-
----
-
-## 二、当前已建（3 个 — P0 方法论完成）
-
-| skill | layer | 触发 | 路由 |
-|-------|-------|------|------|
-| `meritdata-platform-code-spec` | L2 | 写完二开代码提交前自查 / PR review | [SKILL.md](meritdata-platform-code-spec/SKILL.md) |
-| `meritdata-platform-data-boundary` | L2 | 二开库数据访问代码生成 / PR 提交前 / CI 扫描 | [SKILL.md](meritdata-platform-data-boundary/SKILL.md) |
-| `meritdata-platform-domain-model` | L2 | 新二开业务模块的数据库表设计 / 聚合根设计 | [SKILL.md](meritdata-platform-domain-model/SKILL.md) |
-
-**3 个方法论 skill 与 rules §8 铁律一一对应**：
-
-```
-rules/code-dev-rules.md §8.1 ──┬── data-boundary skill
-rules/code-dev-rules.md §8.2 ──┼── domain-model skill
-rules/code-dev-rules.md §8.3 ──┴── code-spec skill
-```
-
----
-
-## 三、待建（28 个 — 按 P1/P2/P3/P4 分批）
-
-### P1 L1 入口（1 个）— 3-5 天
-
-- `meritdata-platform-playbook` — 唯一对外入口，识别动作 → 路由到 L2
-
-### P2 L2 领域（8 个）— 1-2 周
-
-- `meritdata-platform-bpm` — 流程引擎
-- `meritdata-platform-entities` — 平台实体与 Q 类
-- `meritdata-platform-services` — 同 JVM 公共服务
-- `meritdata-platform-integration` — 对外接口 / Feign / HR 同步
-- `meritdata-platform-frontend` — 前端组件与工程
-- `meritdata-platform-job` — 任务调度
-- `meritdata-platform-impexp` — 导入导出
-- `meritdata-platform-sso` — 认证
-
-### P3 L3 单点 API（19 个）— 2 周
-
-- 缓存 / Nacos 配置 / 国密 / 密级 / 会话 / 日志 / 消息中心
-- 字典 API / 组织人员 API / 资源授权
-- 菜单配置 / 菜单资源 / 平台基础配置 API
-- UI 组件 / 前端部署 / 后端部署
-- 数据访问 / 代码审查 / 测试用例
-
-### P4 工具 + L0 治理（6 个）— 1 周
-
-- L4：`meritdata-bootstrap-2nd-dev` / `meritdata-nacos-importer` / `meritdata-platform-2nd-dev-check`
-- L0：`skill-authoring-workflow` / `skill-vetter` / `skill-stocktake`
-
----
-
-## 四、SKILL.md 写法规范（基于3 个方法论精简经验）
-
-### 4.1 必须含
-
-- frontmatter（name / description / metadata.version / layer / risk / source / date_added / last_modified）
-- 触发条件（3-5 条 bullet）
-- 不触发条件（避免误加载，2-4 条 bullet，明确指向替代 skill）
-- 前置约束（引用 rules 章节号，**不重复铁律正文**）
-- 路由（指向 references/ 文件）
-
-### 4.2 禁止写
-
-- ❌ 铁律正文（已存在于 rules）
-- ❌ 完整代码示例（放 references/anti-patterns.md）
-- ❌ CI 命令（放 references/validate-rules.md）
-- ❌ 适用范围（与 rules 重复）
-- ❌ 安全边界（与 rules 重复）
-- ❌ 引用与依赖（路由信息已在 references 头部）
-
-### 4.3 行数控制
-
-- 目标：**15-40 行**（不含 frontmatter）
-- 已精简样本：code-spec 33 行 / data-boundary 38 行 / domain-model 38 行
-
----
-
-## 五、与三方源目录的关系
-
-```
-工业互联codex/  石油skills/  研发skills/    ← 三方源，待归档
-                              ↓ 阶段 2 合稿
-                     skills/meritdata-platform-*/
-                              ↓ 路由
-                     ../rules/code-dev-rules.md §八  ← 铁律摘要
-```
-
-**三方源归档时机**：阶段 2 合稿完成后；归档前加 `LEGACY.md` 标记只读。
-
----
-
-## 六、变更记录
-
-| 日期 | 变更 |
-|------|------|
-| 2026-09-07 | 新建 3 个方法论 skill（code-spec / data-boundary / domain-model），含 SKILL.md + anti-patterns.md + validate-rules.md |
-| 2026-09-07 | 精简 SKILL.md 顶层从 88-111 行到 33-38 行（-65%），删除与 rules 重复内容 |

package/skills/api-design/SKILL.md

@@ -1,523 +0,0 @@
----
-name: api-design
-description: REST API tasarım kalıpları; kaynak isimlendirme, durum kodları, sayfalama, filtreleme, hata yanıtları, versiyonlama ve üretim API'leri için hız sınırlama içerir.
-origin: ECC
----
-
-# API Tasarım Kalıpları
-
-Tutarlı, geliştirici dostu REST API'leri tasarlamak için konvansiyonlar ve en iyi uygulamalar.
-
-## Ne Zaman Aktifleştirmeli
-
-- Yeni API endpoint'leri tasarlarken
-- Mevcut API sözleşmelerini incelerken
-- Sayfalama, filtreleme veya sıralama eklerken
-- API'ler için hata işleme uygularken
-- API versiyonlama stratejisi planlarken
-- Halka açık veya iş ortağı odaklı API'ler oluştururken
-
-## Kaynak Tasarımı
-
-### URL Yapısı
-
-```
-# Kaynaklar isim, çoğul, küçük harf, kebab-case
-GET    /api/v1/users
-GET    /api/v1/users/:id
-POST   /api/v1/users
-PUT    /api/v1/users/:id
-PATCH  /api/v1/users/:id
-DELETE /api/v1/users/:id
-
-# İlişkiler için alt kaynaklar
-GET    /api/v1/users/:id/orders
-POST   /api/v1/users/:id/orders
-
-# CRUD'a uymayan aksiyonlar (fiilleri dikkatli kullanın)
-POST   /api/v1/orders/:id/cancel
-POST   /api/v1/auth/login
-POST   /api/v1/auth/refresh
-```
-
-### İsimlendirme Kuralları
-
-```
-# İYİ
-/api/v1/team-members          # çok sözcüklü kaynaklar için kebab-case
-/api/v1/orders?status=active  # filtreleme için query parametreleri
-/api/v1/users/123/orders      # sahiplik için iç içe kaynaklar
-
-# KÖTÜ
-/api/v1/getUsers              # URL'de fiil
-/api/v1/user                  # tekil (çoğul kullanın)
-/api/v1/team_members          # URL'lerde snake_case
-/api/v1/users/123/getOrders   # iç içe kaynaklarda fiil
-```
-
-## HTTP Metodları ve Durum Kodları
-
-### Metod Semantiği
-
-| Metod | Idempotent | Güvenli | Kullanım Amacı |
-|--------|-----------|------|---------|
-| GET | Evet | Evet | Kaynakları getir |
-| POST | Hayır | Hayır | Kaynak oluştur, aksiyonları tetikle |
-| PUT | Evet | Hayır | Kaynağın tam değişimi |
-| PATCH | Hayır* | Hayır | Kaynağın kısmi güncellemesi |
-| DELETE | Evet | Hayır | Kaynağı kaldır |
-
-*PATCH uygun implementasyonla idempotent yapılabilir
-
-### Durum Kodu Referansı
-
-```
-# Başarı
-200 OK                    — GET, PUT, PATCH (yanıt body'si ile)
-201 Created               — POST (Location header ekleyin)
-204 No Content            — DELETE, PUT (yanıt body'si yok)
-
-# İstemci Hataları
-400 Bad Request           — Validasyon hatası, hatalı JSON
-401 Unauthorized          — Eksik veya geçersiz kimlik doğrulama
-403 Forbidden             — Kimlik doğrulandı ama yetkilendirilmedi
-404 Not Found             — Kaynak mevcut değil
-409 Conflict              — Tekrar kayıt, durum çakışması
-422 Unprocessable Entity  — Semantik olarak geçersiz (geçerli JSON, kötü veri)
-429 Too Many Requests     — Hız limiti aşıldı
-
-# Sunucu Hataları
-500 Internal Server Error — Beklenmeyen hata (detayları açığa çıkarmayın)
-502 Bad Gateway           — Upstream servis başarısız
-503 Service Unavailable   — Geçici aşırı yük, Retry-After ekleyin
-```
-
-### Yaygın Hatalar
-
-```
-# KÖTÜ: Her şey için 200
-{ "status": 200, "success": false, "error": "Not found" }
-
-# İYİ: HTTP durum kodlarını semantik olarak kullanın
-HTTP/1.1 404 Not Found
-{ "error": { "code": "not_found", "message": "User not found" } }
-
-# KÖTÜ: Validasyon hataları için 500
-# İYİ: Alan düzeyinde detaylarla 400 veya 422
-
-# KÖTÜ: Oluşturulan kaynaklar için 200
-# İYİ: Location header ile 201
-HTTP/1.1 201 Created
-Location: /api/v1/users/abc-123
-```
-
-## Yanıt Formatı
-
-### Başarı Yanıtı
-
-```json
-{
-  "data": {
-    "id": "abc-123",
-    "email": "alice@example.com",
-    "name": "Alice",
-    "created_at": "2025-01-15T10:30:00Z"
-  }
-}
-```
-
-### Koleksiyon Yanıtı (Sayfalama ile)
-
-```json
-{
-  "data": [
-    { "id": "abc-123", "name": "Alice" },
-    { "id": "def-456", "name": "Bob" }
-  ],
-  "meta": {
-    "total": 142,
-    "page": 1,
-    "per_page": 20,
-    "total_pages": 8
-  },
-  "links": {
-    "self": "/api/v1/users?page=1&per_page=20",
-    "next": "/api/v1/users?page=2&per_page=20",
-    "last": "/api/v1/users?page=8&per_page=20"
-  }
-}
-```
-
-### Hata Yanıtı
-
-```json
-{
-  "error": {
-    "code": "validation_error",
-    "message": "Request validation failed",
-    "details": [
-      {
-        "field": "email",
-        "message": "Must be a valid email address",
-        "code": "invalid_format"
-      },
-      {
-        "field": "age",
-        "message": "Must be between 0 and 150",
-        "code": "out_of_range"
-      }
-    ]
-  }
-}
-```
-
-### Yanıt Zarfı Varyantları
-
-```typescript
-// Seçenek A: Data sarmalayıcılı zarf (halka açık API'ler için önerilir)
-interface ApiResponse<T> {
-  data: T;
-  meta?: PaginationMeta;
-  links?: PaginationLinks;
-}
-
-interface ApiError {
-  error: {
-    code: string;
-    message: string;
-    details?: FieldError[];
-  };
-}
-
-// Seçenek B: Düz yanıt (daha basit, dahili API'ler için yaygın)
-// Başarı: kaynağı doğrudan döndür
-// Hata: hata nesnesini döndür
-// HTTP durum koduyla ayırt et
-```
-
-## Sayfalama
-
-### Offset-Tabanlı (Basit)
-
-```
-GET /api/v1/users?page=2&per_page=20
-
-# Implementasyon
-SELECT * FROM users
-ORDER BY created_at DESC
-LIMIT 20 OFFSET 20;
-```
-
-**Artıları:** Uygulaması kolay, "N sayfasına git" destekler
-**Eksileri:** Büyük offset'lerde yavaş (OFFSET 100000), eş zamanlı eklemelerde tutarsız
-
-### Cursor-Tabanlı (Ölçeklenebilir)
-
-```
-GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
-
-# Implementasyon
-SELECT * FROM users
-WHERE id > :cursor_id
-ORDER BY id ASC
-LIMIT 21;  -- has_next belirlemek için bir fazla getir
-```
-
-```json
-{
-  "data": [...],
-  "meta": {
-    "has_next": true,
-    "next_cursor": "eyJpZCI6MTQzfQ"
-  }
-}
-```
-
-**Artıları:** Pozisyondan bağımsız tutarlı performans, eş zamanlı eklemelerde kararlı
-**Eksileri:** Rastgele sayfaya atlayamaz, cursor opak
-
-### Hangisi Ne Zaman Kullanılmalı
-
-| Kullanım Senaryosu | Sayfalama Tipi |
-|----------|----------------|
-| Admin panelleri, küçük veri setleri (<10K) | Offset |
-| Sonsuz kaydırma, akışlar, büyük veri setleri | Cursor |
-| Halka açık API'ler | Cursor (varsayılan) ile offset (opsiyonel) |
-| Arama sonuçları | Offset (kullanıcılar sayfa numarası bekler) |
-
-## Filtreleme, Sıralama ve Arama
-
-### Filtreleme
-
-```
-# Basit eşitlik
-GET /api/v1/orders?status=active&customer_id=abc-123
-
-# Karşılaştırma operatörleri (köşeli parantez notasyonu kullanın)
-GET /api/v1/products?price[gte]=10&price[lte]=100
-GET /api/v1/orders?created_at[after]=2025-01-01
-
-# Çoklu değerler (virgülle ayrılmış)
-GET /api/v1/products?category=electronics,clothing
-
-# İç içe alanlar (nokta notasyonu)
-GET /api/v1/orders?customer.country=US
-```
-
-### Sıralama
-
-```
-# Tek alan (azalan için - öneki)
-GET /api/v1/products?sort=-created_at
-
-# Çoklu alanlar (virgülle ayrılmış)
-GET /api/v1/products?sort=-featured,price,-created_at
-```
-
-### Tam Metin Arama
-
-```
-# Arama query parametresi
-GET /api/v1/products?q=wireless+headphones
-
-# Alana özel arama
-GET /api/v1/users?email=alice
-```
-
-### Seyrek Fieldset'ler
-
-```
-# Sadece belirtilen alanları döndür (payload'ı azaltır)
-GET /api/v1/users?fields=id,name,email
-GET /api/v1/orders?fields=id,total,status&include=customer.name
-```
-
-## Kimlik Doğrulama ve Yetkilendirme
-
-### Token-Tabanlı Auth
-
-```
-# Authorization header'da Bearer token
-GET /api/v1/users
-Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
-
-# API key (sunucudan sunucuya)
-GET /api/v1/data
-X-API-Key: sk_live_abc123
-```
-
-### Yetkilendirme Kalıpları
-
-```typescript
-// Kaynak seviyesi: sahipliği kontrol et
-app.get("/api/v1/orders/:id", async (req, res) => {
-  const order = await Order.findById(req.params.id);
-  if (!order) return res.status(404).json({ error: { code: "not_found" } });
-  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
-  return res.json({ data: order });
-});
-
-// Rol-tabanlı: yetkileri kontrol et
-app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
-  await User.delete(req.params.id);
-  return res.status(204).send();
-});
-```
-
-## Hız Sınırlama
-
-### Header'lar
-
-```
-HTTP/1.1 200 OK
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 95
-X-RateLimit-Reset: 1640000000
-
-# Aşıldığında
-HTTP/1.1 429 Too Many Requests
-Retry-After: 60
-{
-  "error": {
-    "code": "rate_limit_exceeded",
-    "message": "Rate limit exceeded. Try again in 60 seconds."
-  }
-}
-```
-
-### Hız Limit Katmanları
-
-| Katman | Limit | Pencere | Kullanım Senaryosu |
-|------|-------|--------|----------|
-| Anonim | 30/dk | IP Başına | Halka açık endpoint'ler |
-| Kimlik Doğrulanmış | 100/dk | Kullanıcı Başına | Standart API erişimi |
-| Premium | 1000/dk | API key Başına | Ücretli API planları |
-| Dahili | 10000/dk | Servis Başına | Servisten servise |
-
-## Versiyonlama
-
-### URL Yolu Versiyonlama (Önerilen)
-
-```
-/api/v1/users
-/api/v2/users
-```
-
-**Artıları:** Açık, yönlendirmesi kolay, cache'lenebilir
-**Eksileri:** Versiyonlar arası URL değişir
-
-### Header Versiyonlama
-
-```
-GET /api/users
-Accept: application/vnd.myapp.v2+json
-```
-
-**Artıları:** Temiz URL'ler
-**Eksileri:** Test etmesi zor, unutulması kolay
-
-### Versiyonlama Stratejisi
-
-```
-1. /api/v1/ ile başlayın — ihtiyaç duyana kadar versiyonlamayın
-2. En fazla 2 aktif versiyon koruyun (mevcut + önceki)
-3. Kullanımdan kaldırma zaman çizelgesi:
-   - Kullanımdan kaldırmayı duyurun (halka açık API'ler için 6 ay önceden)
-   - Sunset header ekleyin: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
-   - Sunset tarihinden sonra 410 Gone döndürün
-4. Breaking olmayan değişiklikler yeni versiyon gerektirmez:
-   - Yanıtlara yeni alanlar eklemek
-   - Yeni opsiyonel query parametreleri eklemek
-   - Yeni endpoint'ler eklemek
-5. Breaking değişiklikler yeni versiyon gerektirir:
-   - Alanları kaldırmak veya yeniden adlandırmak
-   - Alan tiplerini değiştirmek
-   - URL yapısını değiştirmek
-   - Kimlik doğrulama metodunu değiştirmek
-```
-
-## Implementasyon Kalıpları
-
-### TypeScript (Next.js API Route)
-
-```typescript
-import { z } from "zod";
-import { NextRequest, NextResponse } from "next/server";
-
-const createUserSchema = z.object({
-  email: z.string().email(),
-  name: z.string().min(1).max(100),
-});
-
-export async function POST(req: NextRequest) {
-  const body = await req.json();
-  const parsed = createUserSchema.safeParse(body);
-
-  if (!parsed.success) {
-    return NextResponse.json({
-      error: {
-        code: "validation_error",
-        message: "Request validation failed",
-        details: parsed.error.issues.map(i => ({
-          field: i.path.join("."),
-          message: i.message,
-          code: i.code,
-        })),
-      },
-    }, { status: 422 });
-  }
-
-  const user = await createUser(parsed.data);
-
-  return NextResponse.json(
-    { data: user },
-    {
-      status: 201,
-      headers: { Location: `/api/v1/users/${user.id}` },
-    },
-  );
-}
-```
-
-### Python (Django REST Framework)
-
-```python
-from rest_framework import serializers, viewsets, status
-from rest_framework.response import Response
-
-class CreateUserSerializer(serializers.Serializer):
-    email = serializers.EmailField()
-    name = serializers.CharField(max_length=100)
-
-class UserSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = User
-        fields = ["id", "email", "name", "created_at"]
-
-class UserViewSet(viewsets.ModelViewSet):
-    serializer_class = UserSerializer
-    permission_classes = [IsAuthenticated]
-
-    def get_serializer_class(self):
-        if self.action == "create":
-            return CreateUserSerializer
-        return UserSerializer
-
-    def create(self, request):
-        serializer = CreateUserSerializer(data=request.data)
-        serializer.is_valid(raise_exception=True)
-        user = UserService.create(**serializer.validated_data)
-        return Response(
-            {"data": UserSerializer(user).data},
-            status=status.HTTP_201_CREATED,
-            headers={"Location": f"/api/v1/users/{user.id}"},
-        )
-```
-
-### Go (net/http)
-
-```go
-func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
-    var req CreateUserRequest
-    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-        writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
-        return
-    }
-
-    if err := req.Validate(); err != nil {
-        writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
-        return
-    }
-
-    user, err := h.service.Create(r.Context(), req)
-    if err != nil {
-        switch {
-        case errors.Is(err, domain.ErrEmailTaken):
-            writeError(w, http.StatusConflict, "email_taken", "Email already registered")
-        default:
-            writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
-        }
-        return
-    }
-
-    w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
-    writeJSON(w, http.StatusCreated, map[string]any{"data": user})
-}
-```
-
-## API Tasarım Kontrol Listesi
-
-Yeni bir endpoint yayınlamadan önce:
-
-- [ ] Kaynak URL isimlendirme konvansiyonlarını takip ediyor (çoğul, kebab-case, fiil yok)
-- [ ] Doğru HTTP metodu kullanılıyor (okumalar için GET, oluşturmalar için POST, vb.)
-- [ ] Uygun durum kodları döndürülüyor (her şey için 200 değil)
-- [ ] Girdi şema ile validasyona tabi tutuluyor (Zod, Pydantic, Bean Validation)
-- [ ] Hata yanıtları kodlar ve mesajlarla standart formatı takip ediyor
-- [ ] Liste endpoint'leri için sayfalama uygulanmış (cursor veya offset)
-- [ ] Kimlik doğrulama gerekli (veya açıkça halka açık işaretlenmiş)
-- [ ] Yetkilendirme kontrol ediliyor (kullanıcı sadece kendi kaynaklarına erişebilir)
-- [ ] Hız sınırlama yapılandırılmış
-- [ ] Yanıt dahili detayları sızdırmıyor (stack trace'ler, SQL hataları)
-- [ ] Mevcut endpoint'lerle tutarlı isimlendirme (camelCase vs snake_case)
-- [ ] Dokümante edilmiş (OpenAPI/Swagger spec güncellenmiş)