@chongyan/autospec 1.0.1

package/knowledge/environment/component-knowledge.md

@@ -0,0 +1,316 @@
+# 组件知识模板
+
+> 本模板定义组件知识的标准格式。供 env-sync 生成知识文件时参考。
+
+---
+
+## 文件位置
+
+`.autospec/environment/component-lib/components/{name}/component.md`
+
+---
+
+## 基本信息
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| 名称 | 是 | 组件名称，如 auth、payment |
+| 类型 | 是 | 参见类型枚举 |
+| 版本 | 是 | 组件版本，如 v2.1.0 |
+| 维护者 | 否 | 维护团队或个人 |
+| 最后更新 | 否 | 更新日期 |
+
+### 类型枚举
+
+| 类型 | 说明 | 典型示例 |
+|------|------|---------|
+| service-component | 服务组件，封装外部服务调用 | 认证组件、支付网关 |
+| utility | 工具组件，提供通用功能 | 日志组件、配置组件 |
+| library | 库组件，封装业务逻辑 | 领域模型、数据访问层 |
+
+---
+
+## 功能描述
+
+简要描述组件的核心功能和用途。
+
+---
+
+## 接口定义
+
+| 方法名 | 说明 |
+|--------|------|
+| {method1} | 方法说明 |
+| {method2} | 方法说明 |
+
+### 方法详情
+
+#### {method1}
+
+**输入参数**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| param1 | string | 是 | 参数说明 |
+| param2 | number | 否 | 参数说明 |
+
+**输出参数**
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| result | any | 返回结果 |
+
+**错误码**
+
+| 错误码 | 说明 |
+|--------|------|
+| ERROR_CODE_1 | 错误描述 |
+| ERROR_CODE_2 | 错误描述 |
+
+---
+
+## 使用示例
+
+按语言分节，提供安装命令和代码示例。
+
+### Node.js
+
+**安装**
+
+```bash
+npm install @org/component-name
+```
+
+**使用**
+
+```javascript
+import { Component } from '@org/component-name';
+
+const component = new Component({
+  endpoint: process.env.COMPONENT_ENDPOINT,
+  timeout: 30000
+});
+
+// 调用方法
+const result = await component.method1(param1, param2);
+```
+
+### Python
+
+**安装**
+
+```bash
+pip install org-component
+```
+
+**使用**
+
+```python
+from org_component import Component
+
+component = Component(
+    endpoint=os.environ['COMPONENT_ENDPOINT'],
+    timeout=30000
+)
+
+# 调用方法
+result = component.method1(param1, param2)
+```
+
+---
+
+## 配置项
+
+### 必需配置
+
+| 配置项 | 说明 |
+|--------|------|
+| CONFIG_ENDPOINT | 服务地址 |
+| CONFIG_API_KEY | API密钥 |
+
+### 可选配置
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| CONFIG_TIMEOUT | 30 | 超时时间(秒) |
+| CONFIG_RETRY | 3 | 重试次数 |
+
+---
+
+## 环境差异配置
+
+| 环境 | 配置项 | 值 |
+|------|--------|-----|
+| development | CONFIG_ENDPOINT | http://dev.example.com |
+| staging | CONFIG_ENDPOINT | http://staging.example.com |
+| production | CONFIG_ENDPOINT | http://api.example.com |
+
+---
+
+## 使用检查清单
+
+### 使用前检查
+
+- [ ] 确认依赖服务已部署且可访问
+- [ ] 确认必需环境变量已配置
+- [ ] 确认应用已注册到服务
+
+### 使用后检查
+
+- [ ] 验证核心功能正常
+- [ ] 验证错误处理正确
+- [ ] 验证日志记录完整
+
+---
+
+## 最佳实践
+
+1. 使用前检查服务可用性
+2. 实现完善的错误处理
+3. 记录关键操作日志
+4. 设置合理的超时时间
+
+---
+
+## 反模式清单
+
+| 反模式 | 风险 | 替代方案 |
+|--------|------|----------|
+| 硬编码服务地址 | 环境切换困难 | 使用环境变量 |
+| 忽略错误处理 | 系统不稳定 | 实现完善的错误处理 |
+| 不设置超时 | 请求阻塞 | 设置合理的超时时间 |
+
+---
+
+## 示例：认证组件知识
+
+```markdown
+# 认证组件知识
+
+## 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 名称 | auth |
+| 类型 | service-component |
+| 版本 | v2.1.0 |
+| 维护者 | platform-team |
+
+## 功能描述
+
+统一认证组件，支持 JWT Token、OAuth2.0、Session 等多种认证方式。
+提供用户登录、登出、Token 刷新、权限校验等核心功能。
+
+## 接口定义
+
+| 方法名 | 说明 |
+|--------|------|
+| login | 用户登录 |
+| validateToken | 验证Token |
+| logout | 用户登出 |
+
+### 方法详情
+
+#### login
+
+**输入参数**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| username | string | 是 | 用户名 |
+| password | string | 是 | 密码 |
+
+**输出参数**
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| token | string | Token（成功时） |
+| errorCode | string | 错误码（失败时） |
+
+**错误码**
+
+| 错误码 | 说明 |
+|--------|------|
+| AUTH_FAILED | 用户名或密码错误 |
+| ACCOUNT_LOCKED | 账户已被锁定 |
+
+## 使用示例
+
+### Node.js
+
+**安装**
+
+```bash
+npm install @acme/auth-client
+```
+
+**使用**
+
+```javascript
+import { AuthClient } from '@acme/auth-client';
+
+const authClient = new AuthClient({
+  endpoint: process.env.AUTH_SERVICE_ENDPOINT,
+  redisUrl: process.env.REDIS_URL
+});
+
+// 登录
+const result = await authClient.login(username, password);
+
+// 验证Token
+const user = await authClient.validateToken(token);
+
+// 登出
+await authClient.logout(token);
+```
+
+## 配置项
+
+### 必需配置
+
+| 配置项 | 说明 |
+|--------|------|
+| AUTH_SERVICE_ENDPOINT | 认证服务地址 |
+| REDIS_URL | Redis连接地址 |
+
+### 可选配置
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| AUTH_TOKEN_EXPIRY | 3600 | Token过期时间(秒) |
+| AUTH_MAX_RETRY | 3 | 最大重试次数 |
+
+## 使用检查清单
+
+### 使用前检查
+
+- [ ] 确认Redis已部署且可访问
+- [ ] 确认AUTH_SERVICE_ENDPOINT环境变量已配置
+- [ ] 确认应用已注册到认证服务
+
+### 使用后检查
+
+- [ ] 验证登录流程正常
+- [ ] 验证Token刷新机制
+- [ ] 验证权限校验正确
+```
+
+---
+
+## 自检清单
+
+生成组件知识文件后，检查以下项目：
+
+- [ ] 基本信息章节完整，包含名称、类型、版本
+- [ ] 功能描述清晰
+- [ ] 接口定义包含方法名和参数说明
+- [ ] 使用示例包含安装命令和代码
+- [ ] 配置项包含必需和可选配置
+- [ ] 使用检查清单完整
+
+---
+
+**维护者**: AutoSpec 团队
+**进化分区**: 🟡 受控区
+**关联文档**: `knowledge/environment/template-registry.md`