@boyingliu01/xp-gate 0.8.21 → 0.9.1

package/skills/admin-template-guidelines/references/rule-1.md

@@ -0,0 +1,91 @@
+# Rule 1: Route Splitting — Examples
+
+## ❌ 错误示例：单文件膨胀（800+ 行）
+
+```typescript
+// admin/routes/index.ts — 反模式
+import { FastifyInstance } from 'fastify';
+
+export async function adminRoutes(fastify: FastifyInstance) {
+  // 模板列表 — 第 10 行
+  fastify.get('/admin/templates', async (req, reply) => { ... });
+  // 模板创建 — 第 45 行
+  fastify.post('/admin/templates', async (req, reply) => { ... });
+  // 模板编辑 — 第 80 行
+  fastify.get('/admin/templates/:id/edit', async (req, reply) => { ... });
+  // 模板删除 — 第 115 行
+  fastify.delete('/admin/templates/:id', async (req, reply) => { ... });
+  // 计划列表 — 第 150 行
+  fastify.get('/admin/plans', async (req, reply) => { ... });
+  // 计划创建 — 第 190 行
+  fastify.post('/admin/plans', async (req, reply) => { ... });
+  // ... 持续膨胀到 800+ 行 ...
+}
+```
+
+## ✅ 正确示例：按模块拆分
+
+```typescript
+// admin/routes/admin-shared.ts
+import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+
+export function registerAdminShared(fastify: FastifyInstance) {
+  // 共享中间件：认证
+  fastify.addHook('onRequest', authenticateAdmin);
+
+  // 共享 helper：渲染带布局的页面
+  fastify.decorate('renderAdmin', async function (
+    this: FastifyInstance,
+    req: FastifyRequest,
+    reply: FastifyReply,
+    template: string,
+    data: Record<string, unknown>
+  ) {
+    return reply.view(`admin/layouts/main.njk`, {
+      ...data,
+      _content: await reply.view(`admin/${template}.njk`, data),
+    });
+  });
+}
+
+// admin/routes/templates.ts
+import { FastifyInstance } from 'fastify';
+
+export async function registerTemplateRoutes(fastify: FastifyInstance) {
+  fastify.get('/admin/templates', { onRequest: [authenticateAdmin] }, listTemplates);
+  fastify.get('/admin/templates/new', { onRequest: [authenticateAdmin] }, showNewTemplate);
+  fastify.post('/admin/templates', { onRequest: [authenticateAdmin] }, createTemplate);
+  fastify.get('/admin/templates/:id/edit', { onRequest: [authenticateAdmin] }, showEditTemplate);
+  fastify.put('/admin/templates/:id', { onRequest: [authenticateAdmin] }, updateTemplate);
+  fastify.delete('/admin/templates/:id', { onRequest: [authenticateAdmin] }, deleteTemplate);
+}
+
+// admin/routes/plans.ts
+import { FastifyInstance } from 'fastify';
+
+export async function registerPlanRoutes(fastify: FastifyInstance) {
+  fastify.get('/admin/plans', { onRequest: [authenticateAdmin] }, listPlans);
+  fastify.post('/admin/plans', { onRequest: [authenticateAdmin] }, createPlan);
+  fastify.post('/admin/plans/:id/start', { onRequest: [authenticateAdmin] }, startPlan);
+  fastify.post('/admin/plans/:id/pause', { onRequest: [authenticateAdmin] }, pausePlan);
+  fastify.post('/admin/plans/:id/complete', { onRequest: [authenticateAdmin] }, completePlan);
+}
+
+// admin/routes/index.ts — 仅负责聚合注册
+import { FastifyInstance } from 'fastify';
+import { registerAdminShared } from './admin-shared';
+import { registerTemplateRoutes } from './templates';
+import { registerPlanRoutes } from './plans';
+import { registerReportRoutes } from './reports';
+import { registerAnalyticsRoutes } from './analytics';
+import { registerTreeRoutes } from './tree';
+
+export async function registerAllAdminRoutes(fastify: FastifyInstance) {
+  registerAdminShared(fastify);
+  await registerTemplateRoutes(fastify);
+  await registerPlanRoutes(fastify);
+  await registerReportRoutes(fastify);
+  await registerAnalyticsRoutes(fastify);
+  await registerTreeRoutes(fastify);
+}
+```

