backend-service-implement（后端服务实现）

backend-service-implement

Bridge spec to code — generate full service implementations with business logic from TODO stubs and upstream specs.

Context Files

• $JAAN_CONTEXT_DIR/tech.md - Tech stack context (CRITICAL — determines framework, ORM, patterns)

- Uses sections: #current-stack, #frameworks, #constraints, #patterns

• $JAAN_CONTEXT_DIR/config.md - Project configuration
• $JAAN_TEMPLATES_DIR/jaan-to-backend-service-implement.template.md - Output template
• $JAAN_LEARN_DIR/jaan-to-backend-service-implement.learn.md - Past lessons (loaded in Pre-Execution)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol
• ${CLAUDE_PLUGIN_ROOT}/docs/research/70-dev-backend-service-implementation-generation.md - Research: service layer architecture, ORM queries, RFC 9457 errors, pagination, transactions, idempotency, JWT lifecycle

Input

Upstream Artifacts: $ARGUMENTS

Accepts 1-4 file paths or directory references:

• backend-scaffold — Path to scaffold output (route handlers with TODO stubs, service stubs, ORM schema)
• backend-api-contract — Path to OpenAPI 3.1 YAML (endpoint specs, request/response schemas, error codes)
• backend-data-model — Path to data model document (table definitions, relationships, constraints, indexes)
• backend-task-breakdown — Path to BE task breakdown (vertical slices with implementation notes)
• Empty — Interactive wizard prompting for each artifact

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: backend-service-implement Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

• $JAAN_CONTEXT_DIR/tech.md — Know the tech stack for framework-specific service generation
• $JAAN_CONTEXT_DIR/config.md — Project configuration

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_backend-service-implement

Language exception: Generated code output (variable names, code blocks, schemas, SQL, API specs) is NOT affected by this setting and remains in the project's programming language.

PHASE 1: Analysis (Read-Only)

Thinking Mode

ultrathink

Use extended reasoning for:

• Cross-referencing scaffold TODO stubs against API contract + data model + task breakdown
• Deriving business logic from endpoint relationships and status code semantics
• Planning service implementation order (dependency graph)
• Identifying state machines, transactions, and idempotency requirements

Step 1: Validate & Parse Inputs

For each provided path:

• backend-scaffold: Read route handlers, service stubs, ORM schema. Extract all // TODO comments and map to endpoint operations
• backend-api-contract: Read api.yaml. Extract paths, schemas, error responses, security schemes, pagination config
• backend-data-model: Read data model doc. Extract table definitions, constraints, indexes, relationships, migration notes
• backend-task-breakdown: Read task breakdown. Extract vertical slices, implementation notes, acceptance criteria, business rules

Report which inputs found vs missing; suggest fallback for missing:

• Missing scaffold: generate service implementations from API contract + data model (scaffold-less mode)
• Missing API contract: derive endpoints from scaffold route definitions
• Missing data model: derive from Prisma/Eloquent schema in scaffold
• Missing task breakdown: derive business rules from API contract status codes and schema differences

Present input summary:

INPUT SUMMARY
─────────────
Sources Found:    {list}
Sources Missing:  {list with fallback suggestions}
Entities:         {extracted entity/resource names}
TODO Stubs:       {count from scaffold}
Endpoints:        {count from API contract}
Tables:           {count from data model}
Task Slices:      {count from task breakdown}
Business Rules:   {count of derived rules}

Step 2: Detect Tech Stack

Read $JAAN_CONTEXT_DIR/tech.md:

• Extract framework from #current-stack (default: Fastify v5+)
• Extract ORM from #current-stack (default: Prisma)
• Extract DB from #current-stack (default: PostgreSQL)
• Extract patterns from #patterns (auth, error handling, logging)
• If tech.md missing: ask framework/ORM/DB via AskUserQuestion

Multi-Stack Detection:

Step 3: Map TODOs to Implementation Plan

3.1: TODO Inventory

Parse all // TODO: implement stubs from scaffold. For each:

