init

specs/002-fiber-single-proxy/plan.md

@@ -0,0 +1,69 @@
+# Implementation Plan: HTTP 服务与单仓代理
+
+**Branch**: `002-fiber-single-proxy` | **Date**: 2025-11-13 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/002-fiber-single-proxy/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+Deliver a Phase 1-ready proxy: Fiber HTTP server routing by Host→Hub, disk cache with TTL + conditional revalidation, and runnable Docker/NPM samples backed by integration tests. Core work spans server/router scaffolding, cache/proxy pipeline, observability, and documentation to prove the feature end to end.
+
+## Technical Context
+
+**Language/Version**: Go 1.25+ (静态链接，单二进制交付)  
+**Primary Dependencies**: Fiber v3（HTTP 服务）、Viper（配置）、Logrus + Lumberjack（结构化日志 & 滚动）、标准库 `net/http`/`io`  
+**Storage**: 本地文件系统缓存目录 `StoragePath/<Hub>/<path>` + `.meta` 元数据  
+**Testing**: `go test ./...`，配合 `httptest`、fake upstream server、临时目录验证路由/缓存/集成路径  
+**Target Platform**: Linux/Unix CLI 进程，由 systemd/supervisor 管理，匿名下游客户端  
+**Project Type**: 单 Go 项目（`cmd/` 入口 + `internal/*` 包）  
+**Performance Goals**: 缓存命中路径需低延迟（相对首个请求减少 ≥70%），回源路径流式传输并限制常驻内存 <256MB，日志可追踪命中/回源/错误  
+**Constraints**: 禁止 Web/UI、账号体系、额外配置源；必须通过 `config.toml` 驱动 Host、端口、缓存策略；请求匿名；不可新增未审核依赖  
+**Scale/Scope**: Phase 1 仅实现单 Hub 路由 + Docker/NPM 示例；后续多 Hub、多协议将基于此扩展
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- 方案遵守“轻量 CLI 代理”定位，不引入 UI/账号/外部控制面。
+- 继续使用 Go + Fiber/Viper/Logrus/Lumberjack + 标准库，Helm/DB/Web 依赖均不在 scope。
+- 仅依赖 `config.toml` 说明 Host/端口/缓存字段；新增字段需写入配置 schema 与文档。
+- 缓存策略保持“命中即返回、未命中流式回源”，并要求结构化日志记录 `cache_hit`、上游状态等字段。
+- 计划包含配置解析、Host Header 路由、缓存逻辑、示例及测试，满足宪法强制测试/文档 Gate。
+
+**Post-design re-check (Phase 1)**: 设计阶段将审查 server/cache/示例文档，确认未引入新依赖且 quickstart/contract 体现在 spec/plan/task 中；若出现额外库或多配置源，需重新申请豁免。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-fiber-single-proxy/
+├── plan.md              # 当前文件
+├── research.md          # Phase 0 研究决策
+├── data-model.md        # 实体/关系/约束
+├── quickstart.md        # 演练 Docker/NPM 示例步骤
+├── contracts/           # CLI/Fiber/缓存交付合同（md 或 OpenAPI）
+└── tasks.md             # Phase 2 工作拆解（/speckit.tasks 输出）
+```
+
+### Source Code (repository root)
+```text
+cmd/any-hub/             # CLI 入口，启动 server/cache
+internal/server/         # Fiber app、Host Registry、路由/中间件
+internal/cache/          # 磁盘缓存/元数据/TTL
+internal/proxy/          # 回源/条件请求/流式复制
+internal/logging/        # 结构化日志字段
+configs/                 # 示例 config (docker|npm)
+tests/integration/       # upstream stub + e2e 测试
+```
+
+**Structure Decision**: 仍按单仓库单二进制；新增 `internal/server`, `internal/cache`, `tests/integration` 目录必须保持与 `internal/proxy` 清晰边界，所有引用通过包级接口注入，避免循环依赖。
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| _None_ | — | — |