package/skills/admin-template-guidelines/references/rule-2.md

@@ -0,0 +1,155 @@
+# Rule 2: Test Consistency — Examples
+
+## ❌ 错误示例：每个测试文件自建实例
+
+```typescript
+// test/admin/templates.test.ts — 反模式
+import Fastify from 'fastify';
+import { registerTemplateRoutes } from '../../admin/routes/templates';
+
+describe('Template Routes', () => {
+  let fastify: any;
+
+  beforeEach(async () => {
+    fastify = Fastify();
+    await fastify.register(prismaPlugin, { datasource: {} }); // 每次自建
+    await fastify.register(registerTemplateRoutes);
+    await fastify.ready();
+  });
+
+  afterEach(async () => {
+    await fastify.close(); // 每个文件重复 teardown 逻辑
+  });
+
+  it('should list templates', async () => {
+    const res = await fastify.inject({ method: 'GET', url: '/admin/templates' });
+    expect(res.statusCode).toBe(200);
+  });
+});
+```
+
+```typescript
+// test/admin/plans.test.ts — 同样重复，但细节不同
+import Fastify from 'fastify';
+import { registerPlanRoutes } from '../../admin/routes/plans';
+
+describe('Plan Routes', () => {
+  let app: any;
+
+  beforeAll(async () => {
+    app = Fastify({ logger: false }); // 不一致的配置
+    await app.register(prismaPlugin, { datasource: {}, skipMigrate: true });
+    await app.register(registerPlanRoutes);
+    await app.listen({ port: 0 });
+  });
+
+  afterAll(async () => {
+    await app.server.close(); // 与 templates.test.ts teardown 方式不同
+  });
+});
+```
+
+## ✅ 正确示例：共享 Helper
+
+```typescript
+// test/helpers/create-admin-test-app.ts
+import Fastify, { FastifyInstance } from 'fastify';
+import { prisma } from '@prisma/client';
+import { registerAllAdminRoutes } from '../../admin/routes';
+
+export interface AdminTestApp {
+  fastify: FastifyInstance;
+  inject: FastifyInstance['inject'];
+  close: () => Promise<void>;
+}
+
+export async function createAdminTestApp(): Promise<AdminTestApp> {
+  const fastify = Fastify({
+    logger: false,
+    trustProxy: true,
+  });
+
+  // 注册 Prisma 插件
+  await fastify.register(async (instance) => {
+    instance.decorate('prisma', prisma);
+  });
+
+  // 注册所有 Admin 路由
+  await registerAllAdminRoutes(fastify);
+
+  await fastify.ready();
+
+  return {
+    fastify,
+    inject: fastify.inject.bind(fastify),
+    close: async () => {
+      await fastify.close();
+    },
+  };
+}
+```
+
+```typescript
+// test/admin/templates.test.ts
+import { createAdminTestApp, AdminTestApp } from '../helpers/create-admin-test-app';
+
+describe('Template Routes', () => {
+  let app: AdminTestApp;
+
+  beforeEach(async () => {
+    app = await createAdminTestApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('should list templates', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/admin/templates',
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(Array.isArray(body.templates)).toBe(true);
+  });
+
+  it('should create a template', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/admin/templates',
+      payload: {
+        name: 'New Template',
+        content: '<h1>Hello</h1>',
+      },
+    });
+    expect(res.statusCode).toBe(302);
+    expect(res.headers.location).toContain('/admin/templates');
+  });
+});
+```
+
+```typescript
+// test/admin/plans.test.ts — 使用同一个 helper，零重复
+import { createAdminTestApp, AdminTestApp } from '../helpers/create-admin-test-app';
+
+describe('Plan Routes', () => {
+  let app: AdminTestApp;
+
+  beforeEach(async () => {
+    app = await createAdminTestApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('should list plans', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/admin/plans',
+    });
+    expect(res.statusCode).toBe(200);
+  });
+});
+```