1. Identify the endpoint (method + path)
2. Match to API contract operation (request/response schemas, error codes)
3. Match to data model tables (required queries, relationships)
4. Match to task breakdown slice (business rules, acceptance criteria)

3.2: Business Logic Derivation

Derive implementation patterns from API spec semantics:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Business Logic Derivation Patterns" for HTTP status code patterns, schema difference analysis, endpoint relationship patterns, and task breakdown derivation rules.

3.3: State Machine Detection

When API specs include status fields with constrained transitions:

• Extract enum values from schema
• Map action endpoints to transitions (e.g., POST /orders/{id}/confirm)
• Generate transition map and validation function

3.4: Dependency Graph

1. Shared helpers (error factory, pagination, cursor encoding)
2. Auth service (JWT lifecycle — if auth endpoints exist)
3. Independent resource services (no cross-service dependencies)
4. Dependent resource services (reference other services)
5. Cross-cutting middleware (idempotency, rate limiting)

Step 4: Clarify Implementation Scope

Use AskUserQuestion:

1. Scope question:

- Question: "Implement all TODOs or select vertical slices?" - Header: "Scope" - Options: - "All TODOs" — Implement every TODO stub found - "Select slices" — Choose specific vertical slices from task breakdown - "Priority subset" — Start with core CRUD, add complex logic later

1. Auth question (if auth endpoints detected):

- Question: "What JWT library should be used for authentication?" - Header: "Auth" - Options: - "jose (Recommended)" — Modern JWT with Web Crypto API, edge-compatible - "jsonwebtoken" — Legacy but widely used - "Already implemented" — Auth service exists, skip generation - "No auth" — Skip auth implementation

1. Pagination question (if list endpoints detected):

- Question: "Which pagination strategy for list endpoints?" - Header: "Pagination" - Options: - "Cursor-based (Recommended)" — Stable under writes, O(1) seek, opaque cursor - "Offset-based" — Simple page + limit, for admin/dashboard endpoints - "Both" — Cursor for public API, offset for admin - "Already implemented" — Pagination helpers exist

1. Transaction depth (if multi-step operations detected):

- Question: "How should multi-step operations be handled?" - Header: "Transactions" - Options: - "Interactive transactions (Recommended)" — Prisma $transaction with isolation levels - "Sequential batch" — Simple array transactions for independent writes - "Optimistic concurrency" — Version-based updates with conflict detection - "Mix by operation" — Choose per operation based on complexity

1. Idempotency question (if POST/PUT endpoints exist):

- Question: "Should POST/PUT endpoints support idempotency keys?" - Header: "Idempotency" - Options: - "Yes (Recommended)" — Idempotency-Key header with DB storage, 24h TTL - "Critical endpoints only" — Only for payment/order creation - "No" — Skip idempotency support

Step 5: Present Implementation Plan

IMPLEMENTATION PLAN
═══════════════════

STACK: {framework} + {orm} + {database}

TODO COVERAGE
─────────────
Total TODOs:     {count}
Implementing:    {count} ({scope choice})
Skipping:        {count} (if partial scope)

SERVICES ({count})
──────────────────
{For each service:}
  {resource}.service.ts
    - {method}: {description} ({status codes})
    ...

SHARED HELPERS
──────────────
  - error-factory.ts (RFC 9457 problem details, error type registry)
  - pagination.ts ({strategy} pagination helper)
  {- cursor.ts (cursor encode/decode) — if cursor pagination}
  {- auth.service.ts (JWT lifecycle with jose) — if auth}
  {- idempotency.ts (Idempotency-Key middleware) — if enabled}

STATE MACHINES ({count if any})
───────────────────────────────
  {resource}: {state1} → {state2} → ...

DEPENDENCY ORDER
────────────────
1. Shared helpers
2. {ordered service list}

HARD STOP — Review Implementation Plan

Use AskUserQuestion:

• Question: "Proceed with generating service implementations?"
• Header: "Generate"
• Options:

