chore: 整理 Docker 启动与部署配置

docs/Deployment.md

@@ -0,0 +1,100 @@
+# Docker 启动与部署说明
+
+## 固定入口
+
+本项目固定使用 Docker Compose 项目名 `hot-comments-tool`，服务入口固定为：
+
+```bash
+http://localhost:8000
+```
+
+启动或重建：
+
+```bash
+docker compose up -d --build
+curl -f http://localhost:8000/health
+```
+
+查看容器：
+
+```bash
+docker compose ps
+```
+
+正常情况下只需要看到一个应用容器：`hot-comments-tool-app-1`。
+
+## 端口占用排查
+
+如果 `8000` 被占用，先确认是不是本项目容器：
+
+```bash
+lsof -nP -iTCP:8000 -sTCP:LISTEN
+docker compose ps
+```
+
+如果是旧的同项目容器，执行：
+
+```bash
+docker compose down
+docker compose up -d --build
+```
+
+不要临时改到 `8001`，否则浏览器验收和文档记录会混乱。
+
+## 环境变量
+
+Docker Compose 读取 `.env`，不要把真实 `.env` 提交到 Git。
+
+首次启动前可以从示例文件复制：
+
+```bash
+cp .env.example .env
+```
+
+必须配置：
+
+```text
+TIKHUB_API_KEY=
+AI_BASE_URL=
+AI_API_KEY=
+AI_MODEL=
+```
+
+## 数据目录
+
+SQLite 数据固定挂载整个目录：
+
+```yaml
+./data:/app/data
+```
+
+不要只挂载单个 `app.db` 文件。SQLite WAL 模式会生成：
+
+```text
+data/app.db
+data/app.db-wal
+data/app.db-shm
+```
+
+这三个文件必须在同一个挂载目录内。
+
+## 重置本地验收数据库
+
+仅在确认不需要保留历史任务后执行：
+
+```bash
+docker compose down
+rm -f data/app.db data/app.db-wal data/app.db-shm
+docker compose up -d --build
+curl -f http://localhost:8000/health
+```
+
+重置后历史任务会消失，首页任务列表会从空状态开始。
+
+## 验收命令
+
+```bash
+.venv/bin/python -m pytest tests/unit tests/integration -q
+docker compose up -d --build
+curl -f http://localhost:8000/health
+```

docs/MVP-WorkOrders.md

@@ -663,6 +663,24 @@ chore: 整理 Docker 启动与部署配置
 - 固定项目名和 8000 端口已完成。
 - 部署文档和数据清理流程仍待补充。
 
+完成记录：
+
+```text
+完成日期：2026-07-03
+相关 commit：chore: 整理 Docker 启动与部署配置
+验证命令：
+- .venv/bin/python -m pytest tests/unit/test_deployment_config.py -q
+- docker compose ps
+- curl -f http://localhost:8000/health
+- .venv/bin/python -m pytest tests/unit tests/integration -q
+验收结论：
+- docker-compose.yml 固定 name: hot-comments-tool。
+- 端口固定为 8000:8000，当前运行容器为 hot-comments-tool-app-1。
+- docker-compose.yml 挂载 ./data:/app/data，未挂载单个 app.db 文件。
+- 新增 docs/Deployment.md，说明启动、重建、端口占用、环境变量、数据目录和本地验收数据库重置流程。
+遗留问题：无；WO-09 会继续补完整用户操作说明。
+```
+
 ### WO-09 文档与用户操作说明
 
 优先级：P1

tests/unit/test_deployment_config.py

@@ -15,6 +15,14 @@ def test_docker_compose_uses_fixed_project_name_for_stable_port_owner():
     compose_content = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
 
     assert "name: hot-comments-tool" in compose_content
+    assert '"8000:8000"' in compose_content or "- 8000:8000" in compose_content
+
+
+def test_docker_compose_mounts_data_directory_for_sqlite_wal_files():
+    compose_content = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
+
+    assert "./data:/app/data" in compose_content
+    assert "app.db:/app/data/app.db" not in compose_content
 
 
 def test_real_env_file_is_gitignored():