package/skills/admin-template-guidelines/references/rule-3.md

@@ -0,0 +1,70 @@
+# Rule 3: Nunjucks Parentheses — Examples
+
+## 优先级规则
+
+```
+表达式:     A <= B | lower
+实际解析:   A <= (B | lower)  ← filter 先执行，比较的是 A 和 "lower" 后的 B
+预期语义:   (A <= B) | lower  ← 先比较，结果再经 filter
+```
+
+## ❌ 错误示例
+
+```nunjucks
+{# admin/views/plans.njk — 反模式 #}
+
+{# 比较在 filter 之后执行 → 逻辑错误 #}
+{% if plan._interviews.length <= 15 | lower %}
+  <span class="badge badge-small">Small Plan</span>
+{% endif %}
+
+{# 实际等价于: plan._interviews.length <= "lower" → 始终 true #}
+
+{# 条件渲染中的陷阱 #}
+{% if plan.status == 'completed' | title %}
+  <span class="status-done">Done</span>
+{% endif %}
+
+{# 字符串格式化错误 #}
+{{ plan.completionRate * 100 | round | default(0) }}
+{# 当 completionRate 为 null 时，null * 100 = NaN → round(NaN) → 错误 #}
+```
+
+## ✅ 正确示例
+
+```nunjucks
+{# admin/views/plans.njk #}
+
+{# 括号确保比较先执行 #}
+{% if (plan._interviews.length <= 15) | lower %}
+  <span class="badge badge-small">Small Plan</span>
+{% endif %}
+
+{# 条件判断中的正确使用 #}
+{% if (plan.status == 'completed') | title %}
+  <span class="status-done">Done</span>
+{% endif %}
+
+{# 数值计算中先处理 null #}
+{{ (plan.completionRate ?? 0) * 100 | round(1) | default('0.0') }}%
+
+{# 多层比较与 filter 组合 #}
+{% if (plan._interviews.length >= 15 and plan._interviews.length <= 60) | bool %}
+  <span class="badge badge-medium">Medium Plan</span>
+{% elif (plan._interviews.length > 60) | bool %}
+  <span class="badge badge-large">Large Plan</span>
+{% endif %}
+
+{# 安全渲染可选字段 #}
+{% if (plan.description | length) > 0 %}
+  <p class="description">{{ plan.description | truncate(120) }}</p>
+{% else %}
+  <p class="description text-muted">No description provided.</p>
+{% endif %}
+```
+
+## 验证清单
+
+- [ ] 所有 `{{ A <= B | filter }}` 改为 `{{ (A <= B) | filter }}`
+- [ ] 所有 `{% if A == B | filter %}` 改为 `{% if (A == B) | filter %}`
+- [ ] 使用 `| bool` 而非裸布尔表达式配合逻辑运算符

package/skills/admin-template-guidelines/references/rule-4.md

