# hubmodule

集中定义和实现 Any-Hub 的“代理 + 缓存”模块体系。

## 目录结构

```
internal/hubmodule/
├── doc.go            # 包级说明与约束
├── README.md         # 本文件
├── registry.go       # 模块注册/发现入口（后续任务）
└── <module-key>/     # 各仓类型模块，例如 legacy、npm、docker
```

## 模块约束
- **单一接口**：每个模块需要同时实现代理与缓存接口，避免跨包耦合。
- **注册流程**：在模块 `init()` 中调用 `hubmodule.Register(ModuleMetadata{...})`，注册失败必须 panic 以阻止启动。
- **缓存布局**：一律使用 `StoragePath/<Hub>/<path>`，即与上游请求完全一致的磁盘路径；当某个路径既要保存正文又要作为子目录父节点时，会在该目录下写入 `__content` 文件以存放正文。
- **配置注入**：模块仅通过依赖注入获取 `HubConfigEntry` 和全局参数，禁止直接读取文件或环境变量。
- **可观测性**：所有模块必须输出 `module_key`、命中/回源状态等日志字段，并在返回错误时附带 Hub 名称。

## 开发流程
1. 复制 `internal/hubmodule/template/`（由 T010 提供）作为起点。
2. 填写模块特有逻辑与缓存策略，并确保包含中文注释解释设计。
3. 在模块目录添加 `module_test.go`，使用 `httptest.Server` 与 `t.TempDir()` 复现真实流量。
4. 运行 `make modules-test` 验证模块单元测试。
5. 更新 `config.toml` 中对应 `[[Hub]].Module` 字段，验证集成测试后再提交。

## 术语
- **Module Key**：模块唯一标识（如 `legacy`、`npm-tarball`）。
- **Cache Strategy Profile**：定义 TTL、验证策略、磁盘布局等策略元数据。
- **Legacy Adapter**：包装当前共享实现，确保迁移期间仍可运行。