fix(alembic): 合并多 head(#65 device 迁移 + comparison_token_cols)

#65 的 device 迁移链与 comparison_token_cols 都从 ceb286289426 分叉成双 head,alembic upgrade head 报 Multiple head revisions;加 merge 迁移 4dc2af7ebe74 合并(空 DDL 仅接链)。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -27,6 +27,11 @@ JG_PRIVATE_KEY_PATH=./secrets/jverify_rsa_private.pem
 JG_VERIFY_ENDPOINT=https://api.verification.jpush.cn/v1/web/loginTokenVerify
 JG_REQUEST_TIMEOUT_SEC=15
 
+# ===== 无障碍保护存活监控(pull 后置检测;本期不接推送)=====
+HEARTBEAT_MONITOR_ENABLED=true
+HEARTBEAT_TIMEOUT_MINUTES=10
+HEARTBEAT_SCAN_INTERVAL_SEC=60
+
 # ===== 短信 (mock 模式) =====
 # mock = true 时,任意 6 位数字均通过,且 /sms/send 不真发短信(只 log)。
 # 后续接阿里云/腾讯云短信时,改成 false 并填供应商相关 key。

.gitignore

@@ -30,6 +30,7 @@ data/*
 !data/media/
 data/media/*
 !data/media/dl.html
+!data/media/taobao_landing.jpg
 
 secrets/*
 !secrets/.gitkeep

alembic/versions/4dc2af7ebe74_merge_device_65_and_comparison_token_.py

@@ -0,0 +1,26 @@
+"""merge device#65 and comparison_token_cols heads
+
+Revision ID: 4dc2af7ebe74
+Revises: comparison_token_cols, ad_feed_reward_trace_id
+Create Date: 2026-06-23 17:57:54.083531
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '4dc2af7ebe74'
+down_revision: Union[str, Sequence[str], None] = ('comparison_token_cols', 'ad_feed_reward_trace_id')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/ad_feed_reward_trace_id.py

@@ -0,0 +1,42 @@
+"""ad_feed_reward_record.trace_id (比价看广告金币归属到比价记录)
+
+Revision ID: ad_feed_reward_trace_id
+Revises: device_kill_alert_pending
+Create Date: 2026-06-21
+
+比价等候期信息流广告(feed_ad_reward)结算时,客户端带上本场比价 trace_id 落此列;
+比价记录页按 trace_id 聚合本场实发金币,显示「比价赚 N 金币」。领券/福利/旧客户端 = NULL。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'ad_feed_reward_trace_id'
+down_revision: Union[str, Sequence[str], None] = 'device_kill_alert_pending'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # SQLite 下 ADD COLUMN(可空) 与 CREATE INDEX 均原生支持,无需 batch_alter_table。
+    op.add_column(
+        'ad_feed_reward_record',
+        sa.Column('trace_id', sa.String(length=64), nullable=True),
+    )
+    op.create_index(
+        op.f('ix_ad_feed_reward_record_trace_id'),
+        'ad_feed_reward_record',
+        ['trace_id'],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        op.f('ix_ad_feed_reward_record_trace_id'),
+        table_name='ad_feed_reward_record',
+    )
+    op.drop_column('ad_feed_reward_record', 'trace_id')

alembic/versions/add_feed_scene.py

@@ -0,0 +1,34 @@
+"""add feed_scene to ad_feed_reward_record
+
+信息流广告点位场景:comparison(比价等待) / coupon(领券) / welfare(福利页)。
+比价与领券共用同一个信息流代码位(AdConfig.feedCodeId),slot_id / our_code_id 都分不出来,
+只能由客户端在各调用点(PriceBotService / CouponForegroundService / WelfareScreen)显式打标。
+可空:历史记录与未升级客户端为 NULL = 未分类。
+
+Revision ID: add_feed_scene
+Revises: drop_force_onboarding
+Create Date: 2026-06-20 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "add_feed_scene"
+down_revision: Union[str, Sequence[str], None] = "drop_force_onboarding"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "ad_feed_reward_record",
+        sa.Column("feed_scene", sa.String(length=16), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ad_feed_reward_record", "feed_scene")

alembic/versions/ceb286289426_merge_add_feed_scene_and_launch_confirm_.py

@@ -0,0 +1,26 @@
+"""merge add_feed_scene and launch_confirm_sample heads
+
+Revision ID: ceb286289426
+Revises: add_feed_scene, launch_confirm_sample_table
+Create Date: 2026-06-20 23:52:57.853400
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'ceb286289426'
+down_revision: Union[str, Sequence[str], None] = ('add_feed_scene', 'launch_confirm_sample_table')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/comparison_debug_fields.py

@@ -0,0 +1,54 @@
+"""comparison_record: 客户端环境 / 性能统计 / LLM 明细 debug 字段
+
+Revision ID: comparison_debug_fields
+Revises: cps_activity_image
+Create Date: 2026-06-17 22:00:00.000000
+
+给 admin 比价记录 debug 页新增采集列，全部 nullable(旧记录 / 未发版客户端为 NULL，向后兼容)：
+- 客户端环境: device_*/rom_*/android_*/app_version*/source_app_version/经纬度
+- 过程统计: total_ms/step_count/llm_call_count/retry_count
+- LLM 明细: llm_calls(JSONB，server 按 trace_id 同机拉 pricebot 落库)
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "comparison_debug_fields"
+down_revision: Union[str, Sequence[str], None] = "cps_activity_image"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_JSONB = sa.JSON().with_variant(postgresql.JSONB(), "postgresql")
+
+
+def upgrade() -> None:
+    op.add_column("comparison_record", sa.Column("device_model", sa.String(64), nullable=True))
+    op.add_column("comparison_record", sa.Column("device_manufacturer", sa.String(64), nullable=True))
+    op.add_column("comparison_record", sa.Column("rom_vendor", sa.String(32), nullable=True))
+    op.add_column("comparison_record", sa.Column("rom_name", sa.String(32), nullable=True))
+    op.add_column("comparison_record", sa.Column("rom_version", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("android_version", sa.String(16), nullable=True))
+    op.add_column("comparison_record", sa.Column("android_sdk", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("app_version", sa.String(32), nullable=True))
+    op.add_column("comparison_record", sa.Column("app_version_code", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("source_app_version", sa.String(32), nullable=True))
+    op.add_column("comparison_record", sa.Column("longitude", sa.Float(), nullable=True))
+    op.add_column("comparison_record", sa.Column("latitude", sa.Float(), nullable=True))
+    op.add_column("comparison_record", sa.Column("total_ms", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("step_count", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("llm_call_count", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("retry_count", sa.Integer(), nullable=True))
+    op.add_column("comparison_record", sa.Column("llm_calls", _JSONB, nullable=True))
+
+
+def downgrade() -> None:
+    for col in (
+        "llm_calls", "retry_count", "llm_call_count", "step_count", "total_ms",
+        "latitude", "longitude", "source_app_version", "app_version_code",
+        "app_version", "android_sdk", "android_version", "rom_version",
+        "rom_name", "rom_vendor", "device_manufacturer", "device_model",
+    ):
+        op.drop_column("comparison_record", col)

alembic/versions/comparison_token_cols.py

@@ -0,0 +1,37 @@
+"""add input_tokens / output_tokens to comparison_record
+
+比价记录增加本次 LLM 累计 token(server 从 llm_calls[].usage 累加),
+供 admin 比价记录页展示 token 数与估算成本。
+
+Revision ID: comparison_token_cols
+Revises: feedback_review_fields
+Create Date: 2026-06-23 00:40:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "comparison_token_cols"
+down_revision: Union[str, Sequence[str], None] = "feedback_review_fields"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "comparison_record",
+        sa.Column("input_tokens", sa.Integer(), nullable=True),
+    )
+    op.add_column(
+        "comparison_record",
+        sa.Column("output_tokens", sa.Integer(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("comparison_record", "output_tokens")
+    op.drop_column("comparison_record", "input_tokens")

alembic/versions/cps_activity_image.py

@@ -0,0 +1,38 @@
+"""cps activity 落地页图: cps_activity.image_url + 回填存量淘宝活动
+
+新建淘宝活动时运营提供落地页主视觉图(上传或选已有),落地页按活动展示对应图。
+存量淘宝活动回填为此前写死的那张图,无缝衔接。
+
+Revision ID: cps_activity_image
+Revises: cps_v2_platforms
+Create Date: 2026-06-17 12:00:00.000000
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+from app.core.config import settings
+
+
+revision: str = "cps_activity_image"
+down_revision: Union[str, Sequence[str], None] = "cps_v2_platforms"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("cps_activity", sa.Column("image_url", sa.String(512), nullable=True))
+    # 回填存量淘宝活动 = 此前写死的那张图(绝对 URL,基于落地页域名 CPS_REDIRECT_BASE;
+    # dev 未配则相对路径)。新活动由运营自传/选,不回填。
+    base = settings.CPS_REDIRECT_BASE.rstrip("/")
+    default_img = f"{base}/media/taobao_landing.jpg" if base else "/media/taobao_landing.jpg"
+    op.execute(
+        sa.text(
+            "UPDATE cps_activity SET image_url = :img WHERE platform = 'taobao'"
+        ).bindparams(img=default_img)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("cps_activity", "image_url")

alembic/versions/cps_v2_platforms.py

@@ -0,0 +1,61 @@
+"""cps v2: 活动 payload(淘口令/京东链接) + 群多平台/sid 可空 + 点击 event_type
+
+Revision ID: cps_v2_platforms
+Revises: cps_link_tables
+Create Date: 2026-06-17 11:00:00.000000
+
+接入淘宝/京东:
+- cps_activity.payload   淘宝整段淘口令文本 / 京东推广链接(美团仍用 act_id)
+- cps_group.platforms    该群发哪些平台(多选);sid 改可空(纯淘宝/京东无 sid)
+- cps_link.sid 可空 + target_url 加长(淘口令较长)
+- cps_click.event_type   visit / copy(淘宝落地页"复制口令")
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "cps_v2_platforms"
+down_revision: Union[str, Sequence[str], None] = "cps_link_tables"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 活动:淘宝淘口令 / 京东链接
+    op.add_column("cps_activity", sa.Column("payload", sa.Text(), nullable=True))
+
+    # 群:多平台(现有群都是美团,server_default 回填)+ sid 可空
+    op.add_column(
+        "cps_group",
+        sa.Column(
+            "platforms",
+            sa.JSON().with_variant(postgresql.JSONB(), "postgresql"),
+            nullable=False,
+            server_default=sa.text("'[\"meituan\"]'::jsonb"),
+        ),
+    )
+    op.alter_column("cps_group", "sid", existing_type=sa.String(64), nullable=True)
+
+    # link:sid 可空 + target 加长
+    op.alter_column("cps_link", "sid", existing_type=sa.String(64), nullable=True)
+    op.alter_column("cps_link", "target_url", existing_type=sa.String(1024), type_=sa.String(2048))
+
+    # click:sid 可空 + 事件类型
+    op.alter_column("cps_click", "sid", existing_type=sa.String(64), nullable=True)
+    op.add_column(
+        "cps_click",
+        sa.Column("event_type", sa.String(16), nullable=False, server_default="visit"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("cps_click", "event_type")
+    op.alter_column("cps_click", "sid", existing_type=sa.String(64), nullable=False)
+    op.alter_column("cps_link", "target_url", existing_type=sa.String(2048), type_=sa.String(1024))
+    op.alter_column("cps_link", "sid", existing_type=sa.String(64), nullable=False)
+    op.drop_column("cps_group", "platforms")
+    op.alter_column("cps_group", "sid", existing_type=sa.String(64), nullable=False)
+    op.drop_column("cps_activity", "payload")

alembic/versions/cps_wx_user.py

@@ -0,0 +1,48 @@
+"""cps 微信用户表 cps_wx_user + cps_click 加 openid
+
+CPS 落地页微信网页授权拿 openid/昵称头像,做用户级群统计。
+
+Revision ID: cps_wx_user
+Revises: comparison_debug_fields
+Create Date: 2026-06-19 12:00:00.000000
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "cps_wx_user"
+down_revision: Union[str, Sequence[str], None] = "comparison_debug_fields"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "cps_wx_user",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("openid", sa.String(64), nullable=False),
+        sa.Column("unionid", sa.String(64), nullable=True),
+        sa.Column("nickname", sa.String(128), nullable=True),
+        sa.Column("headimgurl", sa.String(512), nullable=True),
+        sa.Column("first_code", sa.String(16), nullable=True),
+        sa.Column("first_group_id", sa.Integer(), nullable=True),
+        sa.Column("first_seen", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("last_seen", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_cps_wx_user_openid", "cps_wx_user", ["openid"], unique=True)
+    op.create_index("ix_cps_wx_user_unionid", "cps_wx_user", ["unionid"])
+    op.create_index("ix_cps_wx_user_first_group_id", "cps_wx_user", ["first_group_id"])
+
+    op.add_column("cps_click", sa.Column("openid", sa.String(64), nullable=True))
+    op.create_index("ix_cps_click_openid", "cps_click", ["openid"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_cps_click_openid", table_name="cps_click")
+    op.drop_column("cps_click", "openid")
+    op.drop_index("ix_cps_wx_user_first_group_id", table_name="cps_wx_user")
+    op.drop_index("ix_cps_wx_user_unionid", table_name="cps_wx_user")
+    op.drop_index("ix_cps_wx_user_openid", table_name="cps_wx_user")
+    op.drop_table("cps_wx_user")

alembic/versions/device_kill_alert_pending.py

@@ -0,0 +1,39 @@
+"""device.kill_alert_pending (无障碍掉线「后置检测」待提醒标记)
+
+Revision ID: device_kill_alert_pending
+Revises: device_liveness_table
+Create Date: 2026-06-19
+
+后置检测 pull 版(spec/accessibility-liveness-pull-prompt.md):worker 检出心跳掉线即置此标记,
+客户端下次进 App 拉取到 → 弹「开启自启动」引导,交互后 ack 清回。与 liveness_state 解耦,故单列。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'device_kill_alert_pending'
+down_revision: Union[str, Sequence[str], None] = 'device_liveness_table'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # server_default=sa.false() 跨方言: SQLite 渲染 0 / PG 渲染 false(别用 sa.text("0"),PG 布尔严格会报错),
+    # 给存量行回填 False。
+    with op.batch_alter_table('device_liveness', schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column(
+                'kill_alert_pending',
+                sa.Boolean(),
+                nullable=False,
+                server_default=sa.false(),
+            )
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('device_liveness', schema=None) as batch_op:
+        batch_op.drop_column('kill_alert_pending')

alembic/versions/device_table.py

@@ -0,0 +1,53 @@
+"""device table (无障碍保护存活检测 + 极光推送)
+
+Revision ID: device_liveness_table
+Revises: ceb286289426
+Create Date: 2026-06-15 12:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'device_liveness_table'
+down_revision: Union[str, Sequence[str], None] = 'ceb286289426'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'device_liveness',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('device_id', sa.String(length=128), nullable=False),
+        sa.Column('registration_id', sa.String(length=64), nullable=True),
+        sa.Column('platform', sa.String(length=16), nullable=False),
+        sa.Column('app_version', sa.String(length=32), nullable=True),
+        sa.Column('ever_protected', sa.Boolean(), nullable=False),
+        sa.Column('last_heartbeat_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('last_report_protection_on', sa.Boolean(), nullable=False),
+        sa.Column('liveness_state', sa.String(length=16), nullable=False),
+        sa.Column('notified_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('user_id', 'device_id', name='uq_device_liveness_user_device'),
+    )
+    with op.batch_alter_table('device_liveness', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_device_liveness_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_device_liveness_device_id'), ['device_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_device_liveness_last_heartbeat_at'), ['last_heartbeat_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('device_liveness', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_device_liveness_last_heartbeat_at'))
+        batch_op.drop_index(batch_op.f('ix_device_liveness_device_id'))
+        batch_op.drop_index(batch_op.f('ix_device_liveness_user_id'))
+
+    op.drop_table('device_liveness')

alembic/versions/feedback_review_fields.py

@@ -0,0 +1,78 @@
+"""feedback review fields
+
+Revision ID: feedback_review_fields
+Revises: ceb286289426
+Create Date: 2026-06-22 20:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "feedback_review_fields"
+down_revision: str | Sequence[str] | None = "ceb286289426"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("feedback", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("reject_reason", sa.String(length=256), nullable=True))
+        batch_op.add_column(sa.Column("reward_coins", sa.Integer(), nullable=True))
+        batch_op.add_column(sa.Column("review_note", sa.String(length=256), nullable=True))
+        batch_op.add_column(sa.Column("reviewed_by_admin_id", sa.Integer(), nullable=True))
+        batch_op.add_column(sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True))
+        batch_op.create_index(batch_op.f("ix_feedback_status"), ["status"], unique=False)
+        batch_op.create_foreign_key(
+            batch_op.f("fk_feedback_reviewed_by_admin_id_admin_user"),
+            "admin_user",
+            ["reviewed_by_admin_id"],
+            ["id"],
+        )
+
+    feedback = sa.table(
+        "feedback",
+        sa.column("status", sa.String(length=16)),
+    )
+    op.execute(
+        feedback.update()
+        .where(feedback.c.status == "new")
+        .values(status="pending")
+    )
+    op.execute(
+        feedback.update()
+        .where(feedback.c.status == "handled")
+        .values(status="adopted")
+    )
+
+
+def downgrade() -> None:
+    feedback = sa.table(
+        "feedback",
+        sa.column("status", sa.String(length=16)),
+    )
+    op.execute(
+        feedback.update()
+        .where(feedback.c.status == "pending")
+        .values(status="new")
+    )
+    op.execute(
+        feedback.update()
+        .where(feedback.c.status == "adopted")
+        .values(status="handled")
+    )
+
+    with op.batch_alter_table("feedback", schema=None) as batch_op:
+        batch_op.drop_constraint(
+            batch_op.f("fk_feedback_reviewed_by_admin_id_admin_user"),
+            type_="foreignkey",
+        )
+        batch_op.drop_index(batch_op.f("ix_feedback_status"))
+        batch_op.drop_column("reviewed_at")
+        batch_op.drop_column("reviewed_by_admin_id")
+        batch_op.drop_column("review_note")
+        batch_op.drop_column("reward_coins")
+        batch_op.drop_column("reject_reason")

alembic/versions/launch_confirm_sample_table.py

@@ -0,0 +1,53 @@
+"""launch_confirm_sample table (启动确认窗 agent 兜底样本: LLM 放行的弹窗样本沉淀)
+
+Revision ID: launch_confirm_sample_table
+Revises: cps_wx_user
+Create Date: 2026-06-20 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "launch_confirm_sample_table"
+down_revision: Union[str, Sequence[str], None] = "cps_wx_user"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "launch_confirm_sample",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
+        sa.Column("trace_id", sa.String(length=64), nullable=True),
+        sa.Column("device_id", sa.String(length=64), nullable=True),
+        sa.Column("host_package", sa.String(length=128), nullable=True),
+        sa.Column("target_app", sa.String(length=128), nullable=True),
+        sa.Column("system_locale", sa.String(length=32), nullable=True),
+        sa.Column("exec_success", sa.Boolean(), nullable=False),
+        sa.Column("dialog_title", sa.String(length=256), nullable=True),
+        # PG 上为 JSONB,其它(SQLite)为 JSON——与模型层 with_variant 对齐
+        sa.Column("payload", sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), "postgresql"), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    with op.batch_alter_table("launch_confirm_sample", schema=None) as batch_op:
+        batch_op.create_index(batch_op.f("ix_launch_confirm_sample_created_at"), ["created_at"], unique=False)
+        batch_op.create_index(batch_op.f("ix_launch_confirm_sample_trace_id"), ["trace_id"], unique=False)
+        batch_op.create_index(batch_op.f("ix_launch_confirm_sample_device_id"), ["device_id"], unique=False)
+        batch_op.create_index(batch_op.f("ix_launch_confirm_sample_host_package"), ["host_package"], unique=False)
+        batch_op.create_index(batch_op.f("ix_launch_confirm_sample_system_locale"), ["system_locale"], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("launch_confirm_sample", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_launch_confirm_sample_system_locale"))
+        batch_op.drop_index(batch_op.f("ix_launch_confirm_sample_host_package"))
+        batch_op.drop_index(batch_op.f("ix_launch_confirm_sample_device_id"))
+        batch_op.drop_index(batch_op.f("ix_launch_confirm_sample_trace_id"))
+        batch_op.drop_index(batch_op.f("ix_launch_confirm_sample_created_at"))
+
+    op.drop_table("launch_confirm_sample")

app/admin/main.py

@@ -14,15 +14,18 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.admin.routers.ad_audit import router as ad_audit_router
+from app.admin.routers.ad_config import router as ad_config_router
 from app.admin.routers.ad_revenue import router as ad_revenue_router
 from app.admin.routers.admins import router as admins_router
 from app.admin.routers.audit import router as audit_router
 from app.admin.routers.auth import router as auth_router
+from app.admin.routers.comparison import router as comparison_router
 from app.admin.routers.config import router as config_router
 from app.admin.routers.cps import router as cps_router
 from app.admin.routers.dashboard import router as dashboard_router
 from app.admin.routers.ops_stat_config import router as ops_stat_config_router
 from app.admin.routers.feedback import router as feedback_router
+from app.admin.routers.feedback_qr import router as feedback_qr_router
 from app.admin.routers.onboarding import router as onboarding_router
 from app.admin.routers.ops_marquee_seed import router as ops_marquee_seed_router
 from app.admin.routers.price_report import router as price_report_router
@@ -88,9 +91,12 @@ admin_app.include_router(wallet_router)
 admin_app.include_router(withdraw_router)
 admin_app.include_router(price_report_router)
 admin_app.include_router(feedback_router)
+admin_app.include_router(feedback_qr_router)
 admin_app.include_router(admins_router)
 admin_app.include_router(audit_router)
 admin_app.include_router(config_router)
+admin_app.include_router(comparison_router)
 admin_app.include_router(cps_router)
 admin_app.include_router(ad_audit_router)
+admin_app.include_router(ad_config_router)
 admin_app.include_router(ad_revenue_router)

app/admin/repositories/cps.py

@@ -5,11 +5,11 @@
 """
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from decimal import Decimal, InvalidOperation
 from uuid import uuid4
 
-from sqlalchemy import desc, select
+from sqlalchemy import desc, func, select
 from sqlalchemy.orm import Session
 
 from app.admin.repositories.queries import _as_utc, offset_paginate
@@ -17,12 +17,17 @@ from app.integrations import meituan
 from app.repositories import cps_link as cps_link_repo
 from app.models.cps_activity import CpsActivity
 from app.models.cps_group import CpsGroup
+from app.models.cps_link import CpsClick
 from app.models.cps_order import CpsOrder
+from app.models.cps_wx_user import CpsWxUser
 
 # 美团订单状态:取消(4)/风控(5)不计佣金;结算(6)为佣金真正到账
 _INVALID_STATUS = {"4", "5"}
 _SETTLED_STATUS = "6"
 
+# CPS 点击时序按北京时区分桶(运营看的是北京时间)
+_BJ_TZ = timezone(timedelta(hours=8))
+
 
 # ───────────── 单位换算 ─────────────
 def _yuan_to_cents(v: object) -> int | None:
@@ -71,19 +76,23 @@ def list_groups(
 
 
 def create_group(
-    db: Session, *, name: str, sid: str | None = None,
+    db: Session, *, name: str, platforms: list[str], sid: str | None = None,
     member_count: int | None = None, remark: str | None = None, commit: bool = True,
 ) -> CpsGroup:
-    """建群。sid 留空 → 自动 g<id>(先 flush 拿 id 再回填)。"""
+    """建群。含 meituan 才有 sid(留空自动 g<id>);纯淘宝/京东 sid=None(那俩不支持 sid)。"""
+    has_meituan = "meituan" in (platforms or [])
+    # 含美团:用填的 sid,或临时占位待回填 g<id>;不含美团:sid 恒 None
+    seed_sid = (sid or f"tmp{uuid4().hex[:20]}") if has_meituan else None
     group = CpsGroup(
         name=name,
-        sid=sid or f"tmp{uuid4().hex[:20]}",  # 临时唯一占位,留空时下面回填 g<id>
+        platforms=list(platforms or []),
+        sid=seed_sid,
         member_count=member_count,
         remark=remark,
     )
     db.add(group)
     db.flush()
-    if not sid:
+    if has_meituan and not sid:
         group.sid = f"g{group.id}"
         db.flush()
     if commit:
@@ -94,11 +103,14 @@ def create_group(
 
 def update_group(
     db: Session, group: CpsGroup, *, name: str | None = None,
+    platforms: list[str] | None = None,
     member_count: int | None = None, status: str | None = None,
     remark: str | None = None, commit: bool = True,
 ) -> CpsGroup:
     if name is not None:
         group.name = name
+    if platforms is not None:
+        group.platforms = list(platforms)
     if member_count is not None:
         group.member_count = member_count
     if status is not None:
@@ -113,6 +125,15 @@ def update_group(
     return group
 
 
+def delete_group(db: Session, group: CpsGroup, *, commit: bool = True) -> None:
+    """硬删群。不级联删已生成的 cps_link(已发链接继续可用);该群历史点击/订单按 sid 仍在库。"""
+    db.delete(group)
+    if commit:
+        db.commit()
+    else:
+        db.flush()
+
+
 # ───────────── 活动 ─────────────
 def get_activity(db: Session, activity_id: int) -> CpsActivity | None:
     return db.get(CpsActivity, activity_id)
@@ -130,13 +151,29 @@ def list_activities(
     return offset_paginate(db, stmt, (desc(CpsActivity.id),), limit=limit, cursor=cursor)
 
 
+def list_activity_images(db: Session) -> list[str]:
+    """已用过的活动落地页图(distinct 非空 image_url),供新建活动复用选择。"""
+    rows = (
+        db.execute(
+            select(CpsActivity.image_url)
+            .where(CpsActivity.image_url.is_not(None))
+            .distinct()
+        )
+        .scalars()
+        .all()
+    )
+    return [r for r in rows if r]
+
+
 def create_activity(
     db: Session, *, name: str, platform: str = "meituan", act_id: str | None = None,
-    product_view_sign: str | None = None, remark: str | None = None, commit: bool = True,
+    product_view_sign: str | None = None, payload: str | None = None,
+    image_url: str | None = None, remark: str | None = None, commit: bool = True,
 ) -> CpsActivity:
     activity = CpsActivity(
         name=name, platform=platform, act_id=act_id,
-        product_view_sign=product_view_sign, remark=remark,
+        product_view_sign=product_view_sign, payload=payload,
+        image_url=image_url, remark=remark,
     )
     db.add(activity)
     if commit:
@@ -147,6 +184,46 @@ def create_activity(
     return activity
 
 
+def update_activity(
+    db: Session, activity: CpsActivity, *, name: str | None = None,
+    platform: str | None = None, act_id: str | None = None,
+    product_view_sign: str | None = None, payload: str | None = None,
+    image_url: str | None = None, remark: str | None = None,
+    status: str | None = None, commit: bool = True,
+) -> CpsActivity:
+    if name is not None:
+        activity.name = name
+    if platform is not None:
+        activity.platform = platform
+    if act_id is not None:
+        activity.act_id = act_id
+    if product_view_sign is not None:
+        activity.product_view_sign = product_view_sign
+    if payload is not None:
+        activity.payload = payload
+    if image_url is not None:
+        activity.image_url = image_url
+    if remark is not None:
+        activity.remark = remark
+    if status is not None:
+        activity.status = status
+    if commit:
+        db.commit()
+        db.refresh(activity)
+    else:
+        db.flush()
+    return activity
+
+
+def delete_activity(db: Session, activity: CpsActivity, *, commit: bool = True) -> None:
+    """硬删活动。不级联删 cps_link(已发链接继续可用;淘宝落地页缺活动时取图走兜底默认图)。"""
+    db.delete(activity)
+    if commit:
+        db.commit()
+    else:
+        db.flush()
+
+
 # ───────────── 订单(对账) ─────────────
 def _map_order_fields(r: dict) -> dict:
     """美团 query_order 单条 dataList → CpsOrder 字段(金额转分、时间转 datetime)。"""
@@ -233,55 +310,217 @@ def group_stats(
     """按 sid 聚合订单 + join 群信息。已建但本期无单的活跃群也列出(全 0)。
     未归群的 sid(历史/其它来源)单独成行 group_id=None。按预估佣金降序。
     """
-    stmt = select(CpsOrder)
+    ostmt = select(CpsOrder)
     if date_from is not None:
-        stmt = stmt.where(CpsOrder.pay_time >= _as_utc(date_from))
+        ostmt = ostmt.where(CpsOrder.pay_time >= _as_utc(date_from))
     if date_to is not None:
-        stmt = stmt.where(CpsOrder.pay_time <= _as_utc(date_to))
-    orders = list(db.execute(stmt).scalars().all())
+        ostmt = ostmt.where(CpsOrder.pay_time <= _as_utc(date_to))
+    orders_by_sid: dict[str | None, list[CpsOrder]] = {}
+    for o in db.execute(ostmt).scalars().all():
+        orders_by_sid.setdefault(o.sid, []).append(o)
 
-    groups = {g.sid: g for g in db.execute(select(CpsGroup)).scalars().all()}
+    clicks = cps_link_repo.click_stats_by_group(db, date_from=date_from, date_to=date_to)
+    groups = list(db.execute(select(CpsGroup)).scalars().all())
 
-    buckets: dict[str | None, list[CpsOrder]] = {}
-    for o in orders:
-        buckets.setdefault(o.sid, []).append(o)
-
-    rows: list[dict] = []
-    for sid, items in buckets.items():
-        g = groups.get(sid) if sid else None
+    def _order_agg(items: list[CpsOrder]) -> dict:
         valid = [o for o in items if o.mt_status not in _INVALID_STATUS]
         settled = [o for o in items if o.mt_status == _SETTLED_STATUS]
         canceled = [o for o in items if o.mt_status in _INVALID_STATUS]
-        rows.append({
-            "group_id": g.id if g else None,
-            "sid": sid,
-            "name": g.name if g else (sid or "（无 sid 归属）"),
-            "member_count": g.member_count if g else None,
+        return {
             "order_count": len(valid),
             "settled_count": len(settled),
             "canceled_count": len(canceled),
             "gmv_cents": sum(o.pay_price_cents or 0 for o in valid),
             "est_commission_cents": sum(o.commission_cents or 0 for o in valid),
             "settled_commission_cents": sum(o.commission_cents or 0 for o in settled),
-        })
+        }
 
-    # 已建的活跃群但本期无单 → 补 0 行,让运营看到全部群
-    seen = set(buckets.keys())
-    for sid, g in groups.items():
-        if sid not in seen and g.status == "active":
-            rows.append({
-                "group_id": g.id, "sid": sid, "name": g.name,
-                "member_count": g.member_count, "order_count": 0,
-                "settled_count": 0, "canceled_count": 0, "gmv_cents": 0,
-                "est_commission_cents": 0, "settled_commission_cents": 0,
-            })
+    # 淘宝/京东无法对账 → 对账字段全 None(前端显示 "-")
+    _no_recon = {
+        "order_count": None, "settled_count": None, "canceled_count": None,
+        "gmv_cents": None, "est_commission_cents": None, "settled_commission_cents": None,
+    }
 
-    # 合并点击数据(按 group_id):点击只对生成过我们短链的群有,未归群行(group_id=None)恒 0
-    clicks = cps_link_repo.click_stats_by_group(db, date_from=date_from, date_to=date_to)
-    for r in rows:
-        c = clicks.get(r["group_id"]) if r["group_id"] is not None else None
-        r["click_pv"] = c["pv"] if c else 0
-        r["click_uv"] = c["uv"] if c else 0
+    rows: list[dict] = []
+    seen_sids: set[str] = set()
+    for g in groups:
+        if g.status != "active":
+            continue
+        c = clicks.get(g.id) or {}
+        row = {
+            "group_id": g.id, "sid": g.sid, "name": g.name,
+            "platforms": list(g.platforms or []), "member_count": g.member_count,
+            "click_pv": c.get("pv", 0), "click_uv": c.get("uv", 0),
+            "copy_pv": c.get("copy_pv", 0), "copy_uv": c.get("copy_uv", 0),
+        }
+        # 对账只对美团群(有 sid);淘宝/京东 → None
+        if "meituan" in (g.platforms or []) and g.sid:
+            row.update(_order_agg(orders_by_sid.get(g.sid, [])))
+            seen_sids.add(g.sid)
+        else:
+            row.update(_no_recon)
+        rows.append(row)
 
-    rows.sort(key=lambda x: x["est_commission_cents"], reverse=True)
+    # 未归群的历史美团 sid(如 wonderableai):单列,有对账无点击
+    for sid, items in orders_by_sid.items():
+        if sid is None or sid in seen_sids:
+            continue
+        row = {
+            "group_id": None, "sid": sid, "name": sid, "platforms": ["meituan"],
+            "member_count": None, "click_pv": 0, "click_uv": 0, "copy_pv": 0, "copy_uv": 0,
+        }
+        row.update(_order_agg(items))
+        rows.append(row)
+
+    # 佣金降序(None 当 0),次按点击
+    rows.sort(key=lambda x: ((x["est_commission_cents"] or 0), x["click_pv"]), reverse=True)
     return rows
+
+
+def group_click_timeseries(
+    db: Session, *, group_id: int, granularity: str,
+    start: datetime, end: datetime,
+) -> list[dict]:
+    """该群点击时序(北京时区分桶,granularity=day|hour)。
+
+    每桶:click_pv/uv(visit)+copy_pv/uv;UV=distinct(ip,ua)。**生成连续桶(无数据补 0)**,
+    让折线图 x 轴按所选范围铺满、不断裂(CPS 数据稀疏,补零是关键)。
+    """
+    rows = db.execute(
+        select(CpsClick.clicked_at, CpsClick.event_type, CpsClick.ip, CpsClick.ua)
+        .where(CpsClick.group_id == group_id)
+        .where(CpsClick.clicked_at >= _as_utc(start))
+        .where(CpsClick.clicked_at <= _as_utc(end))
+    ).all()
+
+    agg: dict = {}  # bucket_key -> {vp, vu(set), cp, cu(set)}
+    for clicked_at, event_type, ip, ua in rows:
+        # naive(本地 SQLite 读回无 tz)按 UTC 兜底,再转北京——与 queries._as_utc 约定一致,
+        # 否则 astimezone 会把 UTC 瞬刻当系统本地时区解释,分桶整体偏移。
+        ca = clicked_at if clicked_at.tzinfo else clicked_at.replace(tzinfo=timezone.utc)
+        bj = ca.astimezone(_BJ_TZ)
+        key = bj.strftime("%Y-%m-%d") if granularity == "day" else bj.hour
+        b = agg.setdefault(key, {"vp": 0, "vu": set(), "cp": 0, "cu": set()})
+        uid = f"{ip or ''}|{ua or ''}"
+        if event_type == "copy":
+            b["cp"] += 1
+            b["cu"].add(uid)
+        else:
+            b["vp"] += 1
+            b["vu"].add(uid)
+
+    def _point(label: str, b: dict | None) -> dict:
+        return {
+            "label": label,
+            "click_pv": b["vp"] if b else 0,
+            "click_uv": len(b["vu"]) if b else 0,
+            "copy_pv": b["cp"] if b else 0,
+            "copy_uv": len(b["cu"]) if b else 0,
+        }
+
+    points: list[dict] = []
+    if granularity == "day":
+        cur = start.astimezone(_BJ_TZ).date()
+        last = end.astimezone(_BJ_TZ).date()
+        while cur <= last:
+            points.append(_point(cur.strftime("%m-%d"), agg.get(cur.strftime("%Y-%m-%d"))))
+            cur += timedelta(days=1)
+    else:
+        for h in range(24):
+            points.append(_point(f"{h:02d}:00", agg.get(h)))
+    return points
+
+
+def group_order_daily(
+    db: Session, *, sid: str, start: datetime, end: datetime,
+) -> dict[str, dict]:
+    """美团群订单按天(北京时区,key=YYYY-MM-DD)聚合。口径与 group_stats._order_agg 一致:
+    取消(4)/风控(5)不计有效;结算只数 status=6。退款佣金取当天全部单的 refund_profit_cents 之和。
+    返回 {date: {order_count, canceled_count, gmv_cents, est_commission_cents,
+    refund_profit_cents, settled_commission_cents}};无单的天不在 dict 里(端点侧补零)。
+    """
+    rows = (
+        db.execute(
+            select(CpsOrder)
+            .where(CpsOrder.sid == sid)
+            .where(CpsOrder.pay_time >= _as_utc(start))
+            .where(CpsOrder.pay_time <= _as_utc(end))
+        )
+        .scalars()
+        .all()
+    )
+    by_day: dict[str, list] = {}
+    for o in rows:
+        if not o.pay_time:
+            continue
+        pt = o.pay_time if o.pay_time.tzinfo else o.pay_time.replace(tzinfo=timezone.utc)
+        d = pt.astimezone(_BJ_TZ).strftime("%Y-%m-%d")
+        by_day.setdefault(d, []).append(o)
+
+    out: dict[str, dict] = {}
+    for d, items in by_day.items():
+        valid = [o for o in items if o.mt_status not in _INVALID_STATUS]
+        settled = [o for o in items if o.mt_status == _SETTLED_STATUS]
+        canceled = [o for o in items if o.mt_status in _INVALID_STATUS]
+        out[d] = {
+            "order_count": len(valid),
+            "canceled_count": len(canceled),
+            "gmv_cents": sum(o.pay_price_cents or 0 for o in valid),
+            "est_commission_cents": sum(o.commission_cents or 0 for o in valid),
+            "refund_profit_cents": sum(o.refund_profit_cents or 0 for o in items),
+            "settled_commission_cents": sum(o.commission_cents or 0 for o in settled),
+        }
+    return out
+
+
+def group_wx_users(db: Session, *, group_id: int, limit: int = 200) -> list[dict]:
+    """该群来过的微信用户:在本群有带 openid 点击的所有用户 + 本群 visit/copy 次数 + 画像。
+
+    用「本群点击」判定归属,而非 cps_wx_user.first_group_id —— 同一用户会在多个群活动,
+    first_group_id 只记首次授权群,会漏掉"先在别处授权、cookie 已存、又来本群"的用户。
+    copy=本群点「复制口令」次数(领券意向),visit=进落地页次数。按本群首次点击倒序。
+    昵称/头像来自授权画像;美团/京东群只 302 跳转、无 userinfo 触发点,故多为空。
+    """
+    rows = db.execute(
+        select(CpsClick.openid, CpsClick.event_type, func.count())
+        .where(CpsClick.group_id == group_id)
+        .where(CpsClick.openid.is_not(None))
+        .group_by(CpsClick.openid, CpsClick.event_type)
+    ).all()
+    if not rows:
+        return []
+    stat: dict[str, dict] = {}
+    for openid, event_type, cnt in rows:
+        s = stat.setdefault(openid, {"visit": 0, "copy": 0})
+        if event_type == "copy":
+            s["copy"] = cnt
+        else:
+            s["visit"] = cnt
+    openids = list(stat.keys())
+    # 本群每个 openid 的首次点击时间(排序 + 展示"首次进入")
+    first_seen = dict(
+        db.execute(
+            select(CpsClick.openid, func.min(CpsClick.clicked_at))
+            .where(CpsClick.group_id == group_id)
+            .where(CpsClick.openid.is_not(None))
+            .group_by(CpsClick.openid)
+        ).all()
+    )
+    # 关联画像(未授权 userinfo 的昵称/头像为空)
+    users = {
+        u.openid: u
+        for u in db.execute(select(CpsWxUser).where(CpsWxUser.openid.in_(openids))).scalars().all()
+    }
+    result = [
+        {
+            "openid": openid,
+            "nickname": users[openid].nickname if openid in users else None,
+            "headimgurl": users[openid].headimgurl if openid in users else None,
+            "first_seen": first_seen.get(openid),
+            "visit_count": stat[openid]["visit"],
+            "copy_count": stat[openid]["copy"],
+        }
+        for openid in openids
+    ]
+    result.sort(key=lambda x: x["first_seen"], reverse=True)
+    return result[:limit]

app/admin/repositories/mutations.py

@@ -56,6 +56,35 @@ def update_feedback_status(
     return feedback
 
 
+def review_feedback(
+    db: Session,
+    feedback: Feedback,
+    *,
+    status: str,
+    reviewed_by_admin_id: int,
+    reward_coins: int | None = None,
+    reject_reason: str | None = None,
+    review_note: str | None = None,
+    commit: bool = True,
+) -> Feedback:
+    """审核反馈:置 adopted/rejected + 记录奖励/原因/审核人/审核时间。
+
+    发金币(wallet.grant_coins)由 router 在同一事务里调,确保状态、金币流水、审计一起提交。
+    """
+    feedback.status = status
+    feedback.reward_coins = reward_coins
+    feedback.reject_reason = reject_reason
+    feedback.review_note = review_note
+    feedback.reviewed_by_admin_id = reviewed_by_admin_id
+    feedback.reviewed_at = datetime.now(CN_TZ).replace(tzinfo=None)
+    if commit:
+        db.commit()
+        db.refresh(feedback)
+    else:
+        db.flush()
+    return feedback
+
+
 def review_price_report(
     db: Session,
     report: PriceReport,

app/admin/repositories/queries.py

@@ -11,6 +11,9 @@ from zoneinfo import ZoneInfo
 from sqlalchemy import Select, asc, desc, func, or_, select
 from sqlalchemy.orm import Session
 
+from app.core import rewards
+from app.models.ad_feed_reward import AdFeedRewardRecord
+from app.models.ad_reward import AdRewardRecord
 from app.models.admin import AdminAuditLog
 from app.models.comparison import ComparisonRecord
 from app.models.feedback import Feedback
@@ -19,6 +22,16 @@ from app.models.price_report import PriceReport
 from app.models.user import User
 from app.models.wallet import CashTransaction, CoinAccount, CoinTransaction, WithdrawOrder
 
+# 折算成可提现现金时,非广告金币来源的排除集(广告单独统计、人工调整不算"赚取")
+_NON_TASK_BIZ_TYPES = ("reward_video", "feed_ad_reward", "admin_grant", "admin_deduct")
+
+# 信息流点位场景 → 金币记录「赚取途径」展示名;NULL/未知 = 历史未分类。
+_FEED_SCENE_LABEL = {
+    "comparison": "比价信息流",
+    "coupon": "领券信息流",
+    "welfare": "福利信息流",
+}
+
 
 def cursor_paginate(
     db: Session, stmt: Select, id_col, *, limit: int, cursor: int | None
@@ -109,6 +122,63 @@ def list_users(
     return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)
 
 
+def _attach_user_info(db: Session, records: list[ComparisonRecord]) -> None:
+    """给每条比价记录瞬态挂 phone/nickname(非 DB 列,供 admin schema from_attributes 读)。"""
+    uids = {r.user_id for r in records}
+    if not uids:
+        return
+    rows = db.execute(
+        select(User.id, User.phone, User.nickname).where(User.id.in_(uids))
+    ).all()
+    umap = {uid: (phone, nick) for uid, phone, nick in rows}
+    for r in records:
+        phone, nick = umap.get(r.user_id, (None, None))
+        r.phone = phone
+        r.nickname = nick
+
+
+def list_comparison_records(
+    db: Session,
+    *,
+    user_id: int | None = None,
+    phone: str | None = None,
+    status: str | None = None,
+    business_type: str | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[ComparisonRecord], int | None, int]:
+    """admin 比价记录列表(debug)。按 user_id 精确 或 phone 前缀定位用户 + status/业务类型筛,
+    offset 分页(创建时间倒序、id 兜底)。join User 取 phone/nickname 瞬态挂记录上。"""
+    stmt = select(ComparisonRecord)
+    if user_id is not None:
+        stmt = stmt.where(ComparisonRecord.user_id == user_id)
+    if phone:
+        stmt = stmt.where(
+            ComparisonRecord.user_id.in_(
+                select(User.id).where(User.phone.like(f"{phone}%"))
+            )
+        )
+    if status:
+        stmt = stmt.where(ComparisonRecord.status == status)
+    if business_type:
+        stmt = stmt.where(ComparisonRecord.business_type == business_type)
+    items, next_cursor, total = offset_paginate(
+        db, stmt,
+        (desc(ComparisonRecord.created_at), desc(ComparisonRecord.id)),
+        limit=limit, cursor=cursor,
+    )
+    _attach_user_info(db, items)
+    return items, next_cursor, total
+
+
+def get_comparison_record(db: Session, record_id: int) -> ComparisonRecord | None:
+    """admin 取单条比价记录(任意用户,不限本人;附 phone/nickname 瞬态)。"""
+    rec = db.get(ComparisonRecord, record_id)
+    if rec is not None:
+        _attach_user_info(db, [rec])
+    return rec
+
+
 def list_onboarding_devices(db: Session, *, limit: int = 500) -> list[dict]:
     """按设备(device_id, ANDROID_ID)聚合 onboarding_completion:每台设备走过引导的账号数 +
     最近完成时间,按最近完成倒序。设备维度新手引导管理用。没走过引导的设备不在表里(本就会
@@ -274,6 +344,38 @@ def _as_utc(value: datetime) -> datetime:
     return value.astimezone(timezone.utc)
 
 
+def withdraw_list_enrichment(db: Session, user_ids: list[int]) -> dict[int, dict]:
+    """批量富化提现单列表:按本页 user_id 取 手机号/昵称 + 各自累计成功提现金额(分)。
+
+    两条聚合查询搞定(避免逐行 N+1)。累计口径与 get_user_overview 的 withdraw_success_cents
+    完全一致:SUM(amount_cents) WHERE status='success'。返回 {user_id: {phone, nickname,
+    cumulative_success_cents}};某 user_id 查不到用户则不在 dict 里(路由侧回退到默认值)。
+    """
+    uniq = list(set(user_ids))
+    if not uniq:
+        return {}
+    success_rows = db.execute(
+        select(
+            WithdrawOrder.user_id,
+            func.coalesce(func.sum(WithdrawOrder.amount_cents), 0),
+        )
+        .where(WithdrawOrder.user_id.in_(uniq), WithdrawOrder.status == "success")
+        .group_by(WithdrawOrder.user_id)
+    ).all()
+    success_map = {uid: int(total) for uid, total in success_rows}
+    users = db.execute(
+        select(User.id, User.phone, User.nickname).where(User.id.in_(uniq))
+    ).all()
+    return {
+        uid: {
+            "phone": phone,
+            "nickname": nickname,
+            "cumulative_success_cents": success_map.get(uid, 0),
+        }
+        for uid, phone, nickname in users
+    }
+
+
 def list_feedbacks(
     db: Session,
     *,
@@ -391,15 +493,19 @@ def withdraw_risk_flags(
         created_at = user.created_at.replace(tzinfo=timezone.utc) if user.created_at.tzinfo is None else user.created_at
         if datetime.now(timezone.utc) - created_at < timedelta(hours=24):
             flags.append("新注册用户")
-    failed_or_rejected = sum(1 for item in recent_withdraws if item.status in {"failed", "rejected"})
-    if failed_or_rejected:
-        flags.append(f"历史异常提现{failed_or_rejected}笔")
+    # 历史异常提现拆「拒绝」「失败」两类(口径不同:拒绝=人工驳回退款,失败=打款失败退款)
+    rejected_n = sum(1 for item in recent_withdraws if item.status == "rejected")
+    failed_n = sum(1 for item in recent_withdraws if item.status == "failed")
+    if rejected_n:
+        flags.append(f"提现拒绝{rejected_n}笔")
+    if failed_n:
+        flags.append(f"提现失败{failed_n}笔")
     recent_reviewing = sum(1 for item in recent_withdraws if item.status == "reviewing")
     if recent_reviewing >= 3:
         flags.append(f"待审核提现偏多:{recent_reviewing}笔")
     if cash_balance_cents < 0:
         flags.append("现金余额为负")
-    score = min(100, len(flags) * 20 + failed_or_rejected * 10)
+    score = min(100, len(flags) * 20 + (rejected_n + failed_n) * 10)
     return flags, score
 
 
@@ -489,6 +595,198 @@ def get_user_overview(db: Session, user_id: int) -> dict | None:
     }
 
 
+def _window_conds(col, date_from: datetime | None, date_to: datetime | None) -> list:
+    """把 [date_from, date_to] 转成对 col(created_at)的过滤条件;都为 None = 全量(注册至今)。"""
+    conds = []
+    if date_from is not None:
+        conds.append(col >= _as_utc_naive(date_from))
+    if date_to is not None:
+        conds.append(col <= _as_utc_naive(date_to))
+    return conds
+
+
+def _coins_to_cents(coins: int) -> int:
+    """累计金币折算成可提现现金(分)。COIN_PER_YUAN=10000 → 100 金币 = 1 分。"""
+    return round(coins / (rewards.COIN_PER_YUAN / 100))
+
+
+def user_reward_stats(
+    db: Session,
+    user_id: int,
+    *,
+    date_from: datetime | None = None,
+    date_to: datetime | None = None,
+) -> dict:
+    """提现详情「用户统计区」10 项。窗口作用于除「现金余额」外的所有项(余额是当前快照)。
+
+    口径:激励视频/信息流只统计 granted;数量——视频按条数、信息流按份数(unit_count 累加);
+    平均 eCPM 用原始分值(分/千次)按记录取算术平均;各「提现」= 该来源累计金币折现。
+    传统任务 = 窗口内正向金币中,排除广告(reward_video/feed_ad_reward)与人工调整后的折现。
+    """
+    wd_success = db.execute(
+        select(func.coalesce(func.sum(WithdrawOrder.amount_cents), 0)).where(
+            WithdrawOrder.user_id == user_id,
+            WithdrawOrder.status == "success",
+            *_window_conds(WithdrawOrder.created_at, date_from, date_to),
+        )
+    ).scalar_one()
+    wd_total = db.execute(
+        select(func.count(WithdrawOrder.id)).where(
+            WithdrawOrder.user_id == user_id,
+            *_window_conds(WithdrawOrder.created_at, date_from, date_to),
+        )
+    ).scalar_one()
+
+    acc = db.get(CoinAccount, user_id)  # 现金余额:当前快照,不随窗口
+    cash_balance = acc.cash_balance_cents if acc else 0
+
+    rv = list(db.execute(
+        select(AdRewardRecord).where(
+            AdRewardRecord.user_id == user_id,
+            AdRewardRecord.reward_scene == "reward_video",
+            AdRewardRecord.status == "granted",
+            *_window_conds(AdRewardRecord.created_at, date_from, date_to),
+        )
+    ).scalars())
+    rv_ecpms = [rewards.parse_ecpm_fen(r.ecpm_raw) for r in rv if r.ecpm_raw]
+    rv_coins = sum(r.coin for r in rv)
+
+    feed = list(db.execute(
+        select(AdFeedRewardRecord).where(
+            AdFeedRewardRecord.user_id == user_id,
+            AdFeedRewardRecord.status == "granted",
+            *_window_conds(AdFeedRewardRecord.created_at, date_from, date_to),
+        )
+    ).scalars())
+    feed_ecpms = [rewards.parse_ecpm_fen(f.ecpm_raw) for f in feed if f.ecpm_raw]
+    feed_coins = sum(f.coin for f in feed)
+
+    trad_coins = db.execute(
+        select(func.coalesce(func.sum(CoinTransaction.amount), 0)).where(
+            CoinTransaction.user_id == user_id,
+            CoinTransaction.amount > 0,
+            CoinTransaction.biz_type.not_in(_NON_TASK_BIZ_TYPES),
+            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+        )
+    ).scalar_one()
+
+    return {
+        "withdraw_success_cents": int(wd_success),
+        "cash_balance_cents": int(cash_balance),
+        "withdraw_total": int(wd_total),
+        "traditional_task_cash_cents": _coins_to_cents(int(trad_coins)),
+        "reward_video_count": len(rv),
+        "reward_video_avg_ecpm": round(sum(rv_ecpms) / len(rv_ecpms), 2) if rv_ecpms else 0.0,
+        "reward_video_cash_cents": _coins_to_cents(rv_coins),
+        "feed_count": int(sum(f.unit_count for f in feed)),
+        "feed_avg_ecpm": round(sum(feed_ecpms) / len(feed_ecpms), 2) if feed_ecpms else 0.0,
+        "feed_cash_cents": _coins_to_cents(feed_coins),
+    }
+
+
+def user_coin_records(
+    db: Session,
+    user_id: int,
+    *,
+    date_from: datetime | None = None,
+    date_to: datetime | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[dict], int | None, int]:
+    """金币发放记录(提现详情底部表),按时间倒序、offset 游标分页 + 总数。
+
+    合并三类来源(Phase1 信息流不分比价/领券):
+      - 激励视频 / 签到膨胀 = ad_reward_record(granted)
+      - 信息流广告        = ad_feed_reward_record(granted)
+      - 签到             = coin_transaction(biz_type='signin')
+    每来源各取 offset+limit+1 条(倒序)再归并切片,避免 union 全量拉取。
+    """
+    offset = max(cursor or 0, 0)
+    fetch = offset + limit + 1
+    rows: list[dict] = []
+
+    for rec in db.execute(
+        select(AdRewardRecord)
+        .where(
+            AdRewardRecord.user_id == user_id,
+            AdRewardRecord.status == "granted",
+            *_window_conds(AdRewardRecord.created_at, date_from, date_to),
+        )
+        .order_by(AdRewardRecord.created_at.desc())
+        .limit(fetch)
+    ).scalars():
+        is_video = rec.reward_scene == "reward_video"
+        rows.append({
+            "source": rec.reward_scene,
+            "source_label": "激励视频" if is_video else "签到膨胀",
+            "created_at": rec.created_at,
+            "ecpm": rec.ecpm_raw,
+            "coin": rec.coin,
+        })
+
+    for rec in db.execute(
+        select(AdFeedRewardRecord)
+        .where(
+            AdFeedRewardRecord.user_id == user_id,
+            AdFeedRewardRecord.status == "granted",
+            *_window_conds(AdFeedRewardRecord.created_at, date_from, date_to),
+        )
+        .order_by(AdFeedRewardRecord.created_at.desc())
+        .limit(fetch)
+    ).scalars():
+        rows.append({
+            "source": "feed",
+            "source_label": _FEED_SCENE_LABEL.get(rec.feed_scene, "信息流广告"),
+            "created_at": rec.created_at,
+            "ecpm": rec.ecpm_raw,
+            "coin": rec.coin,
+        })
+
+    for rec in db.execute(
+        select(CoinTransaction)
+        .where(
+            CoinTransaction.user_id == user_id,
+            CoinTransaction.biz_type == "signin",
+            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+        )
+        .order_by(CoinTransaction.created_at.desc())
+        .limit(fetch)
+    ).scalars():
+        rows.append({
+            "source": "signin",
+            "source_label": "签到",
+            "created_at": rec.created_at,
+            "ecpm": None,
+            "coin": rec.amount,
+        })
+
+    rows.sort(key=lambda r: r["created_at"], reverse=True)
+    has_more = len(rows) > offset + limit
+
+    # 总数 = 三源在窗口内 granted 计数之和(供前端页码分页渲染页码/共 N 条)
+    def _count(model, *conds) -> int:
+        return int(db.execute(select(func.count()).select_from(model).where(*conds)).scalar_one())
+
+    total = (
+        _count(
+            AdRewardRecord, AdRewardRecord.user_id == user_id,
+            AdRewardRecord.status == "granted",
+            *_window_conds(AdRewardRecord.created_at, date_from, date_to),
+        )
+        + _count(
+            AdFeedRewardRecord, AdFeedRewardRecord.user_id == user_id,
+            AdFeedRewardRecord.status == "granted",
+            *_window_conds(AdFeedRewardRecord.created_at, date_from, date_to),
+        )
+        + _count(
+            CoinTransaction, CoinTransaction.user_id == user_id,
+            CoinTransaction.biz_type == "signin",
+            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+        )
+    )
+    return rows[offset:offset + limit], (offset + limit if has_more else None), total
+
+
 def list_price_reports(
     db: Session,
     *,

app/admin/repositories/stats.py

@@ -119,7 +119,7 @@ def dashboard_overview(db: Session) -> dict:
             "success": comparison_success,
             "success_rate": success_rate,
         },
-        "feedback": {"new": _count(Feedback, Feedback.status == "new")},
+        "feedback": {"new": _count(Feedback, Feedback.status.in_(("pending", "new")))},
         # CPS 收入数据源未接(referral-link 只换链接,转化/佣金未回收)→ 前端显示"待接入"。
         "cps": {"available": False, "note": "CPS 转化数据未接入(P2)"},
     }

app/admin/routers/ad_config.py

@@ -0,0 +1,45 @@
+"""admin 广告配置:读/写穿山甲 app_id / 各场景广告位ID / 验签密钥 / 各场景开关。
+
+存在 app_config 表的 ad_config dict(见 repositories/app_config.get_ad_config/set_ad_config)。
+客户端经 /api/v1/platform/ad-config 拉取(不含 reward_mkey)。权限 operator/finance + 审计。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Request
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.schemas.ad_config import AdConfigOut, AdConfigUpdate
+from app.models.admin import AdminUser
+from app.repositories import app_config
+
+router = APIRouter(
+    prefix="/admin/api/ad-config",
+    tags=["admin-ad-config"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=AdConfigOut, summary="广告配置(穿山甲ID/验签密钥/各场景开关)")
+def get_ad_config(db: AdminDb) -> AdConfigOut:
+    return AdConfigOut(**app_config.get_ad_config(db))
+
+
+@router.patch("", response_model=AdConfigOut, summary="改广告配置(部分更新,带审计)")
+def update_ad_config(
+    body: AdConfigUpdate,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator", "finance"))],
+    db: AdminDb,
+) -> AdConfigOut:
+    data = body.model_dump(exclude_none=True)
+    app_config.set_ad_config(db, data, admin_id=admin.id, commit=False)
+    # 审计只记改了哪些字段,不记 mkey 明文(机密)
+    write_audit(
+        db, admin, action="ad_config.set", target_type="ad_config", target_id="ad_config",
+        detail={"changed": sorted(data.keys())}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return AdConfigOut(**app_config.get_ad_config(db))

app/admin/routers/comparison.py

@@ -0,0 +1,58 @@
+"""admin 比价记录 debug:按 user_id / phone 查列表 + 单条详情(含 LLM 每次调用明细 / 原始 payload)。
+
+只读。读权限默认即可(get_current_admin),不额外 require_role(查记录是基础 debug 能力)。
+trace_url 无条件下发——admin 是内部 debug 工具,不走 C 端 user.debug_trace_enabled 权限闸。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import queries
+from app.admin.schemas.common import CursorPage
+from app.admin.schemas.comparison import AdminComparisonDetail, AdminComparisonListItem
+
+router = APIRouter(
+    prefix="/admin/api/comparison-records",
+    tags=["admin-comparison"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get(
+    "",
+    response_model=CursorPage[AdminComparisonListItem],
+    summary="比价记录列表(按 user_id/phone 筛 + 分页)",
+)
+def list_comparison_records(
+    db: AdminDb,
+    user_id: Annotated[int | None, Query()] = None,
+    phone: Annotated[str | None, Query(description="手机号前缀")] = None,
+    status: Annotated[str | None, Query(pattern="^(success|failed|cancelled)$")] = None,
+    business_type: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[AdminComparisonListItem]:
+    items, next_cursor, total = queries.list_comparison_records(
+        db, user_id=user_id, phone=phone, status=status,
+        business_type=business_type, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[AdminComparisonListItem.model_validate(r) for r in items],
+        next_cursor=next_cursor,
+        total=total,
+    )
+
+
+@router.get(
+    "/{record_id}",
+    response_model=AdminComparisonDetail,
+    summary="比价记录详情(含 LLM 每次调用明细 + 原始 payload)",
+)
+def get_comparison_record(record_id: int, db: AdminDb) -> AdminComparisonDetail:
+    rec = queries.get_comparison_record(db, record_id)
+    if rec is None:
+        raise HTTPException(status_code=404, detail="记录不存在")
+    return AdminComparisonDetail.model_validate(rec)

app/admin/routers/cps.py

@@ -1,6 +1,7 @@
-"""admin CPS 分发与对账:群(sid)管理 + 活动池 + 生成带 sid 券链接 + 美团订单对账 + 统计。
+"""admin CPS 分发与对账:群/活动管理 + 生成落地页短链 + 美团订单对账 + 统计。
 
-当前仅接美团(get_referral_link / query_order)。淘宝/京东待各自联盟凭证。
+平台:meituan(actId+sid 转链 + query_order 对账) / taobao(整段淘口令) / jd(链接)。
+淘宝/京东无 API → 只统计点击(咱落地页 PV/UV + 淘宝复制),对账字段显示 "-"。
 群/活动管理 = operator;订单对账(涉佣金) = finance;只读列表/统计 = 登录即可。
 """
 from __future__ import annotations
@@ -9,30 +10,35 @@ import time
 from datetime import datetime, timedelta, timezone
 from typing import Annotated
 
-from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, File, HTTPException, Query, Request, UploadFile
 
 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
 from app.admin.repositories import cps as cps_repo
 from app.admin.schemas.common import CursorPage
-from app.core.config import settings
-from app.repositories import cps_link as cps_link_repo
 from app.admin.schemas.cps import (
     CpsActivityCreate,
     CpsActivityOut,
+    CpsActivityUpdate,
     CpsGroupCreate,
     CpsGroupOut,
     CpsGroupStat,
     CpsGroupUpdate,
     CpsOrderOut,
     CpsReconcileResult,
-    CpsReferralLinkOut,
-    CpsReferralLinkRequest,
+    CpsReferralLinkItem,
+    CpsReferralLinksOut,
+    CpsReferralLinksRequest,
     CpsStatsOut,
 )
+from app.core import media
+from app.core.config import settings
 from app.integrations import meituan
 from app.integrations.meituan import MeituanCpsError
 from app.models.admin import AdminUser
+from app.models.cps_activity import CpsActivity
+from app.models.cps_group import CpsGroup
+from app.repositories import cps_link as cps_link_repo
 
 router = APIRouter(
     prefix="/admin/api/cps",
@@ -40,9 +46,11 @@ router = APIRouter(
     dependencies=[Depends(get_current_admin)],
 )
 
+_VALID_PLATFORMS = {"meituan", "taobao", "jd"}
 
-# ───────────── 群(sid) ─────────────
-@router.get("/groups", response_model=CursorPage[CpsGroupOut], summary="群(sid)列表")
+
+# ───────────── 群 ─────────────
+@router.get("/groups", response_model=CursorPage[CpsGroupOut], summary="群列表")
 def list_groups(
     db: AdminDb,
     keyword: Annotated[str | None, Query(max_length=100)] = None,
@@ -60,22 +68,27 @@ def list_groups(
     )
 
 
-@router.post("/groups", response_model=CpsGroupOut, summary="新建群(分配 sid)")
+@router.post("/groups", response_model=CpsGroupOut, summary="新建群")
 def create_group(
     body: CpsGroupCreate,
     request: Request,
     admin: Annotated[AdminUser, Depends(require_role("operator"))],
     db: AdminDb,
 ) -> CpsGroupOut:
-    if body.sid and cps_repo.get_group_by_sid(db, body.sid) is not None:
+    bad = [p for p in body.platforms if p not in _VALID_PLATFORMS]
+    if bad:
+        raise HTTPException(status_code=400, detail=f"非法平台: {bad}")
+    has_meituan = "meituan" in body.platforms
+    if has_meituan and body.sid and cps_repo.get_group_by_sid(db, body.sid) is not None:
         raise HTTPException(status_code=409, detail="sid 已存在")
     group = cps_repo.create_group(
-        db, name=body.name, sid=body.sid, member_count=body.member_count,
-        remark=body.remark, commit=False,
+        db, name=body.name, platforms=body.platforms, sid=body.sid,
+        member_count=body.member_count, remark=body.remark, commit=False,
     )
     write_audit(
         db, admin, action="cps.group.create", target_type="cps_group", target_id=group.id,
-        detail={"sid": group.sid, "name": group.name}, ip=get_client_ip(request), commit=False,
+        detail={"name": group.name, "platforms": group.platforms, "sid": group.sid},
+        ip=get_client_ip(request), commit=False,
     )
     db.commit()
     db.refresh(group)
@@ -93,9 +106,13 @@ def update_group(
     group = cps_repo.get_group(db, group_id)
     if group is None:
         raise HTTPException(status_code=404, detail="群不存在")
+    if body.platforms is not None:
+        bad = [p for p in body.platforms if p not in _VALID_PLATFORMS]
+        if bad:
+            raise HTTPException(status_code=400, detail=f"非法平台: {bad}")
     cps_repo.update_group(
-        db, group, name=body.name, member_count=body.member_count,
-        status=body.status, remark=body.remark, commit=False,
+        db, group, name=body.name, platforms=body.platforms,
+        member_count=body.member_count, status=body.status, remark=body.remark, commit=False,
     )
     write_audit(
         db, admin, action="cps.group.update", target_type="cps_group", target_id=group_id,
@@ -106,6 +123,26 @@ def update_group(
     return CpsGroupOut.model_validate(group)
 
 
+@router.delete("/groups/{group_id}", summary="删除群")
+def delete_group(
+    group_id: int,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> dict:
+    group = cps_repo.get_group(db, group_id)
+    if group is None:
+        raise HTTPException(status_code=404, detail="群不存在")
+    write_audit(
+        db, admin, action="cps.group.delete", target_type="cps_group", target_id=group_id,
+        detail={"name": group.name, "sid": group.sid, "platforms": list(group.platforms or [])},
+        ip=get_client_ip(request), commit=False,
+    )
+    cps_repo.delete_group(db, group, commit=False)
+    db.commit()
+    return {"ok": True}
+
+
 # ───────────── 活动 ─────────────
 @router.get("/activities", response_model=CursorPage[CpsActivityOut], summary="活动列表")
 def list_activities(
@@ -132,15 +169,23 @@ def create_activity(
     admin: Annotated[AdminUser, Depends(require_role("operator"))],
     db: AdminDb,
 ) -> CpsActivityOut:
-    if not body.act_id and not body.product_view_sign:
-        raise HTTPException(status_code=400, detail="act_id 或 product_view_sign 必填其一")
+    if body.platform == "meituan":
+        if not body.act_id and not body.product_view_sign:
+            raise HTTPException(status_code=400, detail="美团活动需填 actId 或 productViewSign")
+    else:  # taobao / jd
+        if not body.payload:
+            label = "淘口令" if body.platform == "taobao" else "推广链接"
+            raise HTTPException(status_code=400, detail=f"{body.platform} 活动需填{label}")
+        if body.platform == "taobao" and not body.image_url:
+            raise HTTPException(status_code=400, detail="淘宝活动需提供落地页图(上传或选已有)")
     activity = cps_repo.create_activity(
         db, name=body.name, platform=body.platform, act_id=body.act_id,
-        product_view_sign=body.product_view_sign, remark=body.remark, commit=False,
+        product_view_sign=body.product_view_sign, payload=body.payload,
+        image_url=media.to_abs_media_url(body.image_url), remark=body.remark, commit=False,
     )
     write_audit(
         db, admin, action="cps.activity.create", target_type="cps_activity", target_id=activity.id,
-        detail={"name": activity.name, "act_id": activity.act_id, "platform": activity.platform},
+        detail={"name": activity.name, "platform": activity.platform},
         ip=get_client_ip(request), commit=False,
     )
     db.commit()
@@ -148,65 +193,150 @@ def create_activity(
     return CpsActivityOut.model_validate(activity)
 
 
-# ───────────── 转链 ─────────────
-@router.post("/referral-link", response_model=CpsReferralLinkOut, summary="生成群发短链(带 sid + 点击统计)")
-def generate_referral_link(
-    body: CpsReferralLinkRequest,
+@router.patch("/activities/{activity_id}", response_model=CpsActivityOut, summary="编辑活动")
+def update_activity(
+    activity_id: int,
+    body: CpsActivityUpdate,
     request: Request,
     admin: Annotated[AdminUser, Depends(require_role("operator"))],
     db: AdminDb,
-) -> CpsReferralLinkOut:
+) -> CpsActivityOut:
+    activity = cps_repo.get_activity(db, activity_id)
+    if activity is None:
+        raise HTTPException(status_code=404, detail="活动不存在")
+    # 用「合并后最终值」校验平台必填项(同新建口径),允许只改部分字段
+    platform = body.platform or activity.platform
+    act_id = body.act_id if body.act_id is not None else activity.act_id
+    pvs = body.product_view_sign if body.product_view_sign is not None else activity.product_view_sign
+    payload = body.payload if body.payload is not None else activity.payload
+    image_url = body.image_url if body.image_url is not None else activity.image_url
+    if platform == "meituan":
+        if not act_id and not pvs:
+            raise HTTPException(status_code=400, detail="美团活动需填 actId 或 productViewSign")
+    else:  # taobao / jd
+        if not payload:
+            label = "淘口令" if platform == "taobao" else "推广链接"
+            raise HTTPException(status_code=400, detail=f"{platform} 活动需填{label}")
+        if platform == "taobao" and not image_url:
+            raise HTTPException(status_code=400, detail="淘宝活动需提供落地页图(上传或选已有)")
+    cps_repo.update_activity(
+        db, activity, name=body.name, platform=body.platform, act_id=body.act_id,
+        product_view_sign=body.product_view_sign, payload=body.payload,
+        image_url=media.to_abs_media_url(body.image_url) if body.image_url else None,
+        remark=body.remark, status=body.status, commit=False,
+    )
+    write_audit(
+        db, admin, action="cps.activity.update", target_type="cps_activity", target_id=activity_id,
+        detail=body.model_dump(exclude_none=True), ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    db.refresh(activity)
+    return CpsActivityOut.model_validate(activity)
+
+
+@router.post("/upload-image", summary="上传活动落地页图(返回绝对 URL)")
+async def upload_activity_image(
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    file: UploadFile = File(..., description="落地页图(jpeg/png/webp,≤5MB)"),
+) -> dict:
+    data = await file.read()
+    try:
+        url = media.save_cps_image(admin.id, data)
+    except media.MediaError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    return {"url": media.to_abs_media_url(url)}
+
+
+@router.get("/activity-images", summary="已有活动落地页图(供新建复用选择)")
+def activity_images(db: AdminDb) -> dict:
+    return {"images": cps_repo.list_activity_images(db)}
+
+
+@router.delete("/activities/{activity_id}", summary="删除活动")
+def delete_activity(
+    activity_id: int,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> dict:
+    activity = cps_repo.get_activity(db, activity_id)
+    if activity is None:
+        raise HTTPException(status_code=404, detail="活动不存在")
+    write_audit(
+        db, admin, action="cps.activity.delete", target_type="cps_activity", target_id=activity_id,
+        detail={"name": activity.name, "platform": activity.platform},
+        ip=get_client_ip(request), commit=False,
+    )
+    cps_repo.delete_activity(db, activity, commit=False)
+    db.commit()
+    return {"ok": True}
+
+
+# ───────────── 生成链接(批量,按平台分支) ─────────────
+def _gen_one_link(db, group: CpsGroup, activity: CpsActivity):
+    """给一个活动生成一条落地页 link。美团:转链拿短链(需群 sid);淘宝/京东:用 payload。"""
+    if activity.platform == "meituan":
+        if not group.sid:
+            raise HTTPException(status_code=400, detail=f"群「{group.name}」无 sid,无法生成美团链接")
+        try:
+            resp = meituan.get_referral_link(
+                act_id=activity.act_id, product_view_sign=activity.product_view_sign,
+                sid=group.sid, link_type_list=[1, 2, 3],
+            )
+        except MeituanCpsError as e:
+            raise HTTPException(status_code=502, detail=f"美团转链失败: {e}") from e
+        link_map = {str(k): v for k, v in (resp.get("referralLinkMap") or {}).items()}
+        if not link_map and resp.get("data"):
+            link_map = {"1": resp["data"]}
+        target = link_map.get("2") or link_map.get("1") or link_map.get("3")
+        if not target:
+            raise HTTPException(status_code=502, detail=f"美团未返回有效链接(活动「{activity.name}」)")
+    else:  # taobao(淘口令) / jd(链接)
+        if not activity.payload:
+            raise HTTPException(status_code=400, detail=f"活动「{activity.name}」缺少内容")
+        target = activity.payload
+    return cps_link_repo.create_link(
+        db, group_id=group.id, activity_id=activity.id, sid=group.sid,
+        target_url=target, platform=activity.platform, commit=False,
+    )
+
+
+@router.post("/referral-links", response_model=CpsReferralLinksOut, summary="批量生成落地页短链")
+def generate_referral_links(
+    body: CpsReferralLinksRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> CpsReferralLinksOut:
     group = cps_repo.get_group(db, body.group_id)
     if group is None:
         raise HTTPException(status_code=404, detail="群不存在")
-    activity = cps_repo.get_activity(db, body.activity_id)
-    if activity is None:
-        raise HTTPException(status_code=404, detail="活动不存在")
-    if activity.platform != "meituan":
-        raise HTTPException(status_code=400, detail=f"当前仅支持美团转链(活动平台={activity.platform})")
-    try:
-        # 全要:短链作跳转目标(微信可打开),长链/deeplink 作参考/备用
-        resp = meituan.get_referral_link(
-            act_id=activity.act_id,
-            product_view_sign=activity.product_view_sign,
-            sid=group.sid,
-            link_type_list=[1, 2, 3],
-        )
-    except MeituanCpsError as e:
-        raise HTTPException(status_code=502, detail=f"美团转链失败: {e}") from e
+    group_platforms = set(group.platforms or [])
+    base = settings.CPS_REDIRECT_BASE.rstrip("/")
 
-    link_map = {str(k): v for k, v in (resp.get("referralLinkMap") or {}).items()}
-    if not link_map and resp.get("data"):
-        link_map = {"1": resp["data"]}
-    # 跳转目标优先短链(2,微信可打开)→ 长链(1)→ deeplink(3)
-    target_url = link_map.get("2") or link_map.get("1") or link_map.get("3")
-    if not target_url:
-        raise HTTPException(status_code=502, detail="美团未返回有效链接(检查 actId 是否在推广有效期)")
+    items: list[CpsReferralLinkItem] = []
+    for aid in body.activity_ids:
+        activity = cps_repo.get_activity(db, aid)
+        if activity is None:
+            raise HTTPException(status_code=404, detail=f"活动 {aid} 不存在")
+        if activity.platform not in group_platforms:
+            raise HTTPException(
+                status_code=400,
+                detail=f"活动「{activity.name}」平台({activity.platform})不在群「{group.name}」范围内",
+            )
+        link = _gen_one_link(db, group, activity)
+        items.append(CpsReferralLinkItem(
+            activity_id=activity.id, activity_name=activity.name, platform=activity.platform,
+            redirect_url=f"{base}/c/{link.code}" if base else f"/c/{link.code}", code=link.code,
+        ))
 
-    # 存我们的短链:发群用 /c/{code},用户点 → 我们记点击 → 302 跳 target_url
-    link = cps_link_repo.create_link(
-        db, group_id=group.id, activity_id=activity.id, sid=group.sid,
-        target_url=target_url, platform=activity.platform, commit=False,
-    )
     write_audit(
-        db, admin, action="cps.referral_link.generate", target_type="cps_link", target_id=link.id,
-        detail={"sid": group.sid, "activity_id": activity.id, "code": link.code},
+        db, admin, action="cps.referral_link.generate", target_type="cps_group", target_id=group.id,
+        detail={"group": group.name, "activity_ids": body.activity_ids, "count": len(items)},
         ip=get_client_ip(request), commit=False,
     )
     db.commit()
-    db.refresh(link)
-
-    base = settings.CPS_REDIRECT_BASE.rstrip("/")
-    redirect_url = f"{base}/c/{link.code}" if base else f"/c/{link.code}"
-    return CpsReferralLinkOut(
-        redirect_url=redirect_url,
-        code=link.code,
-        sid=group.sid,
-        group_name=group.name,
-        activity_name=activity.name,
-        target_url=target_url,
-        link_map=link_map,
-    )
+    return CpsReferralLinksOut(group_name=group.name, results=items)
 
 
 # ───────────── 订单对账 ─────────────
@@ -262,7 +392,107 @@ def get_stats(
     stats = [CpsGroupStat(**r) for r in rows]
     return CpsStatsOut(
         groups=stats,
-        total_order_count=sum(s.order_count for s in stats),
-        total_est_commission_cents=sum(s.est_commission_cents for s in stats),
-        total_settled_commission_cents=sum(s.settled_commission_cents for s in stats),
+        total_order_count=sum(s.order_count or 0 for s in stats),
+        total_est_commission_cents=sum(s.est_commission_cents or 0 for s in stats),
+        total_settled_commission_cents=sum(s.settled_commission_cents or 0 for s in stats),
     )
+
+
+@router.get("/groups/{group_id}/timeseries", summary="群点击时序(折线图:天/小时级 PV/UV/复制)")
+def group_timeseries(
+    group_id: int,
+    db: AdminDb,
+    granularity: Annotated[str, Query(pattern="^(day|hour)$")] = "day",
+    days: Annotated[int, Query(ge=1, le=30)] = 7,
+    date: Annotated[str | None, Query()] = None,  # hour 粒度看哪天(YYYY-MM-DD 北京),默认今天
+) -> dict:
+    group = cps_repo.get_group(db, group_id)
+    if group is None:
+        raise HTTPException(status_code=404, detail="群不存在")
+    bj = timezone(timedelta(hours=8))
+    now_bj = datetime.now(bj)
+    if granularity == "hour":
+        if date:
+            try:
+                day0 = datetime.strptime(date, "%Y-%m-%d").replace(tzinfo=bj)
+            except ValueError as e:
+                raise HTTPException(status_code=400, detail="date 格式应为 YYYY-MM-DD") from e
+        else:
+            day0 = now_bj
+        start = day0.replace(hour=0, minute=0, second=0, microsecond=0)
+        end = start + timedelta(days=1) - timedelta(microseconds=1)
+    else:
+        start = (now_bj - timedelta(days=days - 1)).replace(hour=0, minute=0, second=0, microsecond=0)
+        end = now_bj
+    points = cps_repo.group_click_timeseries(
+        db, group_id=group_id, granularity=granularity, start=start, end=end
+    )
+    return {
+        "group_id": group.id,
+        "group_name": group.name,
+        "granularity": granularity,
+        "points": points,
+    }
+
+
+@router.get("/groups/{group_id}/daily", summary="群每天明细大表格(点击+订单按天合并)")
+def group_daily(
+    group_id: int,
+    db: AdminDb,
+    days: Annotated[int, Query(ge=1, le=90)] = 7,
+) -> dict:
+    group = cps_repo.get_group(db, group_id)
+    if group is None:
+        raise HTTPException(status_code=404, detail="群不存在")
+    bj = timezone(timedelta(hours=8))
+    now_bj = datetime.now(bj)
+    start = (now_bj - timedelta(days=days - 1)).replace(hour=0, minute=0, second=0, microsecond=0)
+    end = now_bj
+    # 点击侧:连续 N 天补零,顺序 = start..end(与下面 while 同序,按 index 对齐避免跨年 MM-DD 碰撞)
+    click_points = cps_repo.group_click_timeseries(
+        db, group_id=group_id, granularity="day", start=start, end=end
+    )
+    # 订单侧:仅美团群(有 sid)有对账;淘宝/京东订单列返回 None(前端显示 "-")
+    is_meituan = "meituan" in (group.platforms or []) and bool(group.sid)
+    order_daily = (
+        cps_repo.group_order_daily(db, sid=group.sid, start=start, end=end) if is_meituan else {}
+    )
+    _ORDER_KEYS = (
+        "order_count", "canceled_count", "gmv_cents",
+        "est_commission_cents", "refund_profit_cents", "settled_commission_cents",
+    )
+    rows = []
+    cur = start.astimezone(bj).date()
+    last = end.astimezone(bj).date()
+    idx = 0
+    while cur <= last:
+        cp = click_points[idx] if idx < len(click_points) else None
+        row = {
+            "date": cur.strftime("%m-%d"),
+            "click_pv": cp["click_pv"] if cp else 0,
+            "click_uv": cp["click_uv"] if cp else 0,
+            "copy_pv": cp["copy_pv"] if cp else 0,
+        }
+        if is_meituan:
+            od = order_daily.get(cur.strftime("%Y-%m-%d"))
+            row.update({k: (od[k] if od else 0) for k in _ORDER_KEYS})
+        else:
+            row.update({k: None for k in _ORDER_KEYS})
+        rows.append(row)
+        idx += 1
+        cur += timedelta(days=1)
+    return {
+        "group_id": group.id,
+        "group_name": group.name,
+        "is_meituan": is_meituan,
+        "days": days,
+        "rows": rows,
+    }
+
+
+@router.get("/groups/{group_id}/wx-users", summary="群内微信用户(领券画像:头像/昵称/领券次数)")
+def group_wx_users(group_id: int, db: AdminDb) -> dict:
+    group = cps_repo.get_group(db, group_id)
+    if group is None:
+        raise HTTPException(status_code=404, detail="群不存在")
+    return {"users": cps_repo.group_wx_users(db, group_id=group_id)}

app/admin/routers/feedback.py

@@ -1,4 +1,4 @@
-"""admin 反馈工单:列表(读,支持 状态/用户ID/内容/时间 筛选 + 排序)+ 标记已处理(写,带审计)。"""
+"""admin 反馈工单:列表筛选 + 审核采纳/拒绝(带金币发放与审计)。"""
 from __future__ import annotations
 
 from datetime import datetime
@@ -10,9 +10,10 @@ from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
 from app.admin.repositories import mutations, queries
 from app.admin.schemas.common import CursorPage, OkResponse
-from app.admin.schemas.feedback import FeedbackOut
+from app.admin.schemas.feedback import FeedbackApproveRequest, FeedbackOut, FeedbackRejectRequest
 from app.models.admin import AdminUser
 from app.models.feedback import Feedback
+from app.repositories import wallet as wallet_repo
 
 router = APIRouter(
     prefix="/admin/api/feedbacks",
@@ -21,6 +22,11 @@ router = APIRouter(
 )
 
 
+def _ensure_pending(fb: Feedback) -> None:
+    if fb.status not in {"pending", "new"}:
+        raise HTTPException(status_code=400, detail="反馈已审核")
+
+
 @router.get("", response_model=CursorPage[FeedbackOut], summary="反馈工单列表")
 def list_feedbacks(
     db: AdminDb,
@@ -56,18 +62,104 @@ def list_feedbacks(
 @router.post("/{feedback_id}/handle", response_model=OkResponse, summary="标记反馈已处理")
 def handle_feedback(
     feedback_id: int,
-    request: Request,
-    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    _admin: Annotated[AdminUser, Depends(require_role("operator"))],
     db: AdminDb,
 ) -> OkResponse:
     fb = db.get(Feedback, feedback_id)
     if fb is None:
         raise HTTPException(status_code=404, detail="反馈不存在")
+    raise HTTPException(status_code=400, detail="请使用采纳或拒绝接口审核反馈")
+
+
+@router.post("/{feedback_id}/approve", response_model=FeedbackOut, summary="采纳反馈并发金币")
+def approve_feedback(
+    feedback_id: int,
+    payload: FeedbackApproveRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> FeedbackOut:
+    fb = db.get(Feedback, feedback_id)
+    if fb is None:
+        raise HTTPException(status_code=404, detail="反馈不存在")
+    _ensure_pending(fb)
+
     before = fb.status
-    mutations.update_feedback_status(db, fb, status="handled", commit=False)
+    mutations.review_feedback(
+        db,
+        fb,
+        status="adopted",
+        reward_coins=payload.reward_coins,
+        review_note=payload.note,
+        reviewed_by_admin_id=admin.id,
+        commit=False,
+    )
+    wallet_repo.grant_coins(
+        db,
+        fb.user_id,
+        payload.reward_coins,
+        biz_type="feedback_reward",
+        ref_id=str(fb.id),
+        remark="意见反馈被采纳",
+    )
     write_audit(
-        db, admin, action="feedback.handle", target_type="feedback", target_id=feedback_id,
-        detail={"before": before, "after": "handled"}, ip=get_client_ip(request), commit=False,
+        db,
+        admin,
+        action="feedback.approve",
+        target_type="feedback",
+        target_id=feedback_id,
+        detail={
+            "before": before,
+            "after": "adopted",
+            "reward_coins": payload.reward_coins,
+            "note": payload.note,
+        },
+        ip=get_client_ip(request),
+        commit=False,
     )
     db.commit()
-    return OkResponse()
+    db.refresh(fb)
+    return FeedbackOut.model_validate(fb)
+
+
+@router.post("/{feedback_id}/reject", response_model=FeedbackOut, summary="拒绝采纳反馈")
+def reject_feedback(
+    feedback_id: int,
+    payload: FeedbackRejectRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> FeedbackOut:
+    fb = db.get(Feedback, feedback_id)
+    if fb is None:
+        raise HTTPException(status_code=404, detail="反馈不存在")
+    _ensure_pending(fb)
+
+    before = fb.status
+    mutations.review_feedback(
+        db,
+        fb,
+        status="rejected",
+        reject_reason=payload.reason,
+        review_note=payload.note,
+        reviewed_by_admin_id=admin.id,
+        commit=False,
+    )
+    write_audit(
+        db,
+        admin,
+        action="feedback.reject",
+        target_type="feedback",
+        target_id=feedback_id,
+        detail={
+            "before": before,
+            "after": "rejected",
+            "reason": payload.reason,
+            "note": payload.note,
+        },
+        ip=get_client_ip(request),
+        commit=False,
+    )
+    db.commit()
+    db.refresh(fb)
+    return FeedbackOut.model_validate(fb)

app/admin/routers/feedback_qr.py

@@ -0,0 +1,92 @@
+"""admin 反馈页二维码卡配置:读 / 改文案开关 / 上传二维码 / 删二维码(带审计)。
+
+整张卡存通用 app_config 表(见 app/repositories/feedback_qr.py),App 反馈页拉
+GET /api/v1/feedback/config 同步。权限:operator 可改(运营维护),super 恒可;
+读为只读(任意已登录 admin)。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.schemas.feedback_qr import FeedbackQrOut, FeedbackQrUpdate
+from app.core import media
+from app.models.admin import AdminUser
+from app.repositories import feedback_qr
+
+router = APIRouter(
+    prefix="/admin/api/feedback-config",
+    tags=["admin-feedback-config"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=FeedbackQrOut, summary="反馈页二维码卡配置")
+def get_config(db: AdminDb) -> FeedbackQrOut:
+    return FeedbackQrOut(**feedback_qr.get_config(db))
+
+
+@router.patch("", response_model=FeedbackQrOut, summary="改反馈页文案/开关(带审计)")
+def update_config(
+    body: FeedbackQrUpdate,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> FeedbackQrOut:
+    before, after = feedback_qr.update_config(
+        db,
+        enabled=body.enabled,
+        title=body.title,
+        group_name=body.group_name,
+        subtitle=body.subtitle,
+        admin_id=admin.id,
+        commit=False,
+    )
+    write_audit(
+        db, admin, action="feedback_qr.update", target_type="feedback_qr", target_id=None,
+        detail={"before": before, "after": after}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return FeedbackQrOut(**after)
+
+
+@router.post("/image", response_model=FeedbackQrOut, summary="上传反馈页二维码(带审计)")
+async def upload_image(
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+    file: UploadFile = File(...),
+) -> FeedbackQrOut:
+    data = await file.read()
+    try:
+        url = media.save_feedback_qr(data)
+    except media.MediaError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    before, after = feedback_qr.set_image(db, url, admin_id=admin.id, commit=False)
+    write_audit(
+        db, admin, action="feedback_qr.set_image", target_type="feedback_qr", target_id=None,
+        detail={"before": before.get("image_url"), "after": url},
+        ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    media.delete_feedback_qr(before.get("image_url"))  # 提交成功后再删旧图,避免新图未落库就丢旧图
+    return FeedbackQrOut(**after)
+
+
+@router.delete("/image", response_model=FeedbackQrOut, summary="移除反馈页二维码(带审计)")
+def delete_image(
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> FeedbackQrOut:
+    before, after = feedback_qr.set_image(db, None, admin_id=admin.id, commit=False)
+    write_audit(
+        db, admin, action="feedback_qr.delete_image", target_type="feedback_qr", target_id=None,
+        detail={"before": before.get("image_url")}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    media.delete_feedback_qr(before.get("image_url"))
+    return FeedbackQrOut(**after)

app/admin/routers/users.py

@@ -17,6 +17,8 @@ from app.admin.schemas.user import (
     GrantCoinsRequest,
     SetDebugTraceRequest,
     SetUserStatusRequest,
+    UserCoinRecord,
+    UserRewardStats,
 )
 from app.models.admin import AdminUser
 from app.repositories import user as user_repo
@@ -66,6 +68,46 @@ def get_user(user_id: int, db: AdminDb) -> AdminUserOverview:
     return AdminUserOverview.model_validate(overview)
 
 
+@router.get(
+    "/{user_id}/reward-stats",
+    response_model=UserRewardStats,
+    summary="用户提现/看广告统计(提现详情用,按时间窗口)",
+)
+def get_user_reward_stats(
+    user_id: int,
+    db: AdminDb,
+    date_from: Annotated[datetime | None, Query()] = None,
+    date_to: Annotated[datetime | None, Query()] = None,
+) -> UserRewardStats:
+    """提现详情抽屉「用户统计区」。date_from/date_to 都不传 = 注册至今(全量)。"""
+    if user_repo.get_user_by_id(db, user_id) is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    return UserRewardStats(
+        **queries.user_reward_stats(db, user_id, date_from=date_from, date_to=date_to)
+    )
+
+
+@router.get(
+    "/{user_id}/coin-records",
+    response_model=CursorPage[UserCoinRecord],
+    summary="用户金币发放记录(提现详情底部表,按时间窗口分页)",
+)
+def get_user_coin_records(
+    user_id: int,
+    db: AdminDb,
+    date_from: Annotated[datetime | None, Query()] = None,
+    date_to: Annotated[datetime | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[UserCoinRecord]:
+    items, next_cursor, total = queries.user_coin_records(
+        db, user_id, date_from=date_from, date_to=date_to, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[UserCoinRecord(**r) for r in items], next_cursor=next_cursor, total=total,
+    )
+
+
 @router.post("/{user_id}/status", response_model=OkResponse, summary="封禁/解封用户")
 def set_user_status(
     user_id: int,

app/admin/routers/withdraw.py

@@ -25,6 +25,7 @@ from app.admin.schemas.wallet import (
     WithdrawBulkItemResult,
     WithdrawDetailOut,
     WithdrawLedgerCheckOut,
+    WithdrawListItemOut,
     WithdrawOrderOut,
     WithdrawRejectRequest,
     WithdrawSummaryOut,
@@ -44,7 +45,7 @@ router = APIRouter(
 )
 
 
-@router.get("", response_model=CursorPage[WithdrawOrderOut], summary="提现单列表")
+@router.get("", response_model=CursorPage[WithdrawListItemOut], summary="提现单列表")
 def list_withdraws(
     db: AdminDb,
     user_id: Annotated[int | None, Query()] = None,
@@ -63,7 +64,7 @@ def list_withdraws(
     ] = None,
     limit: Annotated[int, Query(ge=1, le=100)] = 20,
     cursor: Annotated[int | None, Query()] = None,
-) -> CursorPage[WithdrawOrderOut]:
+) -> CursorPage[WithdrawListItemOut]:
     items, next_cursor, total = queries.list_all_withdraw_orders(
         db,
         user_id=user_id,
@@ -78,11 +79,16 @@ def list_withdraws(
         limit=limit,
         cursor=cursor,
     )
-    return CursorPage(
-        items=[WithdrawOrderOut.model_validate(o) for o in items],
-        next_cursor=next_cursor,
-        total=total,
-    )
+    # 联表带出手机号/昵称 + 累计成功提现(本页 user_id 批量富化,2 条聚合查询,无 N+1)。
+    enrichment = queries.withdraw_list_enrichment(db, [o.user_id for o in items])
+    _empty = {"phone": None, "nickname": None, "cumulative_success_cents": 0}
+    out_items = [
+        WithdrawListItemOut.model_validate(o).model_copy(
+            update=enrichment.get(o.user_id, _empty)
+        )
+        for o in items
+    ]
+    return CursorPage(items=out_items, next_cursor=next_cursor, total=total)
 
 
 @router.get("/summary", response_model=WithdrawSummaryOut, summary="提现审核台统计")

app/admin/schemas/ad_config.py

@@ -0,0 +1,30 @@
+"""admin 广告配置 schemas(穿山甲 app_id/各位ID/验签密钥/各场景开关)。"""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class AdConfigOut(BaseModel):
+    """admin 读到的完整广告配置(含 reward_mkey;admin 有权见,但绝不经 /platform 下发客户端)。"""
+
+    app_id: str
+    reward_code_id: str
+    compare_feed_code_id: str
+    coupon_feed_code_id: str
+    reward_mkey: str
+    reward_enabled: bool
+    compare_ad_enabled: bool
+    coupon_ad_enabled: bool
+
+
+class AdConfigUpdate(BaseModel):
+    """部分更新:只改传入(非 None)字段。空串是合法值(如清空 mkey 回退 .env)。"""
+
+    app_id: str | None = None
+    reward_code_id: str | None = None
+    compare_feed_code_id: str | None = None
+    coupon_feed_code_id: str | None = None
+    reward_mkey: str | None = None
+    reward_enabled: bool | None = None
+    compare_ad_enabled: bool | None = None
+    coupon_ad_enabled: bool | None = None

app/admin/schemas/comparison.py

@@ -0,0 +1,72 @@
+"""admin 比价记录 debug 页 schema(独立于 C 端 app/schemas/compare_record:admin 看任意用户、
+无 debug_trace 权限闸、展示全量 debug 字段)。phone/nickname 由 queries 瞬态挂在 ORM 实例上。"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AdminComparisonListItem(BaseModel):
+    """列表项:概要 + debug 维度概览(不含大字段 raw_payload/llm_calls/明细数组)。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    user_id: int
+    phone: str | None = None        # join User 瞬态(非 DB 列)
+    nickname: str | None = None     # join User 瞬态
+    business_type: str
+    trace_id: str
+    # admin 是 debug 工具,无条件下发 trace_url(不看 user.debug_trace_enabled)
+    trace_url: str | None = None
+    status: str
+    information: str | None = None
+    store_name: str | None = None
+    source_platform_name: str | None = None
+    best_platform_name: str | None = None
+    source_price_cents: int | None = None
+    best_price_cents: int | None = None
+    saved_amount_cents: int | None = None
+    # debug 概览
+    total_ms: int | None = None
+    step_count: int | None = None
+    llm_call_count: int | None = None
+    retry_count: int | None = None
+    input_tokens: int | None = None      # Σ usage.prompt_tokens(server 派生)
+    output_tokens: int | None = None     # Σ usage.completion_tokens(server 派生)
+    device_model: str | None = None
+    rom_vendor: str | None = None
+    rom_name: str | None = None
+    android_version: str | None = None
+    app_version: str | None = None
+    created_at: datetime
+
+
+class AdminComparisonDetail(AdminComparisonListItem):
+    """详情:概要 + 全量明细(逐平台对比 / LLM 每次调用 / 原始 payload)。"""
+
+    source_platform_id: str | None = None
+    source_package: str | None = None
+    best_platform_id: str | None = None
+    best_deeplink: str | None = None
+    is_source_best: bool | None = None
+    total_dish_count: int | None = None
+    skipped_dish_count: int | None = None
+    device_id: str | None = None
+    items: list = []
+    comparison_results: list = []   # 逐平台对比(价格/rank/coupon/打烊...)
+    skipped_dish_names: list = []
+    # 全量环境
+    device_manufacturer: str | None = None
+    rom_version: int | None = None
+    android_sdk: int | None = None
+    app_version_code: int | None = None
+    source_app_version: str | None = None
+    longitude: float | None = None
+    latitude: float | None = None
+    # 每次 LLM 调用明细 [{scene,model,input_messages,output,usage,latency_ms,error}]
+    llm_calls: list | None = None
+    # 原始上报全量;「卡在哪一步」从 raw_payload.platform_results[*].status 读
+    # (store_not_found/items_not_found/below_minimum/unsupported = 卡在 找店/加菜/起送/读价)。
+    raw_payload: dict | None = None

app/admin/schemas/cps.py

@@ -1,4 +1,8 @@
-"""admin CPS 分发与对账 schemas。金额统一「分」(cents),前端 yuan() 展示。"""
+"""admin CPS 分发与对账 schemas。金额统一「分」(cents),前端 yuan() 展示。
+
+平台:meituan(actId+sid 转链对账) / taobao(淘口令,只统计点击) / jd(链接,只统计点击)。
+对账类字段对淘宝/京东为 None → 前端显示 "-"(无法对账)。
+"""
 from __future__ import annotations
 
 from datetime import datetime
@@ -6,13 +10,14 @@ from datetime import datetime
 from pydantic import BaseModel, ConfigDict, Field
 
 
-# ───────────── 群(sid) ─────────────
+# ───────────── 群 ─────────────
 class CpsGroupOut(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
-    sid: str
+    sid: str | None = None  # 仅美团群有
     name: str
+    platforms: list[str] = Field(default_factory=list)
     member_count: int | None = None
     status: str
     remark: str | None = None
@@ -21,7 +26,9 @@ class CpsGroupOut(BaseModel):
 
 class CpsGroupCreate(BaseModel):
     name: str = Field(min_length=1, max_length=128)
-    # 留空 → 后端自动生成 g<id>;填写则必须字母+数字(美团 sid 限制)。
+    # 该群发哪些平台,至少选一个
+    platforms: list[str] = Field(min_length=1)
+    # 仅当含 meituan 时需要(留空自动生成);纯淘宝/京东不填,后端置 None。
     sid: str | None = Field(default=None, max_length=64, pattern=r"^[A-Za-z0-9]+$")
     member_count: int | None = Field(default=None, ge=0)
     remark: str | None = Field(default=None, max_length=256)
@@ -29,12 +36,13 @@ class CpsGroupCreate(BaseModel):
 
 class CpsGroupUpdate(BaseModel):
     name: str | None = Field(default=None, min_length=1, max_length=128)
+    platforms: list[str] | None = None
     member_count: int | None = Field(default=None, ge=0)
     status: str | None = Field(default=None, pattern=r"^(active|archived)$")
     remark: str | None = Field(default=None, max_length=256)
 
 
-# ───────────── 活动(actId) ─────────────
+# ───────────── 活动 ─────────────
 class CpsActivityOut(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
@@ -43,6 +51,8 @@ class CpsActivityOut(BaseModel):
     name: str
     act_id: str | None = None
     product_view_sign: str | None = None
+    payload: str | None = None  # 淘宝淘口令 / 京东链接
+    image_url: str | None = None  # 淘宝落地页图(绝对 URL)
     status: str
     remark: str | None = None
     created_at: datetime
@@ -50,36 +60,55 @@ class CpsActivityOut(BaseModel):
 
 class CpsActivityCreate(BaseModel):
     name: str = Field(min_length=1, max_length=128)
-    platform: str = Field(default="meituan", pattern=r"^(meituan|taobao|jd)$")
+    platform: str = Field(pattern=r"^(meituan|taobao|jd)$")
+    # 美团:act_id 或 product_view_sign 二选一
     act_id: str | None = Field(default=None, max_length=64)
     product_view_sign: str | None = Field(default=None, max_length=128)
+    # 淘宝:整段淘口令文本 / 京东:推广链接
+    payload: str | None = Field(default=None, max_length=4096)
+    # 淘宝落地页图(绝对/相对 URL;淘宝必填,由 router 校验)
+    image_url: str | None = Field(default=None, max_length=512)
     remark: str | None = Field(default=None, max_length=256)
 
 
-# ───────────── 转链 ─────────────
-class CpsReferralLinkRequest(BaseModel):
+class CpsActivityUpdate(BaseModel):
+    """编辑活动(PATCH):全字段可选,只更新传入的非 None 项;最终平台对应字段由 router 校验。"""
+
+    name: str | None = Field(default=None, min_length=1, max_length=128)
+    platform: str | None = Field(default=None, pattern=r"^(meituan|taobao|jd)$")
+    act_id: str | None = Field(default=None, max_length=64)
+    product_view_sign: str | None = Field(default=None, max_length=128)
+    payload: str | None = Field(default=None, max_length=4096)
+    image_url: str | None = Field(default=None, max_length=512)
+    remark: str | None = Field(default=None, max_length=256)
+    status: str | None = Field(default=None, pattern=r"^(active|archived)$")
+
+
+# ───────────── 生成链接(批量) ─────────────
+class CpsReferralLinksRequest(BaseModel):
     group_id: int
+    activity_ids: list[int] = Field(min_length=1)
+
+
+class CpsReferralLinkItem(BaseModel):
     activity_id: int
-    # 链接类型:1长链 2短链 3deeplink。默认短链(微信可打开)+deeplink。
-    link_types: list[int] = Field(default_factory=lambda: [2, 3])
-
-
-class CpsReferralLinkOut(BaseModel):
-    redirect_url: str  # ★ 我们的群发短链(/c/{code}),发群就用这个,点击经我们统计
-    code: str
-    sid: str
-    group_name: str
     activity_name: str
-    target_url: str  # 实际 302 跳转的美团短链
-    link_map: dict[str, str]  # 美团原始 1长链/2短链/3deeplink(参考/备用)
+    platform: str
+    redirect_url: str  # 我们的落地页 /c/{code}(发群用)
+    code: str
+
+
+class CpsReferralLinksOut(BaseModel):
+    group_name: str
+    results: list[CpsReferralLinkItem]
 
 
 # ───────────── 对账拉单 ─────────────
 class CpsReconcileResult(BaseModel):
-    fetched: int      # 本次美团返回的订单条数
-    inserted: int     # 新入库
-    updated: int      # 已存在→更新状态/佣金
-    pages: int        # 翻了几页
+    fetched: int
+    inserted: int
+    updated: int
+    pages: int
 
 
 # ───────────── 订单明细 ─────────────
@@ -101,18 +130,22 @@ class CpsOrderOut(BaseModel):
 
 # ───────────── 统计 ─────────────
 class CpsGroupStat(BaseModel):
-    group_id: int | None = None   # None = 未归群的 sid(历史/其它来源)
+    group_id: int | None = None
     sid: str | None = None
     name: str
+    platforms: list[str] = Field(default_factory=list)
     member_count: int | None = None
-    click_pv: int = 0             # 点击总次数
-    click_uv: int = 0             # 独立点击(按 ip+ua 近似去重)
-    order_count: int              # 有效订单数(不含取消/风控)
-    settled_count: int            # 已结算单数
-    canceled_count: int           # 取消+风控单数
-    gmv_cents: int                # 成交额(有效单 payPrice 合计)
-    est_commission_cents: int     # 预估佣金(有效单 profit 合计)
-    settled_commission_cents: int  # 已结算佣金
+    click_pv: int = 0
+    click_uv: int = 0
+    copy_pv: int = 0   # 淘宝"复制口令"次数
+    copy_uv: int = 0
+    # 对账类:淘宝/京东无法对账 → None(前端显示 "-");美团群为数值
+    order_count: int | None = None
+    settled_count: int | None = None
+    canceled_count: int | None = None
+    gmv_cents: int | None = None
+    est_commission_cents: int | None = None
+    settled_commission_cents: int | None = None
 
 
 class CpsStatsOut(BaseModel):

app/admin/schemas/feedback.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.core.rewards import FEEDBACK_REWARD_MAX_COINS
 
 
 class FeedbackOut(BaseModel):
@@ -15,4 +17,23 @@ class FeedbackOut(BaseModel):
     contact: str
     images: list[str] | None = None
     status: str
+    reject_reason: str | None = None
+    reward_coins: int | None = None
+    review_note: str | None = None
+    reviewed_by_admin_id: int | None = None
+    reviewed_at: datetime | None = None
     created_at: datetime
+
+
+class FeedbackApproveRequest(BaseModel):
+    reward_coins: int = Field(
+        ge=1,
+        le=FEEDBACK_REWARD_MAX_COINS,
+        description="采纳后发放金币数",
+    )
+    note: str | None = Field(default=None, max_length=256, description="采纳要点/审核备注")
+
+
+class FeedbackRejectRequest(BaseModel):
+    reason: str = Field(min_length=1, max_length=256, description="未采纳原因,用户端可见")
+    note: str | None = Field(default=None, max_length=256, description="运营内部审核备注")

app/admin/schemas/feedback_qr.py

@@ -0,0 +1,22 @@
+"""admin 反馈页二维码卡配置 schemas。"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class FeedbackQrOut(BaseModel):
+    enabled: bool
+    image_url: str | None = None
+    title: str
+    group_name: str
+    subtitle: str
+    updated_at: str | None = None
+
+
+class FeedbackQrUpdate(BaseModel):
+    """改文案/开关(均可选,只改传了的字段;图片走单独的上传/删除接口)。"""
+
+    enabled: bool | None = None
+    title: str | None = Field(default=None, max_length=40)
+    group_name: str | None = Field(default=None, max_length=40)
+    subtitle: str | None = Field(default=None, max_length=60)

app/admin/schemas/user.py

@@ -37,6 +37,36 @@ class AdminUserOverview(BaseModel):
     feedback_total: int
 
 
+class UserRewardStats(BaseModel):
+    """提现详情抽屉「用户统计区」:按时间窗口算的提现 + 看广告行为统计。
+
+    窗口由 date_from/date_to 决定(都不传 = 注册至今 = 全量);现金余额除外——它是当前快照。
+    各「*_cash_cents」是把该来源累计发放金币折算成可提现现金(分):100 金币 = 1 分(COIN_PER_YUAN=10000)。
+    eCPM 单位沿用穿山甲原值「分/千次」。
+    """
+
+    withdraw_success_cents: int  # 累计提现(窗口内 success 金额)
+    cash_balance_cents: int  # 现金余额(当前快照,不随窗口)
+    withdraw_total: int  # 提现总次数(窗口内全部状态)
+    traditional_task_cash_cents: int  # 传统任务提现(非广告非人工的金币折现)
+    reward_video_count: int  # 累计激励视频数(granted 条数)
+    reward_video_avg_ecpm: float  # 平均激励视频 eCPM(分/千次)
+    reward_video_cash_cents: int  # 激励视频提现(金币折现)
+    feed_count: int  # 累计信息流广告数(granted 份数,unit_count 累加)
+    feed_avg_ecpm: float  # 平均信息流广告 eCPM(分/千次)
+    feed_cash_cents: int  # 信息流广告提现(金币折现)
+
+
+class UserCoinRecord(BaseModel):
+    """金币发放记录(提现详情底部表)。source 见 source_label;非广告来源 ecpm 为 None。"""
+
+    source: str  # reward_video / signin_boost / feed / signin
+    source_label: str  # 激励视频 / 签到膨胀 / 信息流广告 / 签到
+    created_at: datetime
+    ecpm: str | None = None  # 原始 eCPM(分/千次),非广告为 None
+    coin: int  # 发放金币数
+
+
 def _strip_reason(v: str) -> str:
     # min_length=1 放过纯空白(" "),trim 后再校验非空,避免审计记到空原因
     if not v.strip():

app/admin/schemas/wallet.py

@@ -50,6 +50,17 @@ class WithdrawOrderOut(BaseModel):
     updated_at: datetime
 
 
+class WithdrawListItemOut(WithdrawOrderOut):
+    """提现单列表项:在提现单字段基础上,补本页用户的手机号/昵称 + 累计成功提现金额(分)。
+
+    仅列表接口用(需联表 User + 聚合);详情/批量仍用 WithdrawOrderOut(不带这些字段)。
+    """
+
+    phone: str | None = None
+    nickname: str | None = None
+    cumulative_success_cents: int = 0  # 累计成功提现 = SUM(amount_cents) WHERE status='success'
+
+
 class WithdrawSummaryOut(BaseModel):
     reviewing_count: int
     reviewing_amount_cents: int

app/api/internal/app_version.py

@@ -0,0 +1,58 @@
+"""最新 App 版本写入端点(发布流程 → app-server)。
+
+发车流程出 APK 后,把版本号 / 下载链接 / sha256 等 POST 到这里,落 app_config(key=latest_app_version)。
+客户端再 GET /api/v1/platform/app-version 读取做 OTA 检查更新。**不是给客户端的接口**:
+不走用户 JWT,靠 server 间共享密钥头 `X-Internal-Secret` 校验(== settings.INTERNAL_API_SECRET)。
+密钥未配置(默认空)时直接 503,避免裸奔的写端点。也是应急改版本信息(紧急下线/改 apk_url)的入口。
+"""
+from __future__ import annotations
+
+import hmac
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Header, HTTPException, status
+
+from app.api.deps import DbSession
+from app.core.config import settings
+from app.repositories import app_config
+from app.schemas.platform import AppVersionOut, AppVersionWriteIn
+
+logger = logging.getLogger("shagua.internal.app_version")
+
+router = APIRouter(prefix="/internal", tags=["internal"])
+
+
+def _check_secret(x_internal_secret: str | None) -> None:
+    """共享密钥校验。未配置 → 503(挡住裸奔写端点);不匹配 → 401(常量时间比较)。"""
+    configured = settings.INTERNAL_API_SECRET
+    if not configured:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="internal api not configured",
+        )
+    if not x_internal_secret or not hmac.compare_digest(x_internal_secret, configured):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="invalid internal secret",
+        )
+
+
+@router.post(
+    "/app-version",
+    response_model=AppVersionOut,
+    summary="写最新 App 版本(发布流程→app-server,落 app_config)",
+)
+def write_app_version(
+    payload: AppVersionWriteIn,
+    db: DbSession,
+    x_internal_secret: Annotated[str | None, Header()] = None,
+) -> AppVersionOut:
+    _check_secret(x_internal_secret)
+    data = payload.model_dump()
+    app_config.set_app_version(db, data)
+    logger.info(
+        "app_version set code=%d name=%s url=%s",
+        payload.latest_version_code, payload.latest_version_name, payload.apk_url,
+    )
+    return AppVersionOut(**data)

app/api/internal/launch_confirm.py

@@ -0,0 +1,63 @@
+"""启动确认窗兜底样本内部上报端点(pricebot → app-server)。
+
+pricebot 的 launch_confirm_agent 每次靠 LLM 兜底放行一个"静态 PROFILES 没认出"的跨 App
+启动确认窗时,把完整样本 POST 到这里落库。**不是给客户端的接口**:不走用户 JWT,靠
+server 间共享密钥头 `X-Internal-Secret` 校验(== settings.INTERNAL_API_SECRET)。密钥未配置
+(默认空)时直接 503,避免裸奔写端点。
+
+研发定期人工把 exec_success=true 的样本沉淀进 pricebot 的 launch_confirm.PROFILES。
+"""
+from __future__ import annotations
+
+import hmac
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Header, HTTPException, status
+
+from app.api.deps import DbSession
+from app.core.config import settings
+from app.repositories import launch_confirm_sample as repo
+from app.schemas.launch_confirm_sample import (
+    LaunchConfirmSampleIn,
+    LaunchConfirmSampleOut,
+)
+
+logger = logging.getLogger("shagua.internal.launch_confirm")
+
+router = APIRouter(prefix="/internal", tags=["internal"])
+
+
+def _check_secret(x_internal_secret: str | None) -> None:
+    """共享密钥校验。未配置 → 503(挡裸奔写端点);不匹配 → 401(常量时间比较)。"""
+    configured = settings.INTERNAL_API_SECRET
+    if not configured:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="internal api not configured",
+        )
+    if not x_internal_secret or not hmac.compare_digest(x_internal_secret, configured):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="invalid internal secret",
+        )
+
+
+@router.post(
+    "/launch-confirm-sample",
+    response_model=LaunchConfirmSampleOut,
+    summary="启动确认窗兜底样本上报(pricebot→app-server,落 launch_confirm_sample)",
+)
+def report_launch_confirm_sample(
+    payload: LaunchConfirmSampleIn,
+    db: DbSession,
+    x_internal_secret: Annotated[str | None, Header()] = None,
+) -> LaunchConfirmSampleOut:
+    _check_secret(x_internal_secret)
+    sid = repo.insert_sample(db, payload)
+    logger.info(
+        "launch_confirm_sample id=%d host=%s locale=%s success=%s trace=%s",
+        sid, payload.host_package, payload.system_locale,
+        payload.exec_success, payload.trace_id,
+    )
+    return LaunchConfirmSampleOut(id=sid)

app/api/v1/ad.py

@@ -24,6 +24,7 @@ from app.repositories import ad_ecpm as crud_ecpm
 from app.repositories import ad_feed_reward as crud_feed
 from app.repositories import ad_reward as crud_ad
 from app.repositories import ad_watch as crud_watch
+from app.repositories import app_config
 from app.repositories import signin as crud_signin
 from app.schemas.ad import (
     AdRewardStatusOut,
@@ -31,6 +32,7 @@ from app.schemas.ad import (
     EcpmReportOut,
     FeedRewardIn,
     FeedRewardOut,
+    FeedRewardUnitsOut,
     PangleCallbackOut,
     RewardNoShowIn,
     RewardNoShowOut,
@@ -80,14 +82,22 @@ def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
     验签失败 403(留给真请求重试);参数缺/坏或 user 不存在 → is_verify=false + reason(不发,不重试)。
     granted / capped → is_verify=true + reason=0。
     """
-    if not settings.pangle_callback_configured:
+    if not settings.PANGLE_CALLBACK_ENABLED:
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="pangle callback not configured"
         )
 
     params = dict(request.query_params)
 
-    if not pangle.verify_callback_sign_any(params, settings.pangle_reward_secrets):
+    # 验签密钥:admin 后台配的 reward_mkey 优先,.env 的 PANGLE_REWARD_SECRET* 兜底(兼容/过渡)。
+    # 换激励位时后台同步换 mkey 即可,无需改 .env。两者都空才视为未配置。
+    ad_mkey = app_config.get_ad_config(db).get("reward_mkey") or ""
+    secrets = ([ad_mkey] if ad_mkey else []) + settings.pangle_reward_secrets
+    if not secrets:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="pangle callback not configured"
+        )
+    if not pangle.verify_callback_sign_any(params, secrets):
         logger.warning("pangle callback bad sign trans_id=%s", params.get("trans_id"))
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="bad sign")
 
@@ -363,6 +373,8 @@ def feed_reward(payload: FeedRewardIn, user: CurrentUser, db: DbSession) -> Feed
         ad_session_id=payload.ad_session_id,
         adn=payload.adn,
         slot_id=payload.slot_id,
+        feed_scene=payload.feed_scene,
+        trace_id=payload.trace_id,
         app_env=payload.app_env,
         our_code_id=payload.our_code_id,
         aborted=payload.aborted,
@@ -380,6 +392,21 @@ def feed_reward(payload: FeedRewardIn, user: CurrentUser, db: DbSession) -> Feed
     )
 
 
+@router.get(
+    "/feed-reward/units",
+    response_model=FeedRewardUnitsOut,
+    summary="查账号累计信息流发奖份数(前端算因子2 LT、做实时金币进度条用)",
+    dependencies=[Depends(rate_limit(120, 60, "ad-feed-units"))],
+)
+def feed_reward_units(user: CurrentUser, db: DbSession) -> FeedRewardUnitsOut:
+    """返回账号累计已发奖份数(因子2 LT 基线)。
+
+    信息流金币进度条:前端 show 时拉一次,之后每满 10 秒一份、逐份用 (granted_units + offset)
+    查 LT 因子,精确复刻发奖公式 → 进度条数值 ≈ 实际到账。
+    """
+    return FeedRewardUnitsOut(granted_units=crud_feed.granted_unit_total(db, user.id))
+
+
 @router.post(
     "/reward-noshow",
     response_model=RewardNoShowOut,

app/api/v1/compare.py

@@ -116,3 +116,11 @@ async def intent_precoupon_step(request: Request) -> dict[str, Any]:
 @router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传到 pricebot)")
 async def price_step(request: Request) -> dict[str, Any]:
     return await _passthrough(request, "/api/price/step")
+
+
+@router.post("/trace/finalize", summary="比价 trace 收尾上云 (透传到 pricebot, 终止/未识别拿 trace_url)")
+async def trace_finalize(request: Request) -> dict[str, Any]:
+    # 用户终止 / Phase1 未识别没走到 done 帧, pricebot 没上云也没回传 trace_url。客户端收尾时
+    # 打这个, _passthrough 按 trace_id 一致性 hash 落到处理这条 trace 的同一 pricebot 进程
+    # (dir_cache 在那, 才能算对 trace 目录), 由后者打包上云返回 {trace_url}。
+    return await _passthrough(request, "/api/trace/finalize")

app/api/v1/compare_record.py

@@ -15,10 +15,13 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, HTTPException, Query, status
+from fastapi import APIRouter, BackgroundTasks, HTTPException, Query, status
 
 from app.api.deps import CurrentUser, DbSession
+from app.db.session import SessionLocal
+from app.models.comparison import ComparisonRecord
 from app.repositories import comparison as crud_compare
+from app.services.pricebot_llm_calls import fetch_llm_calls
 from app.schemas.compare_record import (
     CompareStatsOut,
     ComparisonRecordCreatedOut,
@@ -39,11 +42,18 @@ router = APIRouter(prefix="/api/v1/compare", tags=["compare-record"])
     summary="上报一次比价结果(幂等)",
 )
 def report_record(
-    payload: ComparisonRecordIn, user: CurrentUser, db: DbSession
+    payload: ComparisonRecordIn,
+    user: CurrentUser,
+    db: DbSession,
+    background_tasks: BackgroundTasks,
 ) -> ComparisonRecordCreatedOut:
     rec = crud_compare.upsert_record(db, user_id=user.id, payload=payload)
+    # LLM 调用明细异步回填:同机拉 pricebot llm_calls 最长 5s 且是 best-effort,放后台
+    # 任务做,不阻塞上报响应(顺带给 pricebot 落盘留足余量)。upsert 已 commit,后台用
+    # 独立 session 按 record id 回填 llm_calls + 派生 llm_call_count/retry_count。
+    background_tasks.add_task(_backfill_llm_calls, rec.id, rec.trace_id)
     logger.info(
-        "compare record user=%s trace=%s biz=%s status=%s saved=%s",
+        "compare record user=%s trace=%s biz=%s status=%s saved=%s (llm_calls backfill queued)",
         user.id,
         rec.trace_id,
         rec.business_type,
@@ -53,6 +63,35 @@ def report_record(
     return ComparisonRecordCreatedOut(id=rec.id)
 
 
+def _backfill_llm_calls(record_id: int, trace_id: str) -> None:
+    """后台回填本次比价的 LLM 调用明细 + 派生 llm_call_count/retry_count。
+    独立 DB session(请求 session 此时已关);拉取/写库失败只 log,绝不影响已落库的上报。"""
+    calls = fetch_llm_calls(trace_id)
+    if not calls:
+        return
+    db = SessionLocal()
+    try:
+        rec = db.get(ComparisonRecord, record_id)
+        if rec is None:
+            return
+        rec.llm_calls = calls
+        rec.llm_call_count = len(calls)
+        rec.retry_count = sum(1 for c in calls if c.get("error"))
+        # token 累加(usage 已被 pricebot llm_client 归一为 prompt/completion_tokens;
+        # error 的调用 usage 可能为 None,or {} 兜底)
+        rec.input_tokens = sum((c.get("usage") or {}).get("prompt_tokens") or 0 for c in calls)
+        rec.output_tokens = sum((c.get("usage") or {}).get("completion_tokens") or 0 for c in calls)
+        db.commit()
+        logger.info(
+            "backfill llm_calls trace=%s n=%d in_tok=%d out_tok=%d",
+            trace_id, len(calls), rec.input_tokens, rec.output_tokens,
+        )
+    except Exception as e:  # noqa: BLE001 best-effort
+        logger.warning("backfill llm_calls failed trace=%s: %s", trace_id, e)
+    finally:
+        db.close()
+
+
 @router.get(
     "/stats",
     response_model=CompareStatsOut,
@@ -73,13 +112,20 @@ def list_records(
     db: DbSession,
     limit: int = Query(20, ge=1, le=100),
     cursor: int | None = Query(None, description="上一页末条 id"),
+    include_trace: bool = Query(
+        False,
+        description="客户端开了本机 agent 调试模式时带 true,放行本人记录的 trace_url",
+    ),
 ) -> ComparisonRecordPage:
     items, next_cursor = crud_compare.list_records(
         db, user.id, limit=limit, cursor=cursor
     )
     outs = [ComparisonRecordOut.model_validate(it) for it in items]
-    # 权限闸:未开 debug_trace_enabled 的用户不下发 trace_url(列表页「复制调试链接」靠它)
-    if not user.debug_trace_enabled:
+    # 权限闸:未开 debug_trace_enabled 的用户不下发 trace_url(列表页「复制调试链接」靠它)。
+    # include_trace=true 例外:客户端开了本机 agent 调试模式时带上,放行**本人记录**的 trace_url
+    # ——list_records 只查 user.id 自己的记录,给本人看自己的调试链接无越权,与实时结果页
+    # CompResultScreen「debug 权限 OR 本机 agent 调试」同口径(领导 2026-06-12 拍板)。
+    if not (user.debug_trace_enabled or include_trace):
         for o in outs:
             o.trace_url = None
     return ComparisonRecordPage(items=outs, next_cursor=next_cursor)

app/api/v1/cps_redirect.py

@@ -1,21 +1,48 @@
-"""CPS 群发短链跳转:用户点 /c/{code} → 记一条点击 → 302 跳美团。
+"""CPS 群发短链落地:用户点 /c/{code} → 记点击 → 按平台 302 跳 或 返回淘宝落地页。
 
-公网、无鉴权(群里任何人点都要能跳)。记点击失败绝不影响跳转(用户体验优先)。
+公网无鉴权(群里任何人点都要能跳/能领)。记点击失败绝不影响用户。
+- 美团/京东:记 visit + 302 跳 target(美团短链 / 京东链接)
+- 淘宝:记 visit + 返回 H5 落地页(整段淘口令复制按钮);点"复制口令"→ POST /c/{code}/copy 记 copy
 """
 from __future__ import annotations
 
+import html
+import json
+import logging
+
 from fastapi import APIRouter, Depends, Request
-from fastapi.responses import RedirectResponse
+from fastapi.responses import HTMLResponse, PlainTextResponse, RedirectResponse
 from sqlalchemy.orm import Session
 
+from app.core import media
+from app.core.config import settings
 from app.db.session import get_db
+from app.integrations import wx_oauth
+from app.models.cps_activity import CpsActivity
+from app.models.cps_link import CpsLink
 from app.repositories import cps_link as cps_link_repo
+from app.repositories import cps_wx_user as cps_wx_user_repo
+
+logger = logging.getLogger("shagua.cps_redirect")
 
 router = APIRouter(tags=["cps-redirect"])
 
-# code 不存在/失效时的兜底落地(避免用户看到报错)
+# code 不存在/失效时的兜底落地
 _FALLBACK_URL = "https://www.meituan.com/"
 
+# 淘宝活动未设图时的兜底主视觉(存量已回填,基本只在老 link/异常时触发)
+_DEFAULT_TAOBAO_IMAGE = "/media/taobao_landing.jpg"
+
+# 微信网页授权拿到的用户标识 cookie(种在 coupon 域,30 天免重复授权)
+_WX_OPENID_COOKIE = "wx_openid"
+_WX_UINFO_COOKIE = "wx_uinfo"  # "1" = 已拿过昵称头像(userinfo),点领券不再跳授权
+_COOKIE_MAX_AGE = 30 * 86400
+
+
+def _is_wechat(request: Request) -> bool:
+    """是否微信内置浏览器(网页授权只在微信内有意义,外部浏览器不跳授权)。"""
+    return "micromessenger" in (request.headers.get("user-agent", "").lower())
+
 
 def _client_ip(request: Request) -> str | None:
     xff = request.headers.get("x-forwarded-for")
@@ -24,16 +51,158 @@ def _client_ip(request: Request) -> str | None:
     return request.client.host if request.client else None
 
 
-@router.get("/c/{code}", summary="群发短链跳转(记点击 + 302)")
-def cps_redirect(code: str, request: Request, db: Session = Depends(get_db)):
-    link = cps_link_repo.get_by_code(db, code)
-    if link is None:
-        return RedirectResponse(_FALLBACK_URL, status_code=302)
+def _record(
+    db: Session, link: CpsLink, request: Request, event_type: str, openid: str | None = None
+) -> None:
     try:
         cps_link_repo.record_click(
             db, link=link, ip=_client_ip(request),
-            ua=request.headers.get("user-agent"),
+            ua=request.headers.get("user-agent"), event_type=event_type, openid=openid,
         )
     except Exception:
-        pass  # 记点击失败不阻断跳转
+        pass  # 记点击失败不阻断
+
+
+@router.get("/MP_verify_F7wnRQ7xPbhVOWC8.txt", include_in_schema=False)
+def wx_mp_domain_verify() -> PlainTextResponse:
+    """微信「网页授权域名」归属校验文件。coupon.shaguabijia.com 全反代 app-server,
+    微信请求 coupon.shaguabijia.com/MP_verify_xxx.txt 验证域名归属;内容=文件名核心串。
+    放域名根目录(本端点即根路径),为微信网页授权(拿 openid)接入做准备。"""
+    return PlainTextResponse("F7wnRQ7xPbhVOWC8")
+
+
+@router.get("/c/{code}", summary="群发短链落地(微信授权拿 openid + 记点击 + 跳转/淘宝落地页)")
+def cps_landing(code: str, request: Request, db: Session = Depends(get_db)):
+    link = cps_link_repo.get_by_code(db, code)
+    if link is None:
+        return RedirectResponse(_FALLBACK_URL, status_code=302)
+    openid = request.cookies.get(_WX_OPENID_COOKIE)
+    # 微信内 + 还没拿到 openid + 配了服务号 → 先 base 静默授权拿 openid,再 302 回本页。
+    # 非微信 / 已有 cookie / 未配服务号 → 直接走原逻辑(openid 可能为 None,绝不阻断领券)。
+    if openid is None and settings.wx_oauth_active and _is_wechat(request):
+        redirect_uri = f"{settings.CPS_REDIRECT_BASE.rstrip('/')}/wx/oauth/cb"
+        auth_url = wx_oauth.build_authorize_url(redirect_uri, "snsapi_base", f"base:{code}")
+        return RedirectResponse(auth_url, status_code=302)
+    _record(db, link, request, "visit", openid=openid)
+    if link.platform == "taobao":
+        activity = db.get(CpsActivity, link.activity_id)
+        image_url = (activity.image_url if activity else None) or _DEFAULT_TAOBAO_IMAGE
+        has_uinfo = request.cookies.get(_WX_UINFO_COOKIE) == "1"
+        return HTMLResponse(
+            _taobao_landing_html(link.target_url, image_url, code, openid, has_uinfo)
+        )
+    # 美团短链 / 京东链接:直接 302 跳
     return RedirectResponse(link.target_url, status_code=302)
+
+
+@router.get("/wx/oauth/cb", include_in_schema=False)
+def wx_oauth_cb(code: str, state: str, db: Session = Depends(get_db)):
+    """微信网页授权回调。state='base:{原code}'(静默拿 openid) 或 'uinfo:{原code}'(补昵称头像)。
+    换 openid(+userinfo)→ upsert 用户 → 种 cookie → 302 回落地页。任何失败兜底回落地页,
+    绝不阻断用户领券。"""
+    kind, _, orig_code = state.partition(":")
+    try:
+        token = wx_oauth.exchange_code(code)  # {openid, access_token, scope, ...}
+        openid = token["openid"]
+        link = cps_link_repo.get_by_code(db, orig_code)
+        group_id = link.group_id if link else None
+        nickname = headimgurl = unionid = None
+        if kind == "uinfo" and "userinfo" in (token.get("scope") or ""):
+            info = wx_oauth.get_userinfo(token["access_token"], openid)
+            nickname, headimgurl, unionid = (
+                info.get("nickname"), info.get("headimgurl"), info.get("unionid"),
+            )
+        cps_wx_user_repo.upsert(
+            db, openid=openid, code=orig_code, group_id=group_id,
+            nickname=nickname, headimgurl=headimgurl, unionid=unionid,
+        )
+    except Exception:
+        logger.exception("[wx_oauth] callback failed state=%s", state)
+        return RedirectResponse(f"/c/{orig_code}" if orig_code else _FALLBACK_URL, status_code=302)
+    # userinfo 授权回来带 ?authed=1,落地页据此自动触发复制(把"点领券→授权→复制"衔接为一步)
+    target = f"/c/{orig_code}" + ("?authed=1" if kind == "uinfo" else "")
+    resp = RedirectResponse(target, status_code=302)
+    resp.set_cookie(_WX_OPENID_COOKIE, openid, max_age=_COOKIE_MAX_AGE, httponly=True, samesite="lax")
+    if nickname:
+        resp.set_cookie(_WX_UINFO_COOKIE, "1", max_age=_COOKIE_MAX_AGE, samesite="lax")
+    return resp
+
+
+@router.post("/c/{code}/copy", summary="淘宝落地页点了「复制口令」(记 copy 事件,带 openid)")
+def cps_copy(code: str, request: Request, db: Session = Depends(get_db)) -> dict:
+    link = cps_link_repo.get_by_code(db, code)
+    if link is not None:
+        _record(db, link, request, "copy", openid=request.cookies.get(_WX_OPENID_COOKIE))
+    return {"ok": True}
+
+
+def _taobao_landing_html(
+    token: str, image_url: str, code: str, openid: str | None, has_uinfo: bool
+) -> str:
+    """淘宝落地页 H5(主视觉图按活动传入,复制淘口令按钮在 75% 屏高)。
+
+    image_url 经 html.escape 嵌入 <img src>(防注入);token 经 json.dumps 安全嵌入 JS。
+    uinfo_url:已有 openid 但还没拿过昵称头像时,生成 userinfo 授权链接 —— 用户点「领券」
+    时先跳它(交互触发,避免微信快照页),授权回来自动复制。已拿过 / 无 openid 则为空,直接复制。
+    """
+    safe_img = html.escape(media.to_abs_media_url(image_url) or image_url, quote=True)
+    uinfo_url = ""
+    if openid and not has_uinfo and settings.wx_oauth_active:
+        redirect_uri = f"{settings.CPS_REDIRECT_BASE.rstrip('/')}/wx/oauth/cb"
+        uinfo_url = wx_oauth.build_authorize_url(redirect_uri, "snsapi_userinfo", f"uinfo:{code}")
+    return (
+        _TAOBAO_HTML
+        .replace("__IMAGE_URL__", safe_img)
+        .replace("__UINFO_URL__", json.dumps(uinfo_url))
+        .replace("__TOKEN_JS__", json.dumps(token))
+    )
+
+
+_TAOBAO_HTML = """<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no">
+<title>淘宝闪购 · 天天领红包</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box;-webkit-tap-highlight-color:transparent}
+body{font-family:-apple-system,"PingFang SC",sans-serif;background:#fff0ef;color:#333;min-height:100vh}
+.hero{display:block;width:100%}
+.btn-wrap{position:fixed;left:0;right:0;top:75vh;padding:0 20px}
+.btn{display:block;width:100%;background:linear-gradient(90deg,#ff5b5b,#ff3b3b);color:#fff;font-size:19px;font-weight:800;text-align:center;padding:16px;border:none;border-radius:30px;box-shadow:0 6px 16px rgba(255,59,59,.4)}
+.btn:active{transform:scale(.98)}
+.toast{position:fixed;left:50%;top:42%;transform:translate(-50%,-50%);background:rgba(0,0,0,.82);color:#fff;padding:12px 22px;border-radius:10px;font-size:15px;opacity:0;transition:opacity .25s;pointer-events:none;z-index:99;white-space:nowrap}
+.toast.show{opacity:1}
+</style>
+</head>
+<body>
+<img class="hero" src="__IMAGE_URL__" alt="淘宝闪购 天天领红包">
+<div class="btn-wrap"><button class="btn" onclick="copyToken()">复制口令去淘宝领红包</button></div>
+<div class="toast" id="toast"></div>
+<script>
+var TOKEN = __TOKEN_JS__;
+var UINFO_URL = __UINFO_URL__;  // 非空=还没拿昵称头像,点领券先跳它补(授权回来自动复制)
+function showToast(m){var t=document.getElementById('toast');t.textContent=m;t.classList.add('show');setTimeout(function(){t.classList.remove('show')},2200)}
+function reportCopy(){try{fetch(location.pathname+'/copy',{method:'POST',keepalive:true})}catch(e){}}
+function done(){showToast('复制成功!打开淘宝即可领取');reportCopy()}
+function fallback(){
+  var ta=document.createElement('textarea');ta.value=TOKEN;ta.style.position='fixed';ta.style.opacity='0';
+  document.body.appendChild(ta);ta.focus();ta.select();
+  try{document.execCommand('copy');done()}catch(e){showToast('复制失败,请长按手动复制')}
+  document.body.removeChild(ta);
+}
+function doCopy(){
+  if(navigator.clipboard&&window.isSecureContext){navigator.clipboard.writeText(TOKEN).then(done).catch(fallback)}
+  else{fallback()}
+}
+function copyToken(){
+  // 第一次领券且还没授权过昵称头像:先跳 userinfo 授权(用户点击=交互触发,避免快照页),
+  // 授权回来 ?authed=1 自动复制;已授权过/无 openid 则直接复制。
+  if(UINFO_URL){location.href=UINFO_URL;return}
+  doCopy();
+}
+// userinfo 授权回流(?authed=1):自动复制,把"点领券→授权→复制"衔接成一步无感
+if(location.search.indexOf('authed=1')>=0){doCopy()}
+</script>
+</body>
+</html>"""

app/api/v1/device.py

@@ -0,0 +1,96 @@
+"""设备注册 / 心跳 endpoint(无障碍保护存活检测)。
+
+路由前缀 /api/v1/device,需 Bearer 鉴权(设备绑登录用户)。
+  POST /register   注册设备 / 更新 registration_id(App 前台、拿到 push token 时调)
+  POST /heartbeat  上报心跳(无障碍服务存活时周期调,刷新存活)
+
+后端 heartbeat_monitor_worker 据此发现心跳超时的设备并极光推送告警。
+见 spec: spec/accessibility-liveness-push.md。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import device as device_repo
+from app.schemas.device import (
+    DeviceOut,
+    DeviceRegisterRequest,
+    HeartbeatRequest,
+    LivenessAckRequest,
+    LivenessOut,
+    OkResponse,
+)
+
+logger = logging.getLogger("shagua.device")
+
+router = APIRouter(prefix="/api/v1/device", tags=["device"])
+
+
+@router.post("/register", response_model=DeviceOut, summary="注册设备/更新推送token")
+def register_device(
+    req: DeviceRegisterRequest,
+    user: CurrentUser,
+    db: DbSession,
+) -> DeviceOut:
+    device = device_repo.register_or_update(
+        db,
+        user_id=user.id,
+        device_id=req.device_id,
+        registration_id=req.registration_id,
+        platform=req.platform,
+        app_version=req.app_version,
+    )
+    logger.info(
+        "device register user_id=%d device_id=%s reg=%s",
+        user.id,
+        req.device_id,
+        bool(req.registration_id),
+    )
+    return DeviceOut.model_validate(device)
+
+
+@router.post("/heartbeat", response_model=OkResponse, summary="上报心跳")
+def report_heartbeat(
+    req: HeartbeatRequest,
+    user: CurrentUser,
+    db: DbSession,
+) -> OkResponse:
+    device_repo.touch_heartbeat(
+        db,
+        user_id=user.id,
+        device_id=req.device_id,
+        accessibility_enabled=req.accessibility_enabled,
+        registration_id=req.registration_id,
+    )
+    return OkResponse()
+
+
+@router.get("/liveness", response_model=LivenessOut, summary="查询本机掉线告警(后置检测)")
+def get_liveness(
+    device_id: str,
+    user: CurrentUser,
+    db: DbSession,
+) -> LivenessOut:
+    """客户端进 App 时拉取: 本机是否被判定掉线过(kill_alert_pending)。
+
+    设备从未注册过 → 返回默认(无告警)。命中 → 客户端弹「开启自启动」引导, 之后调 /liveness/ack 清。
+    见 spec: spec/accessibility-liveness-pull-prompt.md。
+    """
+    device = device_repo.get_device(db, user_id=user.id, device_id=device_id)
+    if device is None:
+        return LivenessOut()
+    return LivenessOut.model_validate(device)
+
+
+@router.post("/liveness/ack", response_model=OkResponse, summary="确认已提醒(清掉线告警)")
+def ack_liveness(
+    req: LivenessAckRequest,
+    user: CurrentUser,
+    db: DbSession,
+) -> OkResponse:
+    """客户端已弹过「开启自启动」引导 → 清掉「待提醒」标记(下次真掉线 worker 再置)。"""
+    device_repo.ack_kill_alert(db, user_id=user.id, device_id=req.device_id)
+    return OkResponse()

app/api/v1/feedback.py

@@ -2,6 +2,7 @@
 
 路由前缀 `/api/v1/feedback`,需 Bearer 鉴权(反馈绑到登录用户,便于回访)。
   POST /  提交反馈(multipart:content 必填;contact 可选(原型改版后客户端已不再采集);images 可选 ≤6 张)
+  GET /records  我的反馈历史(pending/adopted/rejected)
 
 截图复用 [app.core.media] 落盘到 /media/feedback/。
 """
@@ -9,12 +10,19 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from fastapi import APIRouter, File, Form, HTTPException, Query, UploadFile
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import media
 from app.repositories import feedback as feedback_repo
-from app.schemas.feedback import FeedbackOut
+from app.repositories import feedback_qr as feedback_qr_repo
+from app.schemas.feedback import (
+    FeedbackOut,
+    FeedbackQrConfigOut,
+    FeedbackRecordCountsOut,
+    FeedbackRecordOut,
+    FeedbackRecordsOut,
+)
 
 logger = logging.getLogger("shagua.feedback")
 
@@ -23,6 +31,27 @@ router = APIRouter(prefix="/api/v1/feedback", tags=["feedback"])
 _MAX_IMAGES = 6
 _CONTENT_MAX = 200
 _CONTACT_MAX = 128
+_VALID_RECORD_STATUS = {"pending", "adopted", "rejected"}
+
+
+def _app_status(db_status: str) -> str:
+    return {
+        "new": "pending",
+        "handled": "adopted",
+        "approved": "adopted",
+    }.get(db_status, db_status)
+
+
+def _record_out(fb) -> FeedbackRecordOut:
+    return FeedbackRecordOut(
+        id=fb.id,
+        content=fb.content,
+        images=fb.images or [],
+        status=_app_status(fb.status),
+        reject_reason=getattr(fb, "reject_reason", None),
+        reward_coins=getattr(fb, "reward_coins", None),
+        created_at=fb.created_at,
+    )
 
 
 @router.post("", response_model=FeedbackOut, summary="提交反馈")
@@ -60,3 +89,29 @@ async def submit_feedback(
     )
     logger.info("feedback id=%d user_id=%d images=%d", fb.id, user.id, len(urls))
     return FeedbackOut.model_validate(fb)
+
+
+@router.get("/config", response_model=FeedbackQrConfigOut, summary="反馈页二维码卡配置")
+def feedback_config(user: CurrentUser, db: DbSession) -> FeedbackQrConfigOut:
+    """运营后台配的反馈页「加群二维码」卡(开关 + 二维码图 + 三行文案)。客户端进反馈页时拉取。"""
+    return FeedbackQrConfigOut(**feedback_qr_repo.get_config(db))
+
+
+@router.get("/records", response_model=FeedbackRecordsOut, summary="我的反馈历史")
+def feedback_records(
+    user: CurrentUser,
+    db: DbSession,
+    status: str | None = Query(default=None),
+) -> FeedbackRecordsOut:
+    if status is not None and status not in _VALID_RECORD_STATUS:
+        raise HTTPException(status_code=400, detail="invalid status")
+
+    all_records = [_record_out(fb) for fb in feedback_repo.list_feedback(db, user_id=user.id)]
+    counts = FeedbackRecordCountsOut(
+        all=len(all_records),
+        pending=sum(1 for r in all_records if r.status == "pending"),
+        adopted=sum(1 for r in all_records if r.status == "adopted"),
+        rejected=sum(1 for r in all_records if r.status == "rejected"),
+    )
+    records = [r for r in all_records if r.status == status] if status else all_records
+    return FeedbackRecordsOut(records=records, counts=counts)

app/api/v1/platform.py

@@ -17,7 +17,9 @@ from app.repositories import app_config
 from app.repositories import ops_marquee as marquee_crud
 from app.repositories import ops_stat as crud
 from app.schemas.platform import (
+    AdConfigPublicOut,
     AppFlagsOut,
+    AppVersionOut,
     PlatformStatsOut,
     SavingsFeedItem,
     SavingsFeedOut,
@@ -51,3 +53,29 @@ def flags(db: DbSession) -> AppFlagsOut:
     return AppFlagsOut(
         comparing_ad_enabled=bool(app_config.get_value(db, "comparing_ad_enabled")),
     )
+
+
+@router.get("/ad-config", response_model=AdConfigPublicOut, summary="客户端拉广告配置(穿山甲ID+场景开关,不鉴权)")
+def ad_config(db: DbSession) -> AdConfigPublicOut:
+    """客户端启动/每场广告前拉,缓存后用:app_id + 各位ID + 各场景开关。
+    不含验签密钥;空库回退默认(=客户端内置值,维持现状)。"""
+    c = app_config.get_ad_config(db)
+    return AdConfigPublicOut(
+        app_id=c["app_id"],
+        reward_code_id=c["reward_code_id"],
+        compare_feed_code_id=c["compare_feed_code_id"],
+        coupon_feed_code_id=c["coupon_feed_code_id"],
+        reward_enabled=c["reward_enabled"],
+        compare_ad_enabled=c["compare_ad_enabled"],
+        coupon_ad_enabled=c["coupon_ad_enabled"],
+    )
+
+
+@router.get("/app-version", response_model=AppVersionOut, summary="最新 App 版本(OTA 检查更新,不鉴权)")
+def app_version(db: DbSession) -> AppVersionOut:
+    """客户端启动 / 手动检查更新时拉取。不鉴权:版本信息非敏感,且检查更新可能在登录前。
+    用 latest_version_code 与本机 versionCode 比;未配置(返回默认 0)时客户端视为已是最新。"""
+    data = app_config.get_app_version(db)
+    if not data:
+        return AppVersionOut()
+    return AppVersionOut(**data)

app/api/v1/user.py

@@ -18,6 +18,7 @@ from app.api.deps import CurrentUser, DbSession
 from app.core import media
 from app.repositories import onboarding as onboarding_repo
 from app.repositories import user as user_repo
+from app.repositories import wallet as wallet_repo
 from app.schemas.auth import UserOut
 from app.schemas.user import (
     OkResponse,
@@ -87,6 +88,17 @@ def onboarding_status(
 
 @router.delete("", response_model=OkResponse, summary="注销账号(软删除)")
 def delete_account(user: CurrentUser, db: DbSession) -> OkResponse:
+    # 资金前置校验:注销是软删 + 匿名化,余额一旦留在 deleted 行就锁死(既退不出、新号也
+    # 拿不回)。有可提现现金 / 在审提现单 → 拒绝注销,引导用户先把钱处理掉。
+    # (pending 提现转账已在途、对账 worker 不依赖 user.status 照常到账,故不拦 pending。)
+    if wallet_repo.get_cash_balance_cents(db, user.id) > 0:
+        raise HTTPException(
+            status_code=409, detail="账户还有未提现的现金余额,请先提现后再注销"
+        )
+    if wallet_repo.has_reviewing_withdraw(db, user.id):
+        raise HTTPException(
+            status_code=409, detail="有提现正在审核中,请等审核完成后再注销"
+        )
     media.delete_avatar(user.avatar_url)
     user_repo.soft_delete_account(db, user)
     logger.info("delete account user_id=%d", user.id)

app/core/config.py

@@ -66,6 +66,11 @@ class Settings(BaseSettings):
     JG_VERIFY_ENDPOINT: str = "https://api.verification.jpush.cn/v1/web/loginTokenVerify"
     JG_REQUEST_TIMEOUT_SEC: int = 15
 
+    # 无障碍保护存活监控后台任务(pull 后置检测;本期不接推送)
+    HEARTBEAT_MONITOR_ENABLED: bool = True       # 总开关
+    HEARTBEAT_TIMEOUT_MINUTES: int = 10          # 多久没心跳算掉线(≈3 个客户端心跳周期)
+    HEARTBEAT_SCAN_INTERVAL_SEC: int = 60        # 扫描周期
+
     # ===== 短信 =====
     SMS_MOCK: bool = True
     SMS_CODE_TTL_SEC: int = 300
@@ -95,6 +100,25 @@ class Settings(BaseSettings):
         """美团 CPS 凭证齐全(缺则接口返空,而非 502)。"""
         return bool(self.MT_CPS_APP_KEY and self.MT_CPS_APP_SECRET)
 
+    # ===== 微信服务号(网页授权) =====
+    # CPS 落地页在微信内拿用户 openid(base 静默)/昵称头像(userinfo),做用户级群统计。
+    # ⚠️ 区别于 WECHAT_APP_ID(那是 App 移动应用,用于微信支付);这是【已认证服务号】。
+    WX_MP_APPID: str = ""
+    WX_MP_SECRET: str = ""
+    # 落地页微信网页授权【总开关】。默认关:服务号认证审核中/未就绪时,落地页走原逻辑
+    # (不跳授权、不拿 openid),整套微信代码保留。审核通过后 .env 置 true + 重启即启用,无需改代码。
+    WX_MP_OAUTH_ENABLED: bool = False
+
+    @property
+    def wx_mp_configured(self) -> bool:
+        """服务号网页授权凭证齐全(缺则落地页不发起授权,降级为无 openid)。"""
+        return bool(self.WX_MP_APPID and self.WX_MP_SECRET)
+
+    @property
+    def wx_oauth_active(self) -> bool:
+        """落地页是否真正发起微信授权 = 凭证齐全 且 总开关开。"""
+        return self.wx_mp_configured and self.WX_MP_OAUTH_ENABLED
+
     # ===== 微信支付(商家转账到零钱 / 提现)=====
     # 真实凭证放 .env(已 gitignore),证书 .pem 放 secrets/。WECHAT_APP_ID 同时用于
     # 微信登录(code 换 openid)与转账,必须与 App 端开放平台 appid 一致。
@@ -110,10 +134,14 @@ class Settings(BaseSettings):
     WITHDRAW_AUTO_RECONCILE_ENABLED: bool = False
     WITHDRAW_AUTO_RECONCILE_INTERVAL_SEC: int = 300
     WITHDRAW_AUTO_RECONCILE_OLDER_THAN_MINUTES: int = 15
-    # 0 点自动兑金币(由 deploy/daily-exchange.timer 触发 scripts.daily_auto_exchange)。
-    # 客户端已删手动兑入口、改为「0 点自动兑现金」,故默认开;运营要临时停可在 .env 置 false,
-    # 无需动 systemd timer——脚本读此开关,false 时直接 no-op 退出。
+    # 0 点自动兑金币:由 App 进程内任务 app.core.daily_exchange_worker 跨 0 点跑一轮
+    # wallet.daily_auto_exchange(原 deploy/daily-exchange.timer 已不再需要,见 deploy/daily-exchange.md)。
+    # 客户端已删手动兑入口、改为「0 点自动兑现金」,故默认开;运营要临时停在 .env 置 false
+    # (worker 不启动;脚本也 no-op)。
     AUTO_EXCHANGE_ENABLED: bool = True
+    # 进程内自动兑换 worker 的检查间隔(秒):每隔这么久醒一次,跨过北京 0 点就跑一轮。
+    # 默认 600s=10min,即 0 点后最多 10 分钟内兑完(客户端文案已注明「可能存在延迟」)。
+    AUTO_EXCHANGE_CHECK_INTERVAL_SEC: int = 600
     # 免确认收款授权(用户授权免确认模式)的授权结果回调地址,必须公网可访问 HTTPS、不带参数。
     # 发起授权 / 首单顺带授权时作为 authorization_notify_url 传给微信。一期不处理回调内容
     # (授权状态靠 query 查询兜底),但微信要求该字段非空,故启用免确认前必须配置;留空时免确认相关接口返回未配置。

app/core/daily_exchange_worker.py

@@ -0,0 +1,125 @@
+"""0 点金币→现金自动兑换的进程内定时任务。
+
+替代原 systemd timer(deploy/daily-exchange.*):App 启动即自带,每
+`AUTO_EXCHANGE_CHECK_INTERVAL_SEC` 醒一次,跨进北京新的一天(0 点后)就跑一轮
+`wallet.daily_auto_exchange`。
+
+健壮性:
+- **逐用户幂等**:当天已有 exchange_in 流水的用户跳过(见 wallet._has_exchange_in_on),
+  故启动补跑 / 多次唤醒 / 进程重启都安全,不会重复兑。
+- **当天首跑即补**:进程起来时若当天还没兑过,立即兑一轮(等价原 timer 的 Persistent 补跑)。
+- **同机多进程互斥**:文件锁保证多 worker 只有一个实际跑(防跨进程并发导致 TOCTOU 双兑)。
+- **开关**:settings.AUTO_EXCHANGE_ENABLED=false 时不启动(与脚本/原 timer 同一开关)。
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import time
+from collections.abc import Iterator
+from datetime import date
+from pathlib import Path
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from app.core import rewards
+from app.core.config import settings
+from app.db.session import SessionLocal
+from app.repositories import wallet as wallet_repo
+
+logger = logging.getLogger("shagua.daily_exchange")
+_LOCK_PATH = Path(__file__).resolve().parents[2] / "data" / "daily_exchange.lock"
+
+
+def _touch_lock() -> None:
+    with contextlib.suppress(FileNotFoundError):
+        os.utime(_LOCK_PATH, None)
+
+
+@contextlib.contextmanager
+def _single_instance_lock(stale_after_sec: int) -> Iterator[bool]:
+    """同机多进程保护:同一时间只允许一个自动兑换 worker 运行。"""
+    _LOCK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd: int | None = None
+    try:
+        try:
+            fd = os.open(str(_LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            try:
+                age = time.time() - _LOCK_PATH.stat().st_mtime
+            except FileNotFoundError:
+                age = stale_after_sec + 1
+            if age > stale_after_sec:
+                with contextlib.suppress(FileNotFoundError):
+                    _LOCK_PATH.unlink()
+                try:
+                    fd = os.open(str(_LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                except FileExistsError:
+                    fd = None
+
+        if fd is None:
+            yield False
+            return
+
+        os.write(fd, f"pid={os.getpid()} started_at={int(time.time())}\n".encode("ascii"))
+        yield True
+    finally:
+        if fd is not None:
+            os.close(fd)
+            with contextlib.suppress(FileNotFoundError):
+                _LOCK_PATH.unlink()
+
+
+def _exchange_once() -> dict:
+    with SessionLocal() as db:
+        return wallet_repo.daily_auto_exchange(db)
+
+
+async def _run_loop() -> None:
+    interval = max(60, int(settings.AUTO_EXCHANGE_CHECK_INTERVAL_SEC))
+    lock_stale_after = max(interval * 3, 1800)
+    with _single_instance_lock(lock_stale_after) as lock_acquired:
+        if not lock_acquired:
+            logger.warning("daily auto-exchange skipped: another worker owns lock")
+            return
+        await _run_locked_loop(interval)
+
+
+async def _run_locked_loop(interval: int) -> None:
+    logger.info("daily auto-exchange worker started interval=%ss", interval)
+    # 本进程上次跑过的北京日;None=尚未跑过本进程(启动即补当天)。
+    last_run: date | None = None
+    try:
+        while True:
+            try:
+                _touch_lock()
+                today = rewards.cn_today()
+                if last_run != today:
+                    result = await asyncio.to_thread(_exchange_once)
+                    last_run = today
+                    logger.info("daily auto-exchange done date=%s result=%s", today, result)
+            except SQLAlchemyError:
+                logger.exception("daily auto-exchange db error")
+            except Exception:  # noqa: BLE001 - 后台任务不能因单次异常退出
+                logger.exception("daily auto-exchange unexpected error")
+            await asyncio.sleep(interval)
+    except asyncio.CancelledError:
+        logger.info("daily auto-exchange worker stopped")
+        raise
+
+
+def start_daily_exchange_worker() -> asyncio.Task | None:
+    if not settings.AUTO_EXCHANGE_ENABLED:
+        logger.info("daily auto-exchange disabled (AUTO_EXCHANGE_ENABLED=false)")
+        return None
+    return asyncio.create_task(_run_loop(), name="daily-auto-exchange")
+
+
+async def stop_daily_exchange_worker(task: asyncio.Task | None) -> None:
+    if task is None:
+        return
+    task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await task

app/core/heartbeat_monitor_worker.py

@@ -0,0 +1,148 @@
+"""无障碍保护存活监控后台任务。
+
+周期扫描「曾经保护过、当前 alive、心跳超时」的设备 = App 被彻底杀掉/无障碍已停(心跳断了),
+**命中即在服务器终端打印告警**(本期先不接推送,工程量大,用终端打印代替真实通知);并把状态机
+推进到 notified 防每轮重复打印(心跳恢复时由 repositories.device.touch_heartbeat 重置回 alive)。
+结构仿 withdraw_reconcile_worker(单实例锁 + asyncio 轮询 + 优雅退出)。
+
+见 spec: spec/accessibility-liveness-push.md。
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import time
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from pathlib import Path
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from app.core.config import settings
+from app.db.session import SessionLocal
+from app.repositories import device as device_repo
+
+logger = logging.getLogger("shagua.heartbeat_monitor")
+_LOCK_PATH = Path(__file__).resolve().parents[2] / "data" / "heartbeat_monitor.lock"
+
+
+def _touch_lock() -> None:
+    with contextlib.suppress(FileNotFoundError):
+        os.utime(_LOCK_PATH, None)
+
+
+@contextlib.contextmanager
+def _single_instance_lock(stale_after_sec: int) -> Iterator[bool]:
+    """同机多进程保护:同一时间只允许一个监控 worker 运行。"""
+    _LOCK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd: int | None = None
+    try:
+        try:
+            fd = os.open(str(_LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            try:
+                age = time.time() - _LOCK_PATH.stat().st_mtime
+            except FileNotFoundError:
+                age = stale_after_sec + 1
+            if age > stale_after_sec:
+                with contextlib.suppress(FileNotFoundError):
+                    _LOCK_PATH.unlink()
+                try:
+                    fd = os.open(str(_LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                except FileExistsError:
+                    fd = None
+
+        if fd is None:
+            yield False
+            return
+
+        os.write(fd, f"pid={os.getpid()} started_at={int(time.time())}\n".encode("ascii"))
+        yield True
+    finally:
+        if fd is not None:
+            os.close(fd)
+            with contextlib.suppress(FileNotFoundError):
+                _LOCK_PATH.unlink()
+
+
+def _silent_seconds(last: datetime | None) -> int | None:
+    """距上次心跳的秒数(兼容 sqlite 取回的 naive datetime)。"""
+    if last is None:
+        return None
+    ref = datetime.now(timezone.utc) if last.tzinfo is not None else datetime.utcnow()
+    return int((ref - last).total_seconds())
+
+
+def _scan_once(timeout_minutes: int) -> dict:
+    """扫描一轮:找出心跳超时(App 被彻底杀掉/无障碍已停)的设备,在**服务器终端打印**告警代替真实推送。
+
+    本期不接推送(极光/厂商通道工程量大),只做服务端掉线检测:命中即 logger.warning 打印到终端,
+    并把状态机推进到 notified 防每轮重复打印(心跳恢复时 touch_heartbeat 会重置回 alive)。
+    """
+    notified = 0
+    with SessionLocal() as db:
+        overdue = device_repo.list_overdue(db, timeout_minutes=timeout_minutes)
+        for device in overdue:
+            silent = _silent_seconds(device.last_heartbeat_at)
+            logger.warning(
+                "[掉线检测] user_id=%s device_id=%s 已 %s 秒无心跳(阈值 %d 分钟)"
+                " → 判定 App 已被杀/无障碍已停。【已置 kill_alert_pending: 用户下次进 App 将弹「开启自启动」引导(后置检测);推送本期未接】",
+                device.user_id,
+                device.device_id,
+                silent if silent is not None else "?",
+                timeout_minutes,
+            )
+            device_repo.mark_notified(db, device_id_pk=device.id)
+            notified += 1
+        return {"checked": len(overdue), "notified": notified}
+
+
+async def _run_loop() -> None:
+    interval = max(10, int(settings.HEARTBEAT_SCAN_INTERVAL_SEC))
+    timeout_minutes = max(1, int(settings.HEARTBEAT_TIMEOUT_MINUTES))
+    lock_stale_after = max(interval * 3, 600)
+    with _single_instance_lock(lock_stale_after) as lock_acquired:
+        if not lock_acquired:
+            logger.warning("heartbeat monitor skipped: another worker owns lock")
+            return
+        await _run_locked_loop(interval, timeout_minutes)
+
+
+async def _run_locked_loop(interval: int, timeout_minutes: int) -> None:
+    logger.info(
+        "heartbeat monitor started interval=%ss timeout=%sm",
+        interval,
+        timeout_minutes,
+    )
+    try:
+        while True:
+            try:
+                _touch_lock()
+                result = await asyncio.to_thread(_scan_once, timeout_minutes)
+                if result["notified"]:
+                    logger.info("heartbeat monitor result=%s", result)
+            except SQLAlchemyError:
+                logger.exception("heartbeat monitor db error")
+            except Exception:  # noqa: BLE001 - 后台任务不能因单次异常退出
+                logger.exception("heartbeat monitor unexpected error")
+            await asyncio.sleep(interval)
+    except asyncio.CancelledError:
+        logger.info("heartbeat monitor stopped")
+        raise
+
+
+def start_heartbeat_monitor() -> asyncio.Task | None:
+    if not settings.HEARTBEAT_MONITOR_ENABLED:
+        logger.info("heartbeat monitor disabled")
+        return None
+    return asyncio.create_task(_run_loop(), name="heartbeat-monitor")
+
+
+async def stop_heartbeat_monitor(task: asyncio.Task | None) -> None:
+    if task is None:
+        return
+    task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await task

app/core/media.py

@@ -37,7 +37,7 @@ def _sniff_ext(data: bytes) -> str | None:
     return None
 
 
-def _save_image(subdir: str, user_id: int, data: bytes) -> str:
+def _save_named(subdir: str, name_prefix: str, data: bytes) -> str:
     """通用图片落盘:校验非空 / ≤上限 / 魔数为图片,随机文件名,返回相对 URL。"""
     if not data:
         raise MediaError("空文件")
@@ -47,11 +47,16 @@ def _save_image(subdir: str, user_id: int, data: bytes) -> str:
     if ext is None:
         raise MediaError("仅支持 JPEG / PNG / WebP 图片")
 
-    fname = f"u{user_id}_{secrets.token_hex(8)}{ext}"
+    fname = f"{name_prefix}_{secrets.token_hex(8)}{ext}"
     (_media_dir(subdir) / fname).write_bytes(data)
     return f"{settings.MEDIA_URL_PREFIX}/{subdir}/{fname}"
 
 
+def _save_image(subdir: str, user_id: int, data: bytes) -> str:
+    """用户上传图片落盘(文件名带 user_id 前缀)。"""
+    return _save_named(subdir, f"u{user_id}", data)
+
+
 def save_avatar(user_id: int, data: bytes) -> str:
     """保存头像,返回相对 URL(`/media/avatars/<file>`)。"""
     return _save_image("avatars", user_id, data)
@@ -67,15 +72,47 @@ def save_report_image(user_id: int, data: bytes) -> str:
     return _save_image("price_report", user_id, data)
 
 
-def delete_avatar(url: str | None) -> None:
-    """删除本服务托管的旧头像文件;外部 URL(如微信头像)或空值不处理。"""
-    prefix = f"{settings.MEDIA_URL_PREFIX}/avatars/"
+def save_feedback_qr(data: bytes) -> str:
+    """保存反馈页二维码(运营后台上传的运营素材,非用户文件),返回相对 URL(`/media/feedback_qr/<file>`)。"""
+    return _save_named("feedback_qr", "qr", data)
+
+
+def save_cps_image(admin_id: int, data: bytes) -> str:
+    """保存 CPS 活动落地页图,返回相对 URL(`/media/cps/<file>`)。admin_id 入文件名便于追溯。"""
+    return _save_image("cps", admin_id, data)
+
+
+def to_abs_media_url(rel_url: str | None) -> str | None:
+    """相对 `/media/...` → 基于 CPS_REDIRECT_BASE 的绝对 URL(CPS 落地页域名,跨域可访问)。
+
+    已是绝对 URL / 空 / base 未配(dev) 时原样返回。CPS 活动图入库前转绝对,使落地页
+    (coupon 域)与 admin-web(另一域,不 serve /media)都能直接 <img src> 加载。
+    """
+    if not rel_url or rel_url.startswith(("http://", "https://")):
+        return rel_url
+    base = settings.CPS_REDIRECT_BASE.rstrip("/")
+    return f"{base}{rel_url}" if base else rel_url
+
+
+def _delete_managed(subdir: str, url: str | None) -> None:
+    """删除本服务托管的某子目录下文件;外部 URL / 空值 / 非本子目录的不处理。"""
+    prefix = f"{settings.MEDIA_URL_PREFIX}/{subdir}/"
     if not url or not url.startswith(prefix):
         return
     fname = url[len(prefix):]
     if not fname or "/" in fname or "\\" in fname or ".." in fname:
         return  # 防路径穿越
     try:
-        (_media_dir("avatars") / fname).unlink(missing_ok=True)
+        (_media_dir(subdir) / fname).unlink(missing_ok=True)
     except OSError:
         pass
+
+
+def delete_avatar(url: str | None) -> None:
+    """删除本服务托管的旧头像文件;外部 URL(如微信头像)或空值不处理。"""
+    _delete_managed("avatars", url)
+
+
+def delete_feedback_qr(url: str | None) -> None:
+    """删除本服务托管的旧反馈页二维码文件;外部 URL 或空值不处理。"""
+    _delete_managed("feedback_qr", url)

app/core/rewards.py

@@ -108,6 +108,10 @@ def record_milestone_reward(milestone: int) -> int:
 # 与广告/任务同量级;固定值(产品 2026-06 定),要调直接改这里;客户端记录页按 reward_coins 显示。
 PRICE_REPORT_REWARD_COINS: int = 1000
 
+# ===== 意见反馈采纳奖励(人工审核按质量发放)=====
+# 后台审核反馈时允许发放的单条金币上限。只做后端硬保护,具体档位由 admin-web 呈现。
+FEEDBACK_REWARD_MAX_COINS: int = 10000
+
 
 # ===== 邀请好友(注册即生效,邀请人 + 被邀请人各发金币)=====
 # 10000 金币 = 1 元,双方各得 1 元。MVP 先用固定常量(不走 app_config)。

app/integrations/wx_oauth.py

@@ -0,0 +1,75 @@
+"""微信服务号网页授权:构造授权链接 + code 换 openid + 拉 userinfo。
+
+用于 CPS 落地页(coupon.shaguabijia.com)在微信内拿用户身份。流程(见微信文档):
+  授权链接(snsapi_base|snsapi_userinfo) → 回调带 code → sns/oauth2/access_token 换 openid
+  → (userinfo 时)sns/userinfo 拿昵称头像。
+
+注意:
+  - 这里的 access_token 是【网页授权 token】,与基础 access_token(cgi-bin/token)不同,
+    走 sns/* 接口,不需要 IP 白名单。
+  - secret 只在服务器,不下发客户端。
+  - 用 WX_MP_APPID/SECRET(已认证服务号),区别于 WECHAT_APP_ID(App 移动应用)。
+"""
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+
+from app.core.config import settings
+
+_API = "https://api.weixin.qq.com"
+_AUTHORIZE = "https://open.weixin.qq.com/connect/oauth2/authorize"
+_TIMEOUT = 10
+
+
+class WxOauthError(Exception):
+    """网页授权调用失败(凭证/网络/code 失效等)。调用方兜底为无 openid。"""
+
+
+def build_authorize_url(redirect_uri: str, scope: str, state: str) -> str:
+    """构造网页授权跳转链接。scope: 'snsapi_base'(静默,仅 openid) | 'snsapi_userinfo'(昵称头像)。
+
+    微信要求 redirect_uri urlEncode、参数顺序固定、结尾 #wechat_redirect。
+    """
+    return (
+        f"{_AUTHORIZE}?appid={settings.WX_MP_APPID}"
+        f"&redirect_uri={quote(redirect_uri, safe='')}"
+        f"&response_type=code&scope={scope}&state={quote(state, safe='')}"
+        f"#wechat_redirect"
+    )
+
+
+def exchange_code(code: str) -> dict:
+    """code 换网页授权 access_token + openid。返回含 openid/access_token/scope(/unionid)。
+
+    code 5 分钟内一次性有效。失败(errcode)抛 WxOauthError。
+    """
+    resp = httpx.get(
+        f"{_API}/sns/oauth2/access_token",
+        params={
+            "appid": settings.WX_MP_APPID,
+            "secret": settings.WX_MP_SECRET,
+            "code": code,
+            "grant_type": "authorization_code",
+        },
+        timeout=_TIMEOUT,
+    )
+    data = resp.json()
+    if "openid" not in data:
+        raise WxOauthError(f"exchange_code failed: {data}")
+    return data
+
+
+def get_userinfo(access_token: str, openid: str) -> dict:
+    """拉用户信息(nickname/headimgurl/unionid)。需 scope=snsapi_userinfo 的 access_token。"""
+    resp = httpx.get(
+        f"{_API}/sns/userinfo",
+        params={"access_token": access_token, "openid": openid, "lang": "zh_CN"},
+        timeout=_TIMEOUT,
+    )
+    resp.encoding = "utf-8"  # 昵称含中文/emoji,强制 utf-8 避免乱码
+    data = resp.json()
+    if "openid" not in data:
+        raise WxOauthError(f"get_userinfo failed: {data}")
+    return data

app/main.py

@@ -20,7 +20,10 @@ from app.api.v1.compare import router as compare_router
 from app.api.v1.compare_milestone import router as compare_milestone_router
 from app.api.v1.compare_record import router as compare_record_router
 from app.api.v1.coupon import router as coupon_router
+from app.api.v1.device import router as device_router
 from app.api.v1.cps_redirect import router as cps_redirect_router
+from app.api.internal.app_version import router as internal_app_version_router
+from app.api.internal.launch_confirm import router as internal_launch_confirm_router
 from app.api.internal.price import router as internal_price_router
 from app.api.internal.store import router as internal_store_router
 from app.api.v1.feedback import router as feedback_router
@@ -36,6 +39,14 @@ from app.api.v1.user import router as user_router
 from app.api.v1.wallet import router as wallet_router
 from app.api.v1.wxpay import router as wxpay_router
 from app.core.config import settings
+from app.core.heartbeat_monitor_worker import (
+    start_heartbeat_monitor,
+    stop_heartbeat_monitor,
+)
+from app.core.daily_exchange_worker import (
+    start_daily_exchange_worker,
+    stop_daily_exchange_worker,
+)
 from app.core.logging import setup_logging
 from app.core.withdraw_reconcile_worker import (
     start_withdraw_reconcile_worker,
@@ -57,10 +68,14 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
         settings.DATABASE_URL.split("://", 1)[0],
     )
     reconcile_task = start_withdraw_reconcile_worker()
+    heartbeat_task = start_heartbeat_monitor()
+    daily_exchange_task = start_daily_exchange_worker()
     try:
         yield
     finally:
+        await stop_heartbeat_monitor(heartbeat_task)
         await stop_withdraw_reconcile_worker(reconcile_task)
+        await stop_daily_exchange_worker(daily_exchange_task)
         logger.info("shutting down")
 
 
@@ -92,6 +107,7 @@ app.include_router(user_router)
 app.include_router(feedback_router)
 app.include_router(invite_router)
 app.include_router(coupon_router)
+app.include_router(device_router)
 app.include_router(compare_router)
 app.include_router(compare_record_router)
 app.include_router(compare_milestone_router)
@@ -107,6 +123,8 @@ app.include_router(report_router)
 # 内部(server→server)端点:pricebot 上报价格观测 / 店铺映射,靠共享密钥头校验,不对客户端开放。
 app.include_router(internal_price_router)
 app.include_router(internal_store_router)
+app.include_router(internal_app_version_router)
+app.include_router(internal_launch_confirm_router)
 app.include_router(platform_router)
 # CPS 群发短链跳转 /c/{code}(公网无鉴权:记点击 → 302 跳美团)
 app.include_router(cps_redirect_router)

app/models/__init__.py

@@ -10,7 +10,9 @@ from app.models.cps_activity import CpsActivity  # noqa: F401
 from app.models.cps_group import CpsGroup  # noqa: F401
 from app.models.cps_link import CpsClick, CpsLink  # noqa: F401
 from app.models.cps_order import CpsOrder  # noqa: F401
+from app.models.cps_wx_user import CpsWxUser  # noqa: F401
 from app.models.comparison_milestone import ComparisonMilestoneClaim  # noqa: F401
+from app.models.device import DeviceLiveness  # noqa: F401
 from app.models.coupon_state import (  # noqa: F401
     CouponClaimRecord,
     CouponDailyCompletion,
@@ -19,6 +21,7 @@ from app.models.coupon_state import (  # noqa: F401
 from app.models.feedback import Feedback  # noqa: F401
 from app.models.invite import InviteRelation  # noqa: F401
 from app.models.invite_fingerprint import InviteFingerprint  # noqa: F401
+from app.models.launch_confirm_sample import LaunchConfirmSample  # noqa: F401
 from app.models.meituan_coupon import MeituanCoupon  # noqa: F401
 from app.models.onboarding import OnboardingCompletion  # noqa: F401
 from app.models.ops_marquee_seed import OpsMarqueeSeed  # noqa: F401

app/models/ad_ecpm.py

@@ -4,8 +4,8 @@
 由客户端生成,并通过激励视频 extra 透传给 S2S 回调,用于把"展示 eCPM"与
 "奖励完成"绑定。没有 session id 的旧上报仍可作为按天对账补充。
 
-⚠️ `ecpm_raw` 原样存客户端上报的字符串——eCPM 单位(分 / 元)截至 2026-05-31 尚未最终确认,
-确认后再加一列解析好的数值;在此之前对账按"待定单位"处理。
+`ecpm_raw` 原样存客户端上报的字符串——单位是穿山甲 getEcpm 官方口径【分/千次展示】
+(非元!),对账由 `core/rewards.parse_ecpm_fen` 解析、`parse_ecpm_yuan` ÷100 转元;本列只存原值。
 """
 from __future__ import annotations
 

app/models/ad_feed_reward.py

@@ -30,6 +30,12 @@ class AdFeedRewardRecord(Base):
     ecpm_raw: Mapped[str] = mapped_column(String(32), nullable=False)
     adn: Mapped[str | None] = mapped_column(String(32), nullable=True)
     slot_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 点位场景:comparison(比价等待) / coupon(领券) / welfare(福利页)。比价与领券共用同一信息流
+    # 代码位,slot_id/our_code_id 分不出,只能客户端各调用点显式打标;NULL=历史/未升级客户端=未分类。
+    feed_scene: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    # 本次比价 trace_id(仅 comparison 场景由客户端带上):把这场广告金币归属到对应比价记录,
+    # 比价记录页按 trace_id 聚合本场实发金币显示「比价赚 N 金币」。领券/福利/旧客户端 = NULL。
+    trace_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
     # 来源(广告收益报表用):我们的应用环境 prod/test + 我们配置的代码位 104xxx,由客户端 feed-reward 上报带上。旧数据为 NULL。
     app_env: Mapped[str | None] = mapped_column(String(16), nullable=True)
     our_code_id: Mapped[str | None] = mapped_column(String(64), nullable=True)

app/models/comparison.py

@@ -18,6 +18,7 @@ from sqlalchemy import (
     JSON,
     Boolean,
     DateTime,
+    Float,
     ForeignKey,
     Index,
     Integer,
@@ -101,6 +102,35 @@ class ComparisonRecord(Base):
     # 客户端上报的原始 payload(calibration + done.params 全量),未来取数兜底
     raw_payload: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
 
+    # ===== debug 维度(客户端上报;旧记录 / 未发版客户端为 None)=====
+    # 设备环境:无障碍比价高度依赖机型/ROM,这是排"某机型跑不通"类问题的头号线索
+    device_model: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    device_manufacturer: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    rom_vendor: Mapped[str | None] = mapped_column(String(32), nullable=True)   # vivo/OPPO/Xiaomi/HUAWEI/HONOR/samsung
+    rom_name: Mapped[str | None] = mapped_column(String(32), nullable=True)     # OriginOS/ColorOS/HyperOS/MIUI/EMUI/HarmonyOS...
+    rom_version: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    android_version: Mapped[str | None] = mapped_column(String(16), nullable=True)  # Build.VERSION.RELEASE
+    android_sdk: Mapped[int | None] = mapped_column(Integer, nullable=True)          # Build.VERSION.SDK_INT
+    app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)       # 我们 app versionName
+    app_version_code: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 被操控的源平台 App 版本(美团/淘宝/京东),排"平台 App 改版导致 UI 适配失效"用
+    source_app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # 比价时设备定位(影响淘宝 deeplink / 距离匹配)
+    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    # ===== 性能 / 过程统计(debug 用)=====
+    total_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)       # 客户端整场比价墙钟耗时
+    step_count: Mapped[int | None] = mapped_column(Integer, nullable=True)     # 客户端 agent loop 总步数
+    llm_call_count: Mapped[int | None] = mapped_column(Integer, nullable=True) # 本次 LLM 调用次数(server 从 llm_calls 算)
+    retry_count: Mapped[int | None] = mapped_column(Integer, nullable=True)    # LLM 失败重试次数(server 从 llm_calls error 算)
+    # 本次 LLM 累计 token(server 从 llm_calls[].usage 累加;旧记录/未采集为 None)
+    input_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)   # Σ usage.prompt_tokens
+    output_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)  # Σ usage.completion_tokens
+    # 每次 LLM 调用明细 [{scene,model,input_messages,output,usage,latency_ms,error}];
+    # server 收上报后按 trace_id 同机拉 pricebot 落库(见 compare_record 端点)。旧记录/未采集为 None。
+    llm_calls: Mapped[list | None] = mapped_column(_JSON, nullable=True)
+
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
     )

app/models/cps_activity.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from sqlalchemy import DateTime, Integer, String, func
+from sqlalchemy import DateTime, Integer, String, Text, func
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
@@ -24,6 +24,10 @@ class CpsActivity(Base):
     act_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
     # 美团商品券 productViewSign(与 act_id 二选一转链;多数活动用 act_id)。
     product_view_sign: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # 淘宝:整段淘口令文本(落地页原样复制);京东:推广链接(落地页 302 跳)。美团不用这个(用 act_id)。
+    payload: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # 淘宝落地页主视觉图(绝对 URL,基于 CPS_REDIRECT_BASE)。运营建活动时上传/选已有,落地页按活动展示。
+    image_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")  # active | archived
     remark: Mapped[str | None] = mapped_column(String(256), nullable=True)
     created_at: Mapped[datetime] = mapped_column(

app/models/cps_group.py

@@ -7,7 +7,8 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from sqlalchemy import DateTime, Integer, String, func
+from sqlalchemy import JSON, DateTime, Integer, String, func
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
@@ -17,9 +18,13 @@ class CpsGroup(Base):
     __tablename__ = "cps_group"
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    # 每群唯一的渠道标识,建群时分配(留空则自动生成 g<id>)。字母+数字,≤64。
-    sid: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    # 渠道标识。仅美团需要(sid 追踪);纯淘宝/京东群无 sid(那俩不支持)。含美团时建群分配。
+    sid: Mapped[str | None] = mapped_column(String(64), unique=True, index=True, nullable=True)
     name: Mapped[str] = mapped_column(String(128), nullable=False)
+    # 该群发哪些平台的券(多选): ["meituan","taobao","jd"]。含 meituan 才需要 sid。
+    platforms: Mapped[list] = mapped_column(
+        JSON().with_variant(JSONB(), "postgresql"), nullable=False, default=list
+    )
     # 群人数,运营填,作转化率分母(可空)。
     member_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")  # active | archived

app/models/cps_link.py

@@ -23,10 +23,11 @@ class CpsLink(Base):
     code: Mapped[str] = mapped_column(String(16), unique=True, index=True, nullable=False)
     group_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
     activity_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
-    sid: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    # 仅美团 link 有 sid(渠道追踪);淘宝/京东无 sid。
+    sid: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
     platform: Mapped[str] = mapped_column(String(20), nullable=False, default="meituan")
-    # 302 跳转目标(美团短链,微信内可打开并唤起 App)。
-    target_url: Mapped[str] = mapped_column(String(1024), nullable=False)
+    # 跳转/落地目标: 美团短链 / 京东链接(302 跳) / 淘宝整段淘口令文本(H5 落地页复制)。
+    target_url: Mapped[str] = mapped_column(String(2048), nullable=False)
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), nullable=False
     )
@@ -41,9 +42,15 @@ class CpsClick(Base):
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
     link_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
     group_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)  # 冗余,按群聚合快
-    sid: Mapped[str] = mapped_column(String(64), index=True, nullable=False)    # 冗余
+    sid: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)  # 冗余(淘宝/京东无)
+    # 事件类型: visit(进落地页/被跳转) | copy(淘宝落地页点了"复制口令")
+    event_type: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="visit", server_default="visit"
+    )
     ip: Mapped[str | None] = mapped_column(String(64), nullable=True)
     ua: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    # 微信网页授权拿到的用户标识(非微信/未授权为空),做用户级群统计
+    openid: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
     clicked_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
     )

app/models/cps_wx_user.py

@@ -0,0 +1,42 @@
+"""CPS 落地页微信用户(cps_wx_user)。
+
+用户在微信内打开群发短链落地页 /c/{code},经服务号网页授权:
+  - base 静默:拿 openid(唯一标识,统计主力)
+  - userinfo(点领券触发):补 nickname/headimgurl/unionid
+
+按 openid 唯一,记录首次来源群(first_group_id),用于群内用户级统计(谁领了券)。
+下单归因到人需 user-level sid(另一期),本表只承载身份 + 领券/点击侧。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class CpsWxUser(Base):
+    __tablename__ = "cps_wx_user"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 服务号下用户唯一标识(网页授权拿到)
+    openid: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    # 开放平台 unionid(服务号绑开放平台 + scope=userinfo 才有);跨 App/服务号统一用户
+    unionid: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
+    # 昵称/头像:userinfo 授权后才有(base 阶段为空)
+    nickname: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    headimgurl: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    # 首次进入来源(从哪个群的链接授权进来)
+    first_code: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    first_group_id: Mapped[int | None] = mapped_column(Integer, index=True, nullable=True)
+    first_seen: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    last_seen: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<CpsWxUser id={self.id} openid={self.openid!r} nickname={self.nickname!r}>"

app/models/device.py

@@ -0,0 +1,91 @@
+"""设备表(无障碍保护存活检测 + 极光推送)。
+
+每条 = 一个用户的一台设备(per-install,device_id 由客户端 DeviceId.get() 生成)。
+客户端的无障碍服务存活时周期上报心跳刷新 last_heartbeat_at;App 前台/登录时上报
+registration_id(极光推送目标)。后端 heartbeat_monitor_worker 扫描「曾经保护过、
+现在心跳超时」的设备,通过极光推送提醒用户重开无障碍。
+
+liveness_state 状态机(防刷屏,一次掉线只推一条):
+  unknown → alive(收到 service 心跳)→ silent/notified(扫描发现超时并已推送)
+  心跳恢复时 handler 重置回 alive。
+见 spec: spec/accessibility-liveness-push.md。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class DeviceLiveness(Base):
+    # 表名不叫 device:device 易被当成「设备信息(品牌/型号/系统)」表;本表实为**无障碍存活监控状态**
+    # (心跳 last_heartbeat_at + liveness_state + kill_alert_pending + 推送目标 registration_id),故名 device_liveness。
+    __tablename__ = "device_liveness"
+    __table_args__ = (
+        UniqueConstraint("user_id", "device_id", name="uq_device_liveness_user_device"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    # 客户端 DeviceId.get() 生成的 per-install id(如 device_Pixel_ab12cd34)
+    device_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
+    # 极光推送 registration id;拿到才填(JCollectionAuth 同意后才下发)
+    registration_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    platform: Mapped[str] = mapped_column(String(16), nullable=False, default="android")
+    app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)
+
+    # 收到过 service 心跳即 true(=该设备开过无障碍,功能对它有意义)
+    ever_protected: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+    # 最近一次 service 心跳时间(存活证明);超时即视为保护掉线
+    last_heartbeat_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), index=True, nullable=True
+    )
+    # 最近一次上报的无障碍开关状态(观测用)
+    last_report_protection_on: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+    # unknown / alive / silent / notified
+    liveness_state: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="unknown"
+    )
+    # 最近一次推送告警时间
+    notified_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # 掉线告警「待客户端提醒」标记(后置检测 pull 版, 见 spec accessibility-liveness-pull-prompt.md)。
+    # 与 liveness_state 解耦: worker 检出掉线即置 True; touch_heartbeat(心跳恢复)不动它
+    # → 规避「服务随 App 重启先发心跳、state 被重置回 alive → 客户端进 App 漏看」竞态; 只由客户端 ack 清。
+    kill_alert_pending: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<DeviceLiveness id={self.id} user_id={self.user_id} "
+            f"device_id={self.device_id} state={self.liveness_state}>"
+        )

app/models/feedback.py

@@ -2,7 +2,7 @@
 
 每条 = 用户一次提交。content 必填;contact 原为必填(微信/QQ/手机),原型改版后客户端不再采集,
 新数据存空串(列保持 NOT NULL,免迁移;历史数据仍有值);images 为可选的截图 URL 列表
-(/media/feedback/...,JSON 存)。status: new(待处理)/ handled(已处理)。
+(/media/feedback/...,JSON 存)。status: pending(审核中)/adopted(已采纳)/rejected(未采纳)。
 """
 from __future__ import annotations
 
@@ -25,8 +25,18 @@ class Feedback(Base):
     contact: Mapped[str] = mapped_column(String(128), nullable=False)
     # 截图 URL 列表(相对路径,如 ["/media/feedback/u1_ab12.jpg"]);无图为 None
     images: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
-    # new(待处理) / handled(已处理)
-    status: Mapped[str] = mapped_column(String(16), nullable=False, default="new")
+    # pending(审核中) / adopted(已采纳) / rejected(未采纳)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="pending", index=True)
+    reject_reason: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    reward_coins: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 审核批注:采纳时可写采纳要点,未采纳时也可保留运营侧备注
+    review_note: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    reviewed_by_admin_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("admin_user.id"), nullable=True
+    )
+    reviewed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
 
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), index=True, nullable=False

app/models/launch_confirm_sample.py

@@ -0,0 +1,61 @@
+"""启动确认窗 agent 兜底样本表(launch_confirm_sample)。
+
+pricebot 的 launch_confirm_agent 每次"静态 PROFILES 没认出、靠 LLM 兜底放行"一个跨 App
+启动确认窗(繁体 / 英文 / 小语种 / ROM 改版)时,把完整样本 server→server 落这里。研发定期
+**人工**把 exec_success=true 的样本沉淀进 pricebot 的 launch_confirm.PROFILES(静态快路径),
+让以后同款窗不必再调 LLM。
+
+设计:
+- 与登录无关、不鉴权(server→server 共享密钥头 X-Internal-Secret)。
+- **都上报、不去重**(by design):同一种窗多台机器上报多条,研发按 host_package / locale
+  聚合后人工筛。
+- 大字段(弹窗树快照 + LLM plan + 设备信息)塞 payload(JSONB)兜底,免得加字段就迁移 schema。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import JSON, Boolean, DateTime, Integer, String, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+# PG 上用 JSONB(可建 GIN 索引),SQLite(本地/测试)退化为通用 JSON(同 price_observation)。
+_JSON = JSON().with_variant(JSONB(), "postgresql")
+
+
+class LaunchConfirmSample(Base):
+    __tablename__ = "launch_confirm_sample"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    # pricebot 侧 trace_id:回指原始 trace,能去 price.shaguabijia.com 查完整上下文。
+    trace_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
+    device_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
+
+    # 弹窗宿主包(= 触发判据, 也是研发沉淀进 PROFILES.host_packages 的键)。按它聚合人工筛。
+    host_package: Mapped[str | None] = mapped_column(String(128), index=True, nullable=True)
+    # 被打开的目标 App 包名(标题里"想要打开 X"的 X 是变量, 据此把它从 sign 里挖空)。
+    target_app: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # 系统语言地区(zh-TW / en-US…)—— 多语言问题的核心维度。
+    # ⚠️ 前端 AgentStepRequest 暂未上报设备信息 → 现恒 None,待前端加 device_info 字段后回填。
+    system_locale: Mapped[str | None] = mapped_column(String(32), index=True, nullable=True)
+
+    # 这次兜底是否成功放行(弹窗消失=True;放弃 / LLM 没认出=False)。研发只沉淀 True 的。
+    exec_success: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    # 弹窗标题全文(研发据此提 launch_sign),如"「傻瓜比价」想要開啟「京東」"。
+    dialog_title: Mapped[str | None] = mapped_column(String(256), nullable=True)
+
+    # 大 JSON:完整样本。{is_launch_confirm, llm_model, llm_reason, plan, dialog_tree,
+    #   device_info: {screen, locale, brand, model, android_version, rom_version}}
+    payload: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<LaunchConfirmSample id={self.id} host={self.host_package!r} "
+            f"locale={self.system_locale!r} success={self.exec_success}>"
+        )

app/models/signin.py

@@ -1,7 +1,8 @@
 """签到记录表。
 
 每次签到一行,(user_id, signin_date) 唯一,天然防一天签两次。
-  - cycle_day: 1..14,14 天循环里今天落在第几档,决定发多少金币;断签后重置回 1。
+  - cycle_day: 1..7,7 天循环里今天落在第几档,决定发多少金币;断签后重置回 1
+              (周期长度 = rewards.SIGNIN_CYCLE_LEN,2026-06 由 14 天改 7 天一轮)。
   - streak:   连续签到天数(不封顶),用于"已连续签到 N 天"展示;断签后重置回 1。
 """
 from __future__ import annotations

app/repositories/ad_feed_reward.py

@@ -42,21 +42,20 @@ def _granted_today(db: Session, user_id: int, reward_date: str) -> int:
     ).scalar_one()
 
 
-def _unit_reward_total(db: Session, user_id: int, ecpm: str, unit_count: int) -> int:
-    """按每个 10 秒单位逐份计算奖励,LT 使用**账号累计**奖励份序号(不按天重置)。"""
-    if unit_count <= 0:
-        return 0
-    existing_units = db.execute(
-        select(func.coalesce(func.sum(AdFeedRewardRecord.unit_count), 0))
-        .where(
-            AdFeedRewardRecord.user_id == user_id,
-            AdFeedRewardRecord.status == "granted",
-        )
-    ).scalar_one()
-    total = 0
-    for offset in range(1, unit_count + 1):
-        total += rewards.calculate_ad_reward_coin(ecpm, int(existing_units) + offset)
-    return total
+def granted_unit_total(db: Session, user_id: int) -> int:
+    """账号累计已发奖**条**数(COUNT status=granted),不按天重置 = 因子2(LT)基线。
+
+    口径:**一条广告 = 一份额度(一个单次公式值)**,故"已发条数"即"已发份数"。供前端拉取后精确复刻
+    金币公式做实时金币进度条(前端因子2 用 granted_unit_total + 本场已结算条数 + 1 取档,与本表发奖一致)。
+    """
+    return int(
+        db.execute(
+            select(func.count()).select_from(AdFeedRewardRecord).where(
+                AdFeedRewardRecord.user_id == user_id,
+                AdFeedRewardRecord.status == "granted",
+            )
+        ).scalar_one()
+    )
 
 
 def grant_feed_reward(
@@ -69,19 +68,22 @@ def grant_feed_reward(
     ad_session_id: str | None = None,
     adn: str | None = None,
     slot_id: str | None = None,
+    feed_scene: str | None = None,
+    trace_id: str | None = None,
     app_env: str | None = None,
     our_code_id: str | None = None,
     aborted: bool = False,
 ) -> AdFeedRewardRecord:
-    """比价/领券一整场信息流(轮播多条)结束后结算奖励。client_event_id 幂等,同号重试不重复发。
+    """**每条**信息流广告(客户端每条各上报一次)结算奖励。client_event_id 幂等,同号重试不重复发。
 
-    发奖规则:**比价全程不关广告才发**,金额按整场**总观看时长**折份(每 10 秒 1 份)。
-    - aborted=True(用户中途 ✕ 关闭):整场不发,记 status='closed_early' 留痕(原因可查)。
-    - 总时长不足 10 秒(unit_count==0):记 status='too_short' 不发。
+    发奖规则:**一条广告 = 一个单次公式值**(rewards.calculate_ad_reward_coin),因子2(LT)按账号累计
+    **条**数递进;看满一份时长(unit_count>=1, 即 ≥10 秒)才发,**不逐份累加**。
+    - aborted=True(用户中途 ✕ 关闭这条):本条不发,记 status='closed_early'。
+    - 时长不足 10 秒(unit_count==0):记 status='too_short' 不发。
     - 命中当日条数上限:记 status='capped' 不发。
-    duration_seconds 是整场累计秒数。一期 eCPM/时长均由客户端上报,故服务端两道硬闸防刷:时长钳到
-    FEED_MAX_DURATION_SECONDS 限单场份数,eCPM 在 rewards.calculate_ad_reward_coin 内钳到
-    AD_ECPM_MAX_FEN 限单份金额;叠加每日 get_ad_daily_limit 条数上限,把单用户日产出锁进有限区间。
+    duration_seconds 是**这一条**的观看秒数。服务端两道硬闸防刷:时长钳到 FEED_MAX_DURATION_SECONDS、
+    eCPM 在 calculate_ad_reward_coin 内钳到 AD_ECPM_MAX_FEN;叠加每日 get_ad_daily_limit 条数上限。
+    feed_scene:点位场景(comparison/coupon/welfare),仅归类落库,不参与计算。
     """
     existing = _find_by_event(db, client_event_id)
     if existing is not None:
@@ -104,6 +106,8 @@ def grant_feed_reward(
             ecpm_raw=ecpm,
             adn=adn,
             slot_id=slot_id,
+            feed_scene=feed_scene,
+            trace_id=trace_id,
             app_env=app_env,
             our_code_id=our_code_id,
             coin=0,
@@ -122,6 +126,8 @@ def grant_feed_reward(
             ecpm_raw=ecpm,
             adn=adn,
             slot_id=slot_id,
+            feed_scene=feed_scene,
+            trace_id=trace_id,
             app_env=app_env,
             our_code_id=our_code_id,
             coin=0,
@@ -141,6 +147,8 @@ def grant_feed_reward(
             ecpm_raw=ecpm,
             adn=adn,
             slot_id=slot_id,
+            feed_scene=feed_scene,
+            trace_id=trace_id,
             app_env=app_env,
             our_code_id=our_code_id,
             coin=0,
@@ -148,12 +156,14 @@ def grant_feed_reward(
         )
         return _commit_record(db, rec, client_event_id)
 
-    coin = _unit_reward_total(db, user_id, ecpm, unit_count)
+    # 一条广告 = 一个「单次公式值」(因子2 按账号累计**条**数, 即第 existing_ads+1 条);看满一份(unit_count>=1)即发,不逐份累加。
+    existing_ads = granted_unit_total(db, user_id)
+    coin = rewards.calculate_ad_reward_coin(ecpm, existing_ads + 1)
     if coin > 0:
         crud_wallet.grant_coins(
             db, user_id, coin,
             biz_type="feed_ad_reward", ref_id=client_event_id,
-            remark=f"信息流广告奖励 {unit_count}份",
+            remark="信息流广告奖励",
         )
     rec = AdFeedRewardRecord(
         client_event_id=client_event_id,
@@ -165,6 +175,8 @@ def grant_feed_reward(
         ecpm_raw=ecpm,
         adn=adn,
         slot_id=slot_id,
+        feed_scene=feed_scene,
+        trace_id=trace_id,
         app_env=app_env,
         our_code_id=our_code_id,
         coin=coin,

app/repositories/app_config.py

@@ -63,3 +63,81 @@ def list_all(db: Session) -> list[dict]:
             }
         )
     return out
+
+
+# ── 最新 App 版本(OTA 检查更新)──────────────────────────────────────────────
+# 版本信息不是"运营可配置项",不进 CONFIG_DEFS:它由发布流程(发车)/应急整组写入、客户端读取做
+# OTA,语义是"发布系统状态"而非"运营调参"。故走下面专用读写,直接操作 AppConfig 表(复用表不复用 repo)。
+APP_VERSION_KEY = "latest_app_version"
+
+
+def get_app_version(db: Session) -> dict | None:
+    """读最新 App 版本信息(OTA)。无记录返回 None(客户端视为无更新)。"""
+    row = db.get(AppConfig, APP_VERSION_KEY)
+    return row.value if row is not None else None
+
+
+def set_app_version(db: Session, data: dict, *, commit: bool = True) -> AppConfig:
+    """整组原子覆盖最新版本信息(发布流程/应急写,非 admin,故 updated_by_admin_id 留空)。"""
+    row = db.get(AppConfig, APP_VERSION_KEY)
+    if row is None:
+        row = AppConfig(key=APP_VERSION_KEY, value=data, updated_by_admin_id=None)
+        db.add(row)
+    else:
+        row.value = data
+    if commit:
+        db.commit()
+        db.refresh(row)
+    else:
+        db.flush()
+    return row
+
+
+# ── 穿山甲广告配置(admin 可配,客户端动态拉)──────────────────────────────────
+# 同 app_version:结构化 dict,复用 AppConfig 表不进 CONFIG_DEFS(它是一组关联配置,不是散项)。
+# 默认值 = 客户端当前内置的硬编码 ID(AdConfig.kt),空库时下发默认 = 维持现状。
+# reward_mkey 是 GroMore S2S 验签密钥(机密),只后端验签用、绝不下发客户端(见 platform/ad-config)。
+AD_CONFIG_KEY = "ad_config"
+_AD_CONFIG_DEFAULTS: dict[str, Any] = {
+    "app_id": "5830519",                  # 穿山甲应用ID(正式)
+    "reward_code_id": "104099389",        # 福利页激励视频位
+    # ⚠️ 2026-06-21 真机核对穿山甲后台:5830519 名下信息流真实位是 104142227「信息流 1」;
+    # 旧值 104090333 不在该应用名下(请求会报 44406/配置 null、出不了广告)。客户端接入下发后以本值为准。
+    "compare_feed_code_id": "104142227",  # 比价信息流位
+    "coupon_feed_code_id": "104142227",   # 领券信息流位(初始同比价,运营可拆)
+    "reward_mkey": "",                    # 激励位 GroMore 验签密钥(空则回退 .env PANGLE_REWARD_SECRET*)
+    "reward_enabled": True,               # 福利激励视频开关
+    "compare_ad_enabled": True,           # 比价广告开关
+    "coupon_ad_enabled": True,            # 领券广告开关
+}
+
+
+def get_ad_config(db: Session) -> dict:
+    """读广告配置。DB 无则返回默认(=客户端内置值,维持现状);DB 有则与默认 merge
+    (新增字段向后兼容,老记录缺的字段用默认补)。"""
+    row = db.get(AppConfig, AD_CONFIG_KEY)
+    merged = dict(_AD_CONFIG_DEFAULTS)
+    if row is not None and isinstance(row.value, dict):
+        merged.update(row.value)
+    return merged
+
+
+def set_ad_config(db: Session, data: dict, *, admin_id: int, commit: bool = True) -> AppConfig:
+    """admin 写广告配置。与现有值 merge(部分更新),只接受已知字段(防脏键)。"""
+    row = db.get(AppConfig, AD_CONFIG_KEY)
+    merged = dict(_AD_CONFIG_DEFAULTS)
+    if row is not None and isinstance(row.value, dict):
+        merged.update(row.value)
+    merged.update({k: v for k, v in data.items() if k in _AD_CONFIG_DEFAULTS})
+    if row is None:
+        row = AppConfig(key=AD_CONFIG_KEY, value=merged, updated_by_admin_id=admin_id)
+        db.add(row)
+    else:
+        row.value = merged
+        row.updated_by_admin_id = admin_id
+    if commit:
+        db.commit()
+        db.refresh(row)
+    else:
+        db.flush()
+    return row

app/repositories/comparison.py

@@ -11,6 +11,7 @@ from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from app.core.rewards import CN_TZ
+from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.models.comparison import ComparisonRecord
 from app.models.savings import SavingsRecord
 from app.schemas.compare_record import ComparisonRecordIn
@@ -90,6 +91,21 @@ def upsert_record(
         items=[it.model_dump(exclude_none=True) for it in payload.items],
         comparison_results=[r.model_dump() for r in payload.comparison_results],
         skipped_dish_names=list(payload.skipped_dish_names),
+        # 客户端环境 / 性能(debug,客户端上报;旧客户端为 None)
+        device_model=payload.device_model,
+        device_manufacturer=payload.device_manufacturer,
+        rom_vendor=payload.rom_vendor,
+        rom_name=payload.rom_name,
+        rom_version=payload.rom_version,
+        android_version=payload.android_version,
+        android_sdk=payload.android_sdk,
+        app_version=payload.app_version,
+        app_version_code=payload.app_version_code,
+        source_app_version=payload.source_app_version,
+        longitude=payload.longitude,
+        latitude=payload.latitude,
+        total_ms=payload.total_ms,
+        step_count=payload.step_count,
         raw_payload=payload.model_dump(),
         **derived,
     )
@@ -140,6 +156,29 @@ def _ordered_shop_names(db: Session, user_id: int) -> set[str]:
     return {s for s in rows if s}
 
 
+def _ad_coins_by_trace(db: Session, user_id: int, trace_ids: list[str]) -> dict[str, int]:
+    """各 trace_id「看广告赚的金币」:按 trace_id 聚合该用户已发放(granted)的信息流广告金币。
+
+    广告金币来自比价等候期信息流(biz_type=feed_ad_reward);客户端结算时把本场 trace_id 带上,
+    落到 ad_feed_reward_record.trace_id。此处按 trace_id 求和 = 这次比价看广告实发的金币。
+    trace_id 仅比价场景客户端带(领券/福利/旧客户端为 NULL),故按 trace_id 过滤天然只算比价广告。
+    空集合直接返回(避免 IN () 非法)。
+    """
+    if not trace_ids:
+        return {}
+    rows = db.execute(
+        select(
+            AdFeedRewardRecord.trace_id,
+            func.coalesce(func.sum(AdFeedRewardRecord.coin), 0),
+        ).where(
+            AdFeedRewardRecord.user_id == user_id,
+            AdFeedRewardRecord.status == "granted",
+            AdFeedRewardRecord.trace_id.in_(trace_ids),
+        ).group_by(AdFeedRewardRecord.trace_id)
+    ).all()
+    return {tid: int(coin) for tid, coin in rows if tid}
+
+
 def list_records(
     db: Session,
     user_id: int,
@@ -147,7 +186,7 @@ def list_records(
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[ComparisonRecord], int | None]:
-    """比价记录分页(按创建时间倒序、id 兜底,游标式)。附「已下单」店级标记(瞬态,不写库)。"""
+    """比价记录分页(按创建时间倒序、id 兜底,游标式)。附「已下单」店级标记 + 「看广告赚的金币」(瞬态,不写库)。"""
     stmt = select(ComparisonRecord).where(ComparisonRecord.user_id == user_id)
     if cursor is not None:
         stmt = stmt.where(ComparisonRecord.id < cursor)
@@ -157,10 +196,13 @@ def list_records(
     next_cursor = items[-1].id if len(items) == limit else None
 
     # 「已下单」标记:本页记录的 store_name 若落在该用户真实下单的店名集合里即 True。
-    # ordered 非 ORM 列,仅挂实例上供 ComparisonRecordOut(from_attributes) 读出,不持久化。
+    # ordered / ad_coins_earned 均非 ORM 列,仅挂实例上供 ComparisonRecordOut(from_attributes) 读出,不持久化。
     ordered_shops = _ordered_shop_names(db, user_id)
+    # 「本次比价看广告赚的金币」:按本页 trace_id 一次性聚合(同 ordered 范式)。
+    ad_coins = _ad_coins_by_trace(db, user_id, [it.trace_id for it in items])
     for it in items:
         it.ordered = bool(it.store_name and it.store_name in ordered_shops)
+        it.ad_coins_earned = ad_coins.get(it.trace_id, 0)
 
     return items, next_cursor
 
@@ -195,10 +237,13 @@ def get_stats(db: Session, user_id: int) -> tuple[int, int]:
 
 
 def get_record(db: Session, user_id: int, record_id: int) -> ComparisonRecord | None:
-    """取单条(限本人,避免越权读他人记录)。"""
-    return db.execute(
+    """取单条(限本人,避免越权读他人记录)。附「看广告赚的金币」瞬态属性(同 list_records)。"""
+    rec = db.execute(
         select(ComparisonRecord).where(
             ComparisonRecord.id == record_id,
             ComparisonRecord.user_id == user_id,
         )
     ).scalar_one_or_none()
+    if rec is not None:
+        rec.ad_coins_earned = _ad_coins_by_trace(db, user_id, [rec.trace_id]).get(rec.trace_id, 0)
+    return rec

app/repositories/cps_link.py

@@ -26,7 +26,7 @@ def get_by_code(db: Session, code: str) -> CpsLink | None:
 
 
 def create_link(
-    db: Session, *, group_id: int, activity_id: int, sid: str, target_url: str,
+    db: Session, *, group_id: int, activity_id: int, sid: str | None, target_url: str,
     platform: str = "meituan", commit: bool = True,
 ) -> CpsLink:
     """生成唯一短码并存库。冲突重试 5 次,仍冲突用 12 位兜底(概率近 0)。"""
@@ -50,10 +50,15 @@ def create_link(
     return link
 
 
-def record_click(db: Session, *, link: CpsLink, ip: str | None = None, ua: str | None = None) -> None:
+def record_click(
+    db: Session, *, link: CpsLink, ip: str | None = None, ua: str | None = None,
+    event_type: str = "visit", openid: str | None = None,
+) -> None:
+    """记一条点击。event_type: visit(进落地页/被跳转) | copy(淘宝点了"复制口令")。
+    openid: 微信网页授权拿到的用户标识(非微信/未授权为空),做用户级群统计。"""
     db.add(CpsClick(
-        link_id=link.id, group_id=link.group_id, sid=link.sid,
-        ip=ip, ua=(ua[:500] if ua else None),
+        link_id=link.id, group_id=link.group_id, sid=link.sid, event_type=event_type,
+        ip=ip, ua=(ua[:500] if ua else None), openid=openid,
     ))
     db.commit()
 
@@ -61,7 +66,8 @@ def record_click(db: Session, *, link: CpsLink, ip: str | None = None, ua: str |
 def click_stats_by_group(
     db: Session, *, date_from: datetime | None = None, date_to: datetime | None = None,
 ) -> dict[int, dict]:
-    """按 group_id 聚合点击 → {group_id: {"pv": N, "uv": M}}。uv 按 (ip, ua) 近似去重。"""
+    """按 group_id 聚合点击 → {group_id: {pv, uv, copy_pv, copy_uv}}。
+    visit 计入 pv/uv,copy(淘宝复制口令) 计入 copy_pv/copy_uv;uv 按 (ip, ua) 近似去重。"""
     stmt = select(CpsClick)
     if date_from is not None:
         stmt = stmt.where(CpsClick.clicked_at >= date_from)
@@ -70,13 +76,21 @@ def click_stats_by_group(
     clicks = list(db.execute(stmt).scalars().all())
 
     agg: dict[int, dict] = {}
-    seen: dict[int, set] = {}
+    seen_visit: dict[int, set] = {}
+    seen_copy: dict[int, set] = {}
     for c in clicks:
-        a = agg.setdefault(c.group_id, {"pv": 0, "uv": 0})
-        a["pv"] += 1
-        s = seen.setdefault(c.group_id, set())
+        a = agg.setdefault(c.group_id, {"pv": 0, "uv": 0, "copy_pv": 0, "copy_uv": 0})
         key = (c.ip, c.ua)
-        if key not in s:
-            s.add(key)
-            a["uv"] += 1
+        if c.event_type == "copy":
+            a["copy_pv"] += 1
+            s = seen_copy.setdefault(c.group_id, set())
+            if key not in s:
+                s.add(key)
+                a["copy_uv"] += 1
+        else:
+            a["pv"] += 1
+            s = seen_visit.setdefault(c.group_id, set())
+            if key not in s:
+                s.add(key)
+                a["uv"] += 1
     return agg

app/repositories/cps_wx_user.py

@@ -0,0 +1,43 @@
+"""cps_wx_user 数据访问:按 openid upsert。"""
+from __future__ import annotations
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.cps_wx_user import CpsWxUser
+
+
+def get_by_openid(db: Session, openid: str) -> CpsWxUser | None:
+    return db.execute(
+        select(CpsWxUser).where(CpsWxUser.openid == openid)
+    ).scalar_one_or_none()
+
+
+def upsert(
+    db: Session, *, openid: str, code: str | None = None, group_id: int | None = None,
+    nickname: str | None = None, headimgurl: str | None = None, unionid: str | None = None,
+) -> CpsWxUser:
+    """按 openid upsert。
+
+    - 首次:建行,记来源 code/group。
+    - 已存在:仅在传入非 None 时更新昵称/头像/unionid(base 阶段为 None,不覆盖已有画像);
+      并刷新 last_seen(显式 set,因 onupdate 仅在字段有变更时触发)。
+    """
+    u = get_by_openid(db, openid)
+    if u is None:
+        u = CpsWxUser(
+            openid=openid, first_code=code, first_group_id=group_id,
+            nickname=nickname, headimgurl=headimgurl, unionid=unionid,
+        )
+        db.add(u)
+    else:
+        if nickname is not None:
+            u.nickname = nickname
+        if headimgurl is not None:
+            u.headimgurl = headimgurl
+        if unionid is not None:
+            u.unionid = unionid
+        u.last_seen = func.now()
+    db.commit()
+    db.refresh(u)
+    return u

app/repositories/device.py

@@ -0,0 +1,124 @@
+"""device 表读写(设备注册 / 心跳 / 超时扫描)。"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.models.device import DeviceLiveness
+
+
+def _get(db: Session, *, user_id: int, device_id: str) -> DeviceLiveness | None:
+    stmt = select(DeviceLiveness).where(
+        DeviceLiveness.user_id == user_id, DeviceLiveness.device_id == device_id
+    )
+    return db.execute(stmt).scalar_one_or_none()
+
+
+def register_or_update(
+    db: Session,
+    *,
+    user_id: int,
+    device_id: str,
+    registration_id: str | None,
+    platform: str = "android",
+    app_version: str | None = None,
+) -> DeviceLiveness:
+    """注册设备或更新其 registration_id / 元信息。upsert by (user_id, device_id)。"""
+    device = _get(db, user_id=user_id, device_id=device_id)
+    if device is None:
+        device = DeviceLiveness(
+            user_id=user_id,
+            device_id=device_id,
+            registration_id=registration_id,
+            platform=platform or "android",
+            app_version=app_version,
+        )
+        db.add(device)
+    else:
+        if registration_id:
+            device.registration_id = registration_id
+        if platform:
+            device.platform = platform
+        if app_version:
+            device.app_version = app_version
+    db.commit()
+    db.refresh(device)
+    return device
+
+
+def touch_heartbeat(
+    db: Session,
+    *,
+    user_id: int,
+    device_id: str,
+    accessibility_enabled: bool,
+    registration_id: str | None,
+) -> DeviceLiveness:
+    """处理一次心跳(心跳也能自注册)。
+
+    service 心跳或 accessibility_enabled=true 时,刷新存活并把状态机重置回 alive、
+    清掉 notified_at(掉线恢复 → 下次再断才会再推一条)。
+    """
+    now = datetime.now(timezone.utc)
+    device = _get(db, user_id=user_id, device_id=device_id)
+    if device is None:
+        device = DeviceLiveness(user_id=user_id, device_id=device_id)
+        db.add(device)
+
+    if registration_id:
+        device.registration_id = registration_id
+    device.last_report_protection_on = accessibility_enabled
+
+    if accessibility_enabled:
+        device.last_heartbeat_at = now
+        device.ever_protected = True
+        device.liveness_state = "alive"
+        device.notified_at = None
+
+    db.commit()
+    db.refresh(device)
+    return device
+
+
+def list_overdue(db: Session, *, timeout_minutes: int) -> list[DeviceLiveness]:
+    """掉线设备:曾经保护过、当前 alive、心跳超时。
+
+    本期只做终端打印检测、不推送 → 不再要求有 registration_id(没接极光 token 的设备也要检出)。
+    """
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=timeout_minutes)
+    stmt = select(DeviceLiveness).where(
+        DeviceLiveness.ever_protected.is_(True),
+        DeviceLiveness.liveness_state == "alive",
+        DeviceLiveness.last_heartbeat_at.is_not(None),
+        DeviceLiveness.last_heartbeat_at < cutoff,
+    )
+    return list(db.execute(stmt).scalars().all())
+
+
+def mark_notified(db: Session, *, device_id_pk: int) -> None:
+    """标记掉线已检出(状态机进入 notified,避免每轮重复处理)+ 置「待客户端提醒」标记。
+
+    kill_alert_pending 与 state 解耦(见 spec accessibility-liveness-pull-prompt.md):
+    心跳恢复(touch_heartbeat)只重置 state、不动此标记,故客户端下次进 App 必能拉到这次掉线。
+    """
+    device = db.get(DeviceLiveness, device_id_pk)
+    if device is not None:
+        device.liveness_state = "notified"
+        device.notified_at = datetime.now(timezone.utc)
+        device.kill_alert_pending = True
+        db.commit()
+
+
+def get_device(db: Session, *, user_id: int, device_id: str) -> DeviceLiveness | None:
+    """按 (user_id, device_id) 取设备(liveness 查询用)。"""
+    return _get(db, user_id=user_id, device_id=device_id)
+
+
+def ack_kill_alert(db: Session, *, user_id: int, device_id: str) -> None:
+    """客户端已弹过「开启自启动」引导 → 清「待提醒」标记(幂等; 下次真掉线 worker 再置)。"""
+    device = _get(db, user_id=user_id, device_id=device_id)
+    if device is not None and device.kill_alert_pending:
+        device.kill_alert_pending = False
+        db.commit()

app/repositories/feedback.py

@@ -1,8 +1,12 @@
-"""feedback 表写入。"""
+"""feedback 表读写。"""
 from __future__ import annotations
 
+from datetime import datetime
+
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from app.core.rewards import CN_TZ
 from app.models.feedback import Feedback
 
 
@@ -19,9 +23,19 @@ def create_feedback(
         content=content,
         contact=contact,
         images=images or None,
-        status="new",
+        status="pending",
+        created_at=datetime.now(CN_TZ).replace(tzinfo=None),
     )
     db.add(fb)
     db.commit()
     db.refresh(fb)
     return fb
+
+
+def list_feedback(db: Session, *, user_id: int) -> list[Feedback]:
+    stmt = (
+        select(Feedback)
+        .where(Feedback.user_id == user_id)
+        .order_by(Feedback.created_at.desc(), Feedback.id.desc())
+    )
+    return list(db.execute(stmt).scalars().all())

app/repositories/feedback_qr.py

@@ -0,0 +1,106 @@
+"""反馈页二维码卡配置读写(运营后台可配 → App 反馈页同步)。
+
+整张卡(开关 + 二维码图 + 三行文案)作为一个 JSON 对象,复用通用 app_config 表
+(key=feedback_qr_card,value 存这个 dict)。表里没这行 → 返回内置默认(= App 反馈页原
+硬编码文案,空配置 = 改造前现状,图片走 App 本地兜底)。admin 改 → 写一行 → App 下次拉
+GET /api/v1/feedback/config 即生效(跨进程一致)。
+
+不经 app.repositories.app_config(那层按 CONFIG_DEFS 白名单限定 key,且会出现在系统配置页);
+本 key 由本模块独占维护,不进 CONFIG_DEFS,所以不会污染系统配置页。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from app.models.app_config import AppConfig
+
+_KEY = "feedback_qr_card"
+
+# 默认值镜像 App 反馈页原硬编码:空配置时整体行为与改造前一致。
+_DEFAULTS: dict[str, Any] = {
+    "enabled": True,
+    "image_url": None,  # None = App 用本地 asset 兜底(group_qr.png),再不行画占位伪码
+    "title": "长按图片保存二维码",
+    "group_name": "傻瓜比价官方群",
+    "subtitle": "一起唠嗑共创、解锁新玩法",
+}
+
+_FIELDS = tuple(_DEFAULTS.keys())
+
+
+def _merge(raw: Any) -> dict[str, Any]:
+    """把 DB 存的(可能不全的)dict 叠加到默认上,得到完整配置(5 个字段,无 updated_at)。"""
+    out = dict(_DEFAULTS)
+    if isinstance(raw, dict):
+        for k in _FIELDS:
+            v = raw.get(k)
+            if v is not None:  # image_url 的 None 与默认 None 等价,无需特判
+                out[k] = v
+    return out
+
+
+def get_config(db: Session) -> dict[str, Any]:
+    """完整配置 + updated_at(admin 读 / App 读共用;App schema 会忽略多余的 updated_at)。"""
+    row = db.get(AppConfig, _KEY)
+    cfg = _merge(row.value if row is not None else None)
+    cfg["updated_at"] = row.updated_at.isoformat() if row is not None and row.updated_at else None
+    return cfg
+
+
+def _write(db: Session, value: dict[str, Any], *, admin_id: int, commit: bool) -> dict[str, Any]:
+    """整体覆写该行(value 须为完整 5 字段 dict),返回合并后的完整配置(含 updated_at)。"""
+    row = db.get(AppConfig, _KEY)
+    if row is None:
+        row = AppConfig(key=_KEY, value=value, updated_by_admin_id=admin_id)
+        db.add(row)
+    else:
+        row.value = value  # 重新赋整个 dict,SQLAlchemy 能侦测到变更(in-place 改才侦测不到)
+        row.updated_by_admin_id = admin_id
+    if commit:
+        db.commit()
+        db.refresh(row)
+    else:
+        db.flush()
+    out = _merge(row.value)
+    out["updated_at"] = row.updated_at.isoformat() if row.updated_at else None
+    return out
+
+
+def update_config(
+    db: Session,
+    *,
+    enabled: bool | None = None,
+    title: str | None = None,
+    group_name: str | None = None,
+    subtitle: str | None = None,
+    admin_id: int,
+    commit: bool = True,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """改文案/开关(只改传了的字段;图片走 set_image)。返回 (before, after) 供审计。"""
+    row = db.get(AppConfig, _KEY)
+    before = _merge(row.value if row is not None else None)
+    new_value = {k: before[k] for k in _FIELDS}
+    if enabled is not None:
+        new_value["enabled"] = enabled
+    if title is not None:
+        new_value["title"] = title.strip()
+    if group_name is not None:
+        new_value["group_name"] = group_name.strip()
+    if subtitle is not None:
+        new_value["subtitle"] = subtitle.strip()
+    after = _write(db, new_value, admin_id=admin_id, commit=commit)
+    return before, after
+
+
+def set_image(
+    db: Session, image_url: str | None, *, admin_id: int, commit: bool = True
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """设置/清空二维码图 URL。返回 (before, after);before['image_url'] 供调用方删旧文件。"""
+    row = db.get(AppConfig, _KEY)
+    before = _merge(row.value if row is not None else None)
+    new_value = {k: before[k] for k in _FIELDS}
+    new_value["image_url"] = image_url
+    after = _write(db, new_value, admin_id=admin_id, commit=commit)
+    return before, after

app/repositories/launch_confirm_sample.py

@@ -0,0 +1,35 @@
+"""启动确认窗兜底样本落库:单条 insert(都上报、不去重,by design)。"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from sqlalchemy.orm import Session
+
+from app.models.launch_confirm_sample import LaunchConfirmSample
+from app.schemas.launch_confirm_sample import LaunchConfirmSampleIn
+
+logger = logging.getLogger("shagua.launch_confirm")
+
+
+def _trunc(s: Optional[str], n: int) -> Optional[str]:
+    """截断到列长上限(PG varchar 超长会报错;繁体长标题等需要)。空 → None。"""
+    return s[:n] if s else None
+
+
+def insert_sample(db: Session, payload: LaunchConfirmSampleIn) -> int:
+    """写入一条样本,返回新行 id。"""
+    row = LaunchConfirmSample(
+        trace_id=_trunc(payload.trace_id, 64),
+        device_id=_trunc(payload.device_id, 64),
+        host_package=_trunc(payload.host_package, 128),
+        target_app=_trunc(payload.target_app, 128),
+        system_locale=_trunc(payload.system_locale, 32),
+        exec_success=bool(payload.exec_success),
+        dialog_title=_trunc(payload.dialog_title, 256),
+        payload=payload.payload,
+    )
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return row.id

app/repositories/user.py

@@ -111,14 +111,27 @@ def set_avatar_url(db: Session, user: User, *, avatar_url: str) -> User:
 
 
 def soft_delete_account(db: Session, user: User) -> None:
-    """注销账号:软删除 + 匿名化。
+    """注销账号:软删除 + 匿名化 + 释放唯一约束/外部绑定。
 
-    把 phone 改成 `deleted_<id>` 释放唯一约束,允许同号码重新注册成全新账号;
+    把 phone 改成 `deleted_<id>` 释放手机号唯一约束,允许同号码重新注册成全新账号;
     清空 PII(昵称/头像),保留行用于审计。status=deleted 后将无法再登录该行
     (登录接口校验 status==active)。
+
+    ⚠️ 注销必须连同释放 user 上其余唯一约束/外部身份,否则 deleted 行永久占着槽位,
+    对应资源再也无法被复用:
+      - wechat_openid: 不清 → 这个微信再也无法被任何账号绑定(提现通道彻底锁死);
+      - invite_code:   不清 → 邀请码槽位被占 + 裸查仍命中死号(发奖已被 bind 的
+        status==active 校验兜住,清掉更干净)。
+    资金安全(未提现现金 / 在审提现单)由调用方 delete_account 端点前置校验,这里只匿名化。
     """
     user.status = "deleted"
     user.phone = f"deleted_{user.id}"
     user.nickname = None
     user.avatar_url = None
+    # 等价"解绑微信":释放 openid 唯一槽 + 清微信昵称头像
+    user.wechat_openid = None
+    user.wechat_nickname = None
+    user.wechat_avatar_url = None
+    # 释放邀请码唯一槽
+    user.invite_code = None
     db.commit()

app/repositories/wallet.py

@@ -340,6 +340,15 @@ def bind_wechat_openid(db: Session, user_id: int, code: str) -> dict:
     return info
 
 
+def get_cash_balance_cents(db: Session, user_id: int) -> int:
+    """只读查现金余额(分)。账户不存在返回 0,**不创建账户**——注销前置校验用,
+    不该给一个即将被删除的用户凭空建一行空账户(get_or_create_account 会建)。"""
+    val = db.execute(
+        select(CoinAccount.cash_balance_cents).where(CoinAccount.user_id == user_id)
+    ).scalar_one_or_none()
+    return val or 0
+
+
 def has_reviewing_withdraw(db: Session, user_id: int) -> bool:
     """用户是否有「待审核(reviewing)」的提现单。
 

app/schemas/ad.py

@@ -135,6 +135,18 @@ class FeedRewardIn(BaseModel):
     duration_seconds: int = Field(..., ge=0, description="整场累计观看秒数(轮播各条相加)")
     adn: str | None = Field(None, description="实际投放 ADN")
     slot_id: str | None = Field(None, description="实际展示代码位")
+    feed_scene: str | None = Field(
+        None,
+        max_length=16,
+        description="点位场景:comparison(比价等待) / coupon(领券) / welfare(福利页);"
+        "比价与领券共用同一信息流代码位,需客户端在各调用点显式标注,缺省=未分类",
+    )
+    trace_id: str | None = Field(
+        None,
+        max_length=64,
+        description="本次比价 trace_id(比价场景必带):把这场广告金币归属到对应比价记录,"
+        "比价记录页据此显示「比价赚 N 金币」。领券/福利场景为空",
+    )
     app_env: str | None = Field(
         None, max_length=16, description="我们的穿山甲应用环境:prod(傻瓜比价正式) / test(测试应用)"
     )
@@ -154,6 +166,14 @@ class FeedRewardOut(BaseModel):
     daily_limit: int = Field(..., description="每日信息流展示次数上限")
 
 
+class FeedRewardUnitsOut(BaseModel):
+    granted_units: int = Field(
+        ...,
+        description="账号累计已发奖的信息流**条**数(一条广告=一份额度),不按天重置;"
+        "前端据此算因子2(LT)做实时金币进度条,与后端发奖公式对齐",
+    )
+
+
 class RewardNoShowIn(BaseModel):
     """激励视频展示了但用户提前关闭/跳过、未触发发奖——上报留痕(不发金币)。
 

app/schemas/compare_record.py

@@ -51,6 +51,13 @@ class ComparisonResultIn(BaseModel):
     # 跟 coupon_saved 并存, 是更丰富的明细; 空=没抠到 → 前端回退单券路径。
     # 必须显式声明: 落库走 model_dump(), pydantic 默认丢未知字段, 不声明这行会被悄悄吞掉。
     applied_coupons: list[AppliedCouponIn] = Field(default_factory=list)
+    # 逐平台状态(客户端上报前把 done.params 的 comparison_results + platform_results.status 合并写入):
+    #   success / below_minimum / store_closed / store_not_found / items_not_found / unsupported / failed。
+    # 「比价记录」页据此对无价平台显示对应文案(未满起送价/门店打烊/店家未入驻/比价失败)。
+    # 必须显式声明: 落库走 model_dump(), 不声明会被 pydantic 静默丢弃 → 记录页拿不到 status。
+    status: str | None = None
+    # 门店打烊原因(price 为 None 时带): 与 status="store_closed" 等价的更早信号, 一并落库供前端兜底判打烊。
+    store_closed: str | None = None
 
 
 class ComparisonRecordIn(BaseModel):
@@ -69,6 +76,13 @@ class ComparisonRecordIn(BaseModel):
     # 明细
     items: list[ComparisonItemIn] = Field(default_factory=list)
     comparison_results: list[ComparisonResultIn] = Field(default_factory=list)
+    # 逐平台结局摘要(含失败平台的细分原因 status: store_not_found/items_not_found/below_minimum/
+    # unsupported/...)。来自 done.params.platform_results,客户端透传;落 raw_payload(不单列),
+    # admin「卡在哪一步」从这里读。dict{platform_id: {...}} 宽松存(结构由 pricebot 定——是
+    # 按平台 id 索引的 dict 而非 list,只作 debug 展示)。
+    # ⚠️ 早先误声明成 list → 每条成功记录 422 被拒、记录页只剩失败/终止
+    # (2026-06-17 引入 platform_results 上报后复现);改 dict 后修复。
+    platform_results: dict = Field(default_factory=dict)
     skipped_dish_count: int | None = None
     skipped_dish_names: list[str] = Field(default_factory=list)
     total_dish_count: int | None = None
@@ -82,6 +96,23 @@ class ComparisonRecordIn(BaseModel):
     # 时分秒前端拼不出,必须由后端透传)。
     trace_url: str | None = Field(None, description="本次比价公网调试链接")
 
+    # ===== debug 维度(客户端采集上报;旧客户端不带 → None。仅 admin 比价记录页用)=====
+    # 必须显式声明,否则 model_dump() 落 raw_payload 时被 pydantic 静默丢弃(同上面 coupon_saved 的坑)。
+    device_model: str | None = None
+    device_manufacturer: str | None = None
+    rom_vendor: str | None = Field(None, description="vivo/OPPO/Xiaomi/HUAWEI/HONOR/samsung")
+    rom_name: str | None = Field(None, description="OriginOS/ColorOS/HyperOS/MIUI/HarmonyOS...")
+    rom_version: int | None = None
+    android_version: str | None = None
+    android_sdk: int | None = None
+    app_version: str | None = None
+    app_version_code: int | None = None
+    source_app_version: str | None = Field(None, description="被操控的源平台 App 版本")
+    longitude: float | None = None
+    latitude: float | None = None
+    total_ms: int | None = Field(None, description="整场比价墙钟耗时(ms)")
+    step_count: int | None = Field(None, description="agent loop 总步数")
+
 
 # ===== 读取出参 =====
 
@@ -116,6 +147,9 @@ class ComparisonRecordOut(BaseModel):
     # 「已下单」(店级):该店名在该用户真实下单(source='compare')里出现过即 True。
     # 由 list_records 动态算出挂在 ORM 实例上(非 DB 列),from_attributes 读出;缺省 False。
     ordered: bool = False
+    # 「本次比价看广告赚的金币」(feed_ad_reward,按 trace_id 聚合 granted 金币;非 DB 列,
+    # list_records/get_record 动态挂在 ORM 实例上,from_attributes 读出)。0=没赚到 → 记录页不显示金币标。
+    ad_coins_earned: int = 0
     created_at: datetime
 
 

app/schemas/device.py

@@ -0,0 +1,48 @@
+"""设备注册 / 心跳相关 schema(无障碍保护存活检测)。"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DeviceRegisterRequest(BaseModel):
+    device_id: str
+    registration_id: str | None = None
+    platform: str = "android"
+    app_version: str | None = None
+
+
+class HeartbeatRequest(BaseModel):
+    device_id: str
+    source: str = "service"          # service | app
+    accessibility_enabled: bool = True
+    registration_id: str | None = None
+
+
+class DeviceOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    device_id: str
+    registration_id: str | None
+    ever_protected: bool
+    liveness_state: str
+    last_heartbeat_at: datetime | None
+    updated_at: datetime | None
+
+
+class OkResponse(BaseModel):
+    ok: bool = True
+
+
+class LivenessOut(BaseModel):
+    """本机掉线告警状态(后置检测 pull 版)。客户端只需这一个布尔判断要不要弹「开启自启动」引导,
+    故只返回 kill_alert_pending(不暴露设备详情 / 内部 liveness_state 等)。从未注册过 → 默认 False(无告警)。"""
+    model_config = ConfigDict(from_attributes=True)
+
+    kill_alert_pending: bool = False
+
+
+class LivenessAckRequest(BaseModel):
+    device_id: str

app/schemas/feedback.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class FeedbackOut(BaseModel):
@@ -12,3 +12,39 @@ class FeedbackOut(BaseModel):
     id: int
     status: str
     created_at: datetime
+
+
+class FeedbackQrConfigOut(BaseModel):
+    """反馈页二维码卡配置(运营后台可配)。App 反馈页据此渲染整张「加群二维码」卡。
+
+    image_url 是相对 /media 路径(客户端按自己的 BASE_URL 拼绝对地址),为空 → 客户端走本地兜底。
+    """
+
+    enabled: bool
+    image_url: str | None = None
+    title: str
+    group_name: str
+    subtitle: str
+
+
+class FeedbackRecordOut(BaseModel):
+    id: int
+    content: str
+    images: list[str] = Field(default_factory=list)
+    status: str
+    reject_reason: str | None = None
+    reward_coins: int | None = None
+    created_at: datetime
+
+
+class FeedbackRecordCountsOut(BaseModel):
+    all: int = 0
+    pending: int = 0
+    adopted: int = 0
+    rejected: int = 0
+
+
+class FeedbackRecordsOut(BaseModel):
+    records: list[FeedbackRecordOut]
+    counts: FeedbackRecordCountsOut
+

app/schemas/launch_confirm_sample.py

@@ -0,0 +1,26 @@
+"""启动确认窗兜底样本的内部上报模型(pricebot → app-server)。"""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class LaunchConfirmSampleIn(BaseModel):
+    """一次 agent 兜底的完整样本。
+
+    字段一律宽松可空:落盘是辅助数据,绝不能因个别字段缺失就拒收(否则连累 pricebot 兜底)。
+    """
+
+    trace_id: str | None = None
+    device_id: str | None = None
+    host_package: str | None = None
+    target_app: str | None = None
+    system_locale: str | None = None
+    exec_success: bool = False
+    dialog_title: str | None = None
+    payload: dict | None = None
+
+
+class LaunchConfirmSampleOut(BaseModel):
+    """落库结果。"""
+
+    id: int

app/schemas/platform.py

@@ -1,7 +1,7 @@
 """首页平台级展示数据 schemas(客户端首页门面数字)。"""
 from __future__ import annotations
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class PlatformStatsOut(BaseModel):
@@ -28,3 +28,46 @@ class AppFlagsOut(BaseModel):
     """客户端拉取的运营 feature flag(不鉴权,登录前也能拉)。客户端缓存后按需读。"""
 
     comparing_ad_enabled: bool  # 比价/领券期是否展示信息流广告(远程 kill-switch)
+
+
+class AdConfigPublicOut(BaseModel):
+    """下发给客户端的穿山甲广告配置(不鉴权,客户端缓存后用)。
+
+    ⚠️ 不含 reward_mkey(GroMore 验签密钥,机密,只后端验签用,绝不下发)。
+    """
+
+    app_id: str  # 穿山甲应用ID(改了客户端需冷启才生效,SDK init 一次性读)
+    reward_code_id: str  # 福利页激励视频位
+    compare_feed_code_id: str  # 比价信息流位
+    coupon_feed_code_id: str  # 领券信息流位
+    reward_enabled: bool  # 福利激励视频开关
+    compare_ad_enabled: bool  # 比价广告开关
+    coupon_ad_enabled: bool  # 领券广告开关
+
+
+class AppVersionOut(BaseModel):
+    """最新 App 版本信息(OTA 检查更新,不鉴权)。
+
+    客户端用 latest_version_code(整数,单调递增)与本机 versionCode 比较,**不要**用 version_name 字符串比。
+    latest_version_code=0 表示后台尚未配置任何版本 → 客户端一律视为"已是最新"。
+    """
+
+    latest_version_code: int = 0  # 最新版 versionCode;0=未配置(无更新)
+    latest_version_name: str = ""  # 展示用,如 "0.1.4"
+    apk_url: str = ""  # 下载链接(发车产出的永久版本化链接)
+    update_note: str = ""  # 更新说明,弹窗展示
+    min_supported_version_code: int = 0  # 本机低于此版本=强制更新;0=不强更(全可选)
+    apk_size_bytes: int = 0  # 包大小(字节),展示"约 xMB"
+    apk_sha256: str = ""  # APK 完整性校验(客户端下载后比对,防损坏/劫持)
+
+
+class AppVersionWriteIn(BaseModel):
+    """内部写入最新版本(发布流程/应急,X-Internal-Secret 校验)。整组原子覆盖。"""
+
+    latest_version_code: int = Field(gt=0)
+    latest_version_name: str = Field(min_length=1)
+    apk_url: str = Field(min_length=1)
+    update_note: str = ""
+    min_supported_version_code: int = 0
+    apk_size_bytes: int = 0
+    apk_sha256: str = ""

app/services/pricebot_llm_calls.py

@@ -0,0 +1,38 @@
+"""按 trace_id 同机拉 pricebot 的本次比价 LLM 调用明细(供 admin 比价记录 debug)。
+
+pricebot 在 chat() 收口处把每次 LLM input/output 落盘,暴露内部接口
+GET /api/internal/llm_calls/{trace_id}(X-Internal-Secret 校验,与本服务 INTERNAL_API_SECRET 同值)。
+app-server 收到比价记录上报后同机拉一次,落 comparison_record.llm_calls。
+
+best-effort:拉不到(pricebot 未部署该版本 / 旧 trace 无明细 / 网络)一律返 [],绝不阻断
+比价记录上报。多实例下用 pick_pricebot(trace_id) 选对实例(同 trace 落同进程,明细在
+该进程磁盘),与比价透传同一致性 hash 口径。
+"""
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from app.core.config import settings
+from app.core.pricebot_router import pick_pricebot
+
+logger = logging.getLogger("shagua.pricebot_llm")
+
+
+def fetch_llm_calls(trace_id: str) -> list[dict]:
+    """返回该次比价的 LLM 调用明细列表(每条 {scene,model,input_messages,output,usage,latency_ms,error});
+    未配密钥 / 无 trace_id / 拉取失败 → []。"""
+    secret = settings.INTERNAL_API_SECRET
+    if not secret or not trace_id:
+        return []
+    base = pick_pricebot(trace_id).rstrip("/")
+    url = f"{base}/api/internal/llm_calls/{trace_id}"
+    try:
+        resp = httpx.get(url, headers={"X-Internal-Secret": secret}, timeout=5.0)
+        if resp.status_code == 200:
+            return resp.json().get("calls", []) or []
+        logger.warning("fetch_llm_calls trace=%s status=%s", trace_id, resp.status_code)
+    except Exception as e:  # noqa: BLE001 — best-effort,任何异常都不该影响上报
+        logger.warning("fetch_llm_calls trace=%s failed: %s", trace_id, e)
+    return []

deploy/daily-exchange.md

@@ -3,6 +3,15 @@
 > 对象:维护「每天 0 点把用户金币自动兑成现金」这套定时任务的同事。
 > 🔒 服务器登录信息见**私密交接清单**,不入库。
 
+## 现状(2026-06 起):已改为 App 进程内任务,不再需要 systemd timer
+「0 点自动兑换」现由 **App 进程内后台任务** `app.core.daily_exchange_worker` 负责:App 一起来就
+每 10 分钟检查、跨过北京 0 点自动跑一轮(逐用户幂等、文件锁互斥、重启补跑当天遗漏)。**无需再装 / 启用
+`daily-exchange.timer`**。
+
+- 开关仍是 `.env` 的 `AUTO_EXCHANGE_ENABLED`(false → worker 不启动);间隔由 `AUTO_EXCHANGE_CHECK_INTERVAL_SEC`(默认 600s=10min)控。
+- 下方 systemd timer / 脚本属**遗留 + 手动应急**:逻辑同一套且幂等,可手动 `--once` 补跑;
+  但**不要再 `enable` timer 与进程内 worker 并存**(虽幂等不会双兑,纯属多余)。
+
 ## 它是什么
 客户端已删手动「兑金币」入口、改为「0 点自动兑现金（可能存在延迟）」,故服务端每天 0 点跑一轮:
 把每个用户的金币按汇率 **100 金币 = 1 分** 兑成现金。
@@ -21,8 +30,9 @@
 | systemd 单元 | `deploy/daily-exchange.{service,timer}` |
 | 运行锁 | `/tmp/daily_auto_exchange.lock`(可用环境变量 `DAILY_EXCHANGE_LOCK` 覆盖) |
 
-## 部署(Linux 服务器)
+## (遗留 / 可选)systemd timer 部署 — 现已被进程内 worker 取代,正常无需执行
 ```bash
+# ⚠️ 仅在你明确想用外部 timer 而非进程内 worker 时才做(并把 worker 关掉),否则跳过。
 sudo cp deploy/daily-exchange.{service,timer} /etc/systemd/system/
 sudo systemctl daemon-reload && sudo systemctl enable --now daily-exchange.timer
 systemctl list-timers daily-exchange.timer   # 确认下次触发时间

docs/README.md

@@ -1,16 +1,22 @@
 # 后端文档库(docs/)
 
-`shaguabijia-app-server` 的文档都在这里。各文档作用:
+`shaguabijia-app-server` 的文档都在这里。结构:**根目录放总览,其余按领域/用途分目录**。
 
-| 文档 / 目录 | 作用 |
+## 根目录
+
+| 文档 | 作用 |
 |---|---|
-| [后端技术实现.md](./后端技术实现.md) | **后端技术方案**:业务概览、分层架构与目录、登录链路、美团 CPS、领券透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"看这份。 |
-| [api/](./api/) | **API 接口文档**(目录),采用"索引 + 一接口一文件",结构见下。想查"某个接口的协议"看这里。 |
-| [integrations/](./integrations/) | **集成层实现文档**(目录):穿山甲验签 / 微信支付 / 极光 / 短信 / 美团 CPS 等 SDK 集成的签名、加解密、协议细节与踩坑。想知道"接外部服务那块到底怎么实现"看这里。 |
-| [数据库迁移.md](./数据库迁移.md) | **Alembic 迁移指南**:clone 后如何建表、日常升级、新增迁移、迁移文件命名约定。想"把数据库跑起来 / 改表结构"看这份。 |
-| [待办与技术债.md](./待办与技术债.md) | **待办与技术债账本**:记"现在先简化、以后要补"的事 + 跨前后端技术债(P1 鉴权/用户绑定、引擎移植待办等),免遗忘。想知道"还欠什么、以后要补什么"看这份。 |
-| [看广告赚金币上线清单.md](./看广告赚金币上线清单.md) | **看广告发奖上线 checklist**:跨前后端,记上线前必做(GroMore 回调配置、清理调试脚手架、端到端验收)。上线"看广告赚金币"前对照这份。 |
-| [邀请功能-实现原理与本地测试.md](./邀请功能-实现原理与本地测试.md) | **好友邀请(invite-mvp)实现原理 + 跨前后端具体实现 + 本地内网测试方法**:剪贴板 deferred-deeplink 归因、双方各发 1 万金币、落地页 dl.html、起本地后端 + 编 debug 包 + 两台真机走全链路 + 上线前还差什么。要本地测 / 接手邀请功能看这份。 |
+| [后端技术实现.md](./后端技术实现.md) | **后端技术方案总览**:业务概览、分层架构与目录、登录链路、美团 CPS、领券/比价透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"先看这份。 |
+| README.md | 本文件:文档库索引/传送门。 |
+
+## 子目录
+
+| 目录 | 作用 |
+|---|---|
+| [api/](./api/) | **API 接口文档**:"索引 + 一接口一文件"(组织方式见下)。想查"某个接口的协议"看这里。 |
+| [database/](./database/) | **数据库文档**:每张表一个文件(表结构/字段/索引/约定) + 两份迁移指南——[数据库迁移.md](./database/数据库迁移.md)(Alembic 操作:clone 后建表/日常升级/新增迁移/多 head 排查) + [postgres-migration.md](./database/postgres-migration.md)(SQLite → PostgreSQL 切换步骤,配套 `scripts/init_postgres.py`)。想"把库跑起来 / 改表结构 / 查某张表"看这里。 |
+| [integrations/](./integrations/) | **集成层实现文档**:穿山甲验签 / 微信支付 / 极光 / 短信 / 美团 CPS 等 SDK 集成的签名、加解密、协议细节与踩坑。想知道"接外部服务那块到底怎么实现"看这里。 |
+| [guides/](./guides/) | **开发 / 上线 / 功能 指南**:[待办与技术债.md](./guides/待办与技术债.md)(跨前后端 backlog,P1 鉴权/用户绑定、引擎移植待办等,"还欠什么、以后要补什么"看这份) + [看广告赚金币上线清单.md](./guides/看广告赚金币上线清单.md)(看广告发奖上线 checklist) + [邀请功能-实现原理与本地测试.md](./guides/邀请功能-实现原理与本地测试.md)(invite-mvp 实现原理 + 本地内网全链路测试)。 |
 
 ## api/ 目录是怎么组织的(传送门式)
 

docs/api/README.md

@@ -3,7 +3,7 @@
 > Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
 > 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
 > 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
-> 最后更新:2026-06-07（金币数值体系一期:签到膨胀 + 信息流广告结算）
+> 最后更新:2026-06-18（补录比价透传端点 `intent/precoupon/step`、`intent/step`、`trace/finalize` 与 `meituan/top-sales` 到总览;上一次功能更新 2026-06-07 金币数值体系一期）
 > 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。
 
 ---
@@ -23,9 +23,13 @@
 | 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan-coupons.md) |
 | 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan-feed.md) |
 | 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan-referral-link.md) |
-| **比价透传**（前缀 `/api/v1`,外卖 MVP；与 `coupon/step` 同为透传 pricebot-backend） |||
-| 12 | `POST /api/v1/intent/recognize` | 无 | [详情](./compare-intent-recognize.md) |
-| 13 | `POST /api/v1/price/step` | 无 | [详情](./compare-price-step.md) |
+| 11a | `POST /api/v1/meituan/top-sales` | 无 | [详情](./meituan-top-sales.md)（销量榜:离线库 `meituan_coupon` 按销量降序 + 跨源去重,不实时打美团） |
+| **比价透传**（前缀 `/api/v1`,外卖 MVP；与 `coupon/step` 同为透传 pricebot-backend；下按 Phase 流程列,均不鉴权） |||
+| 12 | `POST /api/v1/intent/recognize` | 无 | [详情](./compare-intent-recognize.md)（Phase 1 意图识别,单次,多数源） |
+| 12a | `POST /api/v1/intent/precoupon/step` | 无 | Phase 0 意图识别前先用券,仅美团源(透传,无单独文档) |
+| 12b | `POST /api/v1/intent/step` | 无 | Phase 1 多帧意图识别,仅淘宝源,循环到 done(透传,无单独文档) |
+| 13 | `POST /api/v1/price/step` | 无 | [详情](./compare-price-step.md)（Phase 2 步进） |
+| 13a | `POST /api/v1/trace/finalize` | 无 | 比价 trace 收尾上云,终止/未识别拿 trace_url(透传,无单独文档) |
 | **比价记录**（前缀 `/api/v1/compare`；按用户落库，**鉴权**，区别于上面不鉴权的透传） |||
 | 12a | `POST /api/v1/compare/record` | Bearer | [详情](./compare-record-report.md) |
 | 12b | `GET /api/v1/compare/records` | Bearer | [详情](./compare-records.md) |
@@ -109,7 +113,7 @@
 | - | `GET /admin/api/health` | 无 | admin 健康检查(无单独文档) |
 
 > ⚠️ 美团三个接口当前**无鉴权**,且 `referral-link` 的 `sid` 允许客户端传值覆盖默认渠道——见各接口"备注"。
-> `coupon/step` 及外卖比价的 `intent/recognize` / `price/step` 都透传到 pricebot-backend,**MVP 阶段均不鉴权**(device_id 透传,待补 JWT——见各接口详情)。
+> `coupon/step` 及外卖比价的 `intent/recognize`、`intent/precoupon/step`、`intent/step`、`price/step`、`trace/finalize` 都透传到 pricebot-backend,**MVP 阶段均不鉴权**(device_id 透传,待补 JWT——见 `app/api/v1/compare.py`)。
 > 福利相关业务接口（wallet/signin/tasks/savings、`ad/reward-status`、`ad/feed-reward`）均需 **Bearer**;`wallet/exchange-info` 是静态规则无鉴权;`ad/pangle-callback` 不走 JWT、靠穿山甲**验签**;`ad/test-grant` **仅本地联调**(开关控制,生产 404)。
 > 金额字段一律以**分**为单位（`*_cents`）。
 

docs/api/compare-intent-recognize.md

@@ -18,7 +18,7 @@ pricebot-backend 的响应**原样返回**（JSON object）。典型含 `result`
 
 外卖比价由客户端无障碍引擎在源平台（淘宝闪购 / 美团 / 京东外卖）购物车页点悬浮球触发 → 调本接口拿 `query` + `calibration` → 进入 `/price/step` 循环。
 
-⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）:`device_id` 透传给 pricebot 区分设备,后端拿不到 `user_id` → 行为暂绑不到登录用户。待补 JWT,见 [待办与技术债.md](../待办与技术债.md) P1。
+⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）:`device_id` 透传给 pricebot 区分设备,后端拿不到 `user_id` → 行为暂绑不到登录用户。待补 JWT,见 [待办与技术债.md](../guides/待办与技术债.md) P1。
 
 **相关配置**:
 - `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`）

docs/api/compare-record-report.md

@@ -5,7 +5,7 @@
 比价 `done` 帧后,客户端用**带 JWT 的通道**上报一条比价结果,落 `comparison_record` 表，作为「我的比价记录」数据源 + 用户级行为画像。
 
 > ⚠️ 与不鉴权的透传端点 [`/api/v1/price/step`](./compare-price-step.md) 不同：那是转发壳，本接口按用户维度落库，**必须鉴权**。
-> 本轮只做 server 端；客户端在 done 帧后调本接口的改动另起一轮（见 [待办与技术债.md](../待办与技术债.md) P1）。
+> 本轮只做 server 端；客户端在 done 帧后调本接口的改动另起一轮（见 [待办与技术债.md](../guides/待办与技术债.md) P1）。
 
 ## 入参（JSON body）
 

docs/api/coupon-step.md

@@ -17,7 +17,7 @@ pricebot-backend 的响应**原样返回**(JSON object)。
 
 是产品"一键领券"的接入点,**前端已接通**:首页「去领取」→ `CouponPromptDialog` 确认 → 权限检查 → 无障碍引擎 `PriceBotService.startCouponClaim()` → 循环调本接口,后端逐张券下发 launch/wait/done。
 
-⚠️ **客户端契约 vs Server 实现**:Android 客户端通过 `AuthInterceptor` 已自动带 `Authorization: Bearer <access_token>` 头(契约层 OK);Server MVP 阶段**暂未启用强校验**——[coupon.py](../../app/api/v1/coupon.py) 没接 `Depends(get_current_user)`,只读 `device_id` 透传给 pricebot 区分设备,后端拿不到 `user_id` → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补强校验 + `device_id↔user_id` 绑定,详见 [待办与技术债.md](../待办与技术债.md) P1。
+⚠️ **客户端契约 vs Server 实现**:Android 客户端通过 `AuthInterceptor` 已自动带 `Authorization: Bearer <access_token>` 头(契约层 OK);Server MVP 阶段**暂未启用强校验**——[coupon.py](../../app/api/v1/coupon.py) 没接 `Depends(get_current_user)`,只读 `device_id` 透传给 pricebot 区分设备,后端拿不到 `user_id` → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补强校验 + `device_id↔user_id` 绑定,详见 [待办与技术债.md](../guides/待办与技术债.md) P1。
 
 **相关配置**:
 - `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`）

docs/database/OVERVIEW.md

@@ -2,7 +2,7 @@
 
 > 跨表视角。单表字段级细节看同目录 `<表名>.md`(索引见 [README](./README.md))。
 > 本文专门回答三件「跨表」的事:**① 每块 App 功能用到哪些表 ② 什么操作往哪张表写 ③ 表和表怎么连(join key,含没有外键约束、靠业务字段对齐的语义关联)**。
-> **范围**:业务表全部在 `shaguabijia-app-server`(SQLAlchemy 2.0 + SQLite 开发 / PostgreSQL 生产)。`pricebot-backend`(比价/领券 Agent)是纯内存态、**无任何表**;Android 客户端只有 EncryptedSharedPreferences / SharedPreferences、**无关系库**。共 **28 张业务表** + `alembic_version`(框架的迁移版本指针)。领券联动的「今日状态」三张表(`coupon_*`)同理:领券过程在 pricebot 内存态跑、**不落库**,只有结果回到 app-server 才落这三张表。
+> **范围**:业务表全部在 `shaguabijia-app-server`(SQLAlchemy 2.0 + SQLite 开发 / PostgreSQL 生产)。`pricebot-backend`(比价/领券 Agent)是纯内存态、**无任何表**;Android 客户端只有 EncryptedSharedPreferences / SharedPreferences、**无关系库**。共 **37 张业务表** + `alembic_version`(框架的迁移版本指针)。注意「比价/领券**过程**」始终在 pricebot 内存态跑、**不落库**——只有**结果**回 app-server 才落库:领券结果落 `coupon_*` 三张今日状态表;比价结果分两路——客户端带 JWT 上报「我的记录」落 `comparison_record`,pricebot 另经 `app/api/internal/` server→server 把客观价格/门店事实落 `price_observation`/`store_mapping`(不鉴权、匿名也记)。此外好友邀请(`invite_*` 2 张)与美团 CPS 群发联盟(`cps_*` 5 张)是两个独立子系统。
 
 ---
 
@@ -16,6 +16,8 @@
 | 比价战绩里程碑(逐档领金币) | [`comparison_milestone_claim`](./comparison_milestone_claim.md) | 累计成功比价 N 次解锁;进度读 `comparison_record` 计数 |
 | profile「累计省了 / 省钱战绩 / 省钱明细」 | [`savings_record`](./savings_record.md) | 真实下单归因(source=compare)+ 无真实数据时 demo 兜底 |
 | 「上报更低价」提交 / 列表 | [`price_report`](./price_report.md) | 众包纠偏:用户举证某平台更便宜,人工审核发奖 |
+| (无 App UI)比价 done 后客观价格沉淀 | [`price_observation`](./price_observation.md) | **pricebot server→server 内部上报**;平台/门店视角的到手价事实,匿名也记,与 `comparison_record`(用户视角)互补 |
+| (无 App UI)跨平台门店身份映射 | [`store_mapping`](./store_mapping.md) | **pricebot 内部上报**;同店在淘宝/美团/京东的 id/名/deeplink,供下次比价 `lookup` 反查省掉现场搜店 |
 
 ### 领券(每日领券联动 · 今日状态)
 | App 位置 / 动作 | 表 | 说明 |
@@ -31,7 +33,7 @@
 | 资产卡 / 钱包余额 | [`coin_account`](./coin_account.md) | 一用户一行的金币+现金余额快照 |
 | 金币明细 | [`coin_transaction`](./coin_transaction.md) | 每次金币变动一笔流水 |
 | 现金明细 | [`cash_transaction`](./cash_transaction.md) | 每次现金变动一笔流水(分) |
-| 每日签到 | [`signin_record`](./signin_record.md) + [`signin_boost_record`](./signin_boost_record.md) | 14 天循环发币;签到后看广告可膨胀一次 |
+| 每日签到 | [`signin_record`](./signin_record.md) + [`signin_boost_record`](./signin_boost_record.md) | 7 天循环发币;签到后看广告可膨胀一次 |
 | 一次性任务(开消息提醒等) | [`user_task`](./user_task.md) | 领一次发币 |
 | 看激励视频赚金币 | [`ad_reward_record`](./ad_reward_record.md) + [`ad_watch_log`](./ad_watch_log.md) + [`ad_ecpm_record`](./ad_ecpm_record.md) | 独立数据流:发奖 / 旧版观看时长 / 收益对账 |
 | 信息流广告结算 | [`ad_feed_reward_record`](./ad_feed_reward_record.md) | 每展示满 10 秒累计一份奖励,完成后一次性入账 |
@@ -46,6 +48,21 @@
 | 新手引导是否再展示 | [`onboarding_completion`](./onboarding_completion.md) | 按 设备+账号 去重;登录响应回 `onboarding_completed`,走完引导时标记,跨卸载重装 |
 | 帮助与反馈 | [`feedback`](./feedback.md) | 含截图,后台人工处理 |
 
+### 好友邀请(注册增长)
+| App 位置 / 动作 | 表 | 说明 |
+|---|---|---|
+| 输入/剪贴板邀请码绑定 | [`invite_relation`](./invite_relation.md) | 注册即生效,邀请人+被邀请人各发 1 万金币;`invitee_user_id` 唯一=幂等防重复发奖 |
+| 落地页访问指纹(剪贴板归因兜底) | [`invite_fingerprint`](./invite_fingerprint.md) | 剪贴板没拿到码时,用 (ip+机型+屏幕) 7 天内反查邀请人 |
+
+### 美团 CPS 群发联盟(私域社群比价,运营后台驱动 · 群发选品→点击→对账漏斗)
+| 后台/用户动作 | 表 | 说明 |
+|---|---|---|
+| 运营建可推广活动 | [`cps_activity`](./cps_activity.md) | 预存券/物料(美团 actId / 淘宝淘口令 / 京东链接) |
+| 运营建微信推广群 | [`cps_group`](./cps_group.md) | 一群一行,`sid`=美团二级渠道追踪位 |
+| 后台批量生成群发短链 | [`cps_link`](./cps_link.md) | 群×活动 → `/c/{code}`,运营复制到微信群 |
+| 用户点短链(落地/复制口令) | [`cps_click`](./cps_click.md) | 记 visit/copy 事件,统计 PV/UV |
+| 定时拉美团联盟订单对账 | [`cps_order`](./cps_order.md) | `query_order` 按 sid 归群,串成点击→下单→佣金漏斗 |
+
 ### 运营后台 admin(独立子应用 `app/admin/`,端口 8771,独立鉴权)
 | 后台模块 | 表 | 说明 |
 |---|---|---|
@@ -84,7 +101,9 @@
 | 首次进 profile 省钱页且无真实记录 | `savings_record`(C `source=demo`) | 懒种子,`ensure_seeded` 按 user 幂等 |
 | 上报更低价 `POST /report` | `price_report`(C) | 读 `comparison_record.best_price_cents` 校验 |
 | 提交反馈 `POST /feedback` | `feedback`(C) | |
-| 领券首帧 `POST /api/v1/coupon/step`(step=0) | `coupon_prompt_engagement`(C/U `claim_started`) | `(device_id, 北京日)` 幂等;best-effort |
+| 绑定邀请 `POST /invite/bind` | `invite_relation`(C `effective`) + `coin_account`(U×2) + `coin_transaction`(C `invite_inviter` + `invite_invitee`) | 同事务;`invitee_user_id` 唯一幂等,双方各发 1 万金币 |
+| 落地页归因 `POST /invite/landing-track` | `invite_fingerprint`(C) | 剪贴板归因兜底线索,登录后用 (ip+机型+屏幕) 反查 |
+| 领券首帧 `POST /api/v1/coupon/step`(step=0) | `coupon_prompt_engagement`(C/U `claim_started`) | `(device_id, package, 北京日)` 幂等;best-effort |
 | 领券每帧结果 `POST /api/v1/coupon/step` | `coupon_claim_record`(C/U) | `(device_id, coupon_id, 北京日)` 幂等;best-effort |
 | 领券跑完 `POST /api/v1/coupon/step`(action.command=done) | `coupon_daily_completion`(C/U) | `(device_id, 北京日)` 幂等;best-effort |
 | 拒绝领券引导窗 `POST /api/v1/coupon/prompt/dismiss` | `coupon_prompt_engagement`(C/U `dismissed`) | 同上;客户端通知(透传链路看不到拒绝) |
@@ -103,7 +122,19 @@
 | 改运营配置 | `app_config`(C/U)+`admin_audit_log`(C) | 同事务 |
 | 任意写操作 | `admin_audit_log`(C,**永不 U/D**) | |
 
-> 没有任何表会被业务流程物理 DELETE。注销是软删(改 user 行),其余只 C/U。
+> 没有任何表会被业务流程物理 DELETE。注销是软删(改 user 行),其余只 C/U(领券 `/prompt/reset`、`/completed-today/reset` 是开发用删除,非业务流程)。
+
+### CPS 群发联盟 & pricebot 内部上报(非 C 端用户、非 admin 常规管理触发)
+| 触发 | 写入 | 操作 |
+|---|---|---|
+| 运营后台建活动 / 建群 | `cps_activity`(C/U) / `cps_group`(C/U) | `app/admin/routers/cps.py`;群含美团平台才分配 `sid` |
+| 后台批量生成短链 `POST /admin/api/cps/referral-links` | `cps_link`(C) | 每 群×活动 一条;美团经 `sid` 转链拿 `target_url`(同群同活动重复生成产生多条) |
+| 用户点群发短链 `GET /c/{code}` / `POST /c/{code}/copy` | `cps_click`(C `visit`/`copy`) | 公开端点不鉴权;`group_id`/`sid` 从 link 冗余进来免 join |
+| 定时拉美团联盟订单对账 | `cps_order`(C/U upsert) | `query_order` 按 `sid` 归群;`order_id` 幂等(状态会变,重复拉则更新) |
+| pricebot 比价 done 内部上报 `POST /internal/price-observation` | `price_observation`(C 批量) | `(trace_id,platform,scope)` 幂等;**不走 JWT、靠 `X-Internal-Secret`**(未配→503) |
+| pricebot 比价 done 内部上报 `POST /internal/store-mapping` | `store_mapping`(C/U 填空合并) | `trace_id` 幂等;另有 `lookup` 反查 + `invalidate` deeplink 失效标记(淘宝/京东) |
+
+> CPS 5 表与本 App `user` **无关**(被推广群的用户在美团下单,不是本 App 注册用户);`price_observation`/`store_mapping` 的 `source_user_id` 是可空旁路(链路不鉴权,匿名也记)。
 
 ---
 
@@ -113,6 +144,8 @@
 - **17 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`signin_record`、`signin_boost_record`、`user_task`、`comparison_record`、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback`。
 - `admin_audit_log.admin_id` → `admin_user.id`。
 - `price_report.comparison_record_id` → `comparison_record.id`(可空:关联记录被删后仍留上报历史)。
+- **邀请两表** → `user.id`:`invite_relation.inviter_user_id`、`invite_relation.invitee_user_id`(唯一)、`invite_fingerprint.inviter_user_id`——注意 FK 列名是 `inviter`/`invitee_user_id`,不是 `user_id`。
+- **CPS 5 表 + 比价沉淀 2 表均无硬 FK**(全靠 `sid`/`trace_id` 语义对齐,见下)。
 
 ### 语义 join key(无 FK 约束,靠业务字段对齐 —— 排障/对账必看)
 - **`coin_transaction.ref_id` 指向随 `biz_type` 变**:
@@ -139,6 +172,8 @@
 - **里程碑解锁进度不存库**:`comparison_milestone_claim` 只记「哪几档已领」;进度 = `comparison_record` 里 `status='success'` 的 `count`。
 - **领券三表无硬 FK,全靠软关联**:`coupon_prompt_engagement` / `coupon_daily_completion` / `coupon_claim_record` 的 `user_id` **软指** `user.id`(可空、有登录态才记、不进唯一键、不阻塞判断);`trace_id` **软指** pricebot work_logs(排查回指);唯一键都以 `device_id` + 北京自然日为主(详见 [`coupon_state.md`](./coupon_state.md))。
 - **`onboarding_completion.(user_id, device_id)`**:`user_id` 语义关联 `user.id`(无硬 FK,同 `coupon_*` 设备表),`device_id` = 客户端硬件级 `ANDROID_ID`(≠ 领券 per-install `device_id`)。登录读、走完引导写,决定是否再展示新手引导。
+- **CPS 群发 5 表全靠 `sid` / id 语义串联(无硬 FK)**:`cps_link.group_id`→`cps_group.id`、`cps_link.activity_id`→`cps_activity.id`、`cps_click.link_id`→`cps_link.id`;**点击与订单无法对到单笔**,只在群维度(`sid`)汇合——`cps_order.sid` ≈ `cps_group.sid` ≈ `cps_link.sid` ≈ `cps_click.sid`(仅美团有 sid,淘宝/京东无)。统计按群聚合,故 `group_id`/`sid` 冗余进 `cps_click` 免 join。
+- **比价沉淀两表(`price_observation` / `store_mapping`)**:`trace_id` 软指 pricebot work_logs(与 `comparison_record.trace_id` 同源但不互 join,各存各视角);`source_user_id` / `source_device_id` 软指用户/设备(可空,匿名也记)。`store_mapping.lookup` 靠**店名字符串精确相等** + geo 取最近,非 id 级 join。
 
 ### ER 关系(文字版)
 ```
@@ -154,6 +189,11 @@ admin_user ─1:N─ admin_audit_log
 app_config                                   (独立, 无外键, key 为主键)
 coupon_prompt_engagement / coupon_daily_completion / coupon_claim_record
                                              (独立, 无硬 FK; 维度=device_id+北京日, user_id/trace_id 仅软关联)
+user ─1:N─ invite_relation                   (inviter_user_id 硬 FK);  invitee_user_id ─1:1─ user (唯一硬 FK)
+user ─1:N─ invite_fingerprint                (inviter_user_id 硬 FK)
+cps_activity / cps_group ──语义(无FK)──▶ cps_link ─1:N─ cps_click
+                                             (CPS 5 表自成子系统; cps_order 经 sid 归群对账, 与本 App user 无关)
+price_observation / store_mapping            (独立, 无硬 FK; 维度=trace_id, source_user/device 仅软关联; pricebot 内部上报)
 ```
 
 ---

docs/database/README.md

@@ -3,13 +3,13 @@
 > 数据库:SQLite 起步(`data/app.db`),生产可切 PostgreSQL(改 `DATABASE_URL`)。
 > ORM:SQLAlchemy 2.0(`app/models/`),迁移:Alembic(`alembic/versions/`,`render_as_batch` 兼容 SQLite)。
 > 金额字段一律存**整数**:金币=个数,现金=**分**(`*_cents`)。时间列 `DateTime(timezone=True)`。
-> 最后更新:2026-06-11(合并:新增 3 张领券今日状态表 `coupon_*` + `onboarding_completion` 新手引导完成表;含 [OVERVIEW 总览](./OVERVIEW.md))
+> 最后更新:2026-06-17(补全 9 张此前缺文档的表:CPS 群发 5 张 `cps_*` + 好友邀请 2 张 `invite_*` + 比价沉淀 `price_observation`/`store_mapping`;并全表 review 对齐 model——`signin_record` 改 7 天循环、`coupon_prompt_engagement` 加 `package` 列按 App 频控、`user` 补 `username`/`invite_code`/`debug_trace_enabled` 等;含 [OVERVIEW 总览](./OVERVIEW.md))
 
 > 🧭 **先看 [OVERVIEW.md — 表 × 功能 × 关系](./OVERVIEW.md)**:跨表的「每块功能用哪些表 / 什么操作写哪张表 / 表间 join key」都在那;本页只做**单表索引**,点进每张表的详情看字段级说明。
 
 ---
 
-## 表总览(28 张业务表 + `alembic_version` 框架表)
+## 表总览(37 张业务表 + `alembic_version` 框架表)
 
 ### 账号 / 反馈
 | 表 | 用途 | 模型 | 文档 |
@@ -18,6 +18,12 @@
 | `onboarding_completion` | 新手引导完成标记(按 设备+账号 去重,登录时据此跳过引导) | `models/onboarding.py` | [详情](./onboarding_completion.md) |
 | `feedback` | 用户帮助与反馈(含截图) | `models/feedback.py` | [详情](./feedback.md) |
 
+### 好友邀请(注册增长)
+| 表 | 用途 | 模型 | 文档 |
+|---|---|---|---|
+| `invite_relation` | 邀请绑定关系(注册即生效,双方各发1万金币;`invitee_user_id` 唯一=幂等防重复发奖) | `models/invite.py` | [详情](./invite_relation.md) |
+| `invite_fingerprint` | 剪贴板归因失败时的指纹兜底(落地页记 ip+屏幕+机型,登录后反查邀请人) | `models/invite_fingerprint.py` | [详情](./invite_fingerprint.md) |
+
 ### 钱包 / 福利(看广告赚钱闭环)
 | 表 | 用途 | 模型 | 文档 |
 |---|---|---|---|
@@ -26,7 +32,7 @@
 | `cash_transaction` | 现金流水账本(分) | `models/wallet.py` | [详情](./cash_transaction.md) |
 | `withdraw_order` | 提现单(现金→微信零钱,含人工审核态) | `models/wallet.py` | [详情](./withdraw_order.md) |
 | `wechat_transfer_authorization` | 微信免确认转账授权(一用户一行) | `models/wallet.py` | [详情](./wechat_transfer_authorization.md) |
-| `signin_record` | 签到记录(14 天循环) | `models/signin.py` | [详情](./signin_record.md) |
+| `signin_record` | 签到记录(7 天循环) | `models/signin.py` | [详情](./signin_record.md) |
 | `signin_boost_record` | 签到后看广告膨胀记录 | `models/signin.py` | [详情](./signin_boost_record.md) |
 | `user_task` | 一次性任务领取去重 | `models/task.py` | [详情](./user_task.md) |
 | `ad_reward_record` | 看激励视频发奖记录(S2S 回调,trans_id 幂等) | `models/ad_reward.py` | [详情](./ad_reward_record.md) |
@@ -42,10 +48,16 @@
 | `savings_record` | 省钱记录(profile 省钱战绩源;真实下单归因 + demo) | `models/savings.py` | [详情](./savings_record.md) |
 | `price_report` | 上报更低价(众包纠偏,人工审核发奖) | `models/price_report.py` | [详情](./price_report.md) |
 
+### 比价数据沉淀(pricebot server→server 内部上报,不走用户鉴权)
+| 表 | 用途 | 模型 | 文档 |
+|---|---|---|---|
+| `price_observation` | 价格观测(平台/门店视角的到手价事实,匿名也记;`comparison_record` 的客观对照) | `models/price_observation.py` | [详情](./price_observation.md) |
+| `store_mapping` | 跨平台「同一家店」id/名/deeplink 身份映射(淘宝/美团/京东,供 lookup 反查省现场搜店) | `models/store_mapping.py` | [详情](./store_mapping.md) |
+
 ### 领券(每日领券联动 · 今日状态)
 | 表 | 用途 | 模型 | 文档 |
 |---|---|---|---|
-| `coupon_prompt_engagement` | 领券引导窗频控源(今日是否已 engage,按 device+日) | `models/coupon_state.py` | [详情](./coupon_state.md) |
+| `coupon_prompt_engagement` | 领券引导窗频控源(今日是否已 engage,按 device+package+日) | `models/coupon_state.py` | [详情](./coupon_state.md) |
 | `coupon_daily_completion` | 首页「去领取」置灰源(今日是否已跑完整轮) | `models/coupon_state.py` | [详情](./coupon_state.md) |
 | `coupon_claim_record` | 每张券领取结果沉淀(资产/画像/排查,不参与判断) | `models/coupon_state.py` | [详情](./coupon_state.md) |
 
@@ -54,6 +66,15 @@
 |---|---|---|---|
 | `meituan_coupon` | 美团 CPS 券本地缓存(智能推荐/销量榜从库出,定时 ETL 灌入) | `models/meituan_coupon.py` | [详情](./meituan_coupon.md) |
 
+### 美团 CPS 群发联盟(私域社群比价 · 群发选品→点击→对账漏斗)
+| 表 | 用途 | 模型 | 文档 |
+|---|---|---|---|
+| `cps_activity` | 可推广活动池(运营预存的券/物料:美团 actId / 淘宝淘口令 / 京东链接) | `models/cps_activity.py` | [详情](./cps_activity.md) |
+| `cps_group` | 推广微信群(`sid`=美团二级渠道追踪位,订单按 sid 归群对账) | `models/cps_group.py` | [详情](./cps_group.md) |
+| `cps_link` | 群发短链 `/c/{code}`(群×活动生成,302 跳/淘宝落地页) | `models/cps_link.py` | [详情](./cps_link.md) |
+| `cps_click` | 短链点击事件流(visit/copy,PV/UV 漏斗源) | `models/cps_link.py` | [详情](./cps_click.md) |
+| `cps_order` | 美团联盟 query_order 拉回的对账订单(按 sid 归群算佣金) | `models/cps_order.py` | [详情](./cps_order.md) |
+
 ### 首页门面数据
 | 表 | 用途 | 模型 | 文档 |
 |---|---|---|---|

docs/database/ad_feed_reward_record.md

@@ -1,5 +1,7 @@
 # ad_feed_reward_record — 信息流广告奖励记录
 
+> 模型 `app/models/ad_feed_reward.py` · 仓库 `app/repositories/ad_feed_reward.py` · 接口 `POST /api/v1/ad/feed-reward`(信息流广告结算) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+
 点位 2 的奖励记录。每条记录对应客户端完成的一次信息流广告展示/播放事件。
 
 ## 字段

docs/database/ad_reward_record.md

@@ -21,7 +21,7 @@
 | `app_env` | String(16) | nullable | 来源应用 `prod`(傻瓜比价)/`test`(测试);S2S 不带,发奖时按 `ad_session_id` 匹配 `ad_ecpm_record` 回填,查不到 NULL。广告收益报表金币侧按它聚合 |
 | `our_code_id` | String(64) | nullable | 我们配置的代码位 104xxx(同上回填) |
 | `coin` | Integer | NOT NULL, default 0 | 实发金币;`capped`/`ecpm_missing`/`closed_early`/业务不满足时为 0 |
-| `status` | String(16) | NOT NULL, default `granted` | 取值:`granted`(已发)/ `capped`(当日次数超限)/ `ecpm_missing`(缺 eCPM)/ `closed_early`(展示了但用户提前关/跳过,未发奖,客户端 reward-noshow 留痕)/ `not_signed`/`already_boosted`/`last_day` |
+| `status` | String(16) | NOT NULL, default `granted` | 取值:`granted`(已发)/ `capped`(当日次数超限)/ `ecpm_missing`(缺 eCPM)/ `closed_early`(展示了但用户提前关/跳过,未发奖,客户端 reward-noshow 留痕)/ `not_signed`/`already_boosted`/`last_day`/ `unknown_scene`(回调 `reward_scene` 不在支持集合,只留痕不发) |
 | `reward_date` | String(10) | index, NOT NULL | 北京时间日期串 `YYYY-MM-DD`,按它等值统计当日发奖次数 |
 | `reward_name` | String(64) | nullable | 穿山甲上报奖励名(参考,不作发奖依据) |
 | `raw` | String(1024) | nullable | 回调原始参数(审计排查) |

docs/database/app_config.md

@@ -14,8 +14,8 @@
 ## 字段
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
 |---|---|---|---|
-| `key` | String(64) | **PK** | 配置标识,取值见 `config_schema.CONFIG_DEFS`:`signin_rewards` / `min_exchange_coin` / `withdraw_min_cents` / `withdraw_max_cents` / `task_rewards` / `record_milestones` / `ad_reward_coin` / `ad_daily_limit` / `ad_max_coin` / `ad_round_count` / `ad_cooldown_sec` / `signin_boost_coin` / `withdraw_auto_reconcile_enabled` |
-| `value` | JSON(PG: JSONB) | NOT NULL | 配置值,类型随 key(`int` / `int_list` 如签到 14 档 / `dict_str_int` 如 task_rewards / `bool` 如 withdraw_auto_reconcile_enabled) |
+| `key` | String(64) | **PK** | 配置标识,取值见 `config_schema.CONFIG_DEFS`:`signin_rewards` / `min_exchange_coin` / `withdraw_min_cents` / `withdraw_max_cents` / `task_rewards` / `record_milestones` / `ad_reward_coin` / `ad_daily_limit` / `ad_max_coin` / `ad_round_count` / `ad_cooldown_sec` / `signin_boost_coin` / `withdraw_auto_reconcile_enabled` / `comparing_ad_enabled` |
+| `value` | JSON(PG: JSONB) | NOT NULL | 配置值,类型随 key(`int` / `int_list` 如签到 14 档 / `dict_str_int` 如 task_rewards / `bool` 如 withdraw_auto_reconcile_enabled / comparing_ad_enabled) |
 | `updated_by_admin_id` | Integer | nullable | 最后修改的管理员 id(= `admin_user.id`,软引用,无 FK) |
 | `updated_at` | DateTime(tz) | server_default now(), onupdate now() | 最后修改时间 |
 

docs/database/cash_transaction.md

@@ -34,6 +34,7 @@
 
 ## 索引与约束
 - PK `id`;index `user_id`、`created_at`。
+- 部分唯一索引 `ux_cash_transaction_withdraw_refund_ref`(`ref_id`),条件 `biz_type = 'withdraw_refund' AND ref_id IS NOT NULL`:一笔提现单只能退款一次(按 `out_bill_no` 去重),挡重复退款。
 
 ## 注意
 - 退款流水 `remark` 是用户可见文案(区分"未成功自动退"vs"审核未通过退");技术原因记在 `withdraw_order.fail_reason`,不外露。

docs/database/coin_transaction.md

@@ -10,8 +10,8 @@
   | 动作 / endpoint | `biz_type` | `amount` | `ref_id` 指向 |
   |---|---|---|---|
   | 签到 `POST /signin/do` | `signin` | + | 当天日期串(= `signin_record.signin_date` ISO) |
-  | 签到后看广告膨胀 `POST /signin/boost` | `signin_boost` | + | 当天日期串(= `signin_boost_record.signin_date` ISO) |
-  | 领任务 `POST /tasks/claim` | `task_<key>`(如 `task_enable_notification`) | + | `user_task.task_key` |
+  | 签到后看广告膨胀 `POST /signin/boost` | `signin_boost` | + | 广告 `trans_id`(= `signin_boost_record.ad_ref_id`);无 ad_ref_id 时回退当天日期 ISO 串 |
+  | 领任务 `POST /tasks/claim` | `task_<key>`(如 `task_enable_notification`) | + | 一次性任务=`user_task.task_key`;可重复任务(`enable_notification`)=带序号 `task_key:N` |
   | 普通激励视频 S2S 回调 `POST /ad/pangle-callback` | `reward_video`(历史兼容:`ad_reward`) | + | `ad_reward_record.trans_id` |
   | 信息流广告结算 `POST /ad/feed-reward` | `feed_ad_reward` | + | `ad_feed_reward_record.client_event_id` |
   | 金币兑现金 `POST /wallet/exchange` | `exchange_out` | − | null(配套 `cash_transaction.exchange_in`) |
@@ -36,10 +36,11 @@
 
 ## 关系 / Join Key
 - `user_id` → `user.id`(多对一)。
-- `ref_id` 是**软关联**(无 FK),目标表随 `biz_type`:`signin`→签到日 / `signin_boost`→`ad_reward_record.trans_id` / `task_<key>`→`user_task.task_key` / `reward_video`/`ad_reward`→`ad_reward_record.trans_id` / `feed_ad_reward`→`ad_feed_reward_record.client_event_id` / 其余 null。
+- `ref_id` 是**软关联**(无 FK),目标随 `biz_type`:`signin`→签到日(`signin_record.signin_date` ISO) / `signin_boost`→`signin_boost_record.ad_ref_id`(无则当天日期) / `task_<key>`→一次性任务=`user_task.task_key`、可重复任务=`task_key:N` / `reward_video`/`ad_reward`→`ad_reward_record.trans_id` / `feed_ad_reward`→`ad_feed_reward_record.client_event_id` / 其余 null。
 
 ## 索引与约束
 - PK `id`;index `user_id`、`created_at`。
+- 部分唯一索引 `ux_coin_transaction_task_ref`(`user_id`, `biz_type`, `ref_id`),条件 `biz_type LIKE 'task%' AND ref_id IS NOT NULL`:可重复任务(如打开消息提醒)按 `ref_id` 序号(`task_key:N`)去重,挡并发/连点重复发放;仅 `task_*` 且 `ref_id` 非空生效,不影响 signin/exchange/withdraw 等其它 `biz_type`。
 
 ## 注意
 - 流水与余额快照(`coin_account`)、与对应业务记录(signin/task/ad_reward/feed_ad_reward 等)在**同一事务**写,不会只发币不留痕。

docs/database/comparison_milestone_claim.md

@@ -5,7 +5,7 @@
 App「记录比价战绩」每档(第 1~6 次)只能领一次,领取后写一行去重。解锁进度**不存本表**——由 `comparison_record` 里 `status='success'` 的条数实时算(第 N 档在"成功比价 ≥ N 次"时解锁)。档位金额来自 `rewards.RECORD_MILESTONES`(默认 `(120,180,300,500,800,1200)`,运营后台 `app_config.record_milestones` 可改)。仿 `user_task` 的一次性领取模型。
 
 ## 用在哪 / 增删改查
-- **C(插入)**:`POST /compare/milestone/claim`(`claim`)。档位合法 + 已解锁(`count_success >= milestone`)+ 未领过 → 写一行(`coin_awarded=0`)。越界 `UnknownMilestoneError`(404)、未解锁 `MilestoneLockedError`(409)、已领 `AlreadyClaimedError`(409)。
+- **C(插入)**:`POST /compare/milestones/{milestone}/claim`(`claim`)。档位合法 + 已解锁(`count_success >= milestone`)+ 未领过 → 写一行(`coin_awarded=0`)。越界 `UnknownMilestoneError`(404)、未解锁 `MilestoneLockedError`(409)、已领 `AlreadyClaimedError`(409)。
 - **U / D**:无。
 - **R**:`GET /compare/milestones`(战绩页:各档 claimed/active/locked + 成功次数),`get_status` 读本表已领集合 + `comparison_record` 成功计数对照。
 

docs/database/comparison_record.md

@@ -5,6 +5,7 @@
 每完成一次比价(外卖/电商/领券),客户端在 done 帧后用**带 JWT** 的通道上报一条。App「我的比价记录」列表/详情的数据源,也是比价战绩里程碑解锁进度的计数源(`status='success'` 条数),还被「上报更低价」反查原最低价。
 
 > 与 `savings_record` 的区别:本表是「每一次**比价行为**的完整明细」(不省钱、甚至失败也记);`savings_record` 是「真正**下单成交**省了多少」。两表独立、互不喂数据。
+> 与 [`price_observation`](./price_observation.md) / `store_mapping` 的区别:本表是**用户视角**(登录后按 `user_id` 存「我的比价记录」);后两张是 server 侧无条件沉淀的**平台/门店视角客观事实**(价格事实 / 跨平台店铺身份映射),与本表 `trace_id` 同源但不互相 join,各存各的视角。
 
 ## 用在哪 / 增删改查
 - **C / U(upsert,幂等)**:`POST /compare/record`(`upsert_record`)。按 `(user_id, trace_id)` 查:不存在→新建;已存在→整行覆盖(客户端重试/重复上报时,**更完整的那次胜出**)。`best_*`/`saved_amount_cents`/`is_source_best`/`status` 由 `_derive` 从 `comparison_results` 算出(协议已按 price 升序、rank=1 最便宜),不信客户端自算。
@@ -19,6 +20,7 @@
 | `device_id` | String(64) | nullable | 设备号(多设备区分 / 与不鉴权期对账) |
 | `business_type` | String(16) | NOT NULL, default `food`, index | 取值:`food`(当前唯一接通)/ `ecom` / `coupon` |
 | `trace_id` | String(64) | NOT NULL | pricebot 侧 trace_id(关联调试落盘 + 幂等键) |
+| `trace_url` | String(512) | nullable | 本次比价公网调试链接(`price.shaguabijia.com/traces/{dir}/`);dir 名含 pricebot 落盘时分秒,前端/server 拼不出必须存。查看接口按 `user.debug_trace_enabled`(或本机 agent 调试 `include_trace`)决定返不返回。旧记录 / 未开上云为 null |
 | `source_platform_id` / `_name` | String(32) | nullable | 源平台代号 / 中文名 |
 | `source_package` | String(128) | nullable | 源平台 Android 包名 |
 | `source_price_cents` | Integer | nullable | 源平台到手价(分) |
@@ -32,7 +34,7 @@
 | `status` | String(16) | NOT NULL, default `success` | 取值:`success`(有非源且有价的目标结果)/ `failed`(出错/没采到目标价)。**里程碑只数 success** |
 | `information` | String(256) | nullable | done 帧文案;成功=摘要,失败=具体原因(前端失败时当原因展示) |
 | `items` | JSON(PG: JSONB) | NOT NULL, default [] | 下单菜品 `[{name, qty, specs?}]` |
-| `comparison_results` | JSON(PG: JSONB) | NOT NULL, default [] | 逐平台对比 `[{platform_id,platform_name,package,price(元),is_source,rank,coupon_saved(元),coupon_name}]`;`coupon_saved`=该平台主优惠额(美团红包/淘宝平台红包/京东百亿补贴,只取一笔),`coupon_name`=优惠来源名(展示用) |
+| `comparison_results` | JSON(PG: JSONB) | NOT NULL, default [] | 逐平台对比 `[{platform_id,platform_name,package,price(元),is_source,rank,coupon_saved(元),coupon_name,applied_coupons}]`;`coupon_saved`=该平台主优惠额(美团红包/淘宝平台红包/京东百亿补贴,只取一笔),`coupon_name`=优惠来源名(展示用),`applied_coupons`=`[{name,amount}]` 多券明细 |
 | `skipped_dish_names` | JSON(PG: JSONB) | NOT NULL, default [] | 被跳过的菜名 |
 | `raw_payload` | JSON(PG: JSONB) | nullable | 客户端原始上报全量(calibration + done.params),取数兜底 |
 | `created_at` | DateTime(tz) | server_default now(), index | 时间 |
@@ -46,7 +48,7 @@
 - 被 `comparison_milestone_claim` 间接依赖:解锁进度 = 本表 `status='success'` 计数。
 
 ## 索引与约束
-- PK `id`;index `user_id`、`business_type`、`created_at`;UNIQUE(`user_id`, `trace_id`) = `uq_comparison_user_trace`(幂等覆盖)。
+- PK `id`;index `user_id`、`business_type`、`created_at`;复合 index `ix_comparison_status_created`(`status`, `created_at`)(按 `status='success'` 过滤 + 近期排序的聚合/轮播,避免随数据量退化为全表扫);UNIQUE(`user_id`, `trace_id`) = `uq_comparison_user_trace`(幂等覆盖)。
 
 ## 注意
 - 4 个 JSON 列用 `JSON().with_variant(JSONB(),"postgresql")`(SQLite 退化 JSON)。结构化金额列存「分」,`comparison_results.price`/`coupon_saved` 原样存「元」。

docs/database/coupon_state.md

@@ -4,7 +4,7 @@
 
 领券（优惠券自动化）联动产生的三张「今日状态」表，都挂在领券透传端点 `POST /api/v1/coupon/step` 这条链路上（pricebot 跑领券，结果回 app-server 落库；**领券过程本身在 pricebot 内存态跑、不落库**）。三表各管一件事：
 
-- **`coupon_prompt_engagement`** — 弹窗频控源。按 `(device, 自然日)` 记「今天是否对领券引导窗表达过**意向**」（点「一键领取」=`claim_started` / 点拒绝关闭=`dismissed` 都算）。切到外卖 App 时据此决定弹不弹：今天 engage 过就不再弹。
+- **`coupon_prompt_engagement`** — 弹窗频控源。按 `(device, App 包名, 自然日)` 记「今天**这个 App** 是否对领券引导窗表达过**意向**」（弹出即记 `shown` / 点「一键领取」=`claim_started` / 点拒绝关闭=`dismissed` 都算）。切到外卖 App 时据此决定弹不弹：今天**该 App** engage 过就不再弹该 App。频控维度自 2026-06-14 起含 `package`，美团/淘宝/京东各自独立、互不压制。
 - **`coupon_daily_completion`** — 首页置灰源。按 `(device, 自然日)` 记「今天是否已**跑完整轮**领券（到 done 帧）」。首页「去领取」卡据此置灰：今天跑完了就不能再领。
 - **`coupon_claim_record`** — 资产沉淀层。按 `(device, 券, 自然日)` 记每张券的领取结果（success/already_claimed/failed/skipped），**纯沉淀**（资产/画像/排查/CPS 归因），当前**不参与**「要不要领 / 弹不弹」的判断。
 
@@ -19,35 +19,38 @@
 
 ---
 
-## coupon_prompt_engagement — 弹窗频控（今日是否已对引导窗表达意向）
+## coupon_prompt_engagement — 弹窗频控（今日这个 App 是否已对引导窗表达意向）
 
-`(device_id, engage_date)` 唯一，一台设备一天一条；今天 engage 过（领或拒）就不再弹。
+`(device_id, package, engage_date)` 唯一，一台设备、一个 App、一天一条；今天**这个 App** engage 过（弹/领/拒）就不再弹该 App。各 App 独立：美团弹过不压淘宝/京东。
 
 ### 用在哪 / 增删改查
-- **C / U（幂等 upsert）**：`mark_engagement`。两条触发：
+- **C / U（幂等 upsert）**：`mark_engagement`。三条触发：
+  - `POST /api/v1/coupon/prompt/shown`（引导窗弹出那刻上报）→ 记 `shown`（频控主判据：弹出即占用今天这个 App 的「一次」，领/拒/无视都算用掉）；
   - `POST /api/v1/coupon/step` 且 `step==0`（领券首帧=用户已发起领券）→ 记 `claim_started`；
   - `POST /api/v1/coupon/prompt/dismiss`（用户点关闭引导窗；server 在透传链路看不到「拒绝」，必须客户端通知）→ 记 `dismissed`。
-  - 已有今天那条则覆盖 `engage_type`（并补 `user_id`），否则插入。
-- **D**：`POST /api/v1/coupon/prompt/reset`（`reset_today_engagement`）—— 删这台设备今天那条，开发设置「重置今日领券弹窗状态」按钮调，测频控用；删后今天又能弹。
-- **R**：`GET /api/v1/coupon/prompt/should-show?device_id=…`（`has_engaged_today`）→ `should_show = not 今天已 engage`。客户端切外卖 App 前查，纯后台判据。
+  - 已有今天那条则覆盖 `engage_type`（并补 `user_id`），否则插入。`step` 帧的 `package` 取 step body 的 `package`，缺/空则退化为 `""` 占位（全局态）。
+- **D**：`POST /api/v1/coupon/prompt/reset`（`reset_today_engagement`）—— 删这台设备今天**所有 App** 的 engagement（不按 package 过滤：重置=从头测，清全部 App 最符预期），开发设置「重置今日领券弹窗状态」按钮调；删后今天又都能弹。
+- **R**：`GET /api/v1/coupon/prompt/should-show?device_id=…&package=…`（`has_engaged_today`）→ `should_show = not 今天该 App 已 engage`。客户端切外卖 App 前带 `package` 查（老客户端不带 → `""` 全局态）。
 
 ### 字段
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
 |---|---|---|---|
 | `id` | Integer | PK, autoincrement | |
 | `device_id` | String(64) | NOT NULL | 判断/聚合维度；客户端 `getOrCreateDeviceId`，重装会变 |
+| `package` | String(64) | NOT NULL, server_default `""` | 触发弹窗的目标 App 包名（`com.sankuai.meituan` / `com.taobao.taobao` / `com.jingdong.app.mall`）。频控维度，各 App 独立。旧行（2026-06-14 改造前）无此值 → 迁移用占位 `""` 填 |
 | `user_id` | Integer | index, 可空 | 登录态有就记（资产）；不进唯一键、不阻塞判断 |
 | `engage_date` | **Date** | NOT NULL | **北京时间**自然日（`today_cn()`） |
-| `engage_type` | String(16) | NOT NULL | `claim_started`（点一键领取）/ `dismissed`（点拒绝关闭）；仅记录区分，**判断只看「今天有没有这条」，type 不影响弹不弹** |
+| `engage_type` | String(16) | NOT NULL | `shown`（自动弹出即记）/ `claim_started`（点一键领取）/ `dismissed`（点拒绝关闭）；仅记录区分，**判断只看「今天这个 App 有没有这条」，type 不影响弹不弹** |
 | `created_at` | DateTime(tz) | server_default now() | |
 | `updated_at` | DateTime(tz) | server_default now(), onupdate now() | |
 
 ### 索引与约束
-- PK `id`；index `user_id`；UNIQUE(`device_id`, `engage_date`) = `uq_coupon_engage_device_date`（一台设备一天一条）。
+- PK `id`；index `user_id`；UNIQUE(`device_id`, `package`, `engage_date`) = `uq_coupon_engage_device_pkg_date`（一台设备、一个 App、一天一条）。
+  - 历史:原为 UNIQUE(`device_id`, `engage_date`) = `uq_coupon_engage_device_date`，2026-06-14 迁移 `coupon_engage_per_package` 加入 `package` 维度改成现状（修「任一 App 弹过就把整台设备当天标记、压住其余 App」的 bug）。
 
 ### 注意
 - `device_id` 重装会变 → 重装当新设备，今天重新弹一次（产品预期）。
-- 判断只看「今天这台设备有没有这条」，不看 `engage_type`（领或拒都算 engage 过、都不再弹）。
+- 判断只看「今天这台设备这个 App 有没有这条」，不看 `engage_type`（弹/领/拒都算 engage 过、都不再弹该 App）。
 
 ---
 
@@ -57,7 +60,7 @@
 
 ### 用在哪 / 增删改查
 - **C / U（幂等 upsert）**：`mark_completed_today`，由 `POST /api/v1/coupon/step` 在 pricebot 返回 `action.command == "done"` 那帧调。pricebot 把中途单券 done 改写成 `wait+continue=true`，只有整套全跑完那帧才保留 `command=="done"`，故 **done 已等价「整轮完成」**。已有今天那条则补 `user_id`/`trace_id`，否则插入。
-- **U / D**：无业务删除。
+- **D**：`POST /api/v1/coupon/completed-today/reset`（`reset_today_completion`）—— 删这台设备今天那条，首页「去领取」卡恢复可点。与 `/prompt/reset` 配套,开发设置「重置今日领券弹窗状态」一键把今日状态全清；MVP 不鉴权。
 - **R**：`GET /api/v1/coupon/completed-today?device_id=…`（`has_completed_today`）→ `completed`。客户端据此把首页「去领取」卡置灰、不可点。
 
 ### 字段
@@ -119,5 +122,5 @@
 
 ## 三表共性小结
 - 数据流向：客户端 → `POST /api/v1/coupon/step`（透传给 pricebot）→ 结果回写这三张表（best-effort，写库失败不影响领券）。
-- 唯一键都含 `device_id` + 某个北京自然日列；`user_id` 永远是可空旁路（资产留痕，不进唯一键、不阻塞判断）。
+- 唯一键都含 `device_id` + 某个北京自然日列（engagement 还含 `package`，按 App 频控）；`user_id` 永远是可空旁路（资产留痕，不进唯一键、不阻塞判断）。
 - 无硬外键：`user_id` 软指 `user.id`、`trace_id` 软指 pricebot work_logs（详见 [OVERVIEW → 表间关系 & Join Key](./OVERVIEW.md)）。

docs/database/cps_activity.md

@@ -0,0 +1,40 @@
+# cps_activity — CPS 可推广活动池(运营预存的券/物料)
+
+> 模型 `app/models/cps_activity.py` · 仓库 `app/admin/repositories/cps.py`(`create_activity` / `list_activities` / `get_activity` / `delete_activity` / `list_activity_images`) · 接口 admin `POST /admin/api/cps/activities`、`GET /admin/api/cps/activities`、`DELETE /admin/api/cps/activities/{id}`、`POST /admin/api/cps/upload-image`、`GET /admin/api/cps/activity-images` · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+
+运营把常推的活动(券)预存成池,生成群发链接时从池里挑,省得每次记物料 ID。数据**全由运营在后台手填/上传**,无外部同步。在 CPS 群发漏斗里它是**最上游的"卖什么"**:活动(本表)× 群([`cps_group`](./cps_group.md))经"批量生成短链"组合出一条条 [`cps_link`](./cps_link.md)。一条活动可被多个群、多次复用生成 link(一对多,无外键)。
+
+## 用在哪 / 增删改查
+- **C(插入)**:`POST /admin/api/cps/activities`(`create_activity`,需 `operator` 角色)。按 `platform` 分支校验:`meituan` 必须填 `act_id` 或 `product_view_sign` 之一;`taobao`/`jd` 必须填 `payload`,且 `taobao` 还必须有 `image_url`(落地页图)。淘宝图经 `POST /admin/api/cps/upload-image`(`media.save_cps_image`)上传得绝对 URL,或经 `GET /admin/api/cps/activity-images` 选已有。无幂等键,重复提交建多条。
+- **U(更新)**:**无更新端点**。改活动 = 删了重建。`status`(active/archived)列存在但目前没有切换它的路由(待确认是否前端规划)。
+- **R(读)**:`GET /admin/api/cps/activities`(`list_activities`,游标分页,可按 `platform`/`status` 过滤,登录即可);生成 link 时 `get_activity` 按 id 取;淘宝落地页渲染时 `cps_redirect` 用 `db.get(CpsActivity, link.activity_id)` 取 `image_url`;`list_activity_images` 取所有 distinct 非空 `image_url` 供新建复用。
+- **D(删除)**:`DELETE /admin/api/cps/activities/{id}`(`delete_activity`,`operator`)。**硬删,不级联** `cps_link`——已发出去的短链继续可用;淘宝落地页若取不到活动(被删),`cps_redirect` 用兜底默认图 `/media/taobao_landing.jpg`。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | 被 `cps_link.activity_id` 语义引用(非 FK) |
+| `platform` | String(20) | NOT NULL, default `meituan` | `meituan` / `taobao` / `jd`。决定转链/落地方式,也决定下面哪些字段必填 |
+| `name` | String(128) | NOT NULL | 活动名,运营自定,后台列表/审计展示 |
+| `act_id` | String(64) | nullable | **美团**联盟「我要推广-活动推广」第一列的物料 ID(actId)。转链 `get_referral_link` 入参 |
+| `product_view_sign` | String(128) | nullable | **美团**商品券 productViewSign,与 `act_id` 二选一转链(多数活动用 `act_id`) |
+| `payload` | Text | nullable | **淘宝**=整段淘口令文本(落地页原样供复制);**京东**=推广链接(落地页 302 跳)。美团不用此列(用 `act_id`)。生成 link 时直接作 `target_url` |
+| `image_url` | String(512) | nullable | **淘宝**落地页主视觉图,存绝对 URL(基于 `CPS_REDIRECT_BASE`,跨域 admin-web 可显示)。落地页按活动展示对应图 |
+| `status` | String(20) | NOT NULL, default `active` | `active` / `archived`(目前无切换入口,主要靠删) |
+| `remark` | String(256) | nullable | 运营备注 |
+| `created_at` | DateTime(tz) | server_default now(), NOT NULL | 创建时间。**无 `updated_at`**(本表无更新路径) |
+
+## 关系 / Join Key
+- `id` ← `cps_link.activity_id`(一活动多 link,**语义关联,无 ForeignKey**;删活动不级联删 link)。
+- `id` ← `cps_redirect` 渲染淘宝落地页时按 `link.activity_id` 反查本表取 `image_url`。
+- 与 [`cps_group`](./cps_group.md) 无直接列关系:两者在"批量生成短链"(`generate_referral_links`)时按 **platform 是否在群范围内**组合,产物是 [`cps_link`](./cps_link.md)。
+
+## 索引与约束
+- PK `id`。
+- **无唯一约束、无额外索引、无外键**(运营低频、量级小,按 id 主键访问即可)。
+
+## 注意
+- **`platform` 是多平台演进的核心**:初版(commit `277f9b1`)只有美团,字段就是 `act_id` + `product_view_sign`;`3a40f61` 接淘宝/京东时**复用本表**,只加了 `payload`(异构标识塞一列);`d55f47f` 再加 `image_url` 把淘宝落地页图"做活"(此前是写死一张图)。所以三平台的"卖点"挤在同一张表,靠 `platform` 分流——这是省表的刻意取舍。
+- **美团二选一**:`act_id` 与 `product_view_sign` 对应 `get_referral_link` 的两种转链入参,router 层强制至少填一个。
+- **淘宝必须有图**:`taobao` 落地页是我们自渲染的 H5(`cps_redirect._taobao_landing_html`),没图页面就空,故建活动时强制。`d55f47f` 的迁移把存量淘宝活动的 `image_url` 回填成此前写死的 `/media/taobao_landing.jpg`,无缝衔接。
+- **`image_url` 存绝对 URL 的原因**:落地页域(`CPS_REDIRECT_BASE`)与 admin-web 跨域,存绝对值两边都能取(`media.to_abs_media_url`)。dev 未配 `CPS_REDIRECT_BASE` 时退化为相对路径。

docs/database/cps_click.md

@@ -0,0 +1,37 @@
+# cps_click — CPS 短链点击事件(/c/{code} 每次访问/复制记一条)
+
+> 模型 `app/models/cps_link.py`(`CpsClick`,与 `CpsLink` 同文件) · 仓库 `app/repositories/cps_link.py`(`record_click` / `click_stats_by_group`) · 接口 用户 `GET /c/{code}`(记 `visit`)、`POST /c/{code}/copy`(记 `copy`,`app/api/v1/cps_redirect.py`);统计 admin `GET /admin/api/cps/stats` · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+
+群发短链 [`cps_link`](./cps_link.md) 每被点一次就在此记一条。在 CPS 群发漏斗里它是**"用户点了"这一步**:用户点 `/c/{code}` 进落地/被跳转记 `visit`,淘宝落地页点"复制口令"记 `copy`。据此统计点击 PV/UV(按群/活动/时段),配合 [`cps_order`](./cps_order.md) 的下单/佣金构成"点击→下单→佣金"漏斗。`group_id`/`sid` 在本表**冗余一份**(来自 link),统计直接按群聚合、不必 join `cps_link`。
+
+## 用在哪 / 增删改查
+- **C(插入)**:`record_click`(`app/repositories/cps_link.py`),由 `cps_redirect` 两处触发——`GET /c/{code}`(`cps_landing`)记 `event_type=visit`;`POST /c/{code}/copy`(`cps_copy`,淘宝落地页点复制按钮 fetch 回调)记 `event_type=copy`。写入时把 link 的 `group_id`/`sid` 冗余进来,`ua` 截断到 500。**记点击失败被 `_record` 吞掉绝不阻断用户跳转/落地**(公网无鉴权,任何人点都要能跳)。无幂等——每次点都写新行(PV 即行数)。
+- **U / D**:**无**。点击是只追加的事件流。
+- **R(读)**:`click_stats_by_group`(`GET /admin/api/cps/stats` 经 `group_stats` 调用)按 `group_id` 聚合 → `{pv, uv, copy_pv, copy_uv}`;UV 按 `(ip, ua)` 近似去重,`visit` 计 pv/uv、`copy` 计 copy_pv/copy_uv。聚合在 Python 侧做(量级小、跨 PG/SQLite 无方言坑)。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `link_id` | Integer | index, NOT NULL | 来源短链 = `cps_link.id`(语义关联,非 FK) |
+| `group_id` | Integer | index, NOT NULL | **冗余**自 link.group_id;按群聚合点击快,免 join cps_link |
+| `sid` | String(64) | index, **nullable** | **冗余**自 link.sid;美团有、淘宝/京东无 |
+| `event_type` | String(16) | NOT NULL, default/server_default `visit` | `visit`(进落地页/被 302 跳) / `copy`(淘宝落地页点了"复制口令") |
+| `ip` | String(64) | nullable | 客户端 IP(取 `X-Forwarded-For` 首段,否则 `request.client.host`),UV 去重键之一 |
+| `ua` | String(512) | nullable | User-Agent,入库截断到 500;UV 去重键之一 |
+| `clicked_at` | DateTime(tz) | server_default now(), index, NOT NULL | 点击时间,统计按时间窗过滤 |
+
+## 关系 / Join Key
+- `link_id` → `cps_link.id`(多对一,**语义关联,无 ForeignKey**)。
+- `group_id` → `cps_group.id`、`sid` ≈ `cps_group.sid`——均**冗余字段**,直接按群聚合用,非 FK。
+- 与 [`cps_order`](./cps_order.md) 无直接关联:点击与订单在 `group_stats` 里**各按 `group_id`/`sid` 聚合后并到同一群行**,共同组成漏斗,但两表之间无 join key(无法把某次点击对到某笔订单——CPS 联盟不回传点击 id)。
+
+## 索引与约束
+- PK `id`;index `link_id`、`group_id`、`sid`、`clicked_at`。
+- **无唯一约束、无外键**(纯事件流,PV 即行数,允许重复)。
+
+## 注意
+- **`event_type` 是接淘宝时新增的**:初版(`277f9b1`)只有 visit(点了就 302 跳美团,记一条即可);`3a40f61` 接淘宝后,淘宝落地页是 H5、用户要点按钮"复制口令"才算转化,故迁移 `cps_v2_platforms` 加 `event_type`(server_default `visit` 回填存量),`copy` 单独统计成 `copy_pv/copy_uv`。同迁移把 `sid` 改 nullable(淘宝/京东点击无 sid)。
+- **`group_id`/`sid` 冗余的理由**:统计是高频读路径,直接 `WHERE group_id=?` 聚合,省掉 `cps_click → cps_link` 的 join;代价是写入时多带两列(`record_click` 从 link 拷)。这与 model docstring 明说的"统计直接按群聚合、不必 join cps_link"一致。
+- **UV 是近似值**:按 `(ip, ua)` 去重,无 Cookie/设备指纹;同一人换网络/浏览器会重复计 UV。够运营看趋势,不作精确口径。
+- **记点击绝不阻断**:`_record` 用 `try/except: pass` 包住,落地/跳转优先级高于统计——丢几条点击可接受,挡住用户领券不可接受。