autosnippet 2.9.0 → 2.10.0

package/lib/http/routes/knowledge.js

@@ -0,0 +1,246 @@
+/**
+ * Knowledge API 路由 (V3)
+ * 统一知识条目的 CRUD + 生命周期操作
+ * 替代 recipes.js + candidates.js （旧路由继续保留用于向后兼容）
+ */
+
+import express from 'express';
+import { asyncHandler } from '../middleware/errorHandler.js';
+import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import { ValidationError } from '../../shared/errors/index.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+import { getContext, safeInt } from '../utils/routeHelpers.js';
+
+const logger = Logger.getInstance();
+const router = express.Router();
+
+const MAX_BATCH_SIZE = 100;
+
+/* ═══ 查询 ═══════════════════════════════════════════════ */
+
+/**
+ * GET /api/v1/knowledge
+ * 获取知识条目列表（支持筛选和分页）
+ */
+router.get('/', asyncHandler(async (req, res) => {
+  const { lifecycle, kind, category, language, knowledgeType, scope, keyword, tag, source } = req.query;
+  const page = safeInt(req.query.page, 1);
+  const pageSize = safeInt(req.query.limit, 20, 1, 1000);
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+
+  if (keyword) {
+    const result = await knowledgeService.search(keyword, { page, pageSize });
+    return res.json({ success: true, data: result });
+  }
+
+  const filters = {};
+  if (lifecycle)     filters.lifecycle = lifecycle;
+  if (kind)          filters.kind = kind;
+  if (category)      filters.category = category;
+  if (language)      filters.language = language;
+  if (knowledgeType) filters.knowledgeType = knowledgeType;
+  if (scope)         filters.scope = scope;
+  if (tag)           filters.tag = tag;
+  if (source)        filters.source = source;
+
+  const result = await knowledgeService.list(filters, { page, pageSize });
+  res.json({ success: true, data: result });
+}));
+
+/**
+ * GET /api/v1/knowledge/stats
+ * 获取统计信息
+ */
+router.get('/stats', asyncHandler(async (req, res) => {
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const stats = await knowledgeService.getStats();
+  res.json({ success: true, data: stats });
+}));
+
+/**
+ * GET /api/v1/knowledge/:id
+ * 获取知识条目详情
+ */
+router.get('/:id', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const entry = await knowledgeService.get(id);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/* ═══ CRUD ═══════════════════════════════════════════════ */
+
+/**
+ * POST /api/v1/knowledge
+ * 创建知识条目（wire format 直通）
+ */
+router.post('/', asyncHandler(async (req, res) => {
+  const data = req.body;
+
+  if (!data.title || !data.content) {
+    throw new ValidationError('title and content are required');
+  }
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.create(data, context);
+  res.status(201).json({
+    success: true,
+    data: entry.toJSON(),
+  });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id
+ * 更新知识条目（白名单字段）
+ */
+router.patch('/:id', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.update(id, req.body, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/**
+ * DELETE /api/v1/knowledge/:id
+ * 删除知识条目
+ */
+router.delete('/:id', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const result = await knowledgeService.delete(id, context);
+  res.json({ success: true, data: result });
+}));
+
+/* ═══ 生命周期操作（3 状态: pending / active / deprecated）═══ */
+
+/**
+ * PATCH /api/v1/knowledge/:id/publish
+ * 发布 (pending → active) — 仅开发者
+ */
+router.patch('/:id/publish', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.publish(id, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id/deprecate
+ * 废弃 (pending|active → deprecated)
+ */
+router.patch('/:id/deprecate', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const { reason } = req.body;
+
+  if (!reason) {
+    throw new ValidationError('reason is required for deprecation');
+  }
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.deprecate(id, reason, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id/reactivate
+ * 重新激活 (deprecated → pending)
+ */
+router.patch('/:id/reactivate', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.reactivate(id, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/* ═══ 批量操作 ═══════════════════════════════════════════ */
+
+/**
+ * POST /api/v1/knowledge/batch-publish
+ * 批量发布 (pending → active)
+ * 支持 autoApprovableOnly=true 参数，只发布 auto_approvable 的条目
+ */
+router.post('/batch-publish', asyncHandler(async (req, res) => {
+  const { ids } = req.body;
+
+  if (!Array.isArray(ids) || ids.length === 0) {
+    throw new ValidationError('ids array is required and must not be empty');
+  }
+  if (ids.length > MAX_BATCH_SIZE) {
+    throw new ValidationError(`Batch size exceeds limit of ${MAX_BATCH_SIZE}`);
+  }
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const results = await Promise.allSettled(
+    ids.map(id => knowledgeService.publish(id, context)),
+  );
+
+  const published = results.filter(r => r.status === 'fulfilled').map(r => r.value.toJSON());
+  const failed = results
+    .map((r, i) => r.status === 'rejected' ? { id: ids[i], error: r.reason?.message } : null)
+    .filter(Boolean);
+
+  res.json({
+    success: true,
+    data: { published, failed, total: ids.length, successCount: published.length, failureCount: failed.length },
+  });
+}));
+
+/* ═══ 使用 / 质量 ═══════════════════════════════════════ */
+
+/**
+ * POST /api/v1/knowledge/:id/usage
+ * 记录使用（adoption / application / guard_hit / view / success）
+ */
+router.post('/:id/usage', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const { type = 'adoption', feedback } = req.body;
+  const context = getContext(req);
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+
+  await knowledgeService.incrementUsage(id, type, { actor: context.userId, feedback });
+  res.json({ success: true, message: `${type} recorded` });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id/quality
+ * 重新计算质量评分
+ */
+router.patch('/:id/quality', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const context = getContext(req);
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+
+  const result = await knowledgeService.updateQuality(id, context);
+  res.json({ success: true, data: result });
+}));
+
+export default router;

package/lib/http/routes/search.js

@@ -44,13 +44,13 @@ router.get('/', asyncHandler(async (req, res) => {
   const results = {};
   const pagination = { page, pageSize: limit };
 
-  // 搜索 Recipe（统一模型，包含所有知识类型）
+  // 搜索知识条目（V3 统一模型）
   if (type === 'all' || type === 'recipe' || type === 'solution') {
     try {
-      const recipeService = container.get('recipeService');
-      results.recipes = await recipeService.searchRecipes(q, pagination);
+      const knowledgeService = container.get('knowledgeService');
+      results.recipes = await knowledgeService.search(q, pagination);
     } catch (err) {
-      logger.warn('Recipe 搜索失败', { query: q, error: err.message });
+      logger.warn('Knowledge 搜索失败', { query: q, error: err.message });
       results.recipes = { items: [], total: 0 };
     }
   }
@@ -66,11 +66,11 @@ router.get('/', asyncHandler(async (req, res) => {
     }
   }
 
-  // 搜索 Candidate
+  // 搜索候选知识条目 (V3: lifecycle=draft/pending)
   if (type === 'all' || type === 'candidate') {
     try {
-      const candidateService = container.get('candidateService');
-      results.candidates = await candidateService.searchCandidates(q, pagination);
+      const knowledgeService = container.get('knowledgeService');
+      results.candidates = await knowledgeService.search(q, pagination);
     } catch (err) {
       logger.warn('Candidate 搜索失败', { query: q, error: err.message });
       results.candidates = { items: [], total: 0 };
@@ -172,18 +172,14 @@ router.get('/graph/all', asyncHandler(async (req, res) => {
   const nodeTypes = {};   // id → 主要类型（供前端区分渲染）
   const nodeCategories = {};  // id → category/target 名（供前端分组布局）
   if (nodeMap.size > 0) {
-    const recipeService = container.get('recipeService');
-    // 使用 repository.findById 避免 RecipeService.getRecipe 在找不到时记录 error 日志
-    const recipeRepo = recipeService?.recipeRepository ?? null;
+    const knowledgeRepo = container.get('knowledgeRepository');
     for (const [id, types] of nodeMap) {
-      // 记录节点主要类型
       const primaryType = types.has('recipe') ? 'recipe' : [...types][0];
       nodeTypes[id] = primaryType;
 
-      if (primaryType === 'recipe' && recipeRepo) {
-        // 仅 recipe 类型才查 DB；直接用 repo 避免 NotFoundError 日志噪音
+      if ((primaryType === 'recipe' || primaryType === 'knowledge') && knowledgeRepo) {
         try {
-          const r = await recipeRepo.findById(id);
+          const r = await knowledgeRepo.findById(id);
           if (r) {
             nodeLabels[id] = r.title || r.name || id;
             nodeCategories[id] = r.category || '';
@@ -191,7 +187,6 @@ router.get('/graph/all', asyncHandler(async (req, res) => {
           }
         } catch { /* not found – fall through */ }
       }
-      // module / candidate 或查不到的 recipe → 直接用 ID
       nodeLabels[id] = id;
     }
   }
@@ -226,9 +221,9 @@ router.post('/context-aware', asyncHandler(async (req, res) => {
     throw new ValidationError('keyword is required');
   }
   const container = getServiceContainer();
-  const recipeService = container.get('recipeService');
+  const knowledgeService = container.get('knowledgeService');
   const pageSize = Math.min(limit || 10, 100);
-  const list = await recipeService.searchRecipes(keyword, { page: 1, pageSize });
+  const list = await knowledgeService.search(keyword, { page: 1, pageSize });
   const items = list.data || list.items || [];
   const results = items.map(r => ({
     name: (r.title || r.id) + '.md',