Back to Details

ln-113-backend-docs-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Backend Documentation Creator

后端文档生成器

L3 Worker that creates 2 backend documentation files. CONDITIONAL - only invoked when project has backend or database.
这是一个L3 Worker，用于生成两份后端文档文件。具有条件性——仅当项目包含后端或数据库时才会被调用。

Purpose & Scope

目的与范围

  • Creates api_spec.md (if hasBackend)
  • Creates database_schema.md (if hasDatabase)
  • Receives Context Store from ln-110-project-docs-coordinator
  • OpenAPI 3.0 compliant API specification
  • ER diagrams in Mermaid for database schema
  • Never gathers context itself; uses coordinator input
  • 生成api_spec.md（当存在后端时）
  • 生成database_schema.md（当存在数据库时）
  • 接收来自ln-110-project-docs-coordinator的Context Store
  • 生成符合OpenAPI 3.0规范的API文档
  • 数据库架构使用Mermaid格式的ER图
  • 不会自行收集上下文，仅使用协调器提供的输入

Invocation (who/when)

调用方式（调用方/时机）

  • ln-110-project-docs-coordinator: CONDITIONALLY invoked when: 
    • hasBackend=true
      (express, fastify, nestjs, fastapi detected)
    • hasDatabase=true
      (pg, mongoose, prisma, sequelize detected)
  • Never called directly by users
  • ln-110-project-docs-coordinator： 在以下条件下会被条件性调用： 
    • hasBackend=true
      （检测到express、fastify、nestjs、fastapi）
    • hasDatabase=true
      （检测到pg、mongoose、prisma、sequelize）
  • 不会被用户直接调用

Inputs

输入参数

From coordinator:
  • contextStore
    : Context Store with backend-specific data
    • API_TYPE (REST, GraphQL, gRPC)
    • API_ENDPOINTS (from route scan)
    • AUTH_SCHEME (JWT, OAuth2, API keys)
    • DATABASE_TYPE (PostgreSQL, MongoDB, MySQL)
    • SCHEMA_OVERVIEW (from migrations/models)
    • ER_DIAGRAM (generated from schema)
  • targetDir
    : Project root directory
  • flags
    : { hasBackend, hasDatabase }
来自协调器的输入：
  • contextStore
    ：包含后端特定数据的上下文存储
    • API_TYPE（REST、GraphQL、gRPC）
    • API_ENDPOINTS（来自路由扫描）
    • AUTH_SCHEME（JWT、OAuth2、API keys）
    • DATABASE_TYPE（PostgreSQL、MongoDB、MySQL）
    • SCHEMA_OVERVIEW（来自迁移/模型）
    • ER_DIAGRAM（从架构生成）
  • targetDir
    ：项目根目录
  • flags
    ：{ hasBackend, hasDatabase }

Documents Created (2, conditional)

生成的文档（2份，条件性生成）

FileConditionQuestionsAuto-Discovery
docs/project/api_spec.mdhasBackendQ39-Q40Medium
docs/project/database_schema.mdhasDatabaseQ41-Q42High
文件条件对应问题自动发现能力
docs/project/api_spec.mdhasBackendQ39-Q40中等
docs/project/database_schema.mdhasDatabaseQ41-Q42高

Workflow

工作流程

Phase 1: Check Conditions

阶段1：检查条件

  1. Parse flags from coordinator
  2. If 
    !hasBackend && !hasDatabase
    : return early with empty result
  3. Determine which documents to create
  1. 解析协调器提供的flags
  2. 如果
    !hasBackend && !hasDatabase
    ：提前返回空结果
  3. 确定需要生成哪些文档

Phase 2: Create Documents

阶段2：生成文档

For each applicable document:
  1. Check if file exists (idempotent)
  2. If exists: skip with log
  3. If not exists:
    • Copy template
    • Replace placeholders with Context Store values
    • Generate ER diagram for database_schema.md
    • Mark 
      [TBD: X]
      for missing data