- "Yes" — Generate all planned service files - "No" — Cancel - "Edit" — Let me revise the scope or architecture first

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Generation (Write Phase)

Phase 2 Output — Flat folder (no nested subfolder)

All files in $JAAN_OUTPUTS_DIR/backend/service-implement/{id}-{slug}/:

{id}-{slug}/
├── {id}-{slug}.md                        # Implementation guide + decisions log
├── {id}-{slug}-services/                  # Service files by domain
│   ├── {resource}.service.ts              # Per-resource service implementation
│   ├── auth.service.ts                    # Auth/JWT service (if applicable)
│   └── ...
├── {id}-{slug}-helpers/                   # Shared helper files
│   ├── error-factory.ts                   # RFC 9457 error creation
│   ├── pagination.ts                      # Pagination utility
│   ├── cursor.ts                          # Cursor encode/decode (if cursor pagination)
│   └── idempotency.ts                     # Idempotency middleware (if enabled)
└── {id}-{slug}-readme.md                  # Integration instructions

File extensions adapt to detected stack (.ts for Node.js,.php for PHP,.go for Go).

Step 6: Generate Shared Helpers

Generate helpers in dependency order (these are used by services):

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Helper Generation Patterns" for Error Factory (RFC 9457), Pagination Helper, Auth Service, and Idempotency Middleware generation templates.

Step 7: Generate Service Implementations

7.1: Service Structure

Node.js/TypeScript (Fastify + Prisma):

// Plain exported functions importing Prisma singleton
// Module caching acts as built-in singleton (no DI container needed)
// Testable via vi.mock()

import { prisma } from '../lib/prisma.js';
import { createProblemDetail, BusinessError } from '../helpers/error-factory.js';
import { paginateWithCursor } from '../helpers/pagination.js';
import type { RequestContext } from '../types.js';

PHP (Laravel + Eloquent):

// Service class with constructor injection
// Repository pattern optional (Eloquent IS the repository)
// API Resources for response transformation

Go (Chi/stdlib + sqlc):

// Feature-based internal package
// Constructor injection with small interfaces (1-3 methods)
// Accept interfaces, return structs

7.2: Per-Method Implementation

For each TODO stub, generate the full implementation:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Per-Method Implementation Patterns" for CREATE, READ, LIST, UPDATE, DELETE, and ACTION operation implementation steps.

7.3: State Machine Generation

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "State Machine Generation" for transition map template and validation function code.

7.4: Cross-Service Operations

For operations spanning multiple services:

• Use Prisma interactive $transaction with explicit isolation level
• Pass tx (transaction client) to all participating service methods
• Keep transactions short — move side effects outside
• Set maxWait: 5000 and timeout: 10000

Step 8: Generate Implementation Guide

8.1: Executive Summary

1-2 sentences: resource count, stack, key patterns implemented (pagination, auth, idempotency).

8.2: Implementation Decisions Log

For each decision made during generation:

8.3: TODO Coverage Report

8.4: Service Dependency Map

Mermaid diagram showing service dependencies and shared helpers.

Step 9: Generate Integration README

1. Setup — How to integrate generated services into the scaffold project
2. File Placement — Where each generated file goes relative to the project root
3. Dependencies — NPM packages to install (jose, etc.)
4. Configuration — Environment variables needed (JWT_SECRET, etc.)
5. Testing — How to test individual services (vi.mock() pattern)
6. Next Steps — Downstream skills:

- /jaan-to:qa-test-generate — Generate tests for these implementations - /jaan-to:sec-audit-remediate — Security audit the implementations

Step 10: Quality Check

Before preview, verify every item in the checklist (coverage, error handling, patterns, security, code quality).

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Quality Check Checklist" for the full verification checklist.

If any check fails, fix before preview.

Step 11: Preview & Approval

Present generated output summary:

• File count and total lines
• TODO coverage percentage
• Service list with method counts
• Helpers generated

Use AskUserQuestion:

• Question: "Write service implementation files to output?"
• Header: "Write Files"
• Options:

- "Yes" — Write the files - "No" — Cancel - "Refine" — Make adjustments first

Step 12: Generate ID and Folder Structure

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/backend/service-implement"
mkdir -p "$SUBDOMAIN_DIR"
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")
slug="{project-name-slug}"
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"

Preview output configuration:

Output Configuration - ID: {NEXT_ID} - Folder: $JAAN_OUTPUTS_DIR/backend/service-implement/{NEXT_ID}-{slug}/ - Main file: {NEXT_ID}-{slug}.md

Step 13: Write Output

1. Create output folder: mkdir -p "$OUTPUT_FOLDER"
2. Create services subdirectory: mkdir -p "$OUTPUT_FOLDER/${NEXT_ID}-${slug}-services"
3. Create helpers subdirectory: mkdir -p "$OUTPUT_FOLDER/${NEXT_ID}-${slug}-helpers"
4. Write all files:

- Main doc: $OUTPUT_FOLDER/${NEXT_ID}-${slug}.md - Service files: $OUTPUT_FOLDER/${NEXT_ID}-${slug}-services/{resource}.service.ts - Helper files: $OUTPUT_FOLDER/${NEXT_ID}-${slug}-helpers/{helper}.ts - Integration readme: $OUTPUT_FOLDER/${NEXT_ID}-${slug}-readme.md

1. Update subdomain index:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
  "$SUBDOMAIN_DIR/README.md" \
  "$NEXT_ID" \
  "${NEXT_ID}-${slug}" \
  "{Project Title} Service Implementations" \
  "{Executive summary — 1-2 sentences}"

1. Confirm completion:

Service implementations written to: $JAAN_OUTPUTS_DIR/backend/service-implement/{NEXT_ID}-{slug}/ Index updated: $JAAN_OUTPUTS_DIR/backend/service-implement/README.md

Step 14: Suggest Next Actions

Service implementations generated successfully! TODO Coverage: {n}/{n} (100%) Next Steps: - Copy service files to your project (see integration readme for placement) - Run /jaan-to:qa-test-generate to generate tests for these implementations - Run /jaan-to:sec-audit-remediate to audit the implementations for security issues - Run your existing test suite to verify integration

Step 15: Capture Feedback

Use AskUserQuestion:

• Question: "How did the service implementations turn out?"
• Header: "Feedback"
• Options:

- "Perfect!" — Done - "Needs fixes" — What should I improve? - "Learn from this" — Capture a lesson for future runs

If "Learn from this": Run /jaan-to:learn-add backend-service-implement "{feedback}"

Key Generation Rules — Node.js/TypeScript (Research-Informed)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Key Generation Rules — Node.js/TypeScript (Research-Informed)" for the full rules list covering Service Layer, Prisma Queries, Error Handler, RFC 9457, JWT, Cursor Pagination, Idempotency, Transactions, Import Extensions, and DTO Mapping.

Multi-Stack Support (Research-Informed)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Multi-Stack Service Patterns" for PHP (Laravel + Symfony) and Go stack-specific service patterns.

Anti-Patterns to NEVER Generate

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-service-implement-reference.md section "Anti-Patterns" for per-stack anti-pattern lists (All Stacks, Node.js, PHP, Go).

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Multi-stack support via tech.md detection
• Template-driven output structure
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

• All TODO stubs from scaffold have corresponding implementations
• Every API contract endpoint has service method coverage
• RFC 9457 error handling implemented with type registry
• Pagination helper generated and used in all list endpoints
• Auth service generated (if auth endpoints exist) with JWT lifecycle
• Idempotency middleware generated (if enabled) for POST/PUT
• State machines generated for resources with status transitions
• Transactions used for multi-step operations with side effects outside
• Quality checks passed (coverage, error handling, patterns, security, code quality)
• Implementation guide with decisions log and TODO coverage report
• Integration readme with setup instructions and next steps
• Output follows v3.0.0 structure (ID, folder, index)
• Index updated with executive summary
• User approved final result