ln-113-backend-docs-creator

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

后端文档创建器

类型： L3 Worker

创建 2 个后端文档文件的 L3 Worker。有条件调用——仅在项目有后端或数据库时调用。

目的与范围

• 创建 api_spec.md（如果有后端）
• 创建 database_schema.md（如果有数据库）
• 接收来自 ln-110-project-docs-coordinator 的 Context Store
• 符合 OpenAPI 3.0 的 API 规范
• 使用 Mermaid 为数据库架构绘制 ER 图
• 从不自行收集上下文；使用协调器提供的输入

调用方式（谁／何时）

• ln-110-project-docs-coordinator： 在以下情况下有条件调用：
  • 检测到 hasBackend=true（express、fastify、nestjs、fastapi）
  • 检测到 hasDatabase=true（pg、mongoose、prisma、sequelize）
• 从不由用户直接调用

输入

来自协调器：

• contextStore：包含后端专属数据的 Context Store
  • API_TYPE（REST、GraphQL、gRPC）
  • API_ENDPOINTS（来自路由扫描）
  • AUTH_SCHEME（JWT、OAuth2、API 密钥）
  • DATABASE_TYPE（PostgreSQL、MongoDB、MySQL）
  • SCHEMA_OVERVIEW（来自迁移文件／模型）
  • ER_DIAGRAM（根据架构生成）
• targetDir：项目根目录
• flags：{ hasBackend, hasDatabase }

必须读取： 加载 references/docs_quality_contract.md 和 references/markdown_read_protocol.md。 可选规则目录：仅在需要精确规则 ID、路径矩阵或允许使用的占位符例外时，加载 references/docs_quality_rules.json。

创建的文档（2 个，有条件）

文件	条件	问题	自动发现
docs/project/api_spec.md	hasBackend	Q39-Q40	中
docs/project/database_schema.md	hasDatabase	Q41-Q42	高

工作流

阶段 1：检查条件

1. 解析协调器提供的 flags
2. 如果 !hasBackend && !hasDatabase：提前返回空结果
3. 确定要创建哪些文档

阶段 2：创建文档

针对每个适用的文档：

1. 检查文件是否存在（幂等）
2. 如果存在：记录日志后跳过
3. 如果不存在：
   • 复制模板
   • 使用 Context Store 中的值替换占位符
   • 保留模板中的共享开篇约定和标准顶部章节
   • 为 database_schema.md 生成 ER 图
   • 发布的后端文档中不得残留模板标记
   • 如果缺少数据：省略相关声明，或使用简洁、中性的替代文本，但不得输出 [TBD: ...]

阶段 3：自我验证

1. 检查 SCOPE 标签和元数据标记
2. 检查必需的顶部章节（Quick Navigation、Agent Entry、Maintenance）
3. 验证格式：
   • api_spec.md：端点表、请求／响应示例
   • database_schema.md：ER 图、表定义
4. 检查是否符合 docs-quality 约定（不含禁止使用的占位符、不泄露模板元数据、文档类型／角色有效）

阶段 4：返回状态

{
  "created_files": ["docs/project/api_spec.md"],
  "skipped_files": ["docs/project/database_schema.md"],
  "quality_inputs": {
    "doc_paths": ["docs/project/api_spec.md", "docs/project/database_schema.md"],
    "owners": {
      "docs/project/api_spec.md": "ln-113-backend-docs-creator",
      "docs/project/database_schema.md": "ln-113-backend-docs-creator"
    }
  },
  "validation_status": "passed"
}

重要说明

• 有条件调用： 未检测到后端／数据库时，完全跳过
• 符合 OpenAPI： api_spec.md 遵循 OpenAPI 3.0 结构
• ER 图： 使用 Mermaid erDiagram 格式生成
• 幂等： 从不覆盖现有文件
• 可发布的输出： 后端文档中不得包含 [TBD: ...]、TODO 或泄露的模板元数据

NO_CODE_EXAMPLES 规则（必须遵守）

API 规范文档描述的是契约，而非实现：

• api_spec.md 中允许： JSON 请求／响应架构（这就是 API 契约）、端点表
• 禁止： 控制器实现、验证类、服务代码、中间件示例
• 模板规则： api_spec_template.md 包含 `` 标签——请遵循

技术栈适配规则（必须遵守）

• 链接必须引用适合相应技术栈的文档（.NET 使用 Microsoft，JS 使用 MDN）
• API 示例必须符合项目技术栈（Node.js 使用 Express，Python 使用 FastAPI）

格式优先级（必须遵守）

表格（端点、架构）> Mermaid（ER 图）> 列表 > 文本

运行时摘要工件

必须阅读： 加载 references/docs_generation_summary_contract.md

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的载荷语义：

• worker = "ln-113"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

将摘要写入提供的工件路径，或在结构化输出中返回相同的封装。

完成定义

• 已检查条件（hasBackend、hasDatabase）
• 已创建适用的文档
• 已生成 ER 图（如果创建了 database_schema.md）
• 自我验证已通过（元数据标记、顶部章节、格式）
• 已验证时效性： 所有文档事实均与当前代码一致（路径、函数、API、配置均存在且准确）
• 已返回状态

参考文件

• 模板：references/templates/api_spec_template.md、references/templates/database_schema_template.md
• 问题：references/questions_backend.md（Q39-Q42）

---

版本： 1.2.0 最后更新： 2025-01-12