create-oo-component-documentation

生成标准面向对象组件文档

为以下位置的面向对象组件创建全面的文档：${input:ComponentPath}。

通过检查所提供路径中的代码来分析组件。如果是文件夹，则分析所有源文件。如果是单个文件，则将其视为主要组件，并分析同一目录中的相关文件。

文档标准

• DOC-001：遵循 C4 模型文档层级（上下文、容器、组件、代码）
• DOC-002：与 Arc42 软件架构文档模板保持一致
• DOC-003：符合 IEEE 1016 软件设计描述标准
• DOC-004：采用敏捷文档原则（仅保留足以创造价值的文档）
• DOC-005：以开发人员和维护人员作为主要受众

分析说明

• ANA-001：确定路径类型（文件夹还是单个文件）并识别主要组件
• ANA-002：检查源代码文件以了解类结构和继承关系
• ANA-003：识别设计模式和架构决策
• ANA-004：记录公共 API、接口和依赖项
• ANA-005：识别创建型/结构型/行为型模式
• ANA-006：记录方法参数、返回值和异常
• ANA-007：评估性能、安全性、可靠性和可维护性
• ANA-008：推断集成模式和数据流

语言特定优化

• LNG-001：C#/.NET - async/await、依赖注入、配置、释放
• LNG-002：Java - Spring 框架、注解、异常处理、打包
• LNG-003：TypeScript/JavaScript - 模块、异步模式、类型、npm
• LNG-004：Python - 包、虚拟环境、类型提示、测试

错误处理

• ERR-001：路径不存在 - 提供正确的格式指引
• ERR-002：未找到源文件 - 建议替代位置
• ERR-003：结构不清晰 - 记录发现结果并请求澄清
• ERR-004：非标准模式 - 记录自定义方法
• ERR-005：代码不足 - 聚焦可用信息，并突出缺口

输出格式

生成结构良好的 Markdown，包含清晰的标题层级、代码块、表格、项目符号以及适当的格式，以提升可读性和可维护性。

文件位置

文档应保存到 /docs/components/ 目录中，并按照以下约定命名：[component-name]-documentation.md。

必需的文档结构

文档文件必须遵循以下模板，确保所有部分都得到适当填写。Markdown 的 front matter 应按照下方示例正确组织：

---
title: [Component Name] - Technical Documentation
component_path: `${input:ComponentPath}`
version: [Optional: e.g., 1.0, Date]
date_created: [YYYY-MM-DD]
last_updated: [Optional: YYYY-MM-DD]
owner: [Optional: Team/Individual responsible for this component]
tags: [Optional: List of relevant tags or categories, e.g., `component`,`service`,`tool`,`infrastructure`,`documentation`,`architecture` etc]
---

# [Component Name] Documentation

[A short concise introduction to the component and its purpose within the system.]

## 1. Component Overview

### Purpose/Responsibility
- OVR-001: State component's primary responsibility
- OVR-002: Define scope (included/excluded functionality)
- OVR-003: Describe system context and relationships

## 2. Architecture Section

- ARC-001: Document design patterns used (Repository, Factory, Observer, etc.)
- ARC-002: List internal and external dependencies with purposes
- ARC-003: Document component interactions and relationships
- ARC-004: Include visual diagrams (UML class, sequence, component)
- ARC-005: Create mermaid diagram showing component structure, relationships, and dependencies

### Component Structure and Dependencies Diagram

Include a comprehensive mermaid diagram that shows:
- **Component structure** - Main classes, interfaces, and their relationships
- **Internal dependencies** - How components interact within the system
- **External dependencies** - External libraries, services, databases, APIs
- **Data flow** - Direction of dependencies and interactions
- **Inheritance/composition** - Class hierarchies and composition relationships

```mermaid
graph TD
    subgraph "Component System"
        A[Main Component] --> B[Internal Service]
        A --> C[Internal Repository]
        B --> D[Business Logic]
        C --> E[Data Access Layer]
    end

    subgraph "External Dependencies"
        F[External API]
        G[Database]
        H[Third-party Library]
        I[Configuration Service]
    end

    A --> F
    E --> G
    B --> H
    A --> I

    classDiagram
        class MainComponent {
            +property: Type
            +method(): ReturnType
            +asyncMethod(): Promise~Type~
        }
        class InternalService {
            +businessOperation(): Result
        }
        class ExternalAPI {
            <<external>>
            +apiCall(): Data
        }

        MainComponent --> InternalService
        MainComponent --> ExternalAPI

3. 接口文档

• INT-001：记录所有公共接口和使用模式
• INT-002：创建方法/属性参考表
• INT-003：记录事件/回调/通知机制

方法/属性	用途	参数	返回类型	使用说明
[名称]	[用途]	[参数]	[类型]	[说明]

4. 实现细节

• IMP-001：记录主要实现类及其职责
• IMP-002：描述配置要求和初始化
• IMP-003：记录关键算法和业务逻辑
• IMP-004：注明性能特征和瓶颈

5. 使用示例

基本用法

// Basic usage example
var component = new ComponentName();
component.DoSomething();

高级用法

// Advanced configuration patterns
var options = new ComponentOptions();
var component = ComponentFactory.Create(options);
await component.ProcessAsync(data);

• USE-001：提供基本用法示例
• USE-002：展示高级配置模式
• USE-003：记录最佳实践和推荐模式

6. 质量属性

• QUA-001：安全性（身份验证、授权、数据保护）
• QUA-002：性能（特征、可扩展性、资源使用）
• QUA-003：可靠性（错误处理、容错、恢复）
• QUA-004：可维护性（标准、测试、文档）
• QUA-005：可扩展性（扩展点、自定义选项）

7. 参考信息

• REF-001：列出依赖项及其版本和用途
• REF-002：完整的配置选项参考
• REF-003：测试指南和 mock 设置
• REF-004：故障排查（常见问题、错误消息）
• REF-005：相关文档链接
• REF-006：变更历史和迁移说明