# Maintenance Debug Guide Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 建立可持续维护的日常排障文档，记录本次端口与 Python CA 证书故障。

**Architecture:** `docs/troubleshooting.md` 保存完整故障记录；`README.md` 和 `docs/technical-guide.md` 仅提供入口与同步维护要求。运行态只保留当前项目的 8080 服务。

**Tech Stack:** Markdown、Git、macOS/Linux 常用诊断命令

---

### Task 1: 新增排障记录

**Files:**
- Create: `docs/troubleshooting.md`

- [ ] 记录故障现象、根因链路、诊断命令、恢复步骤和预防措施。
- [ ] 明确接口、端口、Python 环境或部署方式变化时同步更新本文档。

### Task 2: 增加文档入口

**Files:**
- Modify: `README.md`
- Modify: `docs/technical-guide.md`

- [ ] 在 README 项目结构中加入排障文档。
- [ ] 在技术指南中增加日常维护与排障入口及维护约束。

### Task 3: 验证并合并

**Files:**
- Verify: `docs/troubleshooting.md`
- Verify: `README.md`
- Verify: `docs/technical-guide.md`

- [ ] 检查文档链接与 Markdown 格式。
- [ ] 确认 8770 已关闭，8080 页面和状态接口返回 200。
- [ ] 提交专门分支，并使用 `git merge --no-ff` 合并到 `dev`。