docs: 跟齐 5 月 PR (#4 user/feedback / #5 ad-cooldown / #6 PG / abd8eab meituan 降级)

整轮 doc 跟齐 2026-05 落地但 doc 没补全/没更新的内容. 按 P0~P3 优先级处理.

P0 - 新 API doc + index 更新:
* docs/api/user-profile.md  (新) PATCH /api/v1/user/profile 改昵称
* docs/api/user-avatar.md   (新) POST /api/v1/user/avatar 上传头像(魔数嗅探/旧文件清理)
* docs/api/user-delete.md   (新) DELETE /api/v1/user 注销账号(软删+匿名化)
* docs/api/feedback.md      (新) POST /api/v1/feedback 提交反馈(含截图)
* docs/api/README.md           加 User/Feedback 组 + /media 静态服务段 +
                                修 UserOut "无接口可改恒为 null" 过时描述

P0 - 美团降级 / 现有 doc 校准:
* docs/api/meituan-coupons.md      加 "未配 MT_CPS 凭证降级返空" 说明
* docs/api/meituan-referral-link.md 同上 + 客户端兜底建议
* docs/api/meituan-feed.md         区分两种空结果路径(未配 vs 调用失败) +
                                    /health.mt_cps_configured 排障入口
* docs/integrations/meituan.md     "未配凭证降级" + "feed 静默吞错" 写进集成层
* ad-reward-status.md              PR #5 commit 已自带 doc 更新, 复核无需再改

P1 - 主文档大改:
* docs/后端技术实现.md
  - §1 能力表加 用户资料/外卖比价/钱包/福利/广告/反馈 (从 3 条扩到 9 条)
  - §1 数据模型纠正 "仅 1 张 user 表" -> 现有 10 张 + alembic_version
  - §2 DB 行 PG 主 / SQLite 兜底 + 加 psycopg3 行
  - §3 目录树补 user.py / feedback.py / media.py / repositories/feedback.py /
        scripts 子项 / docs/postgres-migration.md
  - §7 数据模型重写: 10 张业务表速查表 + alembic 合并迁移 f01db5d77dac 始末
  - §8 部署: 加 init_postgres.py 一句话流程 + checklist 加 "DATABASE_URL 切 PG"
        + "psycopg3 已装" + "MEDIA_ROOT 可写"
  - §10 已知问题: 加 美团降级 / agent 不鉴权 / MEDIA_ROOT serve / init_postgres bug /
        alembic 多 head 风险; 删过时 SQLite 行
  - 接口计数 11 -> 38

* docs/待办与技术债.md
  - 已解决追加: PG 切换 / 外卖比价透传 / 用户资料反馈接口 / 美团降级 /
                看广告 4 态冷却
  - 新增 "P2 DB 与 Alembic 治理" 段: alembic 多 head 团队规约 (含本次撞坑实录) +
    init_postgres.py 已知 5 处小 bug + MEDIA_ROOT serve

P2 - PG 迁移文档互指 + 迁移链补完:
* docs/数据库迁移.md
  - 顶部加 postgres-migration.md / 后端技术实现.md 互指
  - §6 迁移链 9 条 -> 12 条 (含 feedback_table / convert_dishes_jsonb /
        merge_pg_jsonb_and_feedback_heads)
  - §7 踩坑里 "多 head" 一行扩成完整故事 + 修复命令 + 团队预防规约
* docs/postgres-migration.md
  - 顶部加 数据库迁移.md / 后端技术实现.md §10 互指

P3 - 上线清单:
* docs/看广告赚金币上线清单.md
  - 设计要点加 PR #5 4 态 CTA + 后端权威派生说明 +
    VIDEO_ROUND_REQUIRED_COUNT/VIDEO_ROUND_COOLDOWN_SECONDS 常量
  - §E 端到端验收加 本轮冷却 / 弹窗 limit note / 跨设备一致 三项

所有最后更新日期同步到 2026-05-31.

docs/后端技术实现.md

@@ -3,21 +3,27 @@
 > 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
 > 仓库:`shaguabijia-app-server`
 > 接口协议详见 [`docs/api/`](./api/)(索引 + 一接口一文件)
-> 最后更新:2026-05-27
+> 最后更新:2026-05-31
 
 ---
 
 ## 1. 这个后端是干什么的
 
-为正式版 App(`shaguabijia-app-android`,包名 `com.jishisongfu.shaguabijia`)提供三块能力:
+为正式版 App(`shaguabijia-app-android`,包名 `com.jishisongfu.shaguabijia`)提供以下能力:
 
 | 能力 | 说明 |
 |---|---|
 | **账号与登录** | 极光一键登录 + 短信验证码登录(mock)→ 签发 JWT |
-| **美团 CPS 选品** | 透传美团联盟优惠券(外卖/到店)、点击换取推广链接(分佣) |
+| **用户资料** | 昵称 / 头像(上传图片含魔数嗅探) / 注销账号(软删除+匿名化) |
+| **美团 CPS 选品** | 透传美团联盟优惠券(外卖/到店)、点击换取推广链接(分佣)、未配凭证时降级返空 |
 | **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,MVP 不鉴权,前端已接通) |
