sub2api/issues/plugin-refactor/phase-1_plugin-kernel/PHASE_SUMMARY.md

# 阶段总结报告: Phase-1 插件内核（Plugin Kernel）

- **阶段状态**: Completed
- **完成时间**: 2026-06-11
- **关联阶段计划**: [链接](../../../.claude/plugin-refactor/phases/phase-1_plugin-kernel/PHASE_PLAN.md)

## 1. 阶段目标达成情况（对照 PHASE_PLAN §3）

1. ✅ 内核接口按契约实现（签名与 ROADMAP 架构树逐项核对一致），单测覆盖硬性清单全部条目（含 Start 半途失败逆序回滚、Stop ctx deadline 专测，-race 全绿）；
2. ✅ **零行为变更**：默认配置下 Phase-0 安全网 42 包全绿；`bench-baseline.sh compare` 7 个基准 allocs/op 完全一致、ns/op 全在噪声内；
3. ✅ wire v0.7.0 工具生成且复跑字节级一致；启动/优雅关闭含模块阶段日志（runtime.Stop 在 cleanup 并行组首位、先于 Redis/Ent）；
4. ✅ `GET /api/v1/admin/modules` 可列出全部模块与状态；job.hello 启用后全生命周期测试通过、禁用后零副作用；
5. ✅ 《模块作者指南》入库（含 .gitignore 白名单放行）；CLAUDE.md 更新（Ent 修正 + 插件开发小节 + 结构树）。

## 2. 任务完成统计

| 任务ID | 任务描述 | 状态 | 完成报告 |
|:--|:--|:--|:--|
| TASK-001 | 内核包：module/registry | Completed | [链接](./TASK-001_kernel_registry.md) |
| TASK-002 | Host/配置子树/Runtime | Completed | [链接](./TASK-002_host_runtime_config.md) |
| TASK-003 | Wire/启动接入 + 插装清单 + hello | Completed | [链接](./TASK-003_wire_bootstrap.md) |
| TASK-004 | Admin 模块可观测 API | Completed | [链接](./TASK-004_admin_modules_api.md) |
| TASK-005 | 作者指南 + CLAUDE.md | Completed | [链接](./TASK-005_author_guide_docs.md) |

**总计**: 5 个任务全部完成。新增 `internal/plugin/`（5 文件内核 + 4 文件单测）、`internal/modules/`（standard 插装清单 + hello 示例）、admin handler、作者指南；对现有代码改动极小且全部纯增量（config.go +41、main.go +10、wire.go +20、handler/routes 各数行、wire_gen.go 工具生成）。

## 3. 关键技术成果

- **Caddy 式进程内插件内核就位**：命名空间注册表（init() 注册 + panic 校验）、四段可选生命周期、Host ports 能力面、`modules:` 配置子树（enabled 三态）、Runtime 状态机（含逆序回滚/逆序关闭）、唯一插装清单 `modules/standard/imports.go`；
- 新增一个模块 = 新建模块包 + 插装清单加一行 import，核心零改动——Phase-2/3 的迁移底座已通电。

## 4. 遇到的问题与解决方案

- **viper 含点 key 拆层坑**：`viper.Unmarshal` 把 `modules.job.hello` 错拆两级 → Modules 字段 `mapstructure:"-"` + `viper.Get("modules")` 手工提取 + 形状校验；
- **规格与内核语义冲突**（未知模块 ID 处理）：架构师裁定以内核为准（格式非法 fail-fast / 合法未注册忽略），规格文件已加注裁定记录；
- **交付物被 .gitignore 忽略**：按现有白名单模式补 `!docs/plugin-architecture/`。

## 5. 技术债务与待优化项

- `make generate` 的无版本号 wire 调用因 go.sum 缺 `github.com/google/subcommands` 失败（**预存在**，与本阶段改动无关）：建议主线单独 PR `go get github.com/google/wire/cmd/wire@v0.7.0` 或 Makefile 改带版本调用；
- modules 子树暂不支持环境变量逐键覆盖（viper AutomaticEnv 限制），需要时后续补充；
- CLAUDE.md 既有过时描述（`service/ports/` 目录、`make wire` 目标）与 usage_log.go 残留 gorm tag，留待后续梳理；
- golangci-lint 在 WSL /mnt 盘超时，以 CI lint job 为最终判定。

## 6. 经验总结与建议

- "接口契约写进 PHASE_PLAN + 实施自由度留给工程师"运转良好：三个实施代理的裁量决定（EnabledByDefault 字段、独立 context、ProviderSet 拆分）都在契约内且有理有据；
- 每任务"主控复跑门禁"的双重验证流程两次发现了值得归档的信息（错误体路径差异、gitignore 问题），建议 Phase-2 保持。

## 7. 下一阶段准备

- Phase-2（试点迁移：payment.provider + moderation 钩子）就绪，待规划任务清单（按渐进式规划原则，PHASE_PLAN 在阶段启动时细化）；
- **当前全部改动尚未 git commit**——建议先按"PR 粒度规划"提交：①Phase-0 安全网（测试+脚本+CI+Makefile）②Phase-1 内核与接入（plugin/modules/wire/main/config）③文档（指南+CLAUDE.md+gitignore），三个独立可 revert 的提交/PR。