@@ -0,0 +1,154 @@
+# Rule 4: View Model Mapper — Examples
+
+## ❌ 错误示例：路由内联转换
+
+```typescript
+// admin/routes/plans.ts — 反模式
+fastify.get('/admin/plans', async (req, reply) => {
+  const plans = await prisma.plan.findMany({
+    include: { _count: { select: { interviews: true } } },
+  });
+
+  // 每个路由都在做同样的转换
+  const viewModels = plans.map((plan) => ({
+    id: plan.id,
+    name: plan.name,
+    status: plan.status,
+    interviewCount: plan._count?.interviews ?? 0,
+    completedCount: plan.interviews?.filter((i) => i.status === 'COMPLETED').length ?? 0,
+    completionRate: plan.interviews?.filter((i) => i.status === 'COMPLETED').length ?? 0
+      / (plan._count?.interviews ?? 1) * 100,
+    createdAt: plan.createdAt.toISOString().split('T')[0],
+  }));
+
+  return reply.view('admin/plans/list.njk', { plans: viewModels });
+});
+```
+
+## ✅ 正确示例：提取 ViewModel 模块
+
+```typescript
+// admin/view-models.ts
+import { Plan, Interview, Template } from '@prisma/client';
+
+export interface PlanViewModel {
+  id: string;
+  name: string;
+  status: string;
+  interviewCount: number;
+  completedCount: number;
+  completionRate: number;
+  createdAt: string;
+}
+
+export interface TemplateViewModel {
+  id: string;
+  name: string;
+  content: string;
+  interviewCount: number;
+  lastUsed: string | null;
+}
+
+/**
+ * 将 Prisma Plan 记录转换为视图模型
+ */
+export function mapPlanToViewModel(
+  plan: Plan & { _count?: { interviews: number } },
+  interviews?: Interview[]
+): PlanViewModel {
+  const completedCount = interviews?.filter((i) => i.status === 'COMPLETED').length ?? 0;
+  const interviewCount = plan._count?.interviews ?? interviews?.length ?? 0;
+
+  return {
+    id: plan.id,
+    name: plan.name,
+    status: plan.status,
+    interviewCount,
+    completedCount,
+    completionRate: interviewCount > 0 ? (completedCount / interviewCount) * 100 : 0,
+    createdAt: plan.createdAt.toISOString().split('T')[0],
+  };
+}
+
+/**
+ * 批量转换 Plan 列表
+ */
+export function mapPlansToViewModels(
+  plans: (Plan & { _count?: { interviews: number } })[],
+  interviewsMap?: Map<string, Interview[]>
+): PlanViewModel[] {
+  return plans.map((plan) =>
+    mapPlanToViewModel(plan, interviewsMap?.get(plan.id))
+  );
+}
+
+/**
+ * 将 Prisma Template 记录转换为视图模型
+ */
+export function mapTemplateToViewModel(
+  template: Template & { _count?: { interviews: number }; interviews?: Interview[] }
+): TemplateViewModel {
+  const interviewCount = template._count?.interviews ?? template.interviews?.length ?? 0;
+  const lastUsed = template.interviews?.length
+    ? Math.max(...template.interviews.map((i) => i.createdAt.getTime()))
+    : null;
+
+  return {
+    id: template.id,
+    name: template.name,
+    content: template.content,
+    interviewCount,
+    lastUsed: lastUsed ? new Date(lastUsed).toISOString().split('T')[0] : null,
+  };
+}
+
+/**
+ * 过滤出已完成的计划
+ */
+export function filterCompletedPlans(plans: PlanViewModel[]): PlanViewModel[] {
+  return plans.filter((p) => p.status === 'COMPLETED');
+}
+
+/**
+ * 计算统计摘要
+ */
+export function calculatePlanStats(plans: PlanViewModel[]) {
+  const total = plans.length;
+  const completed = plans.filter((p) => p.status === 'COMPLETED').length;
+  const inProgress = plans.filter((p) => p.status === 'IN_PROGRESS').length;
+  const avgCompletionRate =
+    total > 0 ? plans.reduce((sum, p) => sum + p.completionRate, 0) / total : 0;
+
+  return { total, completed, inProgress, avgCompletionRate: Math.round(avgCompletionRate) };
+}
+```
+
+```typescript
+// admin/routes/plans.ts — 使用 ViewModel
+import { mapPlansToViewModels, filterCompletedPlans, calculatePlanStats } from '../view-models';
+
+fastify.get('/admin/plans', async (req, reply) => {
+  const plans = await prisma.plan.findMany({
+    include: { _count: { select: { interviews: true } } },
+  });
+
+  const viewModels = mapPlansToViewModels(plans);
+
+  return reply.view('admin/plans/list.njk', {
+    plans: viewModels,
+    stats: calculatePlanStats(viewModels),
+  });
+});
+
+fastify.get('/admin/plans/completed', async (req, reply) => {
+  const plans = await prisma.plan.findMany({
+    where: { status: 'COMPLETED' },
+    include: { _count: { select: { interviews: true } } },
+  });
+
+  const viewModels = mapPlansToViewModels(plans);
+  const completed = filterCompletedPlans(viewModels);
+
+  return reply.view('admin/plans/completed.njk', { plans: completed });
+});
+```

package/skills/admin-template-guidelines/references/rule-5.md