+| **外卖比价透传** | `/intent/recognize` + `/price/step` 透传到 pricebot-backend(food MVP,MVP 不鉴权) |
+| **金币 / 现金钱包** | 金币账户/流水/兑换/微信绑定/提现单 11 端点 |
+| **签到 + 任务 + 省钱战绩** | 福利模块 |
+| **看广告发奖** | 穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 4 态 CTA 冷却 |
+| **帮助与反馈** | 用户提交反馈(含截图)+ 静态 `/media` 服务 |
 
-**本服务自身没有"比价"实现**——名字叫比价,实质是:登录态 + 美团券聚合分佣 + 给真正的领券/比价核心(pricebot-backend,另一个 repo)做"透传壳"。无爬虫、无 LLM、无积分/提现/钱包,数据模型仅一张 `user` 表(美团数据与领券请求均实时透传不落库)。
+**本服务自身没有"比价"实现**——比价/领券业务的核心都在 pricebot-backend(另一个 repo),本服务对 step 类接口做"透传壳"。无爬虫、无 LLM,但**有钱包/福利等业务模型**(数据模型从早期 1 张 `user` 表已扩展到 10 张,见 §7)。
 
 ---
 
@@ -30,7 +36,8 @@
 | ASGI | uvicorn[standard] | 生产 `--host 127.0.0.1 --port 8770` |
 | ORM | SQLAlchemy 2.0(Mapped 风格) | |
 | 迁移 | Alembic | |
-| DB | SQLite 起步 | 改 `DATABASE_URL` 可切 PostgreSQL,无 Redis |
+| DB | **PostgreSQL 16(生产)/ SQLite(开发兜底)** | 一键脚本 `scripts/init_postgres.py` 建库 + 写 `.env` + 跑迁移;开发环境改 `DATABASE_URL=sqlite:///./data/app.db` 即回退。无 Redis。详见 [docs/postgres-migration.md](./postgres-migration.md) |
+| DB 驱动 | psycopg3(`psycopg[binary]>=3.1`) | `DATABASE_URL=postgresql+psycopg://...`,**不要装 psycopg2**——SQLAlchemy 2.0 时代默认 psycopg3 |
 | Auth | PyJWT(HS256) | access + refresh |
 | 极光 | httpx + cryptography | REST 验 token + RSA 解密手机号 |
 | 美团 / pricebot | httpx(含 async) | 美团 S-Ca 网关签名;领券 async 透传 |
@@ -50,16 +57,20 @@ app/
 │   ├── deps.py              # 共享依赖:get_current_user(鉴权)、get_db(注入 session)
 │   └── v1/                  # 接口层(薄):解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码
 │       ├── auth.py          # 登录 6 端点(极光一键登录 / 短信 send+login / refresh / me / logout)
+│       ├── user.py          # 用户资料 3 端点(改昵称 / 上传头像 / 注销账号)
+│       ├── feedback.py      # 帮助与反馈 1 端点(提交反馈含截图)
 │       ├── coupon.py        # 领券透传 /coupon/step(转发 pricebot,MVP 不鉴权)
 │       ├── compare.py       # 外卖比价透传 /intent/recognize + /price/step(转发 pricebot,MVP 不鉴权)
-│       ├── meituan.py       # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS)
+│       ├── meituan.py       # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS),未配 MT_CPS 凭证降级返空
 │       ├── wallet.py        # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单)
 │       ├── signin.py        # 签到 2 端点(状态 / 执行签到)
 │       ├── tasks.py         # 一次性任务 2 端点(列表 / 领取)
 │       ├── savings.py       # 省钱 3 端点(汇总 / 战绩 / 明细)
-│       └── ad.py            # 看广告发奖 3 端点(穿山甲 S2S 回调 / 进度 / 联调发奖)
+│       └── ad.py            # 看广告发奖 3 端点(穿山甲 S2S 回调 / 进度+本轮冷却 / 联调发奖)
 ├── schemas/                 # Pydantic:API 收发的数据契约(与客户端对齐字段看这里)
 │   ├── auth.py