对于每个需要生成的文档：
  1. 检查文件是否已存在（幂等性）
  2. 如果已存在：记录日志并跳过
  3. 如果不存在：
    • 复制模板
    • 用Context Store中的值替换占位符
    • 为database_schema.md生成ER图
    • 为缺失的数据标记
      [TBD: X]

Phase 3: Self-Validate

阶段3：自我验证

  1. Check SCOPE tag
  2. Validate format:
    • api_spec.md: endpoint table, request/response examples
    • database_schema.md: ER diagram, table definitions
  3. Check Maintenance section
  1. 检查SCOPE标签
  2. 验证格式：
    • api_spec.md：包含端点表格、请求/响应示例
    • database_schema.md：包含ER图、表定义
  3. 检查维护部分

Phase 4: Return Status

阶段4：返回状态

json
{
  "created": ["docs/project/api_spec.md"],
  "skipped": ["docs/project/database_schema.md"],
  "tbd_count": 2,
  "validation": "OK"
}
json
{
  "created": ["docs/project/api_spec.md"],
  "skipped": ["docs/project/database_schema.md"],
  "tbd_count": 2,
  "validation": "OK"
}

Critical Notes

重要说明

  • Conditional: Skip entirely if no backend/database detected
  • OpenAPI compliant: api_spec.md follows OpenAPI 3.0 structure
  • ER diagrams: Generated in Mermaid erDiagram format
  • Idempotent: Never overwrite existing files
  • 条件性： 如果未检测到后端或数据库，则完全跳过
  • 符合OpenAPI规范： api_spec.md遵循OpenAPI 3.0结构
  • ER图： 以Mermaid erDiagram格式生成
  • 幂等性： 绝不会覆盖现有文件

NO_CODE_EXAMPLES Rule (MANDATORY)

禁止代码示例规则（强制性）

API spec documents contracts, NOT implementations:
  • ALLOWED in api_spec.md: JSON request/response schemas (this IS the API contract), endpoint tables
  • FORBIDDEN: Controller implementations, validation classes, service code, middleware examples
  • TEMPLATE RULE: api_spec_template.md includes 
    <!-- NO_CODE_EXAMPLES: ... -->
    tag - FOLLOW IT
API文档定义契约，而非实现：
  • api_spec.md中允许的内容： JSON请求/响应架构（这属于API契约）、端点表格
  • 禁止的内容： 控制器实现、验证类、服务代码、中间件示例
  • 模板规则： api_spec_template.md包含
    <!-- NO_CODE_EXAMPLES: ... -->
    标签——必须遵守

Stack Adaptation Rule (MANDATORY)

适配技术栈规则（强制性）

  • Links must reference stack-appropriate docs (Microsoft for .NET, MDN for JS)
  • API examples must match project stack (Express for Node.js, FastAPI for Python)
  • 链接必须指向与技术栈匹配的文档（.NET对应Microsoft文档，JS对应MDN）
  • API示例必须匹配项目技术栈（Node.js对应Express，Python对应FastAPI）

Format Priority (MANDATORY)

格式优先级规则（强制性）

Tables (endpoints, schemas) > Mermaid (ER diagrams) > Lists > Text
表格（端点、架构）> Mermaid（ER图）> 列表 > 文本

Definition of Done

完成标准

  • Conditions checked (hasBackend, hasDatabase)
  • Applicable documents created
  • ER diagram generated (if database_schema.md created)
  • Self-validation passed
  • Status returned to coordinator
  • 已检查条件（hasBackend、hasDatabase）
  • 已生成适用的文档
  • 已生成ER图（如果生成了database_schema.md）
  • 已通过自我验证
  • 已向协调器返回状态

Reference Files

参考文件

  • Templates: 
    references/templates/api_spec_template.md
    , 
    database_schema_template.md
  • Questions: 
    references/questions_backend.md
    (Q39-Q42)
Version: 1.2.0 (Added Stack Adaptation and Format Priority rules) Last Updated: 2025-01-12
  • 模板：
    references/templates/api_spec_template.md
    、
    database_schema_template.md
  • 问题：
    references/questions_backend.md
    （Q39-Q42）
版本： 1.2.0（新增技术栈适配和格式优先级规则） 最后更新： 2025-01-12