---

description: "Tasks for Hub 配置凭证字段"
---

# Tasks: Hub 配置凭证字段

**Input**: Design documents from `/specs/003-hub-auth-fields/`
**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/

**Tests**: 宪法 v1.0.0 要求覆盖配置解析、缓存读写、代理命中/回源与 Host Header 绑定，此清单在相关阶段加入对应测试任务。

**Organization**: Tasks are grouped by user story以支持独立实施与验证。

## Format: `[ID] [P?] [Story] Description`

- **[P]**: 可并行执行（触达不同文件/无直接依赖）
- **[Story]**: 指明所属用户故事（Setup/Foundational/Polish 阶段不写）
- 描述中必须包含精确文件路径

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: 记录迁移策略、同步文档，让团队在单端口与凭证范围上达成一致。

- [X] T001 将全局 `ListenPort`/Hub 凭证迁移指南写入 `DEVELOPMENT.md` 与 `README.md`，提醒去除 `[[Hub]].Port`
- [X] T002 补充 `CHANGELOG.md` 与 `specs/003-hub-auth-fields/quickstart.md` 的前置说明，列出新的配置字段及基本验证命令

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: 改造配置与 server 启动流程，确保所有 Hub 共用单端口并具备新字段；完成前禁止进入任何用户故事。

- [X] T003 更新 `internal/config/types.go` / `internal/config/loader.go`，为 `GlobalConfig` 添加 `ListenPort`，为 `HubConfig` 添加 `Username`/`Password`/`Type`，并删除 Hub 级 `Port`
- [X] T004 扩充 `internal/config/validation.go` 与 `internal/config/config_test.go`，覆盖 `ListenPort` 范围校验、Type 枚举校验及缺失 Type 报错
- [X] T005 重构 `cmd/any-hub/main.go` 与 `internal/server/router.go`，仅根据全局 `ListenPort` 启动 Fiber，并在加载阶段检测到 Hub 级 `Port` 时报告迁移错误
- [X] T006 [P] 更新 `internal/server/hub_registry.go` 及 `internal/server/hub_registry_test.go`，让 Host Registry 仅依赖 Host/Host:port 组合，去除对 per-Hub 端口的引用
- [X] T007 [P] 调整 `configs/config.example.toml`、`configs/docker.sample.toml`、`configs/npm.sample.toml`，移除 Hub 端口字段并添加 `ListenPort`/`Type` 示例

**Checkpoint**: 单端口 + 新字段的配置/路由路径已可运行，各用户故事可并行推进。

---

## Phase 3: User Story 1 - 配置上游凭证 (Priority: P1) 🎯 MVP

**Goal**: Hub 可配置上游凭证，CLI 回源时自动附带 Authorization，日志只输出掩码。

**Independent Test**: 使用带凭证的 `config.toml` 运行 `any-hub --check-config` 与 `go test ./tests/integration -run CredentialProxy`，无须下游凭证即可解除 rate-limit。

### Tests for User Story 1

- [X] T008 [P] [US1] 在 `tests/integration/credential_proxy_test.go` 构建带 Basic Auth 的 upstream stub，验证“无凭证失败→配置凭证成功”的流程

### Implementation for User Story 1

- [X] T009 [US1] 在 `internal/config/types.go` 与 `cmd/any-hub/main.go` 中保存可选凭证，并在所有 `logrus` 输出中仅显示掩码/存在性
- [X] T010 [US1] 修改 `internal/proxy/handler.go`，依据 Hub 凭证自动附加 Authorization header，并在 401/429 时执行一次受控重试与错误字段记录
- [X] T011 [US1] 更新 `README.md` 与 `quickstart.md`，新增凭证写法、敏感信息注意事项以及 `any-hub --check-config` 示例

**Checkpoint**: 代理可凭借配置凭证访问受限仓库，下游仍保持匿名体验。

---

## Phase 4: User Story 2 - 下游透明体验 (Priority: P1)

**Goal**: 确保下游无需配置凭证即可访问，日志/观测字段体现 `auth_mode`、`hub_type` 与上游结果。

**Independent Test**: 运行 `tests/integration/credential_proxy_test.go` 的匿名客户端用例，并以 `npm --registry http://127.0.0.1:<ListenPort>` 手动验证日志输出。

