docs: add t-403 deployment guide

progress.md

@@ -940,3 +940,31 @@
 - 已知限制：真实微信/支付宝商户凭证和生产 SDK 未接入；真实 AI 上游 smoke 尚未执行；图片同步真实耗时仍未验证，需在 T-403 部署 / 运行文档中明确超时配置和风险口径。
 - 决策：T-402 不改业务代码，仅完成验收、口径修正和文档归档；MVP P0 结论为通过。
 - 下一步：领取 T-403 部署 / 运行文档。
+
+## 2026-07-03 T-403 部署 / 运行文档
+
+- 状态：DONE
+- 变更：
+  - 新增 `docs/deployment.md`：按 VPS / 宝塔 / Nginx / Gunicorn(gthread) / MySQL 8.4 写生产部署步骤，覆盖 `.env`、迁移、`collectstatic`、共享 cache、双 Gunicorn 池、Nginx 分流、上线检查和真实图片耗时验证口径。
+  - 新增 `requirements-production.txt`：Linux 生产运行在基础依赖外追加 Gunicorn，避免 Windows 本地开发强制安装生产 runner。
+  - `config/settings.py`：新增 `STATIC_ROOT`、`STATIC_URL` 环境变量支持；新增 `CSRF_TRUSTED_ORIGINS`；新增 `CACHES` 环境变量配置，生产可用 DatabaseCache / Redis / Memcached 等共享 cache；新增 HTTPS cookie、proxy SSL 与 HSTS 环境变量支持。
+  - `.env.example` / `docs/env.md`：同步新增生产静态、共享 cache、CSRF trusted origins、HTTPS cookie/proxy/HSTS 配置项。
+  - `docs/03-tech-stack.md`：部署方式定为 VPS / 宝塔 + Nginx + Gunicorn(gthread) + systemd，并记录生产安装、cache table、collectstatic 与 Gunicorn 命令。
+  - `docs/04-architecture.md`：修正部署分流路径为实际的 `/api/v1/generate/*`。
+  - 同步更新 `README.md`、`docs/00-ai-start-here.md`、`docs/README.md`、`docs/06-tasks.md`、`docs/current-state.md`、`docs/project-brief.md`、`docs/project-onepager.md`；T-403 标记 DONE，计划内 MVP 任务暂无下一个 TODO。
+- 验证：
+  - `./init.ps1`：开工前通过。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py makemigrations --check --dry-run`：通过，No changes detected。
+  - `py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1`：通过，两个本地 static 文件均可发现。
+  - `py -3.12 manage.py check --deploy`：当前开发 `.env` 下只报预期安全配置警告；临时注入生产型安全环境变量（含 HSTS includeSubDomains/preload）后通过，0 issues。
+  - `py -3.12 manage.py collectstatic --dry-run --noinput`：通过，预期收集 169 个 static 文件。
+  - `py -3.12 manage.py createcachetable --dry-run cmhub_cache`：通过，输出 MySQL cache 表 DDL。
+  - `py -3.12 -m compileall config`：通过。
+  - 尝试 `py -3.12 manage.py test apps.api --noinput --keepdb --verbosity 2`：未取得单次全绿；25 条用例通过，`GenerateApiTests` 14 条因远程 MySQL `OperationalError 2013` / 连接重置 / 事务中断被记 ERROR。
+  - `Test-NetConnection 43.128.3.240 -Port 3306`：`TcpTestSucceeded=True`。
+  - `py -3.12 manage.py test apps.api.tests.GenerateApiTests --noinput --keepdb --verbosity 2`：通过，14 tests OK。
+- 阻塞：T-403 文档与配置支撑无功能阻塞；完整 API 套件单次运行仍受远程 MySQL 间歇断连影响。
+- 已知限制：真实 AI 上游和真实图片耗时仍未验证，因当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库无真实 AiModel/ModelAlias；真实微信/支付宝商户配置和 SDK 仍待生产环境提供。`deployment.md` 已明确未跑通真实图片 smoke 前不能声称生产图片链路已验证。
+- 决策：生产限流共享 cache 的 MVP 推荐路径先用 Django `DatabaseCache` + MySQL cache 表，不引入 Redis 作为当前代码依赖；高并发后可切换 Redis/Memcached 并安装对应 backend。生产静态资源采用 `STATIC_ROOT + collectstatic + Nginx/宝塔托管`，不在应用内引入 WhiteNoise。
+- 下一步：计划内 MVP 任务已完成；进入 VPS 实际部署、真实邮件/支付/AI 配置和真实图片耗时验证，或从 Backlog 重新拆后续任务。