+│   ├── user.py              # 改昵称请求 + OkResponse
+│   ├── feedback.py          # 反馈出参(请求是 multipart,在 router 直接校验)
 │   ├── meituan.py
 │   ├── welfare.py           # 钱包/签到/任务/省钱 收发模型
 │   └── ad.py                # 看广告发奖收发模型
@@ -73,35 +84,45 @@ app/
 │   ├── config.py            # pydantic-settings
 │   ├── security.py          # JWT 签发/校验
 │   ├── ratelimit.py         # 同 IP 滑动窗口限流依赖
-│   ├── rewards.py           # 发奖/兑换/提现额度等业务常量与换算
+│   ├── rewards.py           # 发奖/兑换/提现额度等业务常量与换算(2026-05 加 VIDEO_ROUND_REQUIRED_COUNT / VIDEO_ROUND_COOLDOWN_SECONDS)
+│   ├── media.py             # 用户上传文件(头像/反馈截图)落盘 + 魔数嗅探 + 随机文件名
 │   └── logging.py
 ├── repositories/            # 数据访问 + 事务(早期叫 crud,2026-05 统一并入此目录)
-│   ├── user.py              # get_user_by_id / get_user_by_phone / upsert_user_for_login
+│   ├── user.py              # get_user_by_id / by_phone / upsert_for_login / update_nickname / set_avatar_url / soft_delete_account
+│   ├── feedback.py          # 提交反馈写库
 │   ├── wallet.py            # 账户/流水/兑换/提现单(调 integrations/wxpay)
 │   ├── signin.py            # 签到记录 / 连续天数 / 档位
 │   ├── task.py              # 一次性任务领取
 │   ├── savings.py           # 省钱汇总 / 战绩 / 明细
-│   └── ad_reward.py         # 看广告发奖(按 trans_id 幂等 + 每日上限)
+│   └── ad_reward.py         # 看广告发奖(按 trans_id 幂等 + 每日上限 + 本轮冷却派生)
 ├── models/                  # ORM 表结构
 │   ├── user.py              # user(含微信 openid/nickname/avatar)
+│   ├── feedback.py          # 用户反馈(content/contact/images JSON 列/status)
 │   ├── wallet.py            # 金币账户 / 金币流水 / 现金流水 / 提现单
 │   ├── signin.py            # 签到记录
 │   ├── task.py              # 任务领取记录
-│   ├── savings.py           # 省钱明细 / 店铺菜品
+│   ├── savings.py           # 省钱明细 / 店铺菜品 / dishes(PG 上 JSONB)
 │   └── ad_reward.py         # 看广告发奖记录
 └── db/
     ├── base.py              # DeclarativeBase
-    └── session.py           # engine + get_db
+    └── session.py           # engine + get_db(非 SQLite 时启 pool: size=10/overflow=20/recycle=3600)
 
-alembic/                     # 数据库迁移(versions/ 9 个迁移;文件名已去 hex 前缀,链靠文件内 down_revision)
+alembic/                     # 数据库迁移(versions/ 11+ 个迁移含 feedback_table / convert_dishes_jsonb / merge 等)
 deploy/                      # systemd(.service) + nginx(.conf)
 secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git,仅 .gitkeep 占位)
-scripts/                     # 运维脚本(migrate 迁移 / 对账 / 重置签到 / 重置福利 / 模拟穿山甲回调)
-tests/                       # pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy)
+scripts/
+  ├── init_postgres.py       # 一键 PG 初始化:建用户 + 建库 + 写 .env + 跑迁移(2026-05 新增,见已知 bug §10)
+  ├── migrate.sh             # 单独跑 alembic upgrade head(部署/CI 用)
+  ├── reset_signin.py        # 重置今日签到
+  ├── reset_welfare.py       # 重置福利数据
+  ├── reconcile_withdraws.py # 提现对账
+  └── sim_pangle_callback.py # 模拟穿山甲回调
+tests/                       # pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy / compare_proxy)
 run.sh                       # 本地启动脚本(自动先跑迁移再起服务)
 docs/api/                    # API 接口文档(索引 README + 一接口一文件)
 docs/integrations/           # 集成层实现文档(SDK 签名/加解密/协议细节)
 docs/数据库迁移.md           # Alembic 迁移指南(如何建表/升级/新增迁移)
