docs: add maintainer guidance and API contract

docs/guides/deployment.md

@@ -0,0 +1,32 @@
+# 部署与运行
+
+用户可见的安装和日常操作以根 [`README.md`](../../README.md) 为准；本文记录维护代码时必须理解的构建和数据边界。
+
+## 镜像结构
+
+`Dockerfile` 有四个阶段：Node 24.19.0 构建 React 静态资源；Go 1.26.0 以 `CGO_ENABLED=0` 构建后端；Node 阶段安装固定 `@openai/codex`；最终 Debian bookworm 镜像只包含 CA、时区、后端、Node runtime 和 Codex 包。
+
+前端产物复制到 `backend/internal/web/dist` 后嵌入二进制。运行层使用 UID `10001` 的 system 用户 `helper`，默认 `DATA_DIR=/data`、`LISTEN_ADDR=:8080`，并暴露 `/data` volume 和 8080。健康检查调用二进制自身的 `healthcheck` 子命令。
+
+## Compose 与持久化
+
+`docker-compose.yml` 本地构建 `codex-helper:latest`，将宿主机 8180 映射到容器 8080，并把命名卷 `codex-helper-data` 挂载到 `/data`。全部数据库、密钥、Codex 配置和多账号凭据都依赖这个卷。
+
+升级应使用：
+
+```bash
+git pull --ff-only
+docker compose up -d --build
+```
+
+不要使用 `docker compose down -v`，也不要在未确认 volume 名和备份前重建、迁移或删除数据卷。需要改变运行 UID、volume 或 `DATA_DIR` 时，必须提供旧数据权限和路径的升级验证。
+
+## 网络与安全
+
+应用自身监听 HTTP。公网部署应放在 HTTPS 反向代理后，初始化前限制访问来源，并保证到 OpenAI 登录/Codex 服务、Telegram Bot API 和所选 SMTP 服务的出站连接。当前只有 `LISTEN_ADDR` 是 Compose 显式环境变量；运行配置由前端保存到数据库。
+
+设备码登录不需要 OpenAI API Key。Codex app-server 为每个 `CODEX_HOME` 管理 ChatGPT token；不要把这些目录暴露为静态文件或外部共享目录。
+
+## 备份与恢复
+
+维护接口下载的 SQLite 快照适合查看或数据库级备份，但不包含解密密钥和 Codex 凭据。完整恢复步骤是：停止容器、备份或恢复整个 `/data`、确认 UID `10001` 可读写、再启动并检查 `/health/live`、`/health/ready`、管理员登录和各账号连接。恢复过程不得只替换数据库而遗失对应 `secret.key`。

docs/guides/development-and-validation.md

@@ -0,0 +1,75 @@
+# 开发与验证
+
+## 环境政策
+
+宿主机只保证 Docker 和 Docker Compose。所有 Go、Node、npm、格式化、构建、测试和安全扫描都在容器内执行。以下命令从仓库根目录运行；挂载源码时使用只读模式，只有构建输出确实需要写回工作区时才放宽。
+
+## 后端
+
+完整格式、构建、vet 和测试：
+
+```bash
+docker run --rm \
+  -v "$PWD/backend:/app:ro" \
+  -v codex-helper-go-mod:/go/pkg/mod \
+  -v codex-helper-go-cache:/root/.cache/go-build \
+  -w /app golang:1.26.0-bookworm \
+  sh -c 'test -z "$(gofmt -l .)" && go build ./... && go vet ./... && go test -count=1 ./...'
+```
+
+针对性测试可把最后一段替换为 `go test -count=1 ./internal/store` 或相应 package。测试通过 `t.TempDir()` 创建专用 SQLite，禁止把 `DATA_DIR` 指向运行实例。
+
+## 前端
+
+在临时副本中安装依赖、构建并运行 Vitest，避免容器把 root 所有权的 `node_modules` 写入工作区：
+
+```bash
+docker run --rm -v "$PWD/frontend:/src:ro" node:24.19.0-bookworm-slim \
+  sh -c 'cp -a /src /tmp/frontend && cd /tmp/frontend && npm ci --no-audit --no-fund && npm run build && npm test'
+```
+
+依赖或安全改动额外运行：
+
+```bash
+docker run --rm -v "$PWD/frontend:/src:ro" node:24.19.0-bookworm-slim \
+  sh -c 'cp -a /src /tmp/frontend && cd /tmp/frontend && npm ci --no-audit --no-fund && npm audit --omit=dev --audit-level=high'
+```
+
+## Playwright E2E
+
+使用与 `frontend/package.json` 中 `@playwright/test` 匹配的官方镜像：
+
+```bash
+docker run --rm --ipc=host \
+  -v "$PWD/frontend:/src:ro" \
+  mcr.microsoft.com/playwright:v1.62.1-noble \
+  sh -c 'cp -a /src /tmp/frontend && cd /tmp/frontend && npm ci --no-audit --no-fund && npm run test:e2e'
+```
+
+若升级 Playwright，必须同步镜像 tag。E2E 的 API 由 route mock 提供，不要求启动 Go 后端。
+
+## 镜像与 Compose
+
+```bash
+docker compose config --quiet
+docker build --check .
+docker build -t codex-helper:test .
+```
+
+涉及容器启动、静态资源或健康检查时，再使用隔离的临时 Compose project 和专用 volume 验证；不得连接或删除用户的运行卷。
+
+## 最低验证矩阵
+
+| 改动 | 最低验证 |
+| --- | --- |
+| 后端普通逻辑 | 相关 Go test、gofmt 检查、build、vet |
+| SQLite schema、迁移、备份 | 新旧 schema 测试、WAL 快照测试、完整后端门禁 |
+| app-server 生命周期或同步 | codex/app runtime 单测、并发和失败重试路径 |
+| 鉴权、session 或秘密 | security 与 app 测试、成功和拒绝路径 |
+| 通知 | reminder 渲染、去重、计划与异常重置测试 |
+| 前端 | 相关 Vitest、生产 build |
+| 布局、路由、设置或响应式 | Playwright desktop 和 mobile |
+| Dockerfile、Compose、持久化 | 配置检查及相应镜像/运行验证 |
+| 纯文档 | 链接、术语、事实来源和 `git diff --check` |
+
+先运行针对性检查，再按风险扩大范围。修复缺陷时优先添加修复前会失败的回归测试。