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份，条件性生成）

File	Condition	Questions	Auto-Discovery
docs/project/api_spec.md	hasBackend	Q39-Q40	Medium
docs/project/database_schema.md	hasDatabase	Q41-Q42	High

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

Workflow

工作流程

Phase 1: Check Conditions

阶段1：检查条件

Parse flags from coordinator
If
```
!hasBackend && !hasDatabase
```
: return early with empty result
Determine which documents to create

解析协调器提供的flags
如果
```
!hasBackend && !hasDatabase
```
：提前返回空结果
确定需要生成哪些文档

Phase 2: Create Documents

阶段2：生成文档

For each applicable document:

Check if file exists (idempotent)
If exists: skip with log
If not exists:
- Copy template
- Replace placeholders with Context Store values
- Generate ER diagram for database_schema.md
- Mark
```
[TBD: X]
```
  for missing data

对于每个需要生成的文档：

检查文件是否已存在（幂等性）
如果已存在：记录日志并跳过
如果不存在：
- 复制模板
- 用Context Store中的值替换占位符
- 为database_schema.md生成ER图
- 为缺失的数据标记
```
[TBD: X]
```

Phase 3: Self-Validate

阶段3：自我验证

Check SCOPE tag
Validate format:
- api_spec.md: endpoint table, request/response examples
- database_schema.md: ER diagram, table definitions
Check Maintenance section

检查SCOPE标签
验证格式：
- api_spec.md：包含端点表格、请求/响应示例
- database_schema.md：包含ER图、表定义
检查维护部分

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
```

```
tag - FOLLOW IT

API文档定义契约，而非实现：

api_spec.md中允许的内容： JSON请求/响应架构（这属于API契约）、端点表格
禁止的内容： 控制器实现、验证类、服务代码、中间件示例
模板规则： api_spec_template.md包含
```

```
标签——必须遵守

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