### Tests for User Story 2

- [X] T012 [P] [US2] 扩展 `tests/integration/credential_proxy_test.go`，加入“不带 Authorization 仍命中凭证”与日志字段断言

### Implementation for User Story 2

- [X] T013 [US2] 在 `internal/logging/fields.go` 与 `internal/proxy/handler.go` 中输出 `hub_type`、`auth_mode`、`upstream_status`，并确保缓存命中/回源路径均记录
- [X] T014 [US2] 在 `tests/integration/upstream_stub_test.go` 及 `quickstart.md` 中补充匿名客户端示例命令，指导如何验证透明代理

**Checkpoint**: 日志、quickstart 与匿名客户端流程可完整验证下游体验。

---

## Phase 5: User Story 3 - 仓库类型适配 (Priority: P2)

**Goal**: 强制声明 Hub `Type`（docker/npm/go），日志与运行期可识别类型，为未来扩展留接口。

**Independent Test**: 使用覆盖三种 Type 的配置运行 `any-hub --check-config` 与 `go test ./internal/config`，非法/缺失 Type 会被拒绝，日志中能看到正确的 `hub_type`。

### Tests for User Story 3

- [X] T015 [P] [US3] 在 `internal/config/config_test.go` 新增表驱动测试，覆盖合法 Type、非法 Type、缺失 Type 的报错/提示

### Implementation for User Story 3

- [X] T016 [US3] 在 `internal/proxy/handler.go` 与 `internal/server/router.go` 加入 `switch Type`，目前仅设置日志/标签，并对未支持类型抛出明确错误
- [X] T017 [US3] 更新 `quickstart.md` 及 `configs/*.sample.toml`，列出 Type 可选值与未来扩展策略

**Checkpoint**: Hub 类型被强制校验，日志和示例配置均反映正确值。

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: 统一测试、文档及残留引用，确保产物满足宪法门槛。

- [X] T018 [P] 运行 `gofmt ./cmd ./internal ./tests` 与 `GOCACHE=/tmp/go-build go test ./...`，并把命令写入 `DEVELOPMENT.md`
- [X] T019 清理 `DEVELOPMENT.md`、`README.md`、`specs/003-hub-auth-fields/plan.md` 中残留的 Hub 端口描述，确保只推荐全局 `ListenPort`
- [X] T020 在 `CHANGELOG.md` 与 `quickstart.md` 中记录演练结果（docker + npm），并附一次手动验证日志

---

## Dependencies & Execution Order

### Phase Dependencies

1. Setup → Foundational → 所有用户故事 → Polish
2. Foundational 完成前，任何用户故事不得启动。
3. US2 依赖 US1 产出的凭证注入，但可以在实现层并行。
4. US3 仅依赖 Foundational，可与 US1/US2 并行实施。

### User Story Dependencies

- US1 完成后，即可单独交付 MVP。
- US2 依赖 US1 的日志/凭证输出，但测试可提前编写。
- US3 与其他故事仅在配置层相互作用，无硬依赖。

### Parallel Opportunities

- T006 与 T007 可由不同成员分别处理（registry vs. 示例配置）。
- T008/T012/T015 测试任务都可在实现前准备并行执行。
- 不同用户故事的实现（T009- T017）可由独立小组并行推进。
- Polish 阶段 T018 与 T019/T020 可交由不同成员并行完成。

---

## Implementation Strategy

### MVP First (User Story 1)
1. 完成 Setup + Foundational，确认单端口与配置路径无误。
2. 实施 US1（凭证字段 + 代理注入）并通过集成测试。
3. 以此为最小可交付版本，供受限仓库使用。

### Incremental Delivery
1. Increment 1: Setup + Foundational + US1 → 解锁凭证代理。
2. Increment 2: US2 → 强化透明体验与观测性。
3. Increment 3: US3 → 引入 Type 校验及扩展思路。
4. Polish: 全量测试、文档与 quickstart 验证。

### Parallel Team Strategy
- Team A：负责 Foundational + US1。
- Team B：在 Foundational 完成后并行 US2（日志 + quickstart）。
- Team C：并行 US3（Type 校验与示例）。
- Polish 阶段由值班成员统一收尾。