+docs/postgres-migration.md   # SQLite → PostgreSQL 切换指南(配套 scripts/init_postgres.py)
 ```
 
 > **命名说明**:`api/v1/` 的 `v1` 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);`integrations` 装外部 SDK 集成、`repositories` 装数据访问、`core` 装基础设施,三者分离。**数据访问层统一在 `repositories/`**(早期叫 `crud/`,2026-05 已整体并入,`crud/` 不再存在)。`coupon.py` 是领券透传,勿与 `meituan.py` 里的 `coupons`(券列表)混淆。
@@ -197,41 +218,70 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert
 
 ## 7. 数据模型
 
-仅一张 `user` 表(`models/user.py`):
+10 张业务表 + `alembic_version` 框架表。生产 PG / 开发可回退 SQLite。
 
+| 表 | models 文件 | 说明 |
+|---|---|---|
+| `user` | `models/user.py` | 用户(phone 唯一索引;注销时改成 `deleted_<id>` 释放约束) |
+| `feedback` | `models/feedback.py` | 用户反馈(content/contact/images JSON 列/status) |
+| `coin_account` | `models/wallet.py` | 用户的金币余额(`balance_cents` 单位:分) |
+| `coin_transaction` | `models/wallet.py` | 金币流水(签到/任务/兑换/广告;`type` + `amount_cents`) |
+| `cash_transaction` | `models/wallet.py` | 现金流水(兑换/提现) |
+| `withdraw_order` | `models/wallet.py` | 提现单(`status` + `wxpay_batch_id`,微信支付商家转账) |
+| `signin_record` | `models/signin.py` | 签到记录(每日一行,索引 `(user_id, signin_date)`) |
+| `user_task` | `models/task.py` | 一次性任务领取记录 |
+| `savings_record` | `models/savings.py` | 省钱明细(`dishes` 在 PG 上为 JSONB,SQLite 上是 TEXT) |
+| `ad_reward_record` | `models/ad_reward.py` | 看广告发奖(`trans_id` 唯一,幂等) |
+
+**user 表字段速查**:
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | id | INTEGER PK | 自增 |
-| phone | VARCHAR(20) UNIQUE | 登录主键,唯一索引 `ix_user_phone` |
+| phone | VARCHAR(20) UNIQUE | 登录主键(注销后变 `deleted_<id>` 占位) |
 | register_channel | VARCHAR(20) | `jverify` / `sms` |
-| nickname | VARCHAR(64) NULL | 预留,**无接口可写,恒为 null** |
-| avatar_url | VARCHAR(512) NULL | 同上 |
+| nickname | VARCHAR(64) NULL | 由 `PATCH /api/v1/user/profile` 写入 |
+| avatar_url | VARCHAR(512) NULL | 相对路径(`/media/avatars/...`),由 `POST /api/v1/user/avatar` 写入 |
+| wechat_openid | VARCHAR(64) NULL UNIQUE | 微信绑定(提现用),一个微信只绑一个账号 |
+| wechat_nickname / wechat_avatar_url | VARCHAR NULL | 微信侧资料(绑定时拉取) |
 | status | VARCHAR(20) | `active` / `disabled` / `deleted`,仅 active 可登录/鉴权 |
 | created_at / last_login_at | DATETIME(tz) | |
 
-`upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册(注册即登录)。Alembic 实际库里另有框架表 `alembic_version`。
+`upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册(注册即登录)。
+
+**Alembic 迁移**:`alembic/versions/` 当前 11 个迁移 + 1 个合并迁移(`f01db5d77dac_merge_pg_jsonb_and_feedback_heads.py`,2026-05-29 创建——实习生 PG 分支和 user-profile-feedback 分支并行开发时 down_revision 都挂在 `c8d9e0f1a2b3` 上,导致多 head,合并迁移把两条链合并)。详见 [数据库迁移.md](./数据库迁移.md)。
 
 ---
 
 ## 8. 配置与部署
 
-配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`、JWT、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / `PRICEBOT_REQUEST_TIMEOUT_SEC`)**、CORS。
+配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`(默认 SQLite,生产应切 PG)、JWT、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / `PRICEBOT_REQUEST_TIMEOUT_SEC=30` / `PRICEBOT_COMPARE_TIMEOUT_SEC=60`)**、**媒体存储(`MEDIA_ROOT=./data/media` / `MEDIA_URL_PREFIX=/media`)**、CORS。
 
-**生产部署**:systemd `shaguabijia-app-server.service`(WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,uvicorn 监听 `127.0.0.1:8770`,`--workers 1`)+ nginx 443 反代 → 8770。**无 Docker**。
+**生产部署**:systemd `shaguabijia-app-server.service`(WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,uvicorn 监听 `127.0.0.1:8770`,`--workers 1`)+ nginx 443 反代 → 8770。**无 Docker**。**PostgreSQL 16** 同机部署。
 
 ```bash
