feat: 添加 Analytics 分析功能（行为追踪、错误码、协议更新）

deploy/README.md

@@ -28,6 +28,10 @@ deploy/
 ├── build-prod-image.sh
 ├── docker-compose.prod.yml
 ├── .env.prod.example
+├── data/
+│   └── analytics/
+├── static/
+│   └── releases/
 └── README.md
 ```
 
@@ -80,6 +84,18 @@ cp deploy/.env.prod.example deploy/.env.prod
 
 ### 2) 启动常驻服务
 
+确保 analytics 数据目录已存在（用于持久化 `SOCIAL_ANALYTICS__DATA_PATH`）：
+
+```bash
+mkdir -p deploy/data/analytics
+```
+
+如果服务器启用了更严格权限策略（含 rootless Docker 或自定义容器运行用户），请确保该目录对容器运行用户可写：
+
+```bash
+chmod 775 deploy/data/analytics
+```
+
 ```bash
 docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml up -d redis web worker-agent worker-general scheduler
 ```
@@ -122,6 +138,15 @@ docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml up
 
 在 nginx 增加静态目录映射：`location /releases/ { alias /你的项目绝对路径/deploy/static/releases/; }`，这样 `https://你的域名/releases/xxx.apk` 可直接下载安装包。并在 `deploy/.env.prod` 设置 `SOCIAL_APP_VERSION__DOWNLOAD_BASE_URL=https://你的域名` 与 `SOCIAL_APP_VERSION__RELEASE_PATH_PREFIX=releases`，确保 `check-updates` 返回的 `download_url` 指向该路径。
 
+## Analytics 数据持久化
+
+- `SOCIAL_ANALYTICS__DATA_PATH` 默认值是 `backend/data/analytics`。
+- 生产编排已挂载：`deploy/data/analytics -> /app/backend/data/analytics`。
+- `web` 和 `worker-general` 共用同一挂载目录，避免写入与读取不一致。
+- 若你在 `.env.prod` 覆盖了 `SOCIAL_ANALYTICS__DATA_PATH`，请同步调整 `docker-compose.prod.yml` 的挂载目标路径。
+- analytics 挂载为独立目录，不会影响 `deploy/static/releases -> /app/deploy/static/releases` 的 APK 发布链路。
+- 建议将 `deploy/data/analytics` 纳入日常备份策略，避免宿主机磁盘故障导致数据丢失。
+
 ## Android APK 打包
 
 打包 Android APK 时需指定后端地址：