@@ -0,0 +1,126 @@
+# Rule 5: Auth Protection — Examples
+
+## ❌ 错误示例：GET 路由未认证
+
+```typescript
+// admin/routes/plans.ts — 反模式
+import { FastifyInstance } from 'fastify';
+
+export async function registerPlanRoutes(fastify: FastifyInstance) {
+  // GET 路由缺少认证 — 任何人都可查看所有计划
+  fastify.get('/admin/plans', async (req, reply) => {
+    const plans = await prisma.plan.findMany();
+    return reply.view('admin/plans/list.njk', { plans });
+  });
+
+  // 只有 POST 有认证
+  fastify.post('/admin/plans', { onRequest: [authenticateAdmin] }, async (req, reply) => {
+    // ...
+  });
+}
+```
+
+```typescript
+// admin/routes/analytics.ts — 使用不安全的 API Key
+import { FastifyInstance } from 'fastify';
+
+export async function registerAnalyticsRoutes(fastify: FastifyInstance) {
+  fastify.get('/admin/analytics', {
+    onRequest: [
+      // 通过 Header 传递 API Key — 易泄露、不安全
+      async (req: FastifyRequest, reply: FastifyReply) => {
+        const apiKey = req.headers['x-api-key'];
+        if (apiKey !== process.env.ADMIN_API_KEY) {
+          return reply.code(401).send({ error: 'Unauthorized' });
+        }
+      },
+    ],
+  }, async (req, reply) => {
+    // ...
+  });
+}
+```
+
+## ✅ 正确示例：所有路由统一认证
+
+```typescript
+// admin/middleware/authenticate-admin.ts
+import { FastifyRequest, FastifyReply, HookHandlerDoneFunction } from 'fastify';
+
+export async function authenticateAdmin(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  done: HookHandlerDoneFunction
+) {
+  const session = req.session;
+
+  if (!session?.userId) {
+    return reply
+      .code(302)
+      .header('Location', '/login?redirect=' + encodeURIComponent(req.url))
+      .send();
+  }
+
+  // 验证用户具有 Admin 角色
+  const user = await prisma.user.findUnique({
+    where: { id: session.userId },
+    select: { role: true },
+  });
+
+  if (user?.role !== 'ADMIN') {
+    return reply.code(403).view('admin/errors/forbidden.njk', {
+      message: 'You do not have permission to access the admin panel.',
+    });
+  }
+
+  // 将用户信息附加到请求
+  req.user = user;
+  done();
+}
+```
+
+```typescript
+// admin/routes/admin-shared.ts — 全局注册认证中间件
+import { FastifyInstance } from 'fastify';
+import { authenticateAdmin } from '../middleware/authenticate-admin';
+
+export function registerAdminShared(fastify: FastifyInstance) {
+  // 为所有 /admin/* 路由注册认证 hook
+  fastify.addHook('onRequest', authenticateAdmin);
+}
+```
+
+```typescript
+// admin/routes/plans.ts — 继承全局认证
+import { FastifyInstance } from 'fastify';
+
+export async function registerPlanRoutes(fastify: FastifyInstance) {
+  // 所有路由自动继承 authenticateAdmin
+  // 无需在每个 route 上重复声明
+  fastify.get('/admin/plans', async (req, reply) => {
+    const plans = await prisma.plan.findMany();
+    return reply.view('admin/plans/list.njk', { plans });
+  });
+
+  fastify.post('/admin/plans', async (req, reply) => {
+    await prisma.plan.create({ data: req.body as any });
+    return reply.redirect('/admin/plans');
+  });
+}
+```
+
+```typescript
+// admin/routes/analytics.ts — 同样保护
+import { FastifyInstance } from 'fastify';
+
+export async function registerAnalyticsRoutes(fastify: FastifyInstance) {
+  // GET 路由同样受认证保护
+  fastify.get('/admin/analytics', async (req, reply) => {
+    const stats = await prisma.plan.aggregate({
+      _count: { id: true },
+      _avg: { completionRate: true },
+    });
+    return reply.view('admin/analytics/dashboard.njk', { stats });
+  });
+}
+```