+# 首次 PG 初始化(新机器或新环境):
+ssh server "sudo apt install -y postgresql-16 && sudo systemctl enable --now postgresql"
+ssh server "cd /opt/shaguabijia-app-server && .venv/bin/python scripts/init_postgres.py"
+# 该脚本会建业务用户 + 建库 + 写 .env 的 DATABASE_URL + 跑 alembic upgrade head
+
+# 后续日常部署:
 rsync -avz --exclude='.venv' --exclude='__pycache__' --exclude='data' --exclude='secrets/*.pem' ./ server:/opt/shaguabijia-app-server/
 scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/   # 私钥单独传,不入 git
 ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
 ```
 
+完整 PG 切换流程见 [docs/postgres-migration.md](./postgres-migration.md)。
+
 **生产 checklist(均为上线必查)**:
 
 - [ ] `JWT_SECRET_KEY` 改为高熵随机串——默认值 `change-me` 可被伪造 token
 - [ ] `SMS_MOCK=false` 并接真实短信供应商——mock 下任意 6 位码可登录任意手机号
-- [ ] `MT_CPS_APP_KEY` / `MT_CPS_APP_SECRET` 已填(否则美团接口 502)
+- [ ] `MT_CPS_APP_KEY` / `MT_CPS_APP_SECRET` 已填(未配凭证时美团 3 端点降级返空,前端首页空白)
 - [ ] `PRICEBOT_BASE_URL` 指向真实 pricebot-backend(否则领券 502)
 - [ ] RSA 私钥就位且与极光控制台公钥**配对**,权限 600
+- [ ] **DATABASE_URL 已切 PG**(默认 SQLite 单文件并发写锁库,扩 worker 立即撞墙)
+- [ ] **psycopg3 已装**(`pip install "psycopg[binary]>=3.1"`)
+- [ ] `MEDIA_ROOT` 目录可写(头像/反馈截图落盘);建议 nginx 直接 serve 该目录绕过应用进程
 - [ ] `APP_ENV=prod`、`APP_DEBUG=false`、nginx SSL 有效、`alembic upgrade head` 已执行
 
 ---
@@ -255,12 +305,15 @@ conda activate price          # 首次:pip install -e .
 
 | 项 | 说明 |
 |---|---|
-| logout 无服务端失效 | 靠客户端清 token;后续加 jti 黑名单表 |
+| logout 无服务端失效 | 靠客户端清 token;后续加 jti 黑名单表(注销账号也是同问题——软删后旧 token 仍能用到自然过期) |
 | 美团接口无鉴权 + sid 可覆盖 | 评估加鉴权/锁定 sid(注意首页要求未登录可见) |
-| feed 静默吞异常 | 建议给 `_fetch_topic` 加日志,避免无声失败 |
-| 领券依赖 pricebot | `coupon/step` 仅透传,真正逻辑在 pricebot-backend;前端已接通领券链路 |
+| 美团接口未配凭证降级 | 未配 `MT_CPS_APP_KEY` 时 3 端点返空(不报 502),`/feed` 跟"已配但调用失败"路径无法区分——见 [integrations/meituan](./integrations/meituan.md) |
+| 领券/比价依赖 pricebot | `coupon/step` / `intent/recognize` / `price/step` 仅透传,真正逻辑在 pricebot-backend;前端已接通领券链路,比价 food MVP 也已接通 |
+| agent 系列接口 MVP 不鉴权 | 拿不到 user_id → 无法采集"哪个用户领了/买了什么"用户级画像(商业模式核心资产)。见 [待办与技术债.md](./待办与技术债.md) P1 |
 | SMS 为 mock | 上线接真实供应商 + `SMS_MOCK=false` |
 | 短信冷却存内存 | 扩 worker 前需迁移到 Redis |
-| SQLite | 流量上来切 PostgreSQL,只改 `DATABASE_URL` |
+| `MEDIA_ROOT` 进程内 serve | 头像/反馈截图当前用 FastAPI StaticFiles,生产建议 nginx 直 serve 该目录 |
+| `init_postgres.py` 已知小 bug | 5 条小坑,见 [待办与技术债.md](./待办与技术债.md) |
+| Alembic 多 head 风险 | 跨分支并行开发要在 PR 合并前 `alembic heads` 检查只有一个;漏检会出现 "Multiple head revisions",需要 `alembic merge` 合并 |
 
-> 完整接口协议(11 个)见 [`docs/api/`](./api/),以代码为准。
+> 完整接口协议见 [`docs/api/`](./api/)(38 个端点 + `/health` + `/media` 静态服务),以代码为准。