fix: query tenant-sharded private messages

fileMapper.UserHasAccess 恒经 TenantFileUserHasAccess，共享库多租户
模式走 tenant_adapter 的 SQL；此前第 9 条（头像链接行对登录用户放行）
只加在了基础路径 FileUserHasAccess，导致共享库环境下他人下载头像仍
403。同步补齐，与 FileUserHasAccess 保持一致。

.gitea/workflows/deploy.yml

@@ -1,72 +1,69 @@
-name: Deploy im-server (k3s test cluster)
+name: Deploy im-server production
 
 on:
+  push:
+    branches:
+      - pro
   workflow_dispatch:
-    inputs:
-      image_tag:
-        description: '镜像tag，默认为 test（与集群 kustomization 里的 newTag 一致）'
-        required: false
+
+concurrency:
+  group: production-im-server
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  REGISTRY: git.olns.shop
+  IMAGE: git.olns.shop/pro/im_server
+  SERVICE: im-server
+  DEPLOY_HOST: 145.223.69.9
+  DEPLOY_USER: olns-deploy
 
 jobs:
   deploy:
     runs-on: deploy-host
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@v4
 
-      - name: 确定镜像tag
-        id: vars
+      - name: Log in to Gitea Container Registry
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
-          TAG="${{ github.event.inputs.image_tag }}"
-          [ -z "$TAG" ] && TAG=test
-          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          set -euo pipefail
+          printf '%s' "$REGISTRY_TOKEN" | docker login "$REGISTRY" -u admin --password-stdin
 
-      - name: 登录镜像仓库
-        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.118im.com -u admin --password-stdin
-
-      - name: 构建并推送镜像(从本仓库源码编译，不是官方预编译包)
+      - name: Build and push image
+        env:
+          GITHUB_SHA: ${{ github.sha }}
         run: |
+          set -euo pipefail
+          SHORT_SHA="$(printf '%.12s' "$GITHUB_SHA")"
           docker build -f docker/tinode/Dockerfile.build \
-            -t git.118im.com/im_team/im-server:${{ steps.vars.outputs.tag }} .
-          docker push git.118im.com/im_team/im-server:${{ steps.vars.outputs.tag }}
+            -t "${IMAGE}:pro" -t "${IMAGE}:${SHORT_SHA}" .
+          docker push "$IMAGE:pro"
+          docker push "$IMAGE:$SHORT_SHA"
 
-      - name: 部署到k3s测试集群
+      - name: Deploy Compose service
+        env:
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+          DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
-          mkdir -p ~/.kube
-          echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config
-          chmod 600 ~/.kube/config
-          kubectl set resources statefulset/im-server -n im-server-system -c im-server \
-            --requests=cpu=1,memory=512Mi --limits=cpu=2,memory=1Gi
-          kubectl set env statefulset/im-server -n im-server-system -c im-server \
-            CLUSTER_PROXY_TO_MASTER_BUFFER=4096 \
-            CLUSTER_PROXY_TO_MASTER_WORKERS=16 \
-            CLUSTER_PROXY_TO_MASTER_ENQUEUE_TIMEOUT_MS=300 \
-            CLUSTER_ROUTE_RETRIES=3 \
-            CLUSTER_ROUTE_RETRY_BACKOFF_MS=25
-          kubectl patch statefulset/im-server -n im-server-system --type=strategic -p \
-            '{"spec":{"template":{"spec":{"containers":[{"name":"im-server","readinessProbe":{"httpGet":{"path":"/healthz","port":6060},"timeoutSeconds":3,"periodSeconds":10,"failureThreshold":3},"livenessProbe":{"httpGet":{"path":"/livez","port":6060},"timeoutSeconds":3,"periodSeconds":20,"failureThreshold":3}}]}}}}'
-          if kubectl auth can-i get services -n im-server-system >/dev/null 2>&1 && \
-             kubectl auth can-i patch services -n im-server-system >/dev/null 2>&1; then
-            kubectl patch service/im-server -n im-server-system --type=merge -p \
-              '{"spec":{"sessionAffinity":"None"}}'
-          else
-            echo "::warning::ci-deployer cannot get/patch Service; skipped sessionAffinity update"
-          fi
-          if kubectl auth can-i get ingresses.networking.k8s.io -n im-server-system >/dev/null 2>&1 && \
-             kubectl auth can-i patch ingresses.networking.k8s.io -n im-server-system >/dev/null 2>&1 && \
-             kubectl get ingress/im-server -n im-server-system >/dev/null 2>&1; then
-            kubectl annotate ingress/im-server -n im-server-system --overwrite \
-              nginx.ingress.kubernetes.io/load-balance=least_conn
-          else
-            echo "::warning::ci-deployer cannot manage Ingress/im-server or it does not exist; skipped least_conn update"
-          fi
-          kubectl rollout restart statefulset/im-server -n im-server-system
-          kubectl rollout status statefulset/im-server -n im-server-system --timeout=300s
-
-          resources="$(kubectl get statefulset/im-server -n im-server-system -o \
-            jsonpath='{.spec.template.spec.containers[?(@.name=="im-server")].resources}')"
-          liveness="$(kubectl get statefulset/im-server -n im-server-system -o \
-            jsonpath='{.spec.template.spec.containers[?(@.name=="im-server")].livenessProbe.httpGet.path}')"
-          echo "effective resources=${resources} liveness=${liveness}"
-          if [ "${liveness}" != "/livez" ] || ! echo "${resources}" | grep -q '"cpu":"2"'; then
-            echo "::warning::StatefulSet resources/probes were reconciled away; update the ArgoCD source kustomization"
-          fi
+          set -euo pipefail
+          install -d -m 700 "$HOME/.ssh"
+          KEY_FILE="$(mktemp "$HOME/.ssh/olns-deploy.XXXXXX")"
+          cleanup() {
+            shred -u "$KEY_FILE" 2>/dev/null || true
+          }
+          trap cleanup EXIT
+          printf '%s\n' "$DEPLOY_SSH_KEY" > "$KEY_FILE"
+          chmod 600 "$KEY_FILE"
+          printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > "$HOME/.ssh/known_hosts"
+          chmod 600 "$HOME/.ssh/known_hosts"
+          SSH_ARGS=(-i "$KEY_FILE" -o BatchMode=yes -o StrictHostKeyChecking=yes)
+          printf '%s' "$REGISTRY_TOKEN" | ssh "${SSH_ARGS[@]}" "$DEPLOY_USER@$DEPLOY_HOST" \
+            "docker login git.olns.shop -u admin --password-stdin"
+          ssh "${SSH_ARGS[@]}" "$DEPLOY_USER@$DEPLOY_HOST" \
+            "cd /opt/olns && docker compose pull im-server && docker compose up -d --no-deps --wait im-server"

deploy/argocd/im-server-test/README.md

@@ -0,0 +1,61 @@
+# im-server-test ArgoCD patch
+
+The live StatefulSet is owned by the ArgoCD Application `im-server-test`.
+Copy `statefulset-performance-patch.yaml` into that application's Git source
+and reference it from the test overlay:
+
+```yaml
+patches:
+  - path: statefulset-performance-patch.yaml
+```
+
+Also include `backend-debug-metrics-rbac.yaml` as a resource in the test
+overlay. It grants the existing `argocd/backend-debug` service account
+namespaced read access to Pod metrics so the load-test collector can run
+`kubectl top pods -n im-server-system`:
+
+```yaml
+resources:
+  - backend-debug-metrics-rbac.yaml
+```
+
+After ArgoCD sync, verify the effective configuration:
+
+```bash
+kubectl -n im-server-system get statefulset im-server -o jsonpath='{.spec.template.spec.containers[0].resources}'
+kubectl -n im-server-system get statefulset im-server -o jsonpath='{.spec.template.spec.containers[0].livenessProbe.httpGet.path}'
+kubectl -n im-server-system get statefulset im-server -o jsonpath='{.spec.template.spec.containers[0].env}'
+kubectl -n im-server-system get statefulset im-server -o jsonpath='{.spec.template.spec.dnsConfig.options}'
+kubectl auth can-i list pods.metrics.k8s.io \
+  --as=system:serviceaccount:argocd:backend-debug \
+  -n im-server-system
+```
+
+Expected values are requests `2 CPU / 512Mi`, limits `2 CPU / 1Gi`, and
+liveness path `/livez`. The MySQL pool environment must be
+`MYSQL_MAX_OPEN_CONNS=24`, `MYSQL_MAX_IDLE_CONNS=8`,
+`MYSQL_REGISTRY_MAX_OPEN_CONNS=4`, and `MYSQL_REGISTRY_MAX_IDLE_CONNS=2`.
+The MySQL connection lifetime must be `MYSQL_CONN_MAX_LIFETIME_SECONDS=1800`.
+The WebSocket heartbeat environment must be `WS_PING_PERIOD_SECONDS=15` and
+`WS_PONG_WAIT_SECONDS=90`.
+The Pod DNS options must be `ndots:1`, `timeout:2`, and `attempts:2`. Keeping
+`ClusterFirst` preserves short Kubernetes service-name resolution, while the
+lower `ndots` value prevents fully qualified internal and external dependency
+names from being expanded through every cluster search suffix first.
+The application repository's deploy workflow waits for reconciliation and
+fails if ArgoCD restores different values.
+
+After the rollout, verify the generated resolver configuration on every Pod:
+
+```bash
+for pod in im-server-0 im-server-1 im-server-2; do
+  echo "--- ${pod}"
+  kubectl -n im-server-system exec "${pod}" -- cat /etc/resolv.conf
+done
+```
+
+The output must retain the cluster DNS nameserver and search domains, with
+`options ndots:1 timeout:2 attempts:2`. This mitigation reduces amplified DNS
+traffic from the application Pods. If lookup timeouts remain under load,
+CoreDNS capacity or NodeLocal DNSCache must be changed in the cluster
+infrastructure repository by an administrator with `kube-system` access.

deploy/argocd/im-server-test/backend-debug-metrics-rbac.yaml

@@ -0,0 +1,27 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: backend-debug-metrics-reader
+  namespace: im-server-system
+rules:
+  - apiGroups:
+      - metrics.k8s.io
+    resources:
+      - pods
+    verbs:
+      - get
+      - list
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: backend-debug-metrics-reader
+  namespace: im-server-system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: backend-debug-metrics-reader
+subjects:
+  - kind: ServiceAccount
+    name: backend-debug
+    namespace: argocd

deploy/argocd/im-server-test/statefulset-performance-patch.yaml

@@ -0,0 +1,71 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: im-server
+  namespace: im-server-system
+spec:
+  template:
+    spec:
+      dnsPolicy: ClusterFirst
+      dnsConfig:
+        options:
+          - name: ndots
+            value: "1"
+          - name: timeout
+            value: "2"
+          - name: attempts
+            value: "2"
+      containers:
+        - name: im-server
+          env:
+            - name: WS_PING_PERIOD_SECONDS
+              value: "15"
+            - name: WS_PONG_WAIT_SECONDS
+              value: "90"
+            - name: CLUSTER_PROXY_TO_MASTER_BUFFER
+              value: "4096"
+            - name: CLUSTER_PROXY_TO_MASTER_WORKERS
+              value: "16"
+            - name: CLUSTER_PROXY_TO_MASTER_ENQUEUE_TIMEOUT_MS
+              value: "300"
+            - name: CLUSTER_ROUTE_RETRIES
+              value: "3"
+            - name: CLUSTER_ROUTE_RETRY_BACKOFF_MS
+              value: "25"
+            - name: TOPIC_CLIENT_QUEUE_BUFFER
+              value: "4096"
+            - name: TOPIC_SERVER_QUEUE_BUFFER
+              value: "512"
+            - name: TOPIC_PUBLISH_ENQUEUE_WAIT_MS
+              value: "200"
+            - name: MYSQL_MAX_OPEN_CONNS
+              value: "24"
+            - name: MYSQL_MAX_IDLE_CONNS
+              value: "8"
+            - name: MYSQL_REGISTRY_MAX_OPEN_CONNS
+              value: "4"
+            - name: MYSQL_REGISTRY_MAX_IDLE_CONNS
+              value: "2"
+            - name: MYSQL_CONN_MAX_LIFETIME_SECONDS
+              value: "1800"
+          resources:
+            requests:
+              cpu: "2"
+              memory: 512Mi
+            limits:
+              cpu: "2"
+              memory: 1Gi
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: 6060
+            timeoutSeconds: 3
+            periodSeconds: 10
+            failureThreshold: 3
+          livenessProbe:
+            httpGet:
+              path: /livez
+              port: 6060
+            timeoutSeconds: 3
+            periodSeconds: 20
+            failureThreshold: 3

docker/README.md

@@ -193,6 +193,9 @@ You can specify the following environment variables when issuing `docker run` co
 | `CLUSTER_PROXY_TO_MASTER_ENQUEUE_TIMEOUT_MS` | number | `300` | Maximum wait for a full proxy-to-master shard before returning 503. |
 | `CLUSTER_ROUTE_RETRIES` | number | `3` | Number of retries after a remote server-message route is rejected as overloaded. |
 | `CLUSTER_ROUTE_RETRY_BACKOFF_MS` | number | `25` | Initial exponential retry delay for remote server-message routes. |
+| `TOPIC_CLIENT_QUEUE_BUFFER` | number | `4096` | Per-topic client publish queue capacity. Increase for large groups with bursty publishers. |
+| `TOPIC_SERVER_QUEUE_BUFFER` | number | `512` | Per-topic server-message queue capacity. |
+| `TOPIC_PUBLISH_ENQUEUE_WAIT_MS` | number | `200` | Maximum wait for an attached session publish to enter a full topic queue before returning 503. |
 | `DEBUG_EMAIL_VERIFICATION_CODE`[^2] | string |  | Enable dummy email verification code, e.g. `123456`. Disabled by default (empty string). |
 | `DEFAULT_COUNTRY_CODE`[^2] | string | `US` | 2-letter country code to assign to sessions by default when the country isn't specified by the client explicitly and it's impossible to infer it. |
 | `EXT_CONFIG`[^1] | string |  | Path to external config file to use instead of the built-in one. If this parameter is used, most other variables are ignored[^1]. |

docker/tinode/Dockerfile

@@ -194,6 +194,8 @@ ENV TNPG_ORG=
 ENV JPUSH_PUSH_ENABLED=false
 ENV JPUSH_API_DOMAIN=https://api.jpush.cn
 ENV JPUSH_PUSH_PATH=/v3/push
+ENV JPUSH_WORKERS=8
+ENV JPUSH_DEVICE_CACHE_TTL_SECONDS=30
 ENV JPUSH_DEFAULT_TTL_SECONDS=86400
 ENV JPUSH_CALL_TTL_SECONDS=60
 ENV JPUSH_APNS_PRODUCTION=false

docker/tinode/Dockerfile.build

@@ -110,6 +110,8 @@ ENV TNPG_PUSH_ENABLED=false
 ENV JPUSH_PUSH_ENABLED=false
 ENV JPUSH_API_DOMAIN=https://api.jpush.cn
 ENV JPUSH_PUSH_PATH=/v3/push
+ENV JPUSH_WORKERS=8
+ENV JPUSH_DEVICE_CACHE_TTL_SECONDS=30
 ENV JPUSH_DEFAULT_TTL_SECONDS=86400
 ENV JPUSH_CALL_TTL_SECONDS=60
 ENV JPUSH_APNS_PRODUCTION=false

docker/tinode/config.template

@@ -5,6 +5,8 @@
 	"static_mount": "/",
 	"grpc_listen": ":16060",
 	"grpc_keepalive_enabled": true,
+	"ws_ping_period_seconds": $WS_PING_PERIOD_SECONDS,
+	"ws_pong_wait_seconds": $WS_PONG_WAIT_SECONDS,
 	"api_key_salt": "$API_KEY_SALT",
 	"max_message_size": 4194304,
 	"max_subscriber_count": 128,
@@ -79,9 +81,11 @@
 			"mysql": {
 				"database": "meeting_im",
 				"dsn": "$MYSQL_DSN",
-				"max_open_conns": 64,
-				"max_idle_conns": 64,
-				"conn_max_lifetime": 60,
+				"max_open_conns": $MYSQL_MAX_OPEN_CONNS,
+				"max_idle_conns": $MYSQL_MAX_IDLE_CONNS,
+				"registry_max_open_conns": $MYSQL_REGISTRY_MAX_OPEN_CONNS,
+				"registry_max_idle_conns": $MYSQL_REGISTRY_MAX_IDLE_CONNS,
+				"conn_max_lifetime": $MYSQL_CONN_MAX_LIFETIME_SECONDS,
 				"sql_timeout": 10,
 				"tenant_registry_db": "$TENANT_REGISTRY_DB",
 				"tenant_db_routing": true
@@ -124,14 +128,14 @@
 
 	"kafka": {
 		"enabled": true,
-		"brokers": ["kafka.118im.com:30835"],
+		"brokers": $KAFKA_BROKERS_JSON,
 		"client_id": "im-server",
 		"consumer_group": "im-server",
 		"dial_timeout_ms": 3000,
 		"write_timeout_ms": 3000,
 		"read_timeout_ms": 3000,
 		"batch_timeout_ms": 10,
-		"required_acks": 1,
+		"required_acks": -1,
 		"allow_auto_topic_creation": false,
 		"tls_enabled": false,
 		"sasl_enabled": false,
@@ -173,7 +177,7 @@
 		}
 	},
 	"admin_internal_api": {
-		"enabled": true,
+		"enabled": $ADMIN_INTERNAL_API_ENABLED,
 		"base_url": "$ADMIN_INTERNAL_API_BASE_URL",
 		"service_name": "$ADMIN_INTERNAL_API_SERVICE_NAME",
 		"secret": "$ADMIN_INTERNAL_API_SECRET",
@@ -262,6 +266,8 @@
 				"enabled": $JPUSH_PUSH_ENABLED,
 				"api_domain": "$JPUSH_API_DOMAIN",
 				"push_path": "$JPUSH_PUSH_PATH",
+				"workers": $JPUSH_WORKERS,
+				"device_cache_ttl_seconds": $JPUSH_DEVICE_CACHE_TTL_SECONDS,
 				"default_ttl_seconds": $JPUSH_DEFAULT_TTL_SECONDS,
 				"call_ttl_seconds": $JPUSH_CALL_TTL_SECONDS,
 				"apns_production": $JPUSH_APNS_PRODUCTION,

docker/tinode/entrypoint.sh

@@ -13,11 +13,18 @@ else
 	CONFIG=working.config
 
 	: "${REDIS_KEY_PREFIX:=im}"
+	: "${WS_PING_PERIOD_SECONDS:=15}"
+	: "${WS_PONG_WAIT_SECONDS:=90}"
 	: "${CLUSTER_PROXY_TO_MASTER_BUFFER:=4096}"
 	: "${CLUSTER_PROXY_TO_MASTER_WORKERS:=16}"
 	: "${CLUSTER_PROXY_TO_MASTER_ENQUEUE_TIMEOUT_MS:=300}"
 	: "${CLUSTER_ROUTE_RETRIES:=3}"
 	: "${CLUSTER_ROUTE_RETRY_BACKOFF_MS:=25}"
+	: "${MYSQL_MAX_OPEN_CONNS:=24}"
+	: "${MYSQL_MAX_IDLE_CONNS:=8}"
+	: "${MYSQL_REGISTRY_MAX_OPEN_CONNS:=4}"
+	: "${MYSQL_REGISTRY_MAX_IDLE_CONNS:=2}"
+	: "${MYSQL_CONN_MAX_LIFETIME_SECONDS:=1800}"
 	if [ -z "$CLUSTER_NODES_JSON" ] ; then
 		CLUSTER_NODES_JSON='[{"name":"tinode-0","addr":"tinode-0:12000"},{"name":"tinode-1","addr":"tinode-1:12001"},{"name":"tinode-2","addr":"tinode-2:12002"}]'
 	fi

docs/IM-006商户双机消息压力测试方案.md

@@ -6,6 +6,8 @@
 
 > 双机实际操作以 [`loadtest/im-pressure/README.md`](../loadtest/im-pressure/README.md) 为准。当前开发机固定为机器 A，负责数据准备、协调器、agent A、集中采集和最终报告；另一台机器固定为机器 B，只运行 agent B 并回传结果。
 
+> 当前测试环境实际企业码为 `allrich`，沿用本方案最初为 006 商户定义的账号规模、场景和统计口径。已完成的 200 对复测、故障根因和修复证据见 [`docs/test/IM-单聊压测Pod日志根因分析与改进方案-20260927.md`](./test/IM-单聊压测Pod日志根因分析与改进方案-20260927.md)。
+
 本次测试使用 006 商户的 2000 个账号，在两台压测机上各运行 1000 个在线 WebSocket 用户，验证多 Pod 场景下：
 
 1. 1000 对 P2P 会话同时收发时，消息是否被接受、实时投递并最终持久化。
@@ -128,7 +130,7 @@ Idempotency-Key: <unique key for write requests>
 1. `max_subscriber_count >= 2500`。仓库配置默认是 128，必须在所有 Pod 上统一调高并滚动重启。
 2. 006 商户 `max_group_members` 为 0（不限）或不小于 2000；目标群 `max_member_count` 同样满足要求。
 3. IM Server 所有 Pod 版本和配置一致，原生 Cluster 成员数与 Running Pod 数一致。
-4. Kafka 的 P2P、群消息持久化 Topic 可写，消费组无持续积压，死信在基线时为 0。
+4. Kafka 的 P2P、群消息持久化 Topic 可写，消费组无持续积压，死信在基线时为 0；测试环境的 `im.message.persist` 和 `im.group.message.persist` 均为 3 分区、3 副本。
 5. 两台压测机到目标入口网络稳定，文件描述符上限、临时端口和 NAT 容量足够。
 6. 两台压测机使用 chrony/NTP，同一时刻的时钟偏差绝对值小于 5ms，否则跨机器单向延迟无效。
 7. 每台压测机至少预留 2 CPU、4GB 内存和稳定的 100Mbps 网络；测试进程自身 CPU 不应长期超过 70%。
@@ -357,8 +359,8 @@ e2e_realtime_latency = t_data - sent_at
 | 群实时投递丢失率 | <= 0.001%，发布版本验收目标为 0 |
 | 重复投递率 | 0 |
 | Topic `seq` 回退 | 0 |
-| ACK p95 / p99 | < 100ms / < 300ms |
-| 实时投递 p95 / p99 | < 200ms / < 500ms |
+| ACK p95 / p99 | <= 500ms / <= 1s；必须用原始 ACK 时间戳计算，不能用直方图桶上界代替 |
+| 实时投递 p95 / p99 | <= 1s / <= 2s；跨机器时要求时钟偏差达标 |
 | `deliver/hub_full`、WS 写队列满 | 0 |
 | Kafka producer/commit 错误 | 0 |
 | Kafka 消费重试、单条降级、死信新增 | 0 |
@@ -735,7 +737,7 @@ loadtest/im-pressure/internal/collector/
 loadtest/im-pressure/internal/report/
 ```
 
-协调方式：Machine A 启动 coordinator，等待 A/B 两个 agent 都上报 1000 个 READY，然后发布一个至少晚于当前时间 30 秒的 UTC `start_at`。两台机器按相同 `run_id` 和确定性调度执行。任何 agent 失联都将本轮标记为 `INVALID`。
+协调方式：Machine A 启动 coordinator，等待 A/B 两个 agent 都上报 1000 个 READY，然后发布一个至少晚于当前时间 30 秒的 UTC `start_at`。到达 `start_at` 后，A/B 必须在前后 3 秒内向 coordinator 完成最终起跑确认；只有双方都确认后才开始发送，任一方迟到则两边共同终止并将本轮标记为 `INVALID`。两台机器按相同 `run_id` 和确定性调度执行，任何 agent 失联同样判定为 `INVALID`。
 
 `agent` 自身暴露 `/metrics`，提供连接状态、发布、接收、重复、乱序、断连及 Go/process 指标；ACK 和投递延迟分布写入最终 summary。`collect` 只执行只读查询，并把各数据源的原始快照与查询时间一起保存；连接凭证通过环境变量传入，不写入结果目录。
 
@@ -787,8 +789,33 @@ results/<run_id>/report.md
 2. 完成 1000 对好友关系与 2000 人群，运行 `verify` 直到全部通过。
 3. 先用 20 对 P2P、100 人群做冒烟测试，验证统计口径。
 4. 执行 P0 热身。
-5. 执行 S1，等待服务端和 Kafka 恢复基线至少 5 分钟。
-6. 执行 S2，等待恢复基线至少 10 分钟。
-7. 执行 S3。
+5. P2P 按 200 对、500 对、1000 对逐级执行；每一级通过后才能进入下一级。
+6. 执行 S2 群聊，等待恢复基线至少 10 分钟。
+7. 执行 S3 混合场景。
 8. 合并结果，按实时链路与持久化链路分别给出结论。
 9. 全部稳定后再单独进行 Pod 重启、断网或 Kafka/Redis 故障注入，不与本轮无故障基线混跑。
+
+### 14.1 P2P 容量阶梯
+
+三个档位复用同一批账号和好友关系，只裁剪 runtime manifest，不重新注册或重复加好友。每档至少执行两轮；发布验收档建议执行三轮。任何一轮出现消息丢失、重复、乱序、非预期拒绝、数据库不一致或 Pod 重启，都必须停止升级并先定位。
+
+| 档位 | A/B 用户 | WS 总数 | 每用户消息 | Publish 总数 | 目标 |
+|---|---:|---:|---:|---:|---|
+| P2P-200 | 各 200 | 400 | 10 | 4000 | 验证正确性、指标和基础延迟 |
+| P2P-500 | 各 500 | 1000 | 10 | 10000 | 验证 Kafka 三分区、MySQL 和 Cluster 中档容量 |
+| P2P-1000 | 各 1000 | 2000 | 10 | 20000 | 单聊发布验收 |
+
+每档的执行流程固定为：生成唯一 `run_id`；开始前采集至少 2 分钟基线；启动 coordinator；A/B agent 全部 READY；统一时间发压；P2P 发送结束后继续监听至少 30 秒；等待 Kafka lag 归零；执行历史回查与 MySQL `client_mid` 精确核验；发送结束后继续采集至少 5 分钟；最后合并报告。
+
+每档升级门槛：Ready、Publish ACK、实时到达、历史查询和 MySQL 精确匹配全部达到期望数；丢失、重复、乱序、断连、403/502/503、Cluster queue overflow、Kafka retry/dead letter、MySQL deadlock、Pod 重启均为 0；Kafka lag 在发送结束后 60 秒内归零；Pod 无持续 CPU throttling。ACK P95 超标时必须按压测机分别报告，并先排除 DNS、TCP、TLS、WebSocket RTT 和时钟偏差。
+
+### 14.2 P2P 通过后的业务场景
+
+1. **GROUP-2000**：2000 条 WS 全部加入同一群，A/B 各 500 个发送者；每人发送 2 条，两轮合计 2000 条。实时投递期望量按每条消息的实际 Ready 接收者计算，并保留 60 秒 drain。
+2. **MIXED**：300 对私聊用户双方各发 5 条，共 3000 条私聊 Publish；同时 A/B 各 250 个群发送者每人发 2 条，共 1000 条群 Publish。
+3. **稳定性复跑**：GROUP 和 MIXED 至少各两轮，确认无冷启动偶然性。
+4. **故障注入**：分别执行单 Pod 滚动重启、Kafka 短暂不可用与恢复、Redis 短暂不可用与恢复；故障轮只验证恢复能力，不与无故障性能基线混合统计。
+
+### 14.3 当前下一步
+
+当前已通过 P2P-200 的消息正确性、Kafka 60 秒排空、MySQL 精确落库、零乱序、零审计死锁和零 CPU throttling。下一步执行 **P2P-500**：A/B 各取账号索引 `1..500`，共 1000 条 WS、10000 条 Publish。若连续两轮满足上述升级门槛，再进入 P2P-1000。

docs/IM-前后端对接文档.md

@@ -154,6 +154,12 @@ WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。
 
 客户端只使用稳定的 `reason` 分支和本地化文案，不解析 `message`。ID、Topic、Seq 游标在客户端均按字符串处理；时间统一为 UTC RFC3339 毫秒。分页统一使用 `limit` 与不透明 `cursor`，返回 `items`、`next_cursor`、`has_more`。
 
+资源不存在类错误统一语义（2026-09-29 修订）：
+
+- 好友申请 `accept/reject` 在申请不存在时统一返回 `404/20004 RESOURCE_NOT_FOUND`，两个入口语义一致。
+- 群类接口（`DELETE /v1/im/groups/{topic}`、`POST /v1/im/groups/{topic}/leave`、`POST /v1/im/groups/{topic}/qrcodes`、`PUT /v1/im/groups/{topic}/members/me/profile`、`GET/PATCH /v1/im/groups/{topic}/settings` 等经群成员校验的路径）在群不存在时返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散时返回 `410/30004 GROUP_DISSOLVED`；群存在但当前用户非成员仍是 `403/30005 PERMISSION_DENIED`。
+- 服务端对不存在的资源不再返回 5xx 或网关错误。
+
 ### 0.5 WebSocket 建连、登录和恢复顺序
 
 #### 0.5.1 现有服务端可直接执行的冷启动流程
@@ -236,6 +242,8 @@ WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。
 {"sub":{"id":"sub-topic-1","topic":"grp...","get":{"what":"desc sub data del","data":{"since":125,"limit":50},"del":{"since":1,"limit":50}}}}
 ```
 
+**向上翻页（加载更早历史）最终参数约定（后端已确认，2026-09-29）**：复用同一 `get data`，最终参数为 `before`（排他上界，返回 `seq < before`），**没有 REST cursor 语义**。聊天页滚动到顶部时发 `data:{"before":<当前已加载最小 seq>,"limit":50}`（`since` 可省略，默认 0）。服务端返回该锚点之前**最接近 `before` 的 `limit` 条**，`{data}` 按 `seq` 从大到小下发（首条即锚点前最新一条）；收到 `ctrl 204 no content`（`params.what=="data"`）表示已到会话顶部。`data` 参数全集：`since`（含下界）、`before`（排他上界）、`limit`、`ranges`。P2P 与群聊（含热缓存 fallback）语义一致。REST `GET /v1/im/conversations/{topic}/messages` 当前为空占位（见 4.21.1），不得用于历史分页。
+
 订阅成功后才允许 `{pub}`、`note read/recv` 等会话操作。断线恢复必须重新执行 `WebSocket Upgrade -> hi -> token login -> sub me -> 恢复 Topic`，同一连接内不得跳过 `hi` 或切换企业码。
 
 ##### 0.5.1.1 WebSocket 心跳与在线状态
@@ -327,6 +335,8 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 登录失败 | `{"login":{"id":"login-bad","scheme":"basic","secret":"base64(alice:wrong)"}}` | `{"ctrl":{"id":"login-bad","code":401,"text":"authentication failed","params":{"reason":"AUTH_FAILED"}}}` |
 | 租户不匹配 | `{"login":{"id":"login-tenant","scheme":"token","secret":"其他租户 token"}}` | `{"ctrl":{"id":"login-tenant","code":403,"text":"tenant mismatch","params":{"reason":"TENANT_MISMATCH"}}}` |
 
+**注册 `username` 规则（服务端强校验，2026-10-14 确认）**：3~10 个字符，仅允许小写字母 `a-z` 和数字 `0-9`；不允许大写、下划线、点、汉字及任何符号。不传 `username` 只传 `phone` 时服务端自动生成随机用户名（此时 `secret` 使用 `base64(手机号:密码)`）。违规表现：过短返回 `422 policy violation, params.what=auth`（本次联调实测，用户名 `zz` 即此情形）；超长或含非法字符返回 `422, params.what=username, reason=USERNAME_INVALID_FORMAT`。最小长度来自部署配置 `basic` 认证的 `min_login_length`（当前部署模板为 3），服务端代码上限为 10。
+
 ##### 0.5.4.2 启动订阅、会话列表和增量恢复
 
 | 场景 | 客户端发送 | 服务端返回示例 |
@@ -398,6 +408,14 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 `kp/kpa/kpv` 只表示输入态、录音态、视频输入态等短暂 UI 状态，不能作为长连接心跳。长连接保活必须依赖 0.5.1.1 中的 WebSocket Ping/Pong。
 
+**单聊已读/已收回执协议约定（服务端已验证，2026-09-29）：**
+
+1. **在线下行形态**：`info.topic` 为话题名（如 `p2p...`），`info.from` 为报读者，`info.what` 为 `recv`/`read`，`info.seq` 为水位。服务端跳过上报会话自身，推送给对端及本人其他在线设备（多 Pod 部署经 Kafka 同步，各 Pod 均会下发）。
+2. **离线补发形态**：接收方离线时收到 `{"info":{"topic":"me","src":"p2p...","from":"usr...","what":"recv","seq":12}}`，即 `topic` 固定为 `me`、`src` 才是话题名。客户端必须同时兼容上述两种形态。
+3. **序号单调递增**：服务端丢弃 `seq` 不大于当前水位的回执（`read`、`recv` 各自独立判断），`read` 回执会同步抬升 `recv`，恒有 `read ≥ recv`。客户端渲染一律取服务端最大游标，禁止用本地计数覆盖服务端值。
+4. **断线重连恢复**：`sub`/`get desc` 响应的 `desc` 中包含 `seq`、`read`、`recv`、`clear` 四个游标；`get {"what":"sub"}` 也返回各成员的 `read/recv`。重连后以这些游标恢复本地状态，不要依赖进程内存。
+5. **换设备登录**：回执水位按「用户 × 话题」在服务端持久化，与设备无关；新设备订阅后 `desc` 同时返回自己与对端的最新 `read/recv`，可完整恢复对方"已读/已收"状态。发送者自身的 `read/recv` 由服务端自动推进到其最新发出的 `seq`。
+
 ##### 0.5.4.5 Topic 资料、个人群设置和标签
 
 | 场景 | 客户端发送 | 服务端返回/下行示例 |
@@ -620,8 +638,15 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | WebSocket `login basic` | `{"login":{"id":"login-1","scheme":"basic","secret":"base64(username:password)"}}` | `{"ctrl":{"id":"login-1","code":200,"params":{"user":"usr...","token":"token...","expires":"2026-09-03T09:00:00Z","authlvl":"auth"}}}` |
 | WebSocket `acc new` | `{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"15500000000","registration_type":1,"secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"15500000000","resp":"verification_token","params":{"challenge_id":"chg_123"}}]}}` | `{"ctrl":{"id":"acc-1","code":200,"params":{"user":"usr...","username":"alice","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
 | `POST /v0/channels/lp` | Long Polling 首包 `{"hi":{"id":"hi-1","ver":"0.25","tenant":"default"}}` | `{"ctrl":{"id":"hi-1","code":201,"params":{"sid":"lp_sid_123"}}}` |
-| `POST /v0/file/u/` | Multipart 文件；Header `X-MeetingIM-Auth: token <base64_token>`；业务表单可带 `purpose=chat_file&topic=grp...` | `{"ctrl":{"code":200,"params":{"url":"/v0/file/s/file123","name":"a.pdf","size":1024,"mime":"application/pdf"}}}` |
-| `GET /v0/file/s/{file_id}` | Header `X-MeetingIM-Auth: token <base64_token>`，可带 `Range: bytes=0-` | 对象存储模式下鉴权通过后返回 302 到短期签名 URL；客户端跟随 Location 获取文件 |
+| `POST /v0/file/u/` | Multipart 文件；Header `X-MeetingIM-Auth: token <base64_token>`；聊天附件必须带 `topic=<消息所在会话 topic>`（`p2p.../grp...`），可选 `purpose=chat_file`、`id=<幂等ID>` | `{"ctrl":{"code":200,"params":{"expires":"2026-10-13T06:21:20Z","file_id":"s6yhMyiOfaU","url":"/v0/file/s/s6yhMyiOfaU.txt"}}}` |
+| `GET /v0/file/s/{file_id}` | Header `X-MeetingIM-Auth: token <base64_token>`，可带 `Range: bytes=0-`；URL 可带文件扩展名（服务端自动剥离） | 对象存储模式下鉴权通过后返回 302 到短期签名 URL；客户端跟随 Location 获取文件 |
+
+**文件上传/下载鉴权与回收规则（已实现，客户端必须遵守）：**
+
+1. 上传聊天附件（图片/视频/语音/文件）必须携带 `topic=<消息将要发送到的会话 topic>`。服务端校验上传者是该 `p2p`/`grp` 会话的订阅成员（`modewant`/`modegiven` 含读权限），不是成员返回 `403 permission denied`；校验通过则在服务端建立「文件-会话」引用，该会话全体成员凭有效 Token 即可下载。
+2. 不带 `topic` 的上传只有上传者本人可下载。任何文件若一直未被任何会话/消息引用，服务端在创建 1 小时后由后台任务物理回收；上传后必须及时发送消息或携带 `topic`，否则对端将拿到 404。用户头像/资料类文件不受此限：客户端设置头像（PATCH `avatar_file_id`）时服务端自动写入文件引用，该文件不会被回收。
+3. 下载放行范围（2026-10-14 更新）：上传者本人、文件所属会话成员、消息级引用可见者（未撤回未删除且未被执行删除）、群成员、好友关系、收藏引用、**用户头像/资料文件（对任何登录用户放行，2026-10-14 修复：此前仅上传者可读，群成员拉取他人头像 403）**。非授权返回 `403 permission denied`（即 `FILE_FORBIDDEN`），客户端不自动重试。
+4. `avatar_url` 统一回填规则（2026-10-14 起，所有返回用户/群摘要的接口一致）：`avatar_file_id` 为完整 URL 时 `avatar_url` 原样返回；为裸 file_id 时返回 `"/v0/file/s/{file_id}"`（可直接下载，无需客户端拼接）；头像为空时回落默认头像 URL（男/女按性别，`avatar_file_id` 与 `avatar_url` 同值）。涉及接口：`/v1/im/groups/{topic}/members`、`/members/{userId}/profile`、`/v1/im/users/{id}/profile`、`/v1/im/me/profile`、转发目标列表等。
 
 ### 0.6 Topic 与产品消息
 
@@ -927,7 +952,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 **状态：新增。**
 
-- 敏感操作先调用 `POST /v1/im/security/challenges`；开启青少年模式设置独立密码时 Body 为 `{"scene":"set_independent_password","channel":"sms"}`，关闭青少年模式时 Body 为 `{"scene":"close_youth_mode","channel":"sms"}`；群主转让使用 `{"scene":"group_owner_transfer","channel":"sms"}`；解散群聊使用 `{"scene":"group_dissolve","channel":"sms"}`。手机号由登录身份读取，客户端不提交目标手机号。
+- 敏感操作先调用 `POST /v1/im/security/challenges`；开启青少年模式设置独立密码时 Body 为 `{"scene":"set_independent_password","channel":"sms"}`，关闭青少年模式时 Body 为 `{"scene":"close_youth_mode","channel":"sms"}`；群主转让使用 `{"scene":"group_owner_transfer","channel":"sms"}`；解散群聊使用 `{"scene":"group_dissolve","channel":"sms"}`；注销账号使用 `{"scene":"delete_account","channel":"sms"}`。手机号由登录身份读取，客户端不提交目标手机号。
 - 发码/校验：服务端返回 `challenge_id` 和脱敏手机号；提交 `POST /v1/im/security/challenges/{id}/verify`，Body `{"code":"..."}`。
 - 重复发码：同一用户、同一手机号、同一敏感场景存在未过期 challenge 且仍在 `resend_after_seconds` 冷却期内时，服务端返回 HTTP `429 VERIFICATION_RATE_LIMITED`，`details` 带 `challenge_id` 和 `retry_after_seconds`。客户端应复用该 `challenge_id` 继续倒计时，不要当成接口不可达或重新登录。
 - 小时限流：超过一小时创建次数上限时同样返回 HTTP `429 VERIFICATION_RATE_LIMITED`，`details.retry_after_seconds` 可能大于 60 秒且不一定带 `challenge_id`。客户端只展示倒计时，倒计时结束后允许用户重新获取验证码。
@@ -953,7 +978,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 - 页面只调用 `GET /v1/im/security/realname`。`verified` 时返回如 `masked_name:"张*"`、`masked_id_number:"110***********1234"`、`verified_at`。
 - 前端只读展示，不缓存原始证件信息，不提供直接修改接口。
-- 更正信息使用独立申诉 `POST /v1/im/security/realname/appeals`，需二次身份验证；不复用本页保存按钮。
+- 更正信息使用独立申诉 `POST /v1/im/security/realname/appeals`，Body `{"reason":"...","attachments":[]}`（`reason` 必填、≤500 字；`attachments` 最多 9 个 file_id），Bearer 即可，当前无需二次身份验证；不复用本页保存按钮。
 
 ### 1.10 实名认证（安卓）.png
 
@@ -1057,8 +1082,9 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 **状态：需改造。**
 
 - `GET /v1/im/system-notifications?cursor=` 返回 `id,event_type,title,summary,created_at,read_at,action`；实时刷新以 0.5.4.6 的 WS `{info what:"im|group"}` 业务事件为准，系统通知列表记录不等同于每一条实时事件。
+- `summary` 为服务端生成的可直接展示文案（如「对方已同意你的好友申请」「对方已婉拒你的好友申请」），前端直接渲染，无需再做状态码到文案的映射；`action` 读路径统一归一为 `{type,target_id,payload,...原始键}`。
 - 新设备登录事件内容为 `device_name,platform,ip_masked,login_at,security_action`；IP 只下发必要脱敏值。
-- 已读：`POST /v1/im/system-notifications/{id}/read`，带幂等键；跳转目标只接受服务端白名单 `action.type` 和内部参数。
+- 已读：`POST /v1/im/system-notifications/{id}/read`，带幂等键；重复已读返回首次持久化的 `read_at`，不回显本次提交值。跳转目标只接受服务端白名单 `action.type` 和内部参数。
 - 当前普通认证用户可向 `sys` Topic 发布的路径必须封禁。客户端不得渲染普通用户伪造的系统卡片为可信通知。
 
 ### 2.6 接口示例
@@ -1077,7 +1103,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | --- | --- | --- |
 | `GET /v1/im/bootstrap` | Query only | `{"features":{"create_group":true,"user_search":true,"scan_qr":true,"system_notifications":true,"message_recall":true,"message_edit":true,"audio_call":true,"video_call":true},"permissions":{"create_group":true,"user_search":true,"scan_qr":true,"audio_call":true,"video_call":true},"entries":{"new_friends":{"enabled":true,"route":"/contacts/new-friends","unread_count":0},"groups":{"enabled":true,"route":"/contacts/groups","unread_count":0},"file_assistant":{"enabled":true,"route":"/chat/file-assistant","topic":"slf","unread_count":0},"system_messages":{"enabled":true,"route":"/chat/system","topic":"sys","unread_count":0}},"entry_badges":{"new_friends_pending_count":0,"groups_unread_count":0,"file_assistant_unread_count":0,"system_unread_count":0,"workbench_total_unread":0},"system_topic":{"topic":"sys","type":"system"},"message_policy":{"recall_window_seconds":120,"edit_window_seconds":300,"supported_actions":["copy","quote","delete","recall","edit"]},"security":{"realname":{"status":"unverified","required":false,"allow_skip":true,"remind_after":"24h"}}}` |
 | `GET /v1/im/search/conversations?q=&cursor=` | Query only | `{"items":[{"topic":"grp...","public":{"name":"项目群"},"private":{"pinned":false,"mute_notifications":false},"seq":12,"read":10,"recv":12,"unread":2,"updated_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
-| `GET /v1/im/system-notifications?cursor=&limit=20` | Query only | `{"items":[{"id":"evt_1","event_type":"friend.request.created","title":"新的好友申请","summary":"张三请求添加你为好友","action":{"type":"friend_request","request_id":"frq_1"},"read_at":null,"created_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
+| `GET /v1/im/system-notifications?cursor=&limit=20` | Query only | `{"items":[{"id":"evt_1","event_type":"friend.request.created","title":"新的好友申请","summary":"张三请求添加你为好友","action":{"type":"friend_request","target_id":"usr...","payload":{"request_id":"frq_1"},"request_id":"frq_1"},"read_at":null,"created_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
 | `POST /v1/im/system-notifications/{id}/read` | `{"read_at":"2026-08-20T09:00:00Z"}` | `{"status":"ok","id":"evt_1","read_at":"2026-08-20T09:00:00Z"}` |
 
 ## 3. 单聊会话、会话建立与消息状态
@@ -1136,11 +1162,14 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 <img src="images/双方沟通状态.png" alt="双方沟通状态" width="360">
 
-**状态：上传基础已实现；媒体消息 Schema、ACL 和恢复需改造。**
+**状态：上传带 `topic` 与下载按会话授权已在服务端实现；客户端按本节接入。**
 
-- 选择媒体后本地生成 `client_mid` 和稳定占位；调用文件上传，得到 `file_id` 后再 `pub x-im-type=image|video|voice`。
+- 选择媒体后本地生成 `client_mid` 和稳定占位；调用文件上传（**必须带 `topic=<该会话 topic>`**，服务端校验成员资格并自动建立文件-会话引用），得到 `file_id` 后再 `pub x-im-type=image|video|voice`。
 - `content` 至少含 `file_id,name,size,mime,width,height,duration_ms,thumbnail_file_id` 中适用字段；上传进度是客户端任务状态，不写成聊天消息。
-- 服务端发布成功后关联文件与 Topic/消息；文件下载必须校验消息可见性。上传失败只重试上传，成功但 `pub` 失败时复用已上传 `file_id` 和 `client_mid`。
+- 服务端在上传阶段即建立文件与会话的引用（带 `topic`）；消息发布成功后按消息附件引用建立消息级 ACL；文件下载校验会话成员身份与消息可见性。
+- 媒体文件（缩略图、原图、视频、语音）一律走同一次上传流程并带同一个 `topic`；缩略图也必须挂到会话，否则对端只能看到占位图。
+- 上传失败（网络中断、超时、5xx）按**整文件重传**处理：重新调用 `POST /v0/file/u/` 上传完整文件，不做分片/断点续传；每次重传得到新 `file_id`，旧 `file_id` 直接放弃、由服务端 TTL 回收，客户端不得再引用。
+- 上传成功但 `pub` 失败时不重新上传，复用已上传 `file_id` 和原 `client_mid` 重发消息，服务端按 `client_mid` 幂等去重。
 
 ### 3.7 个人对话—拉黑状态／已读状态.png
 
@@ -1294,7 +1323,9 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 **状态：客户端任务管理新增；服务端上传需改造。**
 
-- 每个待发送项保存 `client_mid,local_uri,type,upload_id,progress,state`；同一文件可分片/断点续传时使用稳定 `upload_id`。
+- 每个待发送项保存 `client_mid,local_uri,type,upload_id,progress,state`；`upload_id` 仅在单次上传任务内有效（进度上报与本地去重用）。
+- 重试即新建上传任务：`progress` 归零、生成新 `upload_id`，**整文件重传** `POST /v0/file/u/`，不做分片/断点续传；重传成功后消息体 `file_id` 等字段全部取最新一次上传响应。
+- 自动重试采用指数退避且不超过 3 次，之后转人工点按重试；App 冷启动扫描本地 `failed` 任务队列重新上传。
 - 上传完成后再发布消息；多任务可并发但必须各自保持原排序号。离开页面不取消，退出账号必须暂停并隔离任务。
 - 服务端返回 `FILE_TOO_LARGE`、`FILE_TYPE_NOT_ALLOWED`、`STORAGE_QUOTA_EXCEEDED` 时不可自动无限重试。
 
@@ -1410,10 +1441,10 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 接口 | 输入示例 | 成功 `data` 示例 |
 | --- | --- | --- |
 | `GET /v1/im/conversations/{topic}/context` | Path `p2p...` 或 `grp...` | `{"topic":"p2p...","type":"p2p","relationship":"friend","can_send":true,"capabilities":{"text":true,"image":true,"file":true,"voice":true,"can_call":true},"peer":{"user_id":"usr...","display_name":"张三","avatar_file_id":""}}` |
-| `POST /v1/im/conversations/p2p` 待实现 | `{"peer_user_id":"usr..."}` | `{"topic":"p2p...","relationship":"friend","can_send":true}` |
-| `GET /v1/im/conversations/{topic}/settings` 待实现 | Path topic | `{"pinned":false,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":1,"permissions":{"can_update":true}}` |
-| `PATCH /v1/im/conversations/{topic}/settings` 待实现 | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"pinned":true,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":2}` |
-| `GET /v1/im/conversations/{topic}/messages` 待实现 | Query `?since=12&limit=20` | `{"topic":"p2p...","items":[{"seq":13,"from":"usr...","ts":"2026-08-20T09:00:00Z","head":{"x-im-type":"text"},"content":{"text":"你好"}}],"next_cursor":""}` |
+| `POST /v1/im/conversations/p2p` | `{"peer_user_id":"usr..."}` | `{"topic":"p2p...","relationship":"friend","can_send":true}` |
+| `GET /v1/im/conversations/{topic}/settings` | Path topic | `{"pinned":false,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":1,"permissions":{"can_update":true}}` |
+| `PATCH /v1/im/conversations/{topic}/settings` | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"pinned":true,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":2}` |
+| `GET /v1/im/conversations/{topic}/messages` | **服务端当前为空占位**：GET 恒返回空列表，勿用 `?since=&limit=` 调它；历史消息（首屏与向上翻页）一律走 WS `get data` 的 `since`/`before`/`limit`（向上翻页见 0.5.1 约定） | `{"topic":"p2p...","items":[],"next_cursor":"","has_more":false}` |
 | `PUT /v1/im/topics/{topic}/draft` 待实现 | `{"content":"未发送草稿","version":1}` | `{"topic":"grp...","content":"未发送草稿","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `POST /v1/im/topics/{topic}/messages/{seq}/recall` | 单条撤回；`topic` 可传 `p2p...` 或 `grp...`；Body `{}`，可选 `{"version":1,"reason":"mistake"}` | `{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `POST /v1/im/topics/{topic}/messages/recall` | 多选批量撤回；`{"items":[{"seq":12,"version":1},{"seq":13}],"reason":"mistake"}`；`items` 1～50 条，`version` 可选 | `{"topic":"grp...","items":[{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"},{"seq":13,"status":"failed","http":409,"code":30006,"reason":"VERSION_CONFLICT","message":"message version conflict"}]}` |
@@ -1667,6 +1698,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - `mutation_version` 是会话级水位，不是单条消息的 `version`。
 - 本地只做 `服务端 mutation_version > 本地 mutation_version` 比较，不要假设连续递增。
+- 补偿接口返回的是最新 `limit` 条（默认 50、上限 100）变更的**状态快照**，非严格增量；变更条数超过 `limit` 时更早的变更不再返回。撤回窗口 120 秒、编辑窗口 300 秒，超窗变更无需客户端处理。
 - 拉到 `message.recalled` 后，将本地 `topic + seq` 标记为撤回，并只在 `version` 更高时覆盖。
 - 拉到 `message.edited` 后，按 `seq + version` 拉取或覆盖消息内容。
 - 实时事件和补偿接口可能重复到达，客户端必须按 `topic + seq + version` 幂等处理。
@@ -1679,7 +1711,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增产品通讯录接口。**
 
-- 好友列表：`GET /v1/im/friends?query=&initial=&cursor=`，返回 `user_id,display_name,remark,avatar_file_id,initial,online,online_visibility`；好友展示名统一读取 `display_name`，服务端按当前登录人计算，优先级为备注名、昵称、账号。`remark` 仅用于备注编辑页回显，`nickname` 表示对方自己设置的昵称，不应直接作为好友列表或单聊标题的最终展示名。
+- 好友列表：`GET /v1/im/friends?query=&initial=&cursor=`，返回 `user_id,display_name,remark,avatar_file_id,avatar_url,initial,online,online_visibility`（`avatar_url` 统一回填规则见 0.5.5.1 第 4 条）；好友展示名统一读取 `display_name`，服务端按当前登录人计算，优先级为备注名、昵称、账号。`remark` 仅用于备注编辑页回显，`nickname` 表示对方自己设置的昵称，不应直接作为好友列表或单聊标题的最终展示名。
 - 分页：`next_cursor` 当前按最后一条好友的 `peer_id` 生成，客户端必须作为不透明字符串原样回传，不要自行解析、排序或拼接。
 - 组织成员：`GET /v1/im/organization/members?query=&department_id=&cursor=`；好友和组织成员是两种关系，前端不得混为一个可发消息权限。
 - 新朋友、群列表、文件助手和系统消息入口由 `GET /v1/im/bootstrap` 的 `entries` 控制显示，初始红点由 `entry_badges` 和各入口 `unread_count` 返回。新朋友待处理数使用业务统计；文件助手当前返回 `topic:"slf", unread_source:"topic"`；系统消息当前返回 `topic:"sys", unread_source:"business"`，未读来自系统通知业务表。列表缓存以租户和用户隔离。
@@ -1693,6 +1725,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - 列表：`GET /v1/im/friend-requests?direction=inbound&status=all&cursor=`，返回 `request_id,applicant,message,source,status,created_at,handled_at`。
 - 同意：`POST /v1/im/friend-requests/{request_id}/accept`；拒绝：`POST /v1/im/friend-requests/{request_id}/reject`，均带幂等键和可选 `version`。
 - 成功返回最终 `status` 和 P2P `topic`。重复审批返回原结果；并发冲突返回 `REQUEST_ALREADY_HANDLED` 并附当前状态，前端刷新该项。
+- 申请不存在时 `accept/reject` 统一返回 `404/20004 RESOURCE_NOT_FOUND`；通用语义见 0.4。
 - 主动下行：创建申请时被申请人收到 `info.what="im", event="friend.request.created"`；通过/拒绝后申请人与处理人本人都收到 `friend.request.accepted/rejected`。前端收到后刷新新朋友列表、好友列表、会话 context 和 `bootstrap.entry_badges`。当前系统通知列表只给被申请人/申请人写记录，处理人本人主要靠实时业务事件刷新。
 
 ### 5.3 添加好友.png
@@ -1741,7 +1774,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增。**
 
-- `GET /v1/im/users/{identifier}/profile` 返回按当前查看人裁剪后的 `username,display_name,remark,avatar_file_id,gender,region,public_account,signature,relationship,capabilities`；`identifier` 可传 `user_id`、`username` 或 `public_account`。`username` 是登录账号，`nickname` 是原始昵称，`display_name` 是当前查看人应展示的名称（好友备注优先）；三者不得混用。
+- `GET /v1/im/users/{identifier}/profile` 返回按当前查看人裁剪后的 `username,display_name,remark,avatar_file_id,avatar_url,gender,region,public_account,signature,relationship,capabilities`（`avatar_url` 为可直接下载的头像地址，统一回填规则见 0.5.5.1 第 4 条）；`identifier` 可传 `user_id`、`username` 或 `public_account`。`username` 是登录账号，`nickname` 是原始昵称，`display_name` 是当前查看人应展示的名称（好友备注优先）；三者不得混用。
 - 查看该用户二维码调用 `POST /v1/im/users/{identifier}/qrcodes`，Body `{"purpose":"add_friend","expires_in_seconds":86400}`；前端在个人信息页只有用户名时直接把用户名作为 `identifier` 传入即可。服务端解析到真实用户后生成二维码，并按资料可见性与 `add_me_methods.qr` 做权限校验。
 - 发消息使用返回的 P2P `topic`；没有 Topic 时调用 `POST /v1/im/conversations/p2p`，Body `{"peer_user_id":"..."}` 并由服务端验证好友关系。
 - 音视频按钮只按 `capabilities.can_call` 展示，真正呼叫时再次鉴权。隐藏字段必须从响应中省略，不能只由前端遮挡。
@@ -1810,9 +1843,10 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 <img src="images/黑名单提示.png" alt="黑名单提示" width="360">
 
-**状态：图片文件名与画面语义不一致；按“清除聊天记录”实施，需改造。**
+**状态：图片文件名与画面语义不一致；按“清除聊天记录”实施。服务端已实现并实测（2026-10-09），剩余前端改造。**
 
 - 确认调用 MeetingIM `{del what:"msg",topic,delseq:[{"low":1,"hi":last_seq+1}],hard:false}`，仅删除当前用户视图；或封装 `DELETE /v1/im/conversations/{topic}/messages`。
+- 服务端现状（2026-10-09 测试环境实测通过）：REST 接口仅写 `im_dellog` 本人区间并递增 `deleted_id`，不改动消息行、对方视角不受影响，本人其他设备经 `deleted_id` 同步感知清空；WS `{del}` 语义相同，两条路径二选一即可。对非成员或不存在会话返回 403 FORBIDDEN。
 - 不解除好友、不影响对方历史、不删除收藏；附件仅在无任何有效引用且过保留期后回收。
 - 前端需在确认文案明确“仅清除自己的聊天记录”，成功后清本地 Topic 消息缓存并保留会话关系。
 
@@ -1838,7 +1872,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/friend-requests/{request_id}/reject` | `{"version":1}` | `{"request_id":"frq_1","status":"rejected","handled_at":"2026-08-20T09:00:00Z"}` |
 | `GET /v1/im/users/search?q=&type=account&cursor=` | Query only | `{"items":[{"user_id":"usr...","display_name":"张三","avatar_file_id":"","public_account":"zhangsan","relationship":"none","can_add":true}],"next_cursor":""}` |
 | `GET /v1/im/users/search?q=&type=exact_account` | Query only | `{"items":[{"user_id":"usr...","display_name":"张三","public_account":"zhangsan","relationship":"none","can_add":true}],"next_cursor":""}` |
-| `GET /v1/im/users/{identifier}/profile` | Path `user_id`/`username`/`public_account` | `{"user_id":"usr...","username":"zhangsan7","display_name":"张三","remark":"","avatar_file_id":"","gender":"","region":"","public_account":"zhangsan","signature":"","relationship":"friend","capabilities":{"can_send":true,"can_call":true,"can_add":false},"topic":"p2p..."}` |
+| `GET /v1/im/users/{identifier}/profile` | Path `user_id`/`username`/`public_account` | `{"user_id":"usr...","username":"zhangsan7","display_name":"张三","remark":"","avatar_file_id":"file_avatar","avatar_url":"/v0/file/s/file_avatar","gender":"","region":"","public_account":"zhangsan","signature":"","relationship":"friend","capabilities":{"can_send":true,"can_call":true,"can_add":false},"topic":"p2p..."}` |
 | `PATCH /v1/im/friends/{user_id}` | `{"remark":"老张"}` | `{"user_id":"usr...","remark":"老张","relationship":"friend","updated_at":"2026-08-20T09:00:00Z"}` |
 | `DELETE /v1/im/friends/{user_id}` | Path user ID | `{"user_id":"usr...","relationship":"none","deleted":true}` |
 | `GET /v1/im/blocks?cursor=` | Query only | `{"items":[{"user":{"user_id":"usr...","display_name":"张三","avatar_file_id":""},"blocked_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
@@ -1947,6 +1981,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - `GET /v1/im/groups/{topic}/settings` 返回 `my_role,permissions,profile,announcement,member_count,pinned,mute_notifications` 和群治理开关。
 - 个人置顶/免打扰通过 `PATCH /v1/im/groups/{topic}/member-settings`；群级设置必须使用 6.17，不混在个人设置里。
 - 退出：`POST /v1/im/groups/{topic}/leave`；群主必须先转让或解散。清记录、举报分别见 5.14、11.3。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散返回 `410/30004 GROUP_DISSOLVED`；非群成员返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 
 ### 6.11 群资料.png
 
@@ -1976,6 +2011,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - `PUT /v1/im/groups/{topic}/members/me/profile`，Body `{"nickname":"...","version":n}`。
 - 服务端校验成员资格、长度和敏感词，返回 `nickname,version,updated_at` 并推送成员资料变化。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散返回 `410/30004 GROUP_DISSOLVED`；非群成员返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 - 该昵称仅作用当前群，不能修改全局用户昵称或其他群资料。
 - 群成员列表和群成员资料中的 `display_name` 仍由服务端按当前登录人计算，好友备注优先；群内昵称单独返回为 `group_nickname`，前端不要用 `nickname/group_nickname` 覆盖 `display_name`。
 
@@ -2044,6 +2080,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 **状态：新增。**
 
 - `POST /v1/im/groups/{topic}/qrcodes`，Body `{"expires_in_seconds":86400}`，返回签名 `qr_token,qr_payload,expires_at,group,group_snapshot`；`group` 与 `group_snapshot` 内容一致，前端优先使用 `group`。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散返回 `410/30004 GROUP_DISSOLVED`；非群主/管理员返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 - 扫码调用 `POST /v1/im/qrcodes/resolve`，`purpose:"join_group"`；随后 `POST /v1/im/groups/{topic}/join-requests` 并携带 `qr_token`。
 - 群解散、二维码过期或管理员撤销后必须失效；二维码不得直接承载内部群权限。
 
@@ -2056,6 +2093,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - 查询/更新：`GET/PATCH /v1/im/groups/{topic}/governance`，字段为 `join_approval,mute_all,member_upload_files,member_private_chat,member_invite` 和 `version`。
 - 每个字段返回 `editable`；PATCH 仅群主或被授权管理员可用，记录操作者、旧值、新值和 Request ID。
 - 解散：`DELETE /v1/im/groups/{topic}`，需二次 `X-Action-Token` 和幂等键；成功后撤销 Topic、二维码、邀请和文件新增权限。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；已解散重复解散返回 `410/30004 GROUP_DISSOLVED`；非群主返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 
 ### 6.18 设置群管理员.png
 
@@ -2162,7 +2200,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - 先用 `purpose=group_file,topic=...` 上传，再 `POST /v1/im/groups/{topic}/files`，Body `{"file_id":"...","file_name":"方案.pdf","mime_type":"application/pdf","file_size":1024}` 建立群文件记录。
 - 服务端校验 `member_upload_files`、文件是否已上传完成、`file_name` 长度不超过 255、`mime_type` 长度不超过 128、`file_size` 非负且与上传记录一致、单文件上限、租户总存储和群成员身份；成功返回完整群文件项。
-- 上传失败可复用 `upload_id`；登记失败不得在列表显示，孤立文件按 TTL 回收。
+- 上传失败按整文件重传重新上传并取得新 `file_id`；登记失败不得在列表显示，孤立文件按 TTL 回收。
 
 ### 6.29 接口示例
 
@@ -2191,7 +2229,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `GET /v1/im/groups/{topic}/members?query=&cursor=&mentionable=true` | Query only | `{"topic":"grp...","items":[{"user_id":"usr...","display_name":"张三","group_nickname":"小张","avatar_file_id":"","role":"member","member_status":"active","version":1,"joined_at":"2026-08-20T09:00:00Z","updated_at":"2026-08-20T09:00:00Z","mentionable":true,"acs":{"want":"JRWP","given":"JRWP","mode":"JRWP"}}],"next_cursor":"","sync_mode":"full","permissions":{"can_mention_all":true}}` |
 | `GET /v1/im/groups/{topic}/members/{user_id}` | Path topic/user | `{"topic":"grp...","user_id":"usr...","display_name":"张三","group_nickname":"小张","role":"member","member_status":"active","version":1,"joined_at":"2026-08-20T09:00:00Z","updated_at":"2026-08-20T09:00:00Z","sync_mode":"single","acs":{"want":"JRWP","given":"JRWP","mode":"JRWP"}}` |
 | `DELETE /v1/im/groups/{topic}/members/{user_id}` | Path topic/user；管理员可移除普通成员，群主可移除管理员和普通成员；不能移除群主或自己 | `{"topic":"grp...","user_id":"usr...","status":"left"}` |
-| `GET /v1/im/groups/{topic}/members/{user_id}/profile` | Path topic/user；`topic` 必须是 `grp...`，不能传 `usr...` | `{"topic":"grp...","user_id":"usr...","display_name":"张三","group_nickname":"小张","role":"member","relationship":"friend","capabilities":{"can_send":true,"can_call":true}}` |
+| `GET /v1/im/groups/{topic}/members/{user_id}/profile` | Path topic/user；`topic` 必须是 `grp...`，不能传 `usr...`；`user_id` 可传本人，返回 `relationship:"self"`、`capabilities.can_send=true` | `{"topic":"grp...","user_id":"usr...","display_name":"张三","group_nickname":"小张","role":"member","relationship":"friend","capabilities":{"can_send":true,"can_call":true}}` |
 | `POST /v1/im/groups/{topic}/qrcodes` | `{"expires_in_seconds":86400}` | `{"qr_token":"token...","qr_payload":"im://qr?token=...&purpose=join_group","expires_at":"2026-08-21T09:00:00Z","group":{"topic":"grp...","name":"项目群","member_count":2},"group_snapshot":{"topic":"grp...","name":"项目群","member_count":2}}` |
 | `POST /v1/im/groups/{topic}/invitations` | `{"user_ids":["usr..."],"message":"进群一起讨论"}` | `{"topic":"grp...","items":[{"user_id":"usr...","status":"joined","invitation_id":"ginv_1"}]}` |
 | `POST /v1/im/group-invitations/{invitation_id}/accept` 待实现 | `{}` | `{"invitation_id":"ginv_1","status":"joined","topic":"grp..."}` |
@@ -2303,10 +2341,12 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 <img src="images/文件-下载.png" alt="文件-下载" width="360">
 
-**状态：底层下载已实现租户校验；资源 ACL 需改造。**
+**状态：下载授权已实现（按上传者/会话成员/消息引用/群成员/好友/收藏/头像放行）。**
 
-- 客户端使用 `GET /v0/file/s/{file_id}`，Header 传 API Key 与 `X-MeetingIM-Auth: token <base64_token>`；禁止 `?auth=&secret=`。
-- 服务端除 Token 租户外，还必须校验该用户通过消息、群文件或收藏拥有有效引用，并支持 `Range`、`ETag`、内容长度和安全文件名。
+- 客户端使用 `GET /v0/file/s/{file_id}`，Header 传 API Key 与 `X-MeetingIM-Auth: token <base64_token>`；禁止 `?auth=&secret=`。URL 可带扩展名，服务端自动剥离。
+- 服务端按文件 ACL 放行：上传者本人、文件所属 `p2p`/`grp` 会话成员、消息级引用可见者（未撤回未删除且未被执行删除）、群成员、好友关系、收藏引用、用户头像/资料文件（对任何登录用户放行，2026-10-14 更新）；非授权返回 `403 permission denied`（`FILE_FORBIDDEN`）。对象存储模式下鉴权通过返回 302 短期签名 URL。
+- 头像排障口径：群成员/资料接口返回的 `avatar_url` 可直接下载；若对端头像显示占位图且下载 `404`，说明该头像文件从未被引用或已被回收，让对方重新上传并设置头像即可；`403` 为非登录态（Token 失效），重新登录。
+- 前提：发送方上传附件时带了 `topic`（见 0.5.5.1）。若对端下载一直 404，说明该文件从未关联会话/消息且已被 1 小时回收任务删除，应让发送方重新上传并携带 `topic`。
 - 下载前客户端校验本地空间和网络策略；`FILE_FORBIDDEN` 不自动重试，`FILE_UNAVAILABLE` 显示失效。
 
 ### 7.10 文件-下载中.png
@@ -2931,8 +2971,8 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：MeetingIM `me` 资料更新已有基础；目标产品接口需改造。**
 
-- 查询 `GET /v1/im/me/profile` 返回 `username,avatar_file_id,nickname,birth_date,signature,gender,region,email,public_account,phone_mask,version,field_rules`；`username` 为只读登录账号；`phone_mask` 为只读脱敏手机号（例如 `136****3333`），未绑定手机号时返回空字符串；`email` 当前仅为资料字段，不用于登录或找回密码。
-- 更新统一使用 `PATCH /v1/im/me/profile`，仅提交变更字段并带 `version`；服务端更新后同步 MeetingIM `me.public` 并推送资料事件。
+- 查询 `GET /v1/im/me/profile` 返回 `username,avatar_file_id,avatar_url,nickname,birth_date,signature,gender,region,email,public_account,phone_mask,version,field_rules`（`avatar_url` 统一回填规则见 0.5.5.1 第 4 条）；`username` 为只读登录账号；`phone_mask` 为只读脱敏手机号（例如 `136****3333`），未绑定手机号时返回空字符串；`email` 当前仅为资料字段，不用于登录或找回密码。
+- 更新统一使用 `PATCH /v1/im/me/profile`，仅提交变更字段并带 `version`（乐观锁必填，`version` 取自最近一次 `GET /v1/im/me/profile` 的返回值）；缺失或 `<=0` 返回 `400/20000 MALFORMED_REQUEST`，与当前版本不一致返回 `409/20009 VERSION_CONFLICT`（重新 GET 取最新 `version` 后重试即可）；服务端更新后同步 MeetingIM `me.public` 并推送资料事件。
 - 头像、昵称、签名、性别、地区、公开账号等资料字段以 `im_user_profiles` 为业务真源；`im_users.public` 和 `im_subscriptions.public` 只作为服务端生成的展示投影/缓存，前端不得依赖它们作为可编辑源。
 - 头像先以 `purpose=user_avatar` 上传再 PATCH；任何字段的可见性由隐私策略裁剪。
 
@@ -2944,7 +2984,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - `PATCH /v1/im/me/profile`，Body `{"nickname":"新昵称","version":n}`。
 - 服务端校验 Unicode 长度、全空白、控制字符和敏感内容；返回更新后的 `nickname,version,updated_at`。
-- 成功刷新全局资料和联系人快照，但不得覆盖各群昵称。版本冲突先拉最新资料再由用户确认。
+- 成功刷新全局资料和联系人快照，但不得覆盖各群昵称。版本冲突（`409/20009`）先拉最新资料再由用户确认。
 
 ### 10.4 出生日期.png
 
@@ -3137,8 +3177,8 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | 接口 | 输入示例 | 成功 `data` 示例 |
 | --- | --- | --- |
 | `GET /v1/im/me` | Query only | `{"user_id":"usr...","profile":{"public_account":"usr...","nickname":"张三","avatar_file_id":"","signature":"","version":1},"profile_version":1,"realname":{"status":"unverified"},"youth_mode":{"enabled":false}}` |
-| `GET /v1/im/me/profile` | Query only | `{"username":"zhangsan7","avatar_file_id":"","nickname":"张三","birth_date":"1990-01-01","signature":"签名","gender":"male","region":"上海","email":"a@example.com","public_account":"usr...","phone_mask":"136****3333","version":1,"field_rules":{"nickname":{"min_length":1,"max_length":32},"signature":{"max_length":120}}}` |
-| `PATCH /v1/im/me/profile` | `{"nickname":"新昵称","signature":"新签名","version":1}` | `{"avatar_file_id":"","nickname":"新昵称","signature":"新签名","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
+| `GET /v1/im/me/profile` | Query only | `{"username":"zhangsan7","avatar_file_id":"file_avatar","avatar_url":"/v0/file/s/file_avatar","nickname":"张三","birth_date":"1990-01-01","signature":"签名","gender":"male","region":"上海","email":"a@example.com","public_account":"usr...","phone_mask":"136****3333","version":1,"field_rules":{"nickname":{"min_length":1,"max_length":32},"signature":{"max_length":120}}}` |
+| `PATCH /v1/im/me/profile` | `{"nickname":"新昵称","signature":"新签名","version":1}` | `{"avatar_file_id":"file_avatar","avatar_url":"/v0/file/s/file_avatar","nickname":"新昵称","signature":"新签名","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `GET /v1/im/me/privacy` | Query only | `{"add_me_methods":{"account":true,"phone":true,"qr":true,"group":true},"profile_visibility":"friends","last_seen_visibility":"friends","read_receipts":true,"friend_request_verification":true,"group_invite_verification":false,"version":1,"editable":{"add_me_methods":true,"profile_visibility":true,"last_seen_visibility":true,"read_receipts":true,"friend_request_verification":true,"group_invite_verification":true}}` |
 | `PATCH /v1/im/me/privacy` | `{"add_me_methods":{"phone":false},"read_receipts":false,"friend_request_verification":false,"group_invite_verification":true,"version":1}` | `{"add_me_methods":{"account":true,"phone":false,"qr":true,"group":true},"read_receipts":false,"friend_request_verification":false,"group_invite_verification":true,"version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `GET /v1/im/settings/youth-mode` | Query only | `{"enabled":false,"policy_version":1,"restrictions":["night_quiet","content_filter","payment_guard"],"restriction_items":[{"code":"night_quiet","title":"深夜免打扰","description":"夜间减少消息提醒打扰，帮助用户保持健康作息。","enforced":true},{"code":"content_filter","title":"内容过滤","description":"对不适合青少年的内容进行识别和限制展示。","enforced":true},{"code":"payment_guard","title":"支付守护","description":"限制或确认支付、充值等敏感消费行为。","enforced":false}],"password_set":false,"can_enable":false,"updated_at":"2026-08-20T09:00:00Z"}` |
@@ -3153,9 +3193,29 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/security/challenges/{id}/verify` 关闭青少年模式 | `{"code":"123456"}` | `{"action_token":"close_token","action":"close_youth_mode","expires_at":"2026-08-20T09:05:00Z"}` |
 | `GET /v1/im/security/realname` | Query only | `{"status":"unverified","can_submit":true}` |
 | `POST /v1/im/security/realname/submissions` | `{"name":"张三","id_type":"cn_id","id_number":"110101199001011234"}` | `{"submission_id":"rn_1","status":"pending","can_submit":false}` |
-| `POST /v1/im/security/realname/appeals` 待实现 | `{"reason":"证件变更","description":"需要更正实名信息","action_token":"action_token"}` | `{"appeal_id":"rna_1","status":"pending","submitted_at":"2026-08-20T09:00:00Z"}` |
+| `POST /v1/im/security/realname/appeals` | `{"reason":"证件变更需要更正实名信息","attachments":["file_1"]}` | `{"appeal_id":"rna_1","reason":"...","attachments":["file_1"],"status":"pending"}`；当前无需二次身份验证（如后续启用，将复用 1.7 的 action_token 机制并在此处更新） |
 | `PUT /v1/im/devices/{device_id}/push-token` | `{"provider":"jpush","token":"registration_id","platform":"android","app_version":"1.0.0","push_env":"test","sdk_version":"5.0.0","notification_permission":"granted"}` | `{"device_id":"device_1","provider":"jpush","platform":"android","app_version":"1.0.0","updated_at":"2026-08-20T09:00:00Z"}` |
 | `DELETE /v1/im/security/sessions/{session_id}` 待实现 | Header `X-Action-Token: action_token` | `{"session_id":"sess_1","revoked":true}` |
+| `POST /v1/im/me/password` | `{"old_password":"OldPass123","new_password":"NewPass123"}` | `{"status":"ok"}`；旧密码错误返回 HTTP `401`：`{"code":30001,"reason":"AUTH_REQUIRED","message":"invalid credentials"}`；新密码不满足策略返回 HTTP `400`：`{"code":30040,"reason":"PASSWORD_POLICY_VIOLATION"}` |
+| `POST /v1/im/security/challenges` 注销账号发码 | Header `Idempotency-Key`；Body `{"scene":"delete_account","channel":"sms"}` | `{"challenge_id":"sec_chg_9","phone_mask":"+861****000","expires_in_seconds":300,"resend_after_seconds":60}` |
+| `POST /v1/im/security/challenges/{id}/verify` 注销账号验证 | `{"code":"123456"}` | `{"action_token":"del_token","action":"delete_account","expires_at":"2026-08-20T09:05:00Z"}` |
+| `POST /v1/im/me/deletion` | Header `X-Action-Token: del_token`；Body `{}` | `{"status":"ok"}` |
+
+#### 10.22.2 账号安全：修改密码与注销账号
+
+**修改密码 `POST /v1/im/me/password`（已实现）：**
+
+- 已登录（Bearer）用户提交 `old_password`、`new_password`；两者必填，缺一返回 `400 MALFORMED_REQUEST`。
+- 服务端先用旧密码走 `basic` 认证校验，失败返回 HTTP `401`：`{"code":30001,"reason":"AUTH_REQUIRED","message":"invalid credentials"}`，不泄露账号状态。
+- 新密码不满足密码策略返回 HTTP `400`：`{"code":30040,"reason":"PASSWORD_POLICY_VIOLATION"}`。
+- 成功后服务端递增 `auth_version` 并撤销该用户全部在线 Session（广播 `password_changed`）；包括当前请求在内的所有旧 Token 全部失效，客户端收到成功响应后必须清理本租户凭证并跳转登录页。
+
+**注销账号 `POST /v1/im/me/deletion`（已实现）：**
+
+- 两步挑战复用 1.7 敏感操作基建：`POST /v1/im/security/challenges`（Body `{"scene":"delete_account","channel":"sms"}`，发码到账号绑定手机号）→ `POST /v1/im/security/challenges/{id}/verify`（返回一次性 `action_token`）→ `POST /v1/im/me/deletion`（Header `X-Action-Token` 携带）。
+- 服务端配置 `permanent_accounts=true` 时拒绝注销：HTTP `403` `{"code":30040,"reason":"FORBIDDEN","message":"account deletion is disabled"}`。
+- 执行成功为**软删除**：撤销全部认证记录（含登录密码）、踢出所有在线 Session（`reason=user_deleted`）、退出并停用其拥有的群与 P2P 会话、向关注该用户的好友下发 `gone` 在线状态；账号不再可登录。客户端收到成功响应后清理本地数据并返回企业入口。
+- 挑战阶段限流与错误码同 1.7（`VERIFICATION_RATE_LIMITED`、`CHALLENGE_EXPIRED`、`CODE_INVALID`、`TOO_MANY_ATTEMPTS`）；action token 缺失/无效返回 HTTP `403` `{"code":30042,"reason":"ACTION_TOKEN_INVALID"}`。
 
 ## 11. 反诈安全、举报与意见反馈
 

docs/IM-监控运维对接文档.md

@@ -123,7 +123,7 @@ HEALTHCHECK --interval=1m --timeout=3s --start-period=20s \
 | 探针 | 路径 | 初始延迟 | 周期 | 超时 | 失败次数 |
 |---|---|---:|---:|---:|---:|
 | im-server readinessProbe | `/healthz` | 15s | 10s | 3s | 3 |
-| im-server livenessProbe | `/healthz` | 30s | 30s | 3s | 3 |
+| im-server livenessProbe | `/livez` | 15s | 20s | 3s | 3 |
 | im-manager readinessProbe | `/healthz` | 15s | 10s | 3s | 3 |
 | im-manager livenessProbe | `/healthz` | 30s | 30s | 3s | 3 |
 

docs/problems/IM-R11-Traefik入口故障运维排查手册-20261004.md

@@ -0,0 +1,226 @@
+# IM R11 Traefik 入口故障运维排查手册
+
+## 1. 目标与已知事实
+
+需要定位 2026-10-04 北京时间 `10:39:30–10:42:30`，即 UTC `02:39:30–02:42:30` 的入口整体中断。
+
+已知现象：
+
+- `api.118im.com/metrics` 先后出现超时、HTTP 521 和 HTTP 503。
+- 三个源 IP 的 443 在约 10:40:16 同时 `connection refused`。
+- 2000 个 WebSocket 几乎同时断开，A/B 两台压测机均受影响。
+- Tinode cluster 采样仍为 2/2 live peers。
+- 故障后三个源 IP 返回同一张 `TRAEFIK DEFAULT CERT`，证书 `notBefore` 为 `2026-10-04 10:41:32 +08:00`，与入口恢复窗口重合。
+- 运维已确认 `216.236.31.189:6443` 按安全策略不对公网开放，只允许集群网络访问；外部调试机 TCP 超时属于预期行为。
+
+排查过程中不要先重启 Traefik、节点或 k3s，也不要清理容器和日志。先完成只读取证。
+
+## 2. 运维进入方式
+
+优先在控制面节点直接执行 `kubectl`。如果控制面节点没有配置 kubeconfig，k3s 通常可使用：
+
+```bash
+sudo k3s kubectl get nodes -o wide
+```
+
+普通 Kubernetes 可使用：
+
+```bash
+kubectl get nodes -o wide
+kubectl cluster-info
+```
+
+不建议把 6443 直接向公网完全开放。长期方案应采用 VPN/堡垒机或仅允许固定运维出口 IP。短期也可以让运维直接在控制面节点采集下面的结果。
+
+## 3. 第一优先级：确认 Traefik 是否重启
+
+先找到 Traefik 所在 namespace、工作负载和 Pod：
+
+```bash
+kubectl get deploy,ds,sts,pod -A -o wide | grep -i traefik
+kubectl get pods -A -l app.kubernetes.io/name=traefik -o wide
+kubectl get pods -A -l app=traefik -o wide
+```
+
+对每个 Traefik Pod 执行：
+
+```bash
+kubectl -n kube-system get pod TRAEFIK_POD -o jsonpath='{.metadata.name}{"\nstarted="}{.status.startTime}{"\nrestarts="}{.status.containerStatuses[*].restartCount}{"\nlastReason="}{.status.containerStatuses[*].lastState.terminated.reason}{"\nlastExit="}{.status.containerStatuses[*].lastState.terminated.exitCode}{"\nlastFinished="}{.status.containerStatuses[*].lastState.terminated.finishedAt}{"\n"}'
+
+kubectl -n kube-system describe pod TRAEFIK_POD
+kubectl -n kube-system logs TRAEFIK_POD --all-containers --timestamps --since-time=2026-10-04T02:39:30Z
+kubectl -n kube-system logs TRAEFIK_POD --all-containers --previous --timestamps --since-time=2026-10-04T02:39:30Z
+```
+
+重点检查：
+
+- `OOMKilled`、exit code 137、liveness/readiness failure。
+- `Killing`、`Evicted`、`NodeNotReady`、`Preempted`。
+- `Configuration loaded`、provider reconnect、TLS store/default certificate 重建。
+- 10:41:32 附近是否有容器启动日志。
+
+如果 Traefik 不在 `kube-system`，将命令中的 namespace 替换为实际值。
+
+## 4. 第二优先级：查滚动发布和配置变更
+
+```bash
+kubectl -n kube-system get deploy,ds,rs -l app.kubernetes.io/name=traefik -o wide
+kubectl -n kube-system rollout history deploy/traefik
+kubectl -n kube-system get deploy traefik -o yaml
+kubectl -n kube-system get cm,secret | grep -i traefik
+```
+
+若由 Helm 管理：
+
+```bash
+helm list -A | grep -i traefik
+helm history traefik -n kube-system
+helm get values traefik -n kube-system -a
+```
+
+若由 ArgoCD 管理：
+
+```bash
+kubectl get applications.argoproj.io -A
+kubectl get applications.argoproj.io -A -o yaml | grep -n -i -C 5 traefik
+kubectl get pods -n argocd -o wide
+kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller --all-containers --timestamps --since-time=2026-10-04T02:39:30Z
+```
+
+同时检查 CI/CD 平台在北京时间 10:39–10:42 是否执行过 Traefik、Ingress、Service、证书或节点部署。需要记录操作者、commit、同步 revision 和开始/结束时间。
+
+## 5. 第三优先级：节点是否重启或资源耗尽
+
+```bash
+kubectl get nodes -o wide
+kubectl describe nodes
+kubectl get events -A --sort-by=.metadata.creationTimestamp
+kubectl get events -A --field-selector type=Warning --sort-by=.metadata.creationTimestamp
+```
+
+在承载 Traefik 的节点执行：
+
+```bash
+uptime -s
+last -x | head -30
+sudo journalctl --list-boots
+sudo journalctl --since '2026-10-04 10:39:30' --until '2026-10-04 10:42:30' -u k3s -u k3s-agent -u kubelet -u containerd --no-pager
+sudo journalctl -k --since '2026-10-04 10:39:30' --until '2026-10-04 10:42:30' --no-pager
+sudo dmesg -T | grep -Ei 'oom|killed process|memory cgroup|conntrack|nf_conntrack|link.*down|reset|I/O error'
+```
+
+重点判断：
+
+- 节点是否在 10:41 左右重启。
+- 内核是否 OOM kill Traefik、containerd 或 k3s。
+- 磁盘是否满、只读或发生 I/O error。
+- 网卡是否 link down、驱动 reset。
+- kubelet 是否因 liveness probe 杀掉 Traefik。
+
+## 6. 第四优先级：Service 与 Endpoint 是否短暂清空
+
+```bash
+kubectl get svc,endpoints,endpointslices -A | grep -Ei 'traefik|im-server'
+kubectl -n kube-system describe svc traefik
+kubectl -n kube-system get endpoints traefik -o yaml
+kubectl -n kube-system get endpointslices -l kubernetes.io/service-name=traefik -o yaml
+
+kubectl -n im-server-system get pod,svc,endpoints,endpointslices -o wide
+kubectl -n im-server-system describe svc im-server
+kubectl -n im-server-system get endpoints im-server -o yaml
+kubectl -n im-server-system get endpointslices -l kubernetes.io/service-name=im-server -o yaml
+```
+
+检查 10:40–10:41 是否发生：
+
+- Traefik Service 没有可用 endpoint。
+- `im-server` 三个 Pod 同时 NotReady，导致上游 503。
+- selector、port、targetPort 或 Ingress backend 被 ArgoCD/Helm 临时改写。
+- StatefulSet 滚动时 readiness 配置错误，所有 endpoint 被同时摘除。
+
+## 7. 第五优先级：连接数和 conntrack
+
+在入口节点执行：
+
+```bash
+sudo ss -lntp | grep -E ':443|:6443'
+sudo ss -s
+sudo sysctl net.netfilter.nf_conntrack_count net.netfilter.nf_conntrack_max
+sudo conntrack -S 2>/dev/null || true
+sudo nstat -az | grep -Ei 'ListenDrops|ListenOverflows|RetransSegs|InErrors|OutDiscards'
+sudo ip -s link
+```
+
+如果有节点监控，导出 10:35–10:45 的：
+
+- CPU usage、load、CPU throttling。
+- 内存、OOM、working set。
+- conntrack 使用率。
+- TCP listen overflow、reset、retransmit。
+- 网卡吞吐、drop、error。
+- Traefik active connection、open connection、5xx、upstream duration。
+
+conntrack 达到 `nf_conntrack_max` 通常更偏向 timeout/drop；本轮观察到短时间 `connection refused`，因此还应优先确认 443 监听进程是否消失或入口规则是否被重建。
+
+## 8. im-server 同期状态
+
+```bash
+kubectl -n im-server-system get pods -o wide
+kubectl -n im-server-system get sts im-server -o yaml
+kubectl -n im-server-system describe sts im-server
+
+for pod in $(kubectl -n im-server-system get pods -l app=im-server -o name); do
+  kubectl -n im-server-system logs "$pod" --all-containers --timestamps --since-time=2026-10-04T02:39:30Z > "${pod##*/}.log"
+  kubectl -n im-server-system logs "$pod" --all-containers --previous --timestamps --since-time=2026-10-04T02:39:30Z > "${pod##*/}.previous.log" 2>&1 || true
+done
+```
+
+如果 `app=im-server` 标签不匹配，先执行 `kubectl -n im-server-system get pods --show-labels`，再替换 selector。
+
+需要确认三个 im-server Pod 的：
+
+- `startTime` 和 `restartCount`。
+- readiness/liveness failure。
+- 10:40 左右是否仍持续处理 Kafka、cluster RPC 和 WS。
+- 是否有 `too many open files`、OOM、accept error、DNS error、MySQL/Kafka timeout。
+
+## 9. Kubernetes API 访问方式
+
+从当前调试机访问三个源 IP 的 443 均正常。运维已确认 `216.236.31.189:6443` 只允许集群网络访问，因此外部连接超时符合既定安全策略，也与 VPN/TUN 无关。
+
+运维应检查控制面节点：
+
+```bash
+sudo ss -lntp | grep 6443
+sudo nft list ruleset | grep -n -C 3 6443
+sudo iptables -S | grep 6443
+sudo iptables -t nat -S | grep 6443
+```
+
+后续排查采用以下方式之一：
+
+1. 让排查命令直接在控制面节点运行并回传结果包。
+2. 如确需远程调试，为固定运维出口 IP 临时增加 6443 allowlist，完成后撤销。
+3. 通过堡垒机/VPN 进入控制面网络。
+
+不要为了调试把 6443 对 `0.0.0.0/0` 永久开放。
+
+## 10. 运维需要回传的结果
+
+至少回传以下内容：
+
+1. Traefik Pod YAML、describe、当前日志和 previous 日志。
+2. Traefik Deployment/DaemonSet、ReplicaSet 和 rollout history。
+3. 10:39:30–10:42:30 的 k3s/kubelet/containerd/kernel journal。
+4. 全集群 Warning Event、节点 describe。
+5. Traefik 和 im-server 的 Service、EndpointSlice、Ingress YAML。
+6. ArgoCD/Helm/CI 在故障窗口的发布历史。
+7. 入口节点 CPU、内存、conntrack、TCP overflow/retransmit 和网卡 drop。
+
+拿到这些材料后，按照以下优先级定责：
+
+1. Traefik 容器或节点在 10:41:32 重启。
+2. ArgoCD/Helm/CI 触发 Traefik 滚动或配置重建。
+3. Traefik/im-server endpoint 短暂清空。
+4. OOM、liveness、conntrack、监听队列或节点网络故障。
+5. 其他上游负载均衡或云网络事件。

docs/problems/IM-后端问题清单 (3).md

@@ -22,7 +22,6 @@ _2026-09-14 全面复核：本次对现有33条逐条重新核实（能实测的
 |---|---|---|
 | [问题25](#问题25) | `POST /messages/forward`、`/favorites/forward` | 带附言转发时 `head` 声明类型与 `content` 实际结构对不上 |
 | [问题27](#问题27) | `GET /reports/daily` | `status` 参数不做取值校验，传任何值都返回200+空列表 |
-| [问题30](#问题30) | `GET /system-notifications` | `summary`/`action`结构不一致，且会议响应事件被写成两条重复通知 |
 | [问题33](#问题33) | `GET /reports/daily` | `permissions` 四个字段恒为同一组硬编码值，与用户/参数无关 |
 | [问题35](#问题35) | `GET /users/{id}/profile` | 设了备注之后拿不到对方的原昵称（`GET /friends`一侧已修复） |
 | [新增3](#新增3) | `PATCH /conversations/{topic}/settings` | 单聊置顶没有批量查询接口，会话列表永远看不出置顶效果 |
@@ -32,7 +31,6 @@ _2026-09-14 全面复核：本次对现有33条逐条重新核实（能实测的
 | [新增25](#新增25) | 原生WS `{pub}` | link类型消息协议层可构造，但没有真实用户可从UI触达的发送路径 |
 | [新增30](#新增30) | `GET /settings/youth-mode` | 开启后不对任何功能做实际限制，`enforced` 恒为硬编码false（前端已移除此功能，仅保留记录完整性） |
 | [新增31](#新增31) | `POST /reports/abuse` | 不校验 `requires_description`，可对必填原因提交空描述 |
-| [新增32](#新增32) | `POST /system-notifications/{id}/read` | 对已读通知重复标记，响应回显请求值但真实存储值不变 |
 | [新增34](#新增34) | `POST /tenant-applications` | 统一社会信用代码无去重机制，可无限重复提交 |
 | [新增41](#新增41) | `POST /groups/{topic}/mutes` | 无角色层级保护，管理员可禁言群主、任何角色可自我禁言 |
 | [新增47](#新增47) | `POST /v0/file/u/` | 真实文件上传上限是32MB而非声明的100MB，且从未用于前端预校验 |
@@ -68,6 +66,8 @@ _2026-09-14 全面复核：本次对现有33条逐条重新核实（能实测的
 - **新增42**（群公告按id查询恒定返回最新公告）：**已修复**。代码确认现在正确解析路径里的`announcement_id`并调用`GetAnnouncement`按id查询，不再无视这个参数。
 - **新增43**（群文件登记接口无长度/存在性校验）：**已修复**。代码确认现在对`file_name`(255)/`mime_type`(128)做长度校验，对`file_size`做负数校验，且会调用`store.Files.Get`验证`file_id`真实存在。
 - **新增45**（收藏/搜索/宫格分页off-by-one永久丢失边界记录）：**已修复**。实测：24条真实收藏，用limit=10分3页拉取（10+10+4），合并后24条一条不少、无重复。
+- **问题30**（系统通知`summary`/`action`结构不一致 + 会议响应事件双写）：**已修复/已失效**（2026-10-09复核）。①会议响应双写随上游`0e2f4e7`（2026-09-17把整个workbench/会议模块从im_server移除）消失，现仅剩Kafka单路径写入且按固定event_id幂等upsert，不再适用；②`action`由读路径`normalizeSystemNotificationAction`统一归一为`{type,target_id,payload,...}`；③空`summary`读路径回退`title`；④机器码`summary`（`accepted`/`rejected`/`continue`/`cancel`）已在4处写入点改为人类可读文案（`serveIMFriendRequestAction`/`serveIMRiskChallengeConfirm`/`TenantFriendRequestAccept`/`TenantFriendRequestResolve`）。实测：A对B发好友申请、B拒绝后，A的通知列表返回`summary:"对方已婉拒你的好友申请"`、`action`为归一化结构。
+- **新增32**（系统通知重复已读，响应回显请求值但存储不变）：**已修复**（2026-10-09复核）。存储层`TenantSystemNotificationMarkRead`在`COALESCE`更新后回读真实行返回，handler用返回值构造响应（单测`TestServeIMSystemNotificationsListAndRead`覆盖）。实测：同一通知先以`read_at=T1`标记已读、再以`T2`重复标记，两次响应均返回持久化的`T1`，不再回显本次提交值。
 
 ## 本次复核确认仍是历史误判（从未是真正的后端bug，不应再作为后端问题提出）
 
@@ -163,21 +163,6 @@ _2026-09-14 全面复核：本次对现有33条逐条重新核实（能实测的
 
 ---
 
-<a id="问题30"></a>
-## 问题 30（P2）：系统通知的 `summary` 要么是空串、要么是机器码，`action` 的结构因来源而异，且会议响应事件会被写成两条重复通知
-
-**证据强度**：✅ 实测确认（三种summary情况+两条重复通知具体案例）+代码确认（重复通知根因）
-
-**现象**：`summary`有时空串、有时机器码（如`accepted`/`rejected`）、有时真实数据；`action`是自由结构，不同来源放的键完全不同；会议响应更新会被两条独立代码路径各写一条内容几乎相同、结构不同的重复通知。
-
-**根因（重复通知）**：`serveIMMeetingRespond`同时调用受开关`imReliableHTTPEventsEnabled`控制的`publishIMMeetingEvent`（生成`{meeting_id}`形态）和无条件执行的`publishIMWorkbenchAndAudit`（经Kafka产生`{module,resource_id}`形态），该开关对标准请求头调用恒为true。
-
-**接口**：`GET /v1/im/system-notifications`
-
-**前端现状**：`summary`能在已知事件码表里查到就替换成中文，查不到就原样显示；跳转按钮按action里出现的键分派；重复通知没有做任何去重（不能安全启发式判断"内容相同就是重复"）。
-
----
-
 <a id="问题33"></a>
 ## 问题 33（P2）：`permissions` 的四个字段在不同参数下恒为同一组值
 
@@ -285,19 +270,6 @@ _2026-09-14 全面复核：本次对现有33条逐条重新核实（能实测的
 
 ---
 
-<a id="新增32"></a>
-## 新增 32（P2）：系统通知已读接口对已有 `read_at` 的通知，响应会原样回显客户端提交的值，但真实存储值不变
-
-**证据强度**：✅ 实测确认+代码确认（2026-09-14重读源码确认未变）
-
-**现象**：对已有read_at的通知重复调用已读接口，响应200并原样回显本次提交的read_at（哪怕故意传明显不同值），但真实存储的read_at纹丝不动。
-
-**根因**：`TenantSystemNotificationMarkRead`执行`UPDATE...SET read_at=COALESCE(read_at,?)`，已非空时保留原值；`serveIMSystemNotificationRead`（`server/im_http.go:3576`）直接回显请求体局部变量`readAt`，从未回读真实值。
-
-**接口**：`POST /v1/im/system-notifications/{id}/read`
-
----
-
 <a id="新增34"></a>
 ## 新增 34（P2）：企业注册申请接口对同一个统一社会信用代码没有任何去重/防重复提交机制
 

docs/sql/IM-后台消息与登录审计SQL.sql

@@ -26,6 +26,7 @@ CREATE TABLE IF NOT EXISTS im_user_login_logs (
     created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
     PRIMARY KEY (id),
     INDEX idx_im_user_login_tenant_time (tenant_id, login_at DESC, id DESC),
+    INDEX idx_im_user_login_session_close (tenant_id, session_id, logout_at),
     INDEX idx_im_user_login_user_time (user_id, login_at DESC, id DESC),
     INDEX idx_im_user_login_ip_time (ip, login_at DESC, id DESC),
     INDEX idx_im_user_login_device_time (device_id(64), login_at DESC),

docs/sql/IM-文件上传原始文件名字段SQL.sql

@@ -0,0 +1,5 @@
+-- Persist client-provided upload filename for downstream business modules.
+-- Apply before deploying im_server changes which read/write im_fileuploads.original_name.
+
+ALTER TABLE im_fileuploads
+  ADD COLUMN original_name VARCHAR(255) NOT NULL DEFAULT '' AFTER location;

docs/sql/IM-文件消息链接表MsgId-BIGINT修复SQL.sql

@@ -0,0 +1,44 @@
+-- IM file-message link msgid Snowflake compatibility migration.
+-- Scope: the shared business database (for example meeting_im).
+-- Fixes: im_filemsglinks.msgid was INT (max 2147483647) while message ids are
+--        snowflake int64 values (~1.58e18), so every INSERT into the link table
+--        failed with MySQL error 1264 "Out of range value for column 'msgid'".
+--        Under Kafka persistence that failure retried forever and stalled the
+--        consumer partition, blocking persistence for every message queued
+--        behind it.
+-- Notes: im_filemsglinks is a global (non tenant-sharded) table, but in
+--        tenant-scoped-DB deployments every tenant database has its own copy —
+--        run this script once per database.
+--        Re-running is safe (MODIFY to the same shape is idempotent).
+--        NOT REVERSIBLE: converting back to INT would truncate snowflake ids.
+-- Review and back up before execution. This script does not replay dead letters.
+
+-- 1. Preflight: confirm the live column shape before touching anything.
+SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_TYPE, IS_NULLABLE
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = DATABASE()
+  AND TABLE_NAME = 'im_filemsglinks'
+  AND COLUMN_NAME = 'msgid';
+
+-- 2. Upgrade the column (keeps the nullable semantics of the original schema).
+ALTER TABLE `im_filemsglinks`
+  MODIFY COLUMN `msgid` BIGINT DEFAULT NULL;
+
+-- 3. Post-check: this query must return zero rows.
+SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_TYPE
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = DATABASE()
+  AND TABLE_NAME = 'im_filemsglinks'
+  AND COLUMN_NAME = 'msgid'
+  AND DATA_TYPE <> 'bigint';
+
+-- 4. Observe pending recovery work caused by the overflow (and, before the
+--    startup schema-contract check existed, by any other drift). Replay only
+--    after the post-check passes and the referenced files still exist.
+SELECT status, last_reason, COUNT(*) AS entry_count,
+       MIN(created_at) AS first_created_at, MAX(created_at) AS last_created_at
+FROM im_kafka_dead_letters
+WHERE last_error LIKE '%Out of range value for column %'
+   OR last_error LIKE '%file lifecycle enqueue failed: not found%'
+GROUP BY status, last_reason
+ORDER BY status, last_reason;

docs/test/IM-Web端全功能测试用例.md

@@ -0,0 +1,604 @@
+# MeetingIM Web 端全功能测试用例
+
+> 编制日期：2026-10-16；三域名实测方案补充：2026-10-17
+> 适用环境：MeetingIM Web 测试环境
+> 测试方式：以 Web 页面人工操作为主，浏览器 Network、WebSocket Frames、接口响应和数据库核验为辅
+> 依据：当前 `dev` 代码、`IM-前后端对接文档.md`、会议笔记/App 更新/青少年模式/第三方对接文档及现有问题清单
+
+## 1. 测试目标
+
+本文用于对 Web 端进行完整业务验收，覆盖：
+
+1. 登录、注册、企业入口和账号安全。
+2. WebSocket 建连、消息首页、单聊、群聊、消息状态和断线恢复。
+3. 好友、黑名单、群成员治理、群公告和群文件。
+4. 文件上传下载、收藏、转发、聊天记录搜索和媒体预览。
+5. 音视频通话、工作台、组织、会议、日报、月报和会议笔记。
+6. 个人资料、隐私、版本检查、举报、反馈和跨租户隔离。
+7. 页面四态：加载、空数据、正常数据、失败/重试。
+
+本文不把“接口返回 200”视为完成。每个用例至少同时检查页面结果、网络请求、刷新后的持久化结果；涉及双用户的场景还要检查接收方实时表现和离线补偿。
+
+## 2. 当前服务边界
+
+| 能力 | Web 请求入口 | 服务归属 |
+| --- | --- | --- |
+| 登录、聊天、好友、群、文件、通话、资料、安全 | `/v1/im/*`、`/v0/channels`、`/v0/file/*` | `im_server` |
+| 工作台、组织、考勤、会议、会议笔记、日报、月报、信箱 | `/v1/workbench/*` | `im_workbench` |
+| 用户条款、隐私政策 | `/legal/*` | `im_server` |
+| Web 页面 | `https://web1.118im.com`、`https://web2.118im.com`、`https://web3.118im.com` | 本轮三个独立登录域名 |
+| REST API | `https://api.118im.com` | API Gateway |
+| WebSocket | `wss://api.118im.com/v0/channels?apikey=...` | API Gateway -> `im_server` |
+
+工作台页面如果仍请求 `/v1/im/workbench`、`/v1/im/meetings` 等旧路径，应直接记录为前端路由缺陷。新路径必须是 `/v1/workbench/*`。
+
+### 2.1 验收判定优先级
+
+代码和文档可能处于不同迭代阶段，验收时按以下顺序判定：
+
+1. 当前测试环境实际行为和当前 `dev` 代码是实现事实。
+2. 专项文档（如工作台拆分、App 版本、会议笔记）优先于旧版综合文档。
+3. `IM-前后端对接文档.md` 是完整目标契约；其中标记“新增”、“需改造”、“待实现”的内容必须通过实测确认，不能仅根据文档判定通过。
+4. 历史问题清单只用于选取高风险回归场景，实测通过后应更新结论，不得将历史结论直接当作当前缺陷。
+
+### 2.2 参考文档
+
+- `docs/IM-前后端对接文档.md`
+- `docs/IM-工作台服务拆分迁移稳定方案.md`
+- `docs/IM-会议笔记前后端对接文档.md`
+- `docs/IM-App版本更新前后端对接文档.md`
+- `docs/third/IM-声网音视频通话完整调用流程.md`
+- `docs/third/IM-文件安全第三方接入记录.md`
+- `docs/problems/IM-后端问题清单 (3).md`
+
+## 3. 测试环境与账号准备
+
+### 3.1 三域名浏览器准备
+
+| 编号 | 准备项 | 要求 |
+| --- | --- | --- |
+| ENV-01 | 页面 A | `https://web1.118im.com/tenant`，从企业码 `system` 进入，注册并登录用户 A，负责发起操作 |
+| ENV-02 | 页面 B | `https://web2.118im.com/tenant`，从企业码 `system` 进入，注册并登录用户 B，负责接收、审批、回执 |
+| ENV-03 | 页面 C | `https://web3.118im.com/tenant`，从企业码 `system` 进入，注册并登录用户 C，负责群第三成员、离线恢复和旁观校验 |
+| ENV-04 | 开发者工具 | 保留 Network 日志，开启 Preserve log，显示 WS Frames |
+| ENV-05 | 网络模拟 | 准备 Offline、Slow 3G、断网 15 秒后恢复三种场景 |
+| ENV-06 | 缓存场景 | 对指定域名分别执行普通刷新、强制刷新、退出重登和清站点数据；不要一次清掉三个域名 |
+
+三个域名用于在同一浏览器中并行保留三个登录态；实测时分别核对 Cookie 的 Domain、LocalStorage、Token 和 WebSocket，不能仅凭域名不同就推定不会串号。三个页面都选 `system`，此举只实现**不同账号并行登录同一商户**。跨租户用例需另备真实可用的第二商户，并另行执行。
+
+**当前页面观察（2026-10-17）**：三个 `/tenant` 页均可输入企业码；`web1` 输入 `system` 可进入 `/login`，页面显示 `system merchant`。`/tenant` 的“企业注册”进入 `/enterprise-register`，其字段为统一社会信用代码、营业执照、企业邮箱和提交审核，属于**申请新企业**。当前 `/login` 可见控件中未出现“新用户注册”入口。开始执行第 3.4 节前，先完成 `FLOW-REG-01` 的入口检查；若入口仍缺失，记录 Web 前端阻塞，不要把企业申请当作用户 A/B/C 注册成功，也不要为了绕过页面手工插入账号后宣称注册用例通过。
+
+### 3.2 测试账号矩阵
+
+| 代号 | 租户 | 角色/关系 | 必备条件 |
+| --- | --- | --- | --- |
+| A | `system` | 新注册用户 | 在 `web1` 注册，作为发起方和群主；建议短信方式绑定手机号 |
+| B | `system` | 新注册用户 | 在 `web2` 注册，作为接收方；建议有效邀请码方式验证推荐关系 |
+| C | `system` | 新注册用户 | 在 `web3` 注册，作为第三方、离线方；与 A/B 使用不同手机号 |
+| O | `system` | 群主 | 优先由 A 创建群 G1 后承担，无需额外账号 |
+| M | `system` | 群管理员 | 由 A 将 B 提升为管理员 |
+| N | `system` | 普通群成员 | 由 C 承担 |
+| X | 另一个真实商户 | 跨租户用户 | 仅执行第 17 章时准备；不得把 `web3` 当成另一个商户 |
+| P | `system` | 无手机号用户 | 仅当页面和服务端支持时注册；用于忘记密码负向测试 |
+| R | `system` | 管理范围用户 | 如 A/B/C 均无组织管理权限，另备管理账号 |
+
+注册前选定未使用的用户名/手机号，并准备 `system` 商户有效的邀请码；不要复用已有测试用户作为“新注册成功”的证据。注册完成后记录每个账号的 `username`、`public_account`、`usr...` 用户 ID、群 Topic 和初始资料版本。不要在本文或缺陷单中记录密码、完整 Token、验证码票据和 OSS 签名参数。
+
+### 3.3 测试数据
+
+| 数据 | 要求 |
+| --- | --- |
+| 群 G1 | A/O 为群主，B/M 为管理员，C/N 为普通成员，开启群公告和群文件 |
+| 群 G2 | A 不在群内，用于越权测试 |
+| 文件 F1 | 小于 1 MB 的 PNG |
+| 文件 F2 | 2～5 MB 的 PDF |
+| 文件 F3 | 10 MB 左右的视频 |
+| 文件 F4 | 大于前端允许上限的文件 |
+| 消息数据 | 文本、链接、图片、视频、语音、文件、名片、回复、已撤回消息各至少一条 |
+| 工作台数据 | 部门、成员、会议、日报、月报、会议笔记各至少一条 |
+
+### 3.4 从注册开始的三页面执行剧本
+
+按下表顺序执行，记录每一步是否能通过**可见 Web 页面**完成。注册成功才进入好友、单聊和群聊；入口不可达时，后续依赖新账号的用例标记“阻塞”，可另用预置账号单独继续其他功能验收，但不覆盖注册结果。`system` 商户已存在，用户注册应提交 `registration_type=0` 和 `tenant_code=system`；“企业注册”审核表单不是本节注册动作。
+
+| ID | 优先级 | 页面/操作 | 页面、Network/WS 与跨页预期 |
+| --- | --- | --- | --- |
+| FLOW-REG-01 | P0 | A 从 `web1/tenant` 输入 `system` 进入登录页，寻找“新用户注册”；B/C 同样检查 | 可从页面进入 **system 企业内用户注册**；若只有 `/enterprise-register`，记录实际页面截图和 URL，判“注册入口阻塞” |
+| FLOW-REG-02 | P0 | A 在注册页填独立的用户名、手机号、密码，选择短信验证码 | 显示 `system` 企业上下文；注册请求带 `registration_type=0`、`tenant_code=system`，不进入 `default` |
+| FLOW-REG-03 | P0 | A 点击获取验证码，输入测试环境当前有效验证码，完成校验并提交注册 | 创建 challenge，按接口倒计时；校验后一次性票据用于注册；成功返回 `usr...`、最终 username、Token，A 进入消息首页；测试码 `123456` 仅在该部署仍明确启用时使用 |
+| FLOW-REG-04 | P0 | B 在 `web2` 使用另一组用户名/手机号和有效 5 位邀请码注册 | 统一输入框识别邀请码，保存手机号和推荐关系；邀请码方式不冒充“手机号已短信验证”；B 进入独立登录态 |
+| FLOW-REG-05 | P0 | C 在 `web3` 使用第三组用户名/手机号注册 | C 与 A/B 均属于 `system` 且 ID 各异；三个域名同时在线，各自显示自己的资料和 WebSocket |
+| FLOW-REG-06 | P0 | 三页分别刷新，再单独退出并重新登录 B | A/C 仍保持各自会话；B 退出后只清 `web2` 登录态，重登到 B，不显示 A/C 的会话或缓存 |
+| FLOW-REG-06A | P0 | A/B/C 三个页面同时在线，分别查看个人资料和会话页 | 各页身份、Token 和 WS 登录用户分别对应 A/B/C；如果共享顶级域 Cookie 导致串号，记录为多开阻塞 |
+| FLOW-REG-07 | P0 | A 搜索 B 并申请好友，B 在 `web2` 接受，A 给 B 发消息 | B 实时出现申请/消息；A/B 会话、未读、回执、历史一致；C 无关页面不误收单聊 |
+| FLOW-REG-08 | P0 | A 创建 G1 并邀请 B/C，B/C 分别加入 | 三页成员数一致；A 发群消息 B/C 实时收到，B/C 回信 A 可见 |
+| FLOW-REG-09 | P0 | 将 C 页面断网，A/B 继续在 G1 发消息，C 恢复网络 | C 按群 Topic seq 补齐离线消息，顺序正确、无重复，未读数只计算 C 自己的状态 |
+| FLOW-REG-10 | P1 | A 把 B 设为管理员；B 修改公告或审批入群，C 查看 | B 的治理入口和服务端权限同步；C 仅见自己有权看的通知，三页刷新后状态一致 |
+| FLOW-REG-11 | P1 | A 给 B 发图片/PDF；B 下载，C 从群内访问群文件 | 上传走 OSS/文件服务；仅授权会话/群成员能下载；文件内容与原文件一致 |
+| FLOW-REG-12 | P1 | 三页依次完成资料修改、收藏、搜索、工作台检查 | 每次操作按第 7～16 章对应详细用例记录；A/B/C 的资料、未读和权限不能串号 |
+| FLOW-REG-13 | P1 | 同一 `system` 商户内用独立新账号再次输入 B 已用的用户名或手机号 | 分别提示用户名/手机号已占用，不覆盖 B，也不误判为跨租户冲突 |
+| FLOW-REG-14 | P1 | 依次输入 2 位用户名、大写或下划线用户名、无效邀请码、错误或过期验证码 | 页面给出可定位的校验错误；绕过前端提交仍由服务端拒绝；不创建用户 |
+| FLOW-REG-15 | P1 | A 注册完成后在 `web2` 用 A 登录，再从 `web2` 登出 | A 在 `web1` 的会话按产品多端规则保持或收到明确互踢提示；B/C 账号不能被顶替或清空 |
+
+注册失败分支还需覆盖：用户名重复或格式非法、手机号重复、密码不符合策略、验证码错误/过期/重放、无效/过期/撤销邀请码、频繁取码、`system` 商户停用或用户配额满。负向用例不得消耗 A/B/C 计划使用的有效用户名和手机号。
+
+## 4. 通用验收规则
+
+### 4.1 每条用例必须记录
+
+| 字段 | 内容 |
+| --- | --- |
+| 测试结果 | 通过 / 失败 / 阻塞 / 不适用 |
+| 测试账号 | 账号代号，不写密码 |
+| 时间 | 精确到秒，便于查询日志 |
+| Request ID | HTTP 响应或请求头中的 `X-Request-ID` |
+| Topic/Seq | 消息相关用例记录 Topic 和 Seq，按字符串保存 |
+| 截图 | 页面结果和必要的 Network/WS Frames |
+| 缺陷说明 | 实际结果、预期结果、复现率、是否刷新后仍存在 |
+
+### 4.2 通用网络检查
+
+所有 `/v1/im/*` 和 `/v1/workbench/*` 请求应满足：
+
+- 使用 HTTPS，不出现 Mixed Content。
+- 登录后携带 `Authorization: Bearer ...`，日志中必须打码。
+- 携带 `X-MeetingIM-APIKey`、`X-IM-Schema: 1`、`X-Request-ID`。
+- 写请求携带 `Idempotency-Key`；重试同一操作不得重复创建数据。
+- 成功响应包含 `code=0`、`request_id`、`server_time`。
+- 失败时前端按稳定 `reason` 展示本地化文案，不能直接展示服务端英文 `message`。
+- ID、Topic、Seq、cursor 在 JavaScript 中按字符串处理，不能发生精度丢失或科学计数法。
+
+### 4.3 WebSocket 检查
+
+- Upgrade 成功后第一条业务帧必须是 `hi`，且携带当前企业码。
+- `hi` 成功后才允许 `login`；登录成功后再订阅 `me`、`fnd` 和会话 Topic。
+- 页面不能建立无上限重复连接；刷新、重登、切换企业后旧连接应关闭。
+- 断线重连后按 Topic seq 增量补偿，不重复展示、不丢消息。
+- 同一消息重发使用相同 `client_mid`，服务端只能生成一条业务消息。
+
+## 5. P0 冒烟用例
+
+以下用例应在每次 Web 发版后优先执行。
+
+| ID | 场景 | Web 操作 | 预期结果 |
+| --- | --- | --- | --- |
+| SMK-01 | 打开企业入口 | 依次访问 `web1`、`web2`、`web3` 的 `/tenant` | 页面正常加载，无白屏、无限刷新和 404 静态资源 |
+| SMK-01A | 新用户注册入口 | 三页输入 `system` 后，从登录页打开新用户注册 | 进入 `system` 内用户注册页；若只有企业申请入口，记录 P0 阻塞 |
+| SMK-01B | 三账号注册 | A/B/C 各在指定域名完成注册 | 三个新账号均属于 `system`，各自进入消息首页且互不串号 |
+| SMK-02 | 企业登录 | 在 `web1` 输入 `system`、A 账号密码登录 | `hi` 绑定 `system`，登录成功进入消息页 |
+| SMK-03 | Token 恢复 | 刷新页面 | 使用 Token 恢复，不再次要求输入密码，旧 WS 被关闭 |
+| SMK-04 | 消息首页 | 进入消息页 | 会话列表、未读数、系统消息入口正常 |
+| SMK-05 | 单聊文本 | A 给 B 发消息 | A 获得 ACK/seq，B 实时收到且刷新后仍存在 |
+| SMK-06 | 单聊图片 | A 上传并发送 PNG | B 可查看原图，刷新后可再次打开 |
+| SMK-07 | 已读回执 | B 打开会话 | A 端已读状态更新且游标不回退 |
+| SMK-08 | 好友列表 | 打开通讯录 | 好友昵称、备注、头像、在线状态正常 |
+| SMK-09 | 群聊文本 | A 在 G1 发消息 | 在线成员实时收到，离线后重连可补偿 |
+| SMK-10 | 群成员 | 打开 G1 成员页 | 成员数量和列表一致，分页无重复/缺失 |
+| SMK-11 | 文件下载 | 发送并下载 PDF | 下载成功，文件大小和内容正确 |
+| SMK-12 | 个人资料 | 修改昵称后刷新 | 当前页、会话、好友/群成员投影最终一致 |
+| SMK-13 | 工作台 | 打开工作台 | 请求走 `/v1/workbench/*`，模块正常显示 |
+| SMK-14 | 登出 | 点击退出登录 | Token 被撤销，返回登录页，后续请求为 401 |
+| SMK-15 | 跨租户 | 用 `system` Token 请求另一个真实商户的数据 | 返回 403/404，不出现跨租户数据；需额外商户数据，不能用 `web3` 代替 |
+
+## 6. 登录、注册与账号安全
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-AUTH-01 | P0 | 企业码 `system` + 正确账号密码登录 | 登录成功；URL、日志、LocalStorage 不出现明文密码 |
+| WEB-AUTH-02 | P0 | 输入错误密码 | 页面显示“账号或密码错误”，保留账号、清空密码，不泄露账号是否存在 |
+| WEB-AUTH-03 | P0 | 输入不存在账号 | 与错误密码的状态码、页面文案一致 |
+| WEB-AUTH-04 | P0 | 输入不存在或停用企业码 | 显示企业不可用，不建立已登录 Session |
+| WEB-AUTH-05 | P0 | A 登录后切到另一个真实商户再刷新 | 不得携带 `system` Token 自动进入；应清租户缓存并重新登录 |
+| WEB-AUTH-06 | P0 | 登录成功后普通刷新、强刷、关闭再打开 | Token 恢复稳定，只保留一个有效 WebSocket |
+| WEB-AUTH-07 | P1 | 连续快速点击登录按钮 | 只提交一次或正确禁用按钮，不产生并发登录风暴 |
+| WEB-AUTH-08 | P1 | 模拟登录接口 Slow 3G | 展示加载态，可恢复，不允许重复提交 |
+| WEB-AUTH-09 | P1 | 在注册页打开用户条款和隐私政策 | 在页内弹窗加载 `/legal/*` 正文，无需登录；关闭后保留注册表单，不自动勾选协议 |
+| WEB-AUTH-10 | P0 | 从登录页进入 `system` 商户的新用户注册页 | 页面入口可见，注册按企业用户 `registration_type=0`、`tenant_code=system` 处理；不得进入 `/enterprise-register` 企业申请流程 |
+| WEB-AUTH-11 | P0 | 用户名注册，验证码框填写有效 5 位邀请码 | 注册成功，邀请码可重复使用，建立推荐关系 |
+| WEB-AUTH-12 | P0 | 手机号注册，使用测试验证码 | 验证成功后注册；倒计时以接口返回值为准 |
+| WEB-AUTH-13 | P1 | 验证码填写错误、过期、重复使用 | 分别显示明确状态，已消费票据不可重放 |
+| WEB-AUTH-14 | P1 | 倒计时内重复点击获取验证码 | 按 `retry_after_seconds` 禁用，不生成多个有效挑战 |
+| WEB-AUTH-15 | P0 | 有手机号账号执行忘记密码 | 发码、校验、重置成功；旧 Token 和旧密码失效 |
+| WEB-AUTH-16 | P1 | 无手机号账号 P 点击忘记密码 | 提示联系管理员，不进入短信流程 |
+| WEB-AUTH-17 | P0 | 登录后点击退出 | `/v1/im/auth/logout` 成功，缓存和 Token 清除，后退不能回主页面 |
+| WEB-AUTH-18 | P1 | 两个浏览器登录同一账号，一个修改密码 | 旧 Token 失效；另一端退出或下次请求进入登录页 |
+| WEB-AUTH-19 | P1 | 直接篡改 LocalStorage 中 Token | 返回认证失败，不出现重试死循环 |
+| WEB-AUTH-20 | P1 | 从 `/tenant` 单独进入企业申请页上传营业执照，或进入问题反馈页上传截图 | 上传进度和错误态正常，文件走 OSS/文件服务，不把 base64 正文塞进业务 JSON；企业申请成功不等于 `system` 用户注册成功 |
+
+## 7. 启动、导航、会话列表与系统通知
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-HOME-01 | P0 | 登录后进入首页 | bootstrap、WS 订阅和会话列表顺序正确，无重复初始化 |
+| WEB-HOME-02 | P0 | 检查总未读数和每会话未读数 | 数量一致；打开会话后对应未读归零，总数同步减少 |
+| WEB-HOME-03 | P1 | 完成三账号主流程后，A 再从 `web2` 登录同一账号，一端读消息 | 另一端未读状态最终同步，不出现负数；测试结束后 `web2` 重新登录 B |
+| WEB-HOME-04 | P1 | 置顶一个群聊 | 刷新后仍置顶；取消后恢复更新时间排序 |
+| WEB-HOME-05 | P1 | 置顶一个单聊 | 刷新后列表可识别置顶；若页面丢失置顶，记录批量设置读取缺口 |
+| WEB-HOME-06 | P1 | 设置会话免打扰 | 刷新后保持，来消息不改变设置 |
+| WEB-HOME-07 | P0 | 浏览器切换 Offline 15 秒，B 连续发 3 条消息，再恢复 | A 自动重连并补齐 3 条，顺序正确、无重复 |
+| WEB-HOME-08 | P1 | WS 重连期间切换会话 | 页面不白屏，不把消息写入错误会话 |
+| WEB-HOME-09 | P1 | 搜索会话名称和消息摘要 | 只显示当前租户可见会话，清空关键字恢复完整列表 |
+| WEB-HOME-10 | P1 | 打开系统消息页 | 好友、群、会议、安全等通知标题和摘要可读，不显示机器码 |
+| WEB-HOME-11 | P1 | 点击系统通知 | 跳转到正确对象；已删除对象显示合理空态 |
+| WEB-HOME-12 | P1 | 同一通知重复标记已读 | 已读时间保持第一次持久化值，不重复增加未读/已读计数 |
+| WEB-HOME-13 | P1 | 空账号首次登录 | 会话页显示空态和可用入口，不出现错误占位 |
+| WEB-HOME-14 | P0 | 把 API Key 改成无效值后打开页面 | WS Upgrade 403，页面提示环境配置问题并停止无限重连 |
+
+## 8. 单聊与消息状态
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-P2P-01 | P0 | A 从好友页点击“发消息” | 创建/取得唯一 P2P Topic，进入正确会话 |
+| WEB-P2P-02 | P0 | A 连续发送 10 条文本 | Seq 严格递增，B 顺序一致，刷新后历史一致 |
+| WEB-P2P-03 | P0 | 发送按钮双击或网络重试 | 相同 `client_mid` 只落一条消息 |
+| WEB-P2P-04 | P1 | 发送空白、超长文本 | 前端拦截；绕过前端后服务端仍校验 |
+| WEB-P2P-05 | P0 | B 在线接收 | B 无需刷新实时收到；会话摘要和未读更新 |
+| WEB-P2P-06 | P0 | B 离线，A 发消息，B 再登录 | B 按 seq 拉取补偿；Web 不依赖移动 Push 才能恢复消息 |
+| WEB-P2P-07 | P1 | B 收到后不打开/打开会话 | A 端送达、已读状态分别正确变化 |
+| WEB-P2P-08 | P1 | A 删除本地会话后重新搜索 B | 历史保留策略符合产品约定，不重复创建 Topic |
+| WEB-P2P-09 | P0 | A 拉黑 B，B 尝试发送 | 服务端拒绝；A 不收到；双方页面关系状态一致 |
+| WEB-P2P-10 | P0 | A 删除 B 好友，双方尝试发送 | 历史可查看，新增消息被拒绝并展示好友关系提示 |
+| WEB-P2P-11 | P1 | A 修改 B 的备注 | 好友列表、资料页、会话标题一致；原昵称仍可查看 |
+| WEB-P2P-12 | P1 | 向上翻页历史消息 | 使用 WS `get data before/limit`，无重复、无跳页 |
+| WEB-P2P-13 | P1 | 清除聊天记录 | 只影响当前用户可见历史，不误删对方数据；刷新后保持 |
+| WEB-P2P-14 | P1 | 直接在地址栏访问无权限 P2P Topic | 返回无权限/不存在，不泄露对方资料 |
+
+## 9. 消息类型与消息操作
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-MSG-01 | P0 | 发送 Unicode 表情和多行文本 | 编码正确，刷新后内容一致 |
+| WEB-MSG-02 | P1 | 发送网页链接 | 显示链接卡片或可点击链接；收藏“链接”分类可检索到 |
+| WEB-MSG-03 | P0 | 上传并发送图片 | 本地预览、上传中、成功、失败重试状态完整 |
+| WEB-MSG-04 | P0 | 上传并发送视频 | 封面、大小、时长字段正常，可播放/下载 |
+| WEB-MSG-05 | P1 | 浏览器授权麦克风后发送语音 | 授权拒绝有提示；授权后录制、取消、发送正常 |
+| WEB-MSG-06 | P0 | 发送 PDF/普通文件 | 文件名、大小、类型正确，收件人可下载 |
+| WEB-MSG-07 | P1 | 发送联系人名片 | 点击名片进入正确用户资料，不串租户 |
+| WEB-MSG-08 | P1 | 回复一条消息 | 引用摘要正确；原消息撤回后引用展示降级合理 |
+| WEB-MSG-09 | P1 | 群聊 @单个成员 | 被提醒人收到正确提示，其他成员无错误强提醒 |
+| WEB-MSG-10 | P1 | 群主/管理员使用 @所有人 | 权限允许；普通成员绕过 UI 调用应被拒绝 |
+| WEB-MSG-11 | P0 | 在允许时间内撤回自己的消息 | 双方实时变成“已撤回”，刷新后仍一致 |
+| WEB-MSG-12 | P1 | 超时撤回、撤回他人消息 | 服务端拒绝，原消息不变 |
+| WEB-MSG-13 | P1 | 编辑文本消息 | 内容和版本更新；另一端实时或通过 mutation 水位同步 |
+| WEB-MSG-14 | P1 | 多选删除“仅自己” | 当前用户隐藏，其他用户仍可见 |
+| WEB-MSG-15 | P1 | 逐条转发到单聊和群聊 | 每条消息结构、发送人和文件引用正确 |
+| WEB-MSG-16 | P1 | 合并转发多条混合消息 | 打开合并卡片能看到稳定快照，不依赖源会话权限 |
+| WEB-MSG-17 | P0 | 并发快速转发 12 次 | 页面成功/失败必须与实际落库一致，不得失败后实际已发送 |
+| WEB-MSG-18 | P1 | 带附言转发 | 附言和转发内容类型一致，接收端可正常渲染 |
+| WEB-MSG-19 | P1 | 批量撤回部分成功、部分失败 | 页面逐条展示结果，成功项撤回，失败项保留 |
+| WEB-MSG-20 | P1 | 页面刷新后同步消息变更 | mutation 水位连续，不重复应用撤回/编辑事件 |
+
+## 10. 通讯录、好友与黑名单
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-FRIEND-01 | P0 | 打开通讯录 | 分组、首字母、搜索、头像、备注正确 |
+| WEB-FRIEND-02 | P0 | 精确搜索 C 的用户名/公开账号 | 返回 C，ID 保持 `usr...`，可进入资料页 |
+| WEB-FRIEND-03 | P0 | 搜索跨租户 X | 不返回结果，不泄露用户存在性 |
+| WEB-FRIEND-04 | P1 | C 设置“仅好友可见”，A 查看 C 资料 | 非好友返回受限页/403；不能显示完整隐私资料 |
+| WEB-FRIEND-05 | P0 | A 向 C 发好友申请 | C 的新朋友入口实时或刷新后出现，未读数增加 |
+| WEB-FRIEND-06 | P1 | 重复发送同一好友申请 | 不创建重复申请，页面显示当前状态 |
+| WEB-FRIEND-07 | P0 | C 接受申请 | 双方好友列表出现，P2P Topic 可用，系统通知正确 |
+| WEB-FRIEND-08 | P1 | C 拒绝申请 | A 收到可读通知，双方不建立好友关系 |
+| WEB-FRIEND-09 | P1 | 接受/拒绝不存在或已处理申请 | 返回资源不存在/状态冲突，不出现 500 |
+| WEB-FRIEND-10 | P1 | A 修改好友备注后刷新资料页 | 备注保持，原昵称单独存在，不被备注覆盖丢失 |
+| WEB-FRIEND-11 | P0 | A 拉黑 B | 黑名单页出现；好友列表、会话上下文和资料页状态一致 |
+| WEB-FRIEND-12 | P0 | B 在被拉黑后发送/呼叫 A | 服务端拒绝，A 不收到消息或呼叫 |
+| WEB-FRIEND-13 | P1 | A 解除拉黑 | 黑名单移除，关系按业务规则恢复，不自动制造错误好友关系 |
+| WEB-FRIEND-14 | P1 | 批量移出黑名单 | 成功和失败项分别显示，刷新后保持 |
+| WEB-FRIEND-15 | P0 | A 删除 B 好友 | 双方关系解除，历史保留，发送权限关闭 |
+| WEB-FRIEND-16 | P1 | 生成个人二维码并解析 | 展示资料正确；过期、跨用途 Token 被拒绝 |
+
+## 11. 群聊、成员与治理
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-GRP-01 | P0 | A 创建群并选择 B/N | 创建成功，群主/成员/订阅一致，成员数准确 |
+| WEB-GRP-02 | P1 | 重复点击创建或重放幂等键 | 只创建一个群 |
+| WEB-GRP-03 | P0 | 打开群列表并按拥有/管理/加入筛选 | 分类和角色正确，分页无重漏 |
+| WEB-GRP-04 | P0 | 修改群名、头像、简介 | 所有在线成员实时或刷新后看到新资料 |
+| WEB-GRP-05 | P1 | 使用旧 version 并发修改群资料 | 一个成功，一个 `VERSION_CONFLICT`，页面可刷新恢复 |
+| WEB-GRP-06 | P0 | 拉取全部群成员 | 首屏和分页完整，成员总数与实际列表一致 |
+| WEB-GRP-07 | P1 | 点击单个成员资料 | 只请求单成员详情，不重复拉全量成员页 |
+| WEB-GRP-08 | P1 | 搜索成员、按管理员角色筛选 | 写操作后结果及时更新，不出现 90 秒旧缓存 |
+| WEB-GRP-09 | P0 | O 将 N 设为管理员 | 角色、权限按钮、成员列表和 WS 管理事件一致 |
+| WEB-GRP-10 | P0 | O 取消 M 管理员 | M 立即失去治理权限，绕过 UI 调用也被拒绝 |
+| WEB-GRP-11 | P0 | M 移除普通成员 N | N 离群，群成员数和会话状态同步 |
+| WEB-GRP-12 | P1 | M 尝试移除 O、自己或同级不允许对象 | 页面禁用；绕过 UI 仍被服务端拒绝 |
+| WEB-GRP-13 | P0 | O 禁言 N，N 发送消息 | 发送被拒绝，其他成员不收到 |
+| WEB-GRP-14 | P1 | M 尝试禁言群主或用户自我禁言 | 应被拒绝；若成功，记录角色层级缺陷 |
+| WEB-GRP-15 | P0 | 开启全员禁言 | 普通成员不可发送，群主/管理员按规则可发送 |
+| WEB-GRP-16 | P1 | O 设置允许/禁止成员邀请 | 普通成员邀请入口和服务端权限同步 |
+| WEB-GRP-17 | P0 | 直接邀请用户入群 | 无审批时直接加入；有审批时生成待处理申请 |
+| WEB-GRP-18 | P0 | 通过二维码申请入群 | Token 有效时进入正确群；过期/跨群 Token 拒绝 |
+| WEB-GRP-19 | P0 | 管理员同意/拒绝入群申请 | 申请状态、成员关系、系统消息和成员数一致 |
+| WEB-GRP-20 | P1 | 并发同意达到成员上限的两个申请 | 至多一个成功，成员数不超过上限 |
+| WEB-GRP-21 | P1 | 发布、编辑、删除群公告 | 成员实时看到；权限和版本控制正确 |
+| WEB-GRP-22 | P1 | 普通成员查看公告并标记已读 | 已读状态保持；已读人数/总人数可正确展示 |
+| WEB-GRP-23 | P1 | 修改本人群昵称 | 群成员页和新消息发送者名称更新，个人昵称不被改动 |
+| WEB-GRP-24 | P0 | O 转让群主给 M | 所有权、角色、权限原子切换；旧群主不能继续执行群主专属操作 |
+| WEB-GRP-25 | P1 | 普通成员退出群 | 会话和成员列表更新；群主不能直接退出而不转让/解散 |
+| WEB-GRP-26 | P0 | O 解散群 | 所有成员收到状态变化，后续访问返回 `GROUP_DISSOLVED`/410 |
+| WEB-GRP-27 | P1 | 非成员访问 G2 资料、成员、设置、文件 | 返回 403/404，不泄露群数据 |
+| WEB-GRP-28 | P0 | 群消息断网恢复 | 恢复后按群 Topic seq 补齐，顺序正确、无重复 |
+
+## 12. 文件、收藏与聊天记录搜索
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-FILE-01 | P0 | 上传 PNG/PDF/视频 | 进度、取消、失败重试、成功态完整，文件存入 OSS/文件服务 |
+| WEB-FILE-02 | P0 | 聊天附件上传时检查请求 | 必须带正确 Topic 和 purpose，不能只上传后裸引用 |
+| WEB-FILE-03 | P1 | 上传超限文件 F4 | 前端预检查并阻止；服务端也返回明确 `FILE_TOO_LARGE` |
+| WEB-FILE-04 | P1 | 上传不允许类型或伪造 MIME | 服务端校验，不因扩展名放行 |
+| WEB-FILE-05 | P0 | 接收者下载附件 | 鉴权成功；对象存储 302 可跟随；文件完整 |
+| WEB-FILE-06 | P0 | 非会话成员使用已知 file_id 下载 | 返回 `FILE_FORBIDDEN`/404，不泄露 OSS 地址 |
+| WEB-FILE-07 | P1 | 下载中断后 Range 续传 | 只下载剩余部分，ETag/大小一致 |
+| WEB-FILE-08 | P1 | Token 失效后重新登录继续下载 | 使用新 Token 恢复，不重复已完成分片 |
+| WEB-FILE-09 | P1 | 下载不存在、审核中、已拒绝文件 | 分别显示不可用/审核中/违规提示，不出现 500 |
+| WEB-FAV-01 | P0 | 收藏文本、图片、语音、文件、链接 | 各分类可查询，重复收藏不产生重复项 |
+| WEB-FAV-02 | P1 | 取消收藏 | 列表立即更新，刷新后保持 |
+| WEB-FAV-03 | P1 | 收藏列表分页超过 20 条 | 无边界记录丢失、重复和死循环 |
+| WEB-FAV-04 | P1 | 从收藏转发给好友/群 | 内容可用、权限正确，转发结果与实际落库一致 |
+| WEB-SEARCH-01 | P0 | 搜索明确存在的文本关键词 | 返回全部合法命中，点击后定位到上下文消息 |
+| WEB-SEARCH-02 | P1 | 按文件、链接、图片、视频筛选 | 类型正确，ID 保持 `usr...`/Topic 原格式 |
+| WEB-SEARCH-03 | P1 | 搜索已撤回、仅自己删除、无权限消息 | 按可见性过滤，不泄露内容 |
+| WEB-SEARCH-04 | P1 | 特殊字符、中文、大小写、空关键词 | 页面稳定，结果符合约定，不执行危险模糊查询 |
+
+## 13. 实时语音与视频通话
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-CALL-01 | P0 | A 向在线好友 B 发起语音通话 | B 实时收到邀请，双方显示同一 call_id |
+| WEB-CALL-02 | P0 | B 接听并挂断 | 状态按邀请、接通、结束变化；通话记录双方一致 |
+| WEB-CALL-03 | P1 | B 拒绝 | A 显示已拒绝，记录结束原因正确 |
+| WEB-CALL-04 | P1 | B 不接听直到超时 | 双方记录为未接/超时，不永久停留呼叫中 |
+| WEB-CALL-05 | P1 | A 主叫时取消 | B 邀请立即消失，状态一致 |
+| WEB-CALL-06 | P1 | 拒绝浏览器麦克风/摄像头权限 | 页面提示授权方法，不创建假通话中状态 |
+| WEB-CALL-07 | P1 | 通话中开关麦克风、摄像头、扬声器 | 本地状态和对端媒体表现符合预期 |
+| WEB-CALL-08 | P1 | 通话中刷新或断网恢复 | 通话按产品策略恢复或结束，不产生多条重复记录 |
+| WEB-CALL-09 | P0 | 被拉黑/非好友发起通话 | 服务端拒绝，被叫不收到邀请 |
+| WEB-CALL-10 | P1 | 查看通话记录 | `peer`、方向、开始/接通/结束时间、duration、topic 均可正确渲染 |
+| WEB-CALL-11 | P1 | 同账号多浏览器收到来电 | 接听一个后其他端及时结束响铃 |
+| WEB-CALL-12 | P1 | 检查声网 Token 获取 | 只在合法通话成员请求时返回，过期后不可继续加入 |
+
+## 14. 工作台与办公协同
+
+本章页面请求必须走 `/v1/workbench/*`。如果网关返回 404，先确认路径是否仍误用 `/v1/im/*`。
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-WB-01 | P0 | 打开工作台 | 模块、排序、权限、未读数正常，请求走新服务路径 |
+| WEB-WB-02 | P1 | 普通用户与管理用户分别打开 | 模块权限和入口不同，不只依赖前端隐藏 |
+| WEB-WB-03 | P1 | 刷新工作台 | Redis Token 鉴权通过，不随机 401，不要求二次登录 |
+| WEB-ORG-01 | P0 | 展开组织树 | 根部门、子部门、成员按租户返回，展开状态稳定 |
+| WEB-ORG-02 | P1 | 手机注册测试账号查看组织 | 按产品规则显示允许的组织范围 |
+| WEB-ORG-03 | P1 | 邀请进入账号查看组织 | 只显示本人或配置范围，不泄露全部组织 |
+| WEB-ORG-04 | P1 | 搜索部门/成员 | 只返回可见范围，跨租户同名成员不可见 |
+| WEB-ATT-01 | P1 | 打开考勤页并打卡 | 班次、位置、打卡状态和时间正确，重复打卡有明确结果 |
+| WEB-MTG-01 | P0 | 创建会议并选择真实参会人 | 会议创建、参与人、通知和未读数一致 |
+| WEB-MTG-02 | P1 | 添加不存在/跨租户 user_id | 服务端拒绝，不创建幽灵参会人 |
+| WEB-MTG-03 | P1 | 修改会议并使用旧 version 冲突 | 乐观锁生效，页面可刷新到最新版本 |
+| WEB-MTG-04 | P1 | 参会人接受/拒绝 | 发起人实时或刷新后看到状态，重复响应幂等 |
+| WEB-MTG-05 | P1 | 取消会议并提交错误 version | 应返回版本冲突，不得无条件取消 |
+| WEB-MTG-06 | P1 | 发送会议提醒 | 只提醒未响应/目标用户，不重复轰炸 |
+| WEB-NOTE-01 | P0 | 记录员上传会议笔记 PDF | 文件上传并登记，列表和详情出现文件 |
+| WEB-NOTE-02 | P1 | 普通参会人预览/下载 | 根据权限放行；非参会人拒绝 |
+| WEB-NOTE-03 | P1 | 替换、删除会议笔记 | version 校验正确，旧文件引用按策略处理 |
+| WEB-DAILY-01 | P0 | 创建日报草稿、编辑并提交 | 内容持久化，状态从 draft 到 submitted |
+| WEB-DAILY-02 | P1 | 提交空白日报 | 服务端拒绝，不允许仅靠前端必填校验 |
+| WEB-DAILY-03 | P1 | 输入非法日期、未来异常年份 | 返回校验错误，不创建数据 |
+| WEB-DAILY-04 | P1 | 管理者查看统计和未提交人员 | 权限、数量和列表一致，提醒可追踪 |
+| WEB-MONTH-01 | P0 | 创建月报、保存总结/计划并提交 | 必填项、状态、版本和详情正确 |
+| WEB-MONTH-02 | P1 | 月报分页和管理范围 | 无跨部门/跨租户越权，分页稳定 |
+| WEB-MAIL-01 | P1 | 查看总经理信箱说明并提交 | 必填、匿名、长度、附件数量按配置校验 |
+| WEB-MAIL-02 | P1 | 重复点击提交 | 幂等键防止重复工单 |
+
+## 15. 个人资料、设置与隐私
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-ME-01 | P0 | 打开个人资料 | username、昵称、脱敏手机号、头像、签名字段完整 |
+| WEB-ME-02 | P0 | 修改昵称和签名 | version 递增，刷新保持，好友/群投影最终同步 |
+| WEB-ME-03 | P1 | 两个浏览器并发编辑同一资料 | 一个成功，另一个版本冲突，不覆盖新值 |
+| WEB-ME-04 | P1 | 设置出生日期、性别、地区、邮箱 | 格式与长度校验符合 field_rules |
+| WEB-ME-05 | P0 | 上传头像 | 文件用途为用户头像，成功后所有主要页面可访问 |
+| WEB-ME-06 | P1 | 生成并展示个人二维码 | 二维码包含服务端 Token，不直接暴露内部用户 ID |
+| WEB-PRIV-01 | P0 | profile_visibility 在 everyone/friends/nobody 间切换 | C/A 分别查看时权限立即符合设置 |
+| WEB-PRIV-02 | P0 | 关闭按账号/手机号/二维码/群添加 | 对应搜索或添加入口和服务端结果一致 |
+| WEB-PRIV-03 | P1 | 关闭已读回执 | 对端不再获得已读状态，不能只在 UI 隐藏 |
+| WEB-PRIV-04 | P1 | 开启好友申请验证 | 新申请进入 pending；关闭后按产品规则直接建立/简化流程 |
+| WEB-PRIV-05 | P1 | 开启入群验证 | 邀请进入审批态，不能直接入群 |
+| WEB-SET-01 | P1 | 点击清空缓存 | 只清浏览器缓存，不删除服务端消息；重新加载可恢复 |
+| WEB-SET-02 | P0 | 修改登录密码 | 成功后旧 Token 失效，新密码可登录 |
+| WEB-SET-03 | P1 | 输入错误旧密码或弱密码 | 页面按 reason 提示，密码不变 |
+| WEB-SET-04 | P1 | 发起账号注销并完成验证 | Token 撤销、账号不可继续登录；重复提交幂等 |
+| WEB-VER-01 | P1 | Web 端检查版本 | `platform=web` 返回可用结果；推荐更新可关闭，强更不可绕过 |
+
+青少年模式已从当前 Web 产品入口移除，不作为 Web 发版阻塞项；如后续恢复入口，应单独执行 `IM-青少年模式前后端对接文档.md` 的完整流程。
+
+## 16. 举报、反馈与安全
+
+| ID | 优先级 | 场景与操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-SEC-01 | P1 | 发送疑似风险 URL | 页面按 allow/warn/block 展示，不能直接放行 block |
+| WEB-SEC-02 | P1 | 风险警告选择继续 | risk token 单次有效，重复使用被拒绝 |
+| WEB-SEC-03 | P1 | 风险警告选择取消 | 不发送原消息，不生成可继续使用的 token |
+| WEB-ABUSE-01 | P0 | 举报用户、群和消息 | 目标类型/ID正确，提交后有回执和 report_id |
+| WEB-ABUSE-02 | P1 | 选择 requires_description 的原因但留空 | 前端和服务端都拒绝 |
+| WEB-ABUSE-03 | P1 | 上传举报证据 | 仅合法 file_id 可绑定，超数量/无权限文件拒绝 |
+| WEB-ABUSE-04 | P1 | 重复点击举报提交 | 只生成一个举报工单 |
+| WEB-FB-01 | P0 | 打开意见反馈 | 分类、长度、附件策略和诊断说明来自服务端配置 |
+| WEB-FB-02 | P0 | 提交文本反馈 | 成功后显示受理结果并清空草稿 |
+| WEB-FB-03 | P1 | 带截图提交反馈 | 上传成功、文件审核状态和业务引用正确 |
+| WEB-FB-04 | P1 | 内容超长、附件超限、联系方式非法 | 页面定位到对应字段，服务端返回明确校验错误 |
+| WEB-FB-05 | P1 | 勾选/取消上传诊断信息 | 只有明确同意时才提交脱敏诊断，不上传 Token/密码 |
+
+## 17. 跨租户、安全与可靠性专项
+
+| ID | 优先级 | 操作 | 预期结果 |
+| --- | --- | --- | --- |
+| WEB-TENANT-01 | P0 | `system` 与另一个真实商户使用同名 username 分别登录 | 各自进入正确账号，Token 绑定各自租户；另备第二商户执行，三个 Web 域名不是三个商户 |
+| WEB-TENANT-02 | P0 | 把 `system` Token 放到第二商户请求头 | `TENANT_MISMATCH`/认证失败，不返回任何业务数据 |
+| WEB-TENANT-03 | P0 | 已知跨租户 user/topic/group/file ID 后直接访问 | 统一 403/404，不暴露对象存在性 |
+| WEB-TENANT-04 | P0 | 切换租户后查看会话、搜索、收藏、上传任务 | 不出现上一租户缓存数据 |
+| WEB-TENANT-05 | P1 | 同名群/系统 Topic 在两个租户同时活动 | 消息、未读、系统通知完全隔离 |
+| WEB-REL-01 | P0 | HTTP 写请求重复提交相同幂等键和相同 Body | 返回首次结果，不重复写 |
+| WEB-REL-02 | P0 | 相同幂等键改 Body 重放 | 返回 `IDEMPOTENCY_CONFLICT` |
+| WEB-REL-03 | P1 | 关键请求超时后刷新页面 | 先查询真实状态，不能直接重复创建 |
+| WEB-REL-04 | P0 | 同一 Token 并发发起 20 个只读请求 | 不应随机 401；出现时记录全部 request_id |
+| WEB-REL-05 | P1 | 服务端 429 | 页面按 `retry_after_seconds` 倒计时，不立即重试 |
+| WEB-REL-06 | P1 | 服务端 500/502/503 | 展示可重试错误，不清有效登录态，不无限重试 |
+| WEB-REL-07 | P1 | 浏览器后退/前进恢复页面 | 不重复写操作，不展示其他账号缓存 |
+| WEB-REL-08 | P1 | 登录页和业务页检查 Console | 无 Token、密码、完整手机号、身份证号和 OSS 签名泄漏 |
+
+## 18. 当前高风险专项回归
+
+以下项目来自历史问题清单。无论清单是否已过期，都应在 Web 验收中重新确认，以实际结果更新状态。
+
+| ID | 对应风险 | Web 验证方法 | 通过标准 |
+| --- | --- | --- | --- |
+| RISK-01 | 并发转发真假失败不一致 | 同一目标并发转发 12 次，对照页面、WS 和历史 | 成功数、响应数、落库数一致 |
+| RISK-02 | Bearer Token 并发随机 401 | 同 Token 并发加载首页各模块 | 无随机 401；失败有可追踪日志 |
+| RISK-03 | 文件下载 SQL/死锁错误 | 连续打开图片、头像、会议文件 50 次 | 无 500、死锁直返和错误列异常 |
+| RISK-04 | 好友拉黑状态不一致 | 拉黑后对照好友列表、资料页、会话上下文 | relationship/capabilities 一致 |
+| RISK-05 | 群成员计数双真源 | 对照群详情、设置、二维码、成员分页 | member_count 全部一致 |
+| RISK-06 | 群角色筛选缓存滞后 | 提升/撤销管理员后立即筛选 | 立即返回新角色，不读旧缓存 |
+| RISK-07 | 搜索召回不稳定 | 发送唯一关键词后循环搜索 10 次 | 每次命中，定位上下文一致 |
+| RISK-08 | 用户 ID/Topic 格式不一致 | 检查搜索、收藏、通话记录 | 均返回可寻址 ID，不裁剪 `usr` 或返回内部 hash |
+| RISK-09 | 群二维码字段不一致 | 创建二维码并立即解析 | 创建/解析的 group 字段契约一致 |
+| RISK-10 | 通话记录字段偏离文档 | 完成一轮呼叫后查看列表 | peer、incoming、时间和 duration 可直接渲染 |
+| RISK-11 | 群公告已读人数缺失 | 3 人查看公告后检查详情 | 已读/总人数准确，状态可刷新恢复 |
+| RISK-12 | 文件审核任务不消费 | 上传需审核图片并观察状态 | 在合理时间内进入 approved/rejected，不永久 pending |
+
+## 19. 浏览器兼容与体验
+
+| ID | 场景 | 预期结果 |
+| --- | --- | --- |
+| WEB-UX-01 | Chrome、Edge、Firefox 最新版登录和收发消息 | 核心流程一致 |
+| WEB-UX-02 | 1366x768、1920x1080、窄屏窗口 | 无按钮遮挡、文本溢出和不可滚动区域 |
+| WEB-UX-03 | 浏览器缩放 80%/100%/125%/150% | 布局可用，弹窗和菜单不超出视口 |
+| WEB-UX-04 | 中文、英文、长昵称、长群名 | 截断和换行合理，不覆盖相邻控件 |
+| WEB-UX-05 | 空列表、加载中、请求失败、权限拒绝 | 四态完整且文案准确 |
+| WEB-UX-06 | 键盘 Tab 导航、Enter 发送、Esc 关闭弹窗 | 行为一致，不误提交危险操作 |
+| WEB-UX-07 | 刷新时存在未发送草稿 | 草稿按产品策略恢复，不串会话 |
+| WEB-UX-08 | 页面运行 2 小时并持续收消息 | 内存、WS 数量和事件监听不持续增长 |
+
+## 20. 测试结果记录模板
+
+```markdown
+### [用例 ID] 用例名称
+
+- 结果：通过 / 失败 / 阻塞 / 不适用
+- 环境：测试环境 / 浏览器版本
+- 账号：A、B
+- 时间：YYYY-MM-DD HH:mm:ss
+- Request ID：
+- Topic / Seq：
+- 前置条件：
+- 操作步骤：
+  1. [填写操作一]
+  2. [填写操作二]
+- 预期结果：
+- 实际结果：
+- 刷新后结果：
+- 接收方结果：
+- Network / WS 证据：
+- 截图或录像：
+- 缺陷编号：
+```
+
+## 21. 发版通过门禁
+
+Web 版本满足以下条件才可判定通过：
+
+1. P0 冒烟用例全部通过。
+2. 所有 P0 业务用例通过，P1 无数据丢失、越权、安全或核心流程阻塞问题。
+3. 单聊、群聊各完成一次在线实时、离线补偿、断线重连和多端已读闭环。
+4. 文件上传、下载、无权限下载、Range 续传和 OSS 链路通过。
+5. 好友、拉黑、群治理均完成 UI 权限和服务端绕过校验。
+6. 工作台全部请求已切到 `/v1/workbench/*`，没有旧路径 404。
+7. 跨租户专项全部通过，浏览器缓存中不出现上一租户数据。
+8. 无未解释的 401、403、404、409、500、502、503；预期错误必须有正确 `reason`。
+9. Console 和请求日志不泄露密码、Token、身份证号、完整手机号或 OSS 临时签名。
+10. 所有失败用例均有 Request ID、复现步骤和页面/网络证据。
+
+## 22. 三域名实测记录（2026-10-17）
+
+本节记录本轮实际页面操作，不把准备状态当作注册成功。测试商户为 `system`，浏览器为 Codex 内置浏览器。测试账号密码、Token 不写入本文。
+
+| 用例 | 结果 | 实测记录 |
+| --- | --- | --- |
+| ENV-01～03、SMK-01 | 通过 | `web1`、`web2`、`web3` 的企业码页均能以 `system` 进入登录页，显示 `system merchant`。 |
+| FLOW-REG-01、SMK-01A、WEB-AUTH-10（入口） | 通过 | 首次复用的 `web2`、`web3` 登录页标签未显示注册链接；重新打开三个域名的登录页后，均可见“注册账号”，目标 URL 分别为各自域名的 `/register`。旧标签状态未作为当前版本缺陷。 |
+| FLOW-REG-02、04、05（表单准备） | 部分通过 | 三个域名的 `/register` 均显示 `system merchant`，可填写用户名、手机号、密码、确认密码；本轮先准备三个不同的仅用户名账号，未填写手机号，也未触发短信发送。 |
+| FLOW-REG-03～05、SMK-01B（注册过程） | 未见证 | 用户随后自行完成三个账号的注册并登录；本轮只核对登录结果，未观察协议勾选、注册请求和验证码/邀请码分支，不能据此判这些注册流程通过。 |
+| FLOW-REG-06A、SMK-04（身份/首页） | 通过 | 三域名同时登录 `qa261017a` (`usruLg9kkkulUg`)、`qa261017b` (`usrOTmpE042BPc`)、`qa261017c` (`usradhJQqzgP8U`)；各自资料页身份不同，初始会话空态正常。 |
+| FLOW-REG-07、WEB-FRIEND-02/05/07、SMK-08 | 通过，实时刷新待改进 | A 搜索用户名找到 B/C 的正确 `usr...` ID，发送申请；B/C 的“新朋友”各出现待处理申请并可通过。B 再申请 C，C 通过。三对关系均持久化。审批方列表立即更新；申请方原通讯录未立即出现新好友，刷新后才出现。 |
+| FLOW-REG-07、WEB-P2P-01/05/07、SMK-05/07 | 通过 | A/B 在同一 P2P Topic `p2puLg9kkkulUg5OakTTjYE9w` 双向发文本；双方在线实时收到，发送端出现“已送达/已读”。C 无关会话未显示 A-B 消息。 |
+| FLOW-REG-08、WEB-GRP-01/03/06、SMK-09/10 | 通过 | A 创建 `Web联调三人群-20261017`，Topic `grpW1fvFD1CU8w`；A/B/C 的群列表均显示 3 人，A 群成员页列出 A/B/C，群主为 A。三人各发一条群消息，另外两端实时收到，群消息顺序一致。 |
+| FLOW-REG-10、WEB-GRP-09、WEB-GRP-21/22 | 部分通过 | A 将 B 设为管理员，A/B/C 页面均显示 B 的管理员角色；B 可发布群公告，C 可阅读但无编辑入口。B 刷新后公告已读数为 2/3。未测撤销管理员、公告编辑/删除和入群审批。 |
+| FLOW-REG-09、WEB-GRP-28、WEB-HOME-07 | 部分通过 | C 页首次用网络模拟显示“无网络”，但旧 WS 仍接收三条消息，不能计作离线补偿。随后断网重载令 C 页真正离开应用；新 web3 标签重新登录 C 后，群会话显示 3 条未读，打开后按 1/3、2/3、3/3 顺序显示且无重复。**同一标签自动重连和 seq 增量补偿未验证**。后续原 web3 群聊标签也恢复可用，刷新后三端均保持登录。 |
+| FLOW-REG-11、SMK-06、WEB-FILE-01（小图） | 部分通过 | A 发送仓库公开测试 PNG `docs/ios-pill-128.png`（4,587 字节）；B/C 实时收到并可预览原图，A 看到 2 人已读。但图片正文以 `data:` 内联，不能作为 OSS 上传通过的证据。 |
+| FLOW-REG-11、WEB-FILE-01（大图/OSS） | **失败，P0 阻塞** | A 两次选择 `docs/note/文件-预览.png`（344,005 字节）发送到同一群，页面均提示 `Failed to fetch`，群内无大图消息。浏览器网络事件显示 `POST https://api.118im.com/v0/file/u/` 发起前，`OPTIONS` 预检返回 204，但响应无 `Access-Control-Allow-Origin`；POST 随后为 `net::ERR_FAILED`。预检 Origin 为 `https://web1.118im.com`，请求头含 `authorization,x-meetingim-apikey`。需修复上传入口 CORS 并覆盖 web1/web2/web3 三个 Origin，再重测大图/PDF、下载和 OSS。 |
+| WEB-GRP-15（普通成员） | 部分通过 | A 开启全员禁言后，C 收到群系统提示；C 页面仍允许输入并点发送，但服务端拒绝，消息显示“发送失败，点击重试”。刷新后该消息不在群历史。页面应在已知禁言状态下禁用发送并提示具体原因。 |
+| WEB-GRP-15（管理员豁免） | **失败，P0 权限缺陷** | 群设置明确写“仅群主和管理员可以发言”，B 已由 A 提升为管理员且各端均显示“管理员”。全员禁言期间 B 发送文本两次均失败；第二次 WS `pub` 到 `grpW1fvFD1CU8w` 后，服务端 `ctrl.code=403`、`ctrl.text=permission denied`。刷新后消息不在群历史。A 随后关闭全员禁言，设置恢复为 0。需核查群管理员身份与全员禁言的服务端权限判定。 |
+| WEB-SEARCH-01（群内关键词搜索） | 通过 | B 在群会话搜索唯一关键词 `离线补偿测试 2/3`，结果命中 B 原消息；点击后关闭搜索层并定位到群历史。 |
+| WEB-GRP-15（刷新复测） | **失败，P0 权限缺陷仍在** | A/B/C 三端刷新后，A 的群管理页显示“群管理员 1/10”，B 的成员角色和消息标签均为“管理员”。A 再次开启全员禁言，B 发送唯一文本后出现“发送失败，点击重试”，A/C 未收到。A 随后关闭全员禁言，开关恢复 0。禁言关闭后 B 重新发送另一条文本成功，C 收到，说明失败与全员禁言状态有关，并非 B 普通发言能力故障。 |
+| WEB-FILE-01（刷新及跨域复测） | **失败，P0 阻塞仍在** | A 刷新后从 web1 再传 344,005 字节 PNG，仍提示 `Failed to fetch`；B 从 web2 上传同一文件也失败。B 在“群文件”面板上传 4,587 字节 PNG，同样提示 `Failed to fetch`，列表仍为 0。此轮未重新采集预检头，结合此前 CORS 证据可判上传功能仍阻塞，但不能仅凭本轮页面提示单独断定原因。 |
+| WEB-HOME-04/06（群会话设置） | 通过 | A 开启群聊置顶、消息免打扰后刷新，两项开关均恢复为 1；之后均关闭并确认恢复 0。 |
+| WEB-ME-01（个人资料签名） | 通过 | A 在个人资料页将签名改为 `Web联调签名测试-20261017`，保存后刷新，输入框仍显示相同内容，保存按钮恢复禁用。该测试签名保留在测试账号上。 |
+| WEB-HOME-07（在线未读） | 通过 | C 停在无选中会话的消息页时，B 在解除全员禁言后发送群文本，C 群会话未读变为 1；打开群聊后出现该文本，未读标记清零。会话摘要在打开/加载完成前短暂显示上一条系统消息，随后更新为新文本，未计作稳定缺陷。 |
+| WEB-MSG-01（多行 Unicode） | 通过 | C 发送含表情、中文及换行的两行群消息；B 实时收到，B/C 刷新后两行内容仍完整且顺序一致。 |
+| WEB-GRP-23（群内昵称） | **部分失败，P1 展示缺陷** | C 将“我在本群的昵称”设为 `联调成员C`，刷新后设置页仍显示该值，说明保存成功。但 B 的新群消息发送者按钮仍为 `qa261017c`；C 刷新后的“群成员 3”列表中自己仍为 `qa261017c`。需确认群成员昵称的读取字段与消息发送者展示优先级。 |
+| WEB-GRP-21/22（公告编辑和已读） | 通过 | B 将原公告编辑为含“编辑复测 2026-10-17”的版本并发布；B/C 群聊实时出现新的公告消息。C 打开公告详情，看到新内容和已读 2/3；B 的公告详情显示发布者为 B。未测删除和旧版本并发冲突。 |
+| FLOW-REG-06、12～15、SMK-11～15 | 待执行 | 三域名登出隔离、PDF 下载、昵称等其他资料字段、负向注册、工作台及跨租户等尚未测试；大图上传失败后不继续假定文件链路可用。 |
+
+本轮页面操作发生在 09:00～09:19（Asia/Shanghai）。首次文件上传失败采集了预检/POST 网络事件，首次管理员禁言失败采集了 WS `403` 控制帧；后续复测主要以页面状态为证。其他用例未系统采集 Request ID 和消息 Seq，因此当前记录不能代替协议与数据库层验收。仅用户名注册无法自助找回密码；短信验证码、邀请码和推荐关系仍需使用受控测试手机号及有效邀请码单独验证。
+
+## 23. 缺陷修复与复测状态
+
+第 22 节记录的是修复前版本的实测结果。以下是本轮发布后的复测。首次复测时 web3 测试账号曾被另一设备登录策略踢出；之后恢复登录并完成了普通成员禁言、昵称和群消息复测。
+
+| 缺陷 | 代码修复 | 本地验证 | 发布后复测 |
+| --- | --- | --- | --- |
+| 大图及群文件上传预检失败 | IM Server 上传 `OPTIONS` 按上传方法集校验 `POST`；允许来源匹配后明确回显请求头名，不再用 `Access-Control-Allow-Headers: *` 处理带鉴权预检。 | 上传预检单测通过，Go server/media 测试通过。 | **预检通过，群文件上传未通过**：对 `https://web1/2/3.118im.com` 分别请求 `OPTIONS /v0/file/u/`，均返回 204，正确回显对应 Origin，允许 `POST, PUT, HEAD, OPTIONS` 及 `authorization,x-meetingim-apikey,content-type`。三域名各从群文件页选择 344 KB PNG，均发起 `POST https://api.118im.com/v0/file/u/`；web2 的 OPTIONS 为 204，web1 请求使用已缓存预检。各 POST 观察 8～15 秒均无响应事件，页面持续转圈、列表为 0，浏览器无 Console 错误；刷新后未见文件记录。小图 `docs/ios-pill-128.png` 在群聊正文走 `data:` 内联，不能证明 OSS 上传。需排查上传 POST/服务端处理或 OSS 回源链路，并重测下载。 |
+| 管理员在全员禁言时无法发言 | 群发言检查读取当前业务成员角色，避免依赖已加载 Topic 的旧权限快照；非活跃成员不允许绕过禁言。 | 群角色测试及 Go store/MySQL 构建测试通过。 | **通过**：A 开启全员禁言，C 普通成员发送失败且 A/B 均未收到；同一状态下 B 管理员发送 `发布后复测-禁言管理员重连后-B-20261017`，A/C 均收到。首次管理员尝试遇到 504；刷新 B 重连后再测成功。解除禁言后 C 的新消息及先前失败消息重试均送达。全员禁言最终已关闭。 |
+| 群内昵称未用于成员及发送者显示 | Web 的群成员预览/列表、群消息发送者、引用、历史搜索和 @ 提示优先取 `group_nickname`；IM Server 为群昵称更新广播 `group.member.profile.updated`，Web 收到后定向重取成员数据。 | Web 单测 21/21、生产构建通过；群事件可见性单测通过。 | **通过（跨端成员列表及发送者）**：A 群主修改本人群昵称后，B 管理员无需刷新，群成员列表立即显示新昵称；恢复为账号名后，B 列表也实时恢复。C 登录恢复后，B/A 的成员列表和 C 新发消息均显示 `联调成员C`。 |
+
+补充：本轮实际使用的测试用户为 web1 `qa261017a`（群主）、web2 `qa261017b`（管理员）、web3 `qa261017c`（普通成员）。web3 登录恢复后继续完成普通成员权限复测。web2 首次禁言发言遇到 `CommError: timeout (504)`，刷新重连后管理员豁免发送成功。普通成员禁言失败消息解除禁言后点“重试”成功送达；搜索该消息可返回结果并定位群历史。C→A 私聊及 A→C 回复均实时送达，第三个账号 B 未看到私聊正文。C 通过 `@` 选择管理员 B 后发送群提及，A/B 实时收到并正确呈现提及对象。测试结束时全员禁言为关闭状态。三域名均用 344 KB PNG 测群文件上传，`POST /v0/file/u/` 长时间无响应、状态持续转圈，刷新后列表仍为 0；群聊小图走 `data:` 内联，不应视作 OSS 上传证据。Web 本地开发地址为 `http://127.0.0.1:8094/`，其 API 代理需要本机 IM Server 监听 `127.0.0.1:6060`。
+
+### 本轮追加实测（2026-10-17）
+
+| 用例 | 结果 | 实测记录 |
+| --- | --- | --- |
+| WEB-FAV-01～03（空态/分类筛选） | 部分通过 | A 的收藏页正常加载“暂无收藏内容”；全部、文本、图片、视频、语音、文件、链接分类均可切换，空态保持。暂无收藏记录，无法验证各类型入库、取消和分页。 |
+| WEB-FRIEND-01/10（通讯录/备注） | 通过 | A 通讯录列出好友 B/C；好友资料显示 username、昵称及 `usr...` ID。B 备注临时改为“回归备注-临时”，保存后通讯录和资料标题更新；随后清空并确认恢复“未设置”。 |
+| WEB-FRIEND-10（好友昵称同步回滚） | 部分通过（实时列表缓存延迟） | A 临时修改昵称后，B 通讯录即时显示新昵称；A 恢复原昵称后，B 好友资料面板显示恢复后的 `qa261017a`，但通讯录列表短暂残留临时昵称。B 刷新页面并恢复登录后列表更新为 `qa261017a`，跨端实时列表缓存失效仍有延迟。 |
+| WEB-FRIEND-11（黑名单空态） | 部分通过 | A 的黑名单页正常显示空态，当前 0 人；未把好友加入黑名单，故阻断拉黑/解除及被拉黑发送权限验证。 |
+| WEB-GRP-03/06/07/08（群分类、成员、详情、搜索） | 通过 | 群列表分类计数与角色一致：A“我创建的”1，B“我管理的”1；B 群成员面板显示 3/3，角色为群主/管理员/普通成员，单成员详情可打开。按“联调成员C”搜索只保留 C，清空前未改变成员数据。 |
+| WEB-GRP-08（无匹配成员搜索） | 部分通过 | A 搜索不存在成员名后结果列表清空；清空关键词后 3 名成员恢复。页面未提供可访问文本形式的“无匹配结果”提示。 |
+| WEB-GRP-16/17/19（治理配置/邀请审批入口） | 部分通过 | B 管理员可查看进群验证、全员禁言、群文件上传权限、成员私聊权限、邀请入群权限、禁言成员和进群申请入口，当前设置均未被修改。没有可用于入群审批的第四个账号，审批通过/拒绝、邀请权限变更未执行。 |
+| WEB-ME-01/06、WEB-PRIV-01（资料/二维码/隐私只读） | 部分通过 | A 资料页显示 username、`usr...` ID、昵称、性别、生日、地区和签名；页面未显示手机号字段。个人二维码可生成并展示。隐私当前“资料可见范围”和“最近在线可见范围”均为“仅好友”，添加方式和已读回执开关可见；未切换隐私设置，无法据此验收非好友受限表现。 |
+| WEB-SET-01/02/04（设置页入口） | 部分通过 | 通用页提供“清空缓存”；安全页提供修改密码和注销账号入口。未点击清空缓存；密码修改需账号持有人操作，注销是不可恢复动作，均未执行。 |
+| WEB-HOME-10/12（系统消息） | 部分通过 | A 系统消息中心可读到两条“好友申请已处理”通知，内容可读且标记为新；未执行全部标记已读或通知跳转校验。 |
+| WEB-CALL-10（通话记录空态） | 部分通过 | 通话记录页正常加载并显示“暂无通话记录”；未发起真实音视频通话，无法验证记录字段和声网链路。 |
+| WEB-ABUSE-01（群举报入口） | **失败，功能未开放** | A 在群设置点击“投诉举报”，页面提示“该功能暂未开放，如需投诉举报请联系客服。”没有举报表单，无法提交举报或取得 report_id。 |
+| WEB-MSG-02（群聊文本/链接消息） | 通过（A/B/C） | B 发送 `链接卡片验收-20261017 https://example.com`，A 收到可点击链接；随后 C 发送 `三人群回归消息-C-20261017`，A/B 均收到文本且显示群昵称“联调成员C”。 |
+| WEB-HOME-02（群未读清零复测） | **受控场景通过，曾出现一次异常** | 早先 B 发消息时 A 已处于群聊，正文可见但旧未读 `1` 未即时清除；刷新后该旧徽标消失，未能稳定复现。本轮将 A 留在私聊，由 C 发群消息，A 会话列表出现未读 `1`；A 打开群聊并加载该消息后，徽标清零，C 端显示 2 人已读。需继续观察同会话在线实时更新与多消息连续到达，不据一次旧徽标直接判定服务端游标故障。 |
+| WEB-WB-01～02、WEB-ORG-01～04 等工作台场景 | 本轮不处理 | 按用户本轮要求，工作台网页版部分场景不纳入本轮验收。 |
+| WEB-TENANT-01～05（跨租户隔离） | 阻塞 | 当前只有 `system` 商户三账号；web1/web2/web3 是不同域名，不是不同租户。需要第二个可登录商户及其测试账号，不能用域名替代租户。 |
+| WEB-AUTH-11～16、WEB-PRIV-05、WEB-ABUSE-01～04、WEB-FB-01～05 | 阻塞/未执行 | 邀请码、短信验证码和密码重置需受控手机号/验证码；入群审批需要第四位申请人；举报/反馈会创建后台业务单，需后续按独立测试数据执行。注册异常分支未通过手工数据库方式伪造。 |
+
+本轮仅在测试账号间操作；好友备注已恢复未设置，A 昵称已恢复，群角色/成员/治理开关、A 的隐私设置均保持原值。全功能验收仍未完成：OSS 上传当前仅验证小型 PNG 最终成功，下载链路未通过；缺少第二租户及短信/邀请码测试凭据；通话、举报反馈、消息复杂类型/转发撤回、跨端登出隔离及若干群治理状态转换也尚未实测。工作台网页场景按用户要求排除。未读受控路径本轮通过，旧徽标残留现象暂未稳定复现；B 通讯录昵称在 A 修改后存在实时列表缓存延迟，页面刷新后恢复。
+
+### 本轮定向复测（2026-10-17）
+
+| 用例 | 结果 | 实测记录 |
+| --- | --- | --- |
+| WEB-FILE-01/02（群文件 OSS 上传） | 部分通过 | B 管理员在三人群“群文件”上传 `docs/ios-pill-128.png`（4.5 KB）；上传按钮约 10 秒保持转圈后，列表新增文件记录，上传者、文件名、大小和时间正确。证明群文件上传请求最终完成并生成业务记录，但 UI 仍需明确的上传进度/耗时反馈；单次 UI 记录不能独立证明对象存储 Bucket 内容及审核状态。 |
+| WEB-FILE-06（群文件下载） | 部分通过，存在服务端间歇失败 | 前一轮 C 普通成员从群文件行触发下载，6 次读取中 5 次 `200 image/png`（一次完成传输 5,169 字节），1 次 `500 application/json`，错误体为 `ctrl.code=500, text=internal error`。本轮追加一次下载，收到 `200 image/png` 且 `Network.loadingFinished`，传输长度记录为 531 字节；自动化环境仍未暴露系统下载完成事件，不能确认文件落盘/内容。Web 前端本地已将 Blob URL 撤销延后 1 秒，`npm test` 21/21、`npm run build` 通过，尚未发布复验。 |
+| WEB-FILE-01（普通成员群文件上传及跨成员可见） | 部分通过，曾间歇 500 | 群文件权限为“所有成员”。C 第一次上传 4.5 KB PNG 收到 HTTP 500，响应 `ctrl.code=500, text=internal error`；第二次重试成功，群文件数由 1 增至 2，新增条目上传者为 `qa261017c`，文件名及大小正确。A、B 各自打开群文件列表后也都看到该条目。说明普通成员在该权限下可以上传，文件索引对其他成员可见，但一次失败、一次成功仍提示上传链路有间歇问题；测试集群日志此前因 Kubernetes API 超时尚未取到。源码检查另发现 `member_upload_files` 之前只控制前端入口、服务端未强制执行；已在本地补服务端授权和单测，但尚未部署，且本次在线配置为“所有成员”，该改动不能解释间歇 500。 |
+| WEB-GRP-治理入口与角色边界 | 部分通过 | A 群主管理面板可见进群验证、全员禁言、群文件上传权限、成员私聊权限、邀请入群权限、禁言成员、进群申请及转让群主等控制。普通成员 C 的群资料面板没有“群管理”入口（可访问按钮数 0）；A 可见该入口。当前进群验证/全员禁言关闭，群文件权限为“所有成员”，邀请权限为“所有成员”；本轮只读检查，未改变配置。审批状态转换、管理员移除/禁言对象和权限变更后的服务端拒绝仍需第四位申请人及独立成员数据。 |
+| WEB-HOME-02（未读清零及按用户隔离） | 通过（受控路径） | A、B 均离开群会话，C 发送 `未读复测-C-20261017-1618` 后，A、B 群会话各自显示未读 `1`。A 打开群聊后 A 的未读清零，B 仍显示 `1`；B 再打开群聊后 B 的未读清零。C 端显示 2 人已读。验证未读数按用户独立维护，读取一方不清除另一方未读。 |
+
+工作台网页场景按用户要求不纳入本轮。OSS 链路仍未完整验收：下载有间歇 `500`，且尚未从真实浏览器验证落盘文件；上传覆盖的仍只有 4.5 KB PNG，较大文件、PDF/视频和审核状态尚未覆盖。Web 本地下载修复已将 Blob URL 撤销延后 1 秒，测试 21/21、生产构建通过，尚未发布到测试环境验证。普通成员上传复测由首次 500 转为重试成功，仍需日志定位间歇错误。

docs/test/IM-allrich双机压测执行记录-20260927.md

@@ -16,37 +16,63 @@
 | 机器 A | 当前开发机，`192.168.1.135` |
 | 机器 B | 另一台压测机，运行 `-machine b` |
 
-`config.json`、`.env.test`、`manifest.json` 均被 Git 忽略。manifest 含 2000 个账号 Token，只能通过受控内网传输。
+`config.json`、`.env.test`、`manifest.json` 均被 Git 忽略。manifest 含账号 Token，只能通过受控内网传输。
 
 ## 2. 数据准备结果
 
-2026-09-27 已完成并通过硬校验：
+2026-09-27 首次准备曾按 2000 账号目标执行。当前分阶段压测使用的实际运行文件为：
 
-- 账号：2000，机器 A/B 各 1000。
-- 用户名：`lta0001-lta1000`、`ltb0001-ltb1000`。
-- 测试手机号：A 使用配置前缀加 `0001-1000`，B 使用配置前缀加 `5001-6000`。
-- 好友关系：1000 对，序号相同的 A/B 用户互为好友。
-- P2P Topic：1000 个，全部写入 manifest。
-- 测试群：1 个，成员数 2000，Topic 仅在 manifest 中保存，文档只记录哈希 `98372d54fe65`。
+- `users_per_machine=500`。
+- 账号：1000，机器 A/B 各 500。
+- 好友关系与 P2P Topic：500 对。
+- 测试群：1 个，当前 manifest 的 `group_topic=grp3Ita5tyBIMs`。
+
+正式的 2000 人群测试前，必须将 `users_per_machine` 恢复为 1000，在机器 A 重新执行 `prepare` 和 `verify`，并将新 manifest 同步给机器 B。不能用当前 1000 人清单宣称已完成 2000 人群压测。
 
 准备过程观察到注册和好友同意接口存在少量瞬时 500/404，100 人群邀请批次存在 502、超过 2 分钟及 `IDEMPOTENCY_IN_PROGRESS`。工具使用相同业务幂等键和退避重试后全部恢复；这些属于准备链路现象，不计入正式消息到达率。
 
-## 3. 当前运行状态
+## 3. 最新有效轮次
 
 | 项目 | 值 |
 |---|---|
-| Run ID | `p2p-20260927-01` |
+| Run ID | `p2p500-r5-20260927-05` |
 | 场景 | `p2p` |
-| Coordinator | `http://192.168.1.135:8090` |
-| 机器 A agent | `1000/1000 READY`，意外断连 0 |
-| 机器 B agent | 等待启动 |
-| 远端 dev | `6d17154` 或更新版本 |
+| Git 提交 | `ea8732e` |
+| 连接 | A/B 各 500，合计 1000/1000 READY |
+| 发送 | 10000/10000 获得 ACK |
+| 实时到达 | 10000/10000，到达率 100% |
+| 历史落库 | 10000/10000，落库率 100% |
+| 异常 | 丢失 0、重复 0、乱序 0、断连 0、发送错误 0 |
+| ACK 延迟 | P50 约 650ms，P95 1313ms，最大 2075ms |
+| 同机 echo 投递 P95 | 2s 直方图桶 |
+| 报告门禁 | 正确性通过；延迟门禁未通过 |
 
-机器 A 的 coordinator 和 agent A 已运行。机器 B 启动并达到 1000 READY 后，coordinator 自动下发统一开始时间，无需人工再次触发。
+本轮中 A/B 时钟未对齐，A 端记录到 4334 个跨机器负延迟样本，因此不使用跨机器单向延迟作为结论；延迟门禁使用发送机本机 ACK 和 echo 口径。
 
-## 4. 机器 B 运行文件
+### 3.1 服务端阶段耗时
 
-机器 A 已生成：
+| 阶段 | 平均耗时 | P95 所在桶 |
+|---|---:|---:|
+| `relationship_check` | 66.9ms | 250ms |
+| `redis_idempotency` | 21.1ms | 100ms |
+| `redis_sequence` | 62.7ms | 250ms |
+| `kafka_produce` | 11.0ms | 25ms |
+| `save` | 116.9ms | 500ms |
+
+`meeting_im` 和 `hotgo` 连接池在该轮起压窗口的等待次数和等待时间增量均为 0，未出现连接池枯竭。
+
+### 3.2 Kafka 和落库
+
+- `im-server.message_persist` 的 consumer lag 峰值为 4663。
+- lag 在发压结束后约 2 分钟清零。
+- 测试窗口中批量持久化的单批平均耗时约 3.52s，P95 落在 10s 直方图桶。
+- agent 在等待 Kafka 追平后回查历史，10000 条 ACK 消息全部找到，没有持久化丢失。
+
+结论是当前系统能在突发后最终消化积压，但前台 ACK 和异步落库延迟仍高，这两项应单独作为后续优化指标。
+
+## 4. 历史机器 B 运行文件
+
+以下为首轮历史运行包，不能继续用于新轮次：
 
 ```text
 /tmp/allrich-machine-b-runtime-p2p-20260927-01.zip
@@ -89,3 +115,36 @@ go build -o im-pressure .
 ## 5. 多 Pod 口径说明
 
 当前 A/B 配置均使用 `wss://api.118im.com/v0/channels` 公共入口。该配置验证 LB 实际分配下的多 Pod 能力，但不能保证两台压测机固定落到不同 Pod。若验收要求强制指定不同 Pod，需要提供两个独立 WS 定向入口，分别配置到 `endpoints.a` 和 `endpoints.b`。
+
+## 6. 后续测试顺序
+
+### 6.1 P0：扩容到 2000 个用户
+
+1. 将机器 A 的 `config.json` 修改为 `users_per_machine=1000`。
+2. 机器 A 执行 `prepare` 和 `verify`，确认 2000 账号、1000 对好友、1000 个 P2P Topic 和 2000 人群都就绪。
+3. 重新生成包含 `.env.test`、`config.json`、`manifest.json` 的 B 机运行包，B 机解压后执行 `verify`。
+4. A/B 都执行 NTP 校时，要求偏差小于 50ms，否则继续忽略跨机器单向延迟。
+
+### 6.2 P1：2000 人群聊
+
+使用 `scenario=group`：
+
+- A/B 各建立 1000 个 WS，合计 2000 个在线群成员。
+- A/B 各取前 500 个发送者，每人 2 条，合计 2000 条群消息。
+- A/B 交错每 100ms 发送 1 条，单轮发送窗口约 100s。
+- 期望实时投递为 2000 条消息 x 2000 连接，即 400 万次有效到达。
+- 检查群消息 ACK、每个 WS 的到达数、重复、乱序、断连、`im.group.message.persist` lag 和群消息月表落库。
+
+群聊是下一个应执行的场景，因为它直接验证本次多 Pod 改造的 Redis fanout 和群消息 Kafka 持久化。
+
+### 6.3 P2：混合场景
+
+群聊正确性通过后使用 `scenario=mixed`：
+
+- 300 对私聊用户双向各发 5 条，合计 3000 条私聊消息。
+- A/B 各 250 个群发送者，每人 2 条，合计 1000 条群消息。
+- 同时观察私聊与群聊的到达率、两个 Kafka 持久化 Topic 的 lag，以及 Redis、MySQL 和 3 个 Pod 的资源争用。
+
+### 6.4 P3：单聊完整规模回归
+
+最后在 2000 连接下重跑 `p2p`，即 1000 对用户双向各发 10 条，共 20000 条。延迟门禁仍为 ACK P95 <= 500ms、同机 echo P95 <= 1000ms；若只有正确性通过而延迟未通过，结论必须标记为“可靠性通过，性能未达标”。

docs/test/IM-group2k-r1-群聊压测问题分析-20260927.md

@@ -0,0 +1,145 @@
+# IM 2000 人群聊压测问题分析
+
+日期：2026-09-27  
+Run ID：`group2k-r1-20260927-01`  
+场景：A/B 各 1000 个 WebSocket，各 500 个发送者发 2 条，计划发送 2000 条群消息。
+
+## 1. 结论
+
+本轮失败，且不能仅解读为 WebSocket 丢包。核心问题是 2000 人群每条消息触发 O(群成员数) 的额外用户 `me` Topic 路由，导致 Topic master、集群通道和 MySQL 连接池连锁积压。服务端处理吞吐下降后，发送端先经历 ACK 超时，随后 Topic 队列写满并返回 503。
+
+同时，压测程序对 ACK 超时的口径不完整：超时后服务端仍可能接受、广播并落库，不能把 `ctrl_timeout` 直接当作明确拒绝。
+
+## 2. 客户端结果
+
+| 指标 | A | B | 合计 |
+|---|---:|---:|---:|
+| WS READY | 1000 | 1000 | 2000 |
+| 发送尝试 | 1000 | 1000 | 2000 |
+| 收到 2xx ACK | 16 | 19 | 35 |
+| 503 | 224 | 272 | 496 |
+| ACK 超时 | 732 | 709 | 1441 |
+| socket 错误 | 28 | 0 | 28 |
+| 断线 | 21 | 0 | 21 |
+| ACK 台账内实时缺失 | 735 | 0 | 735 |
+| ACK 台账内历史落库缺失 | 0 | 0 | 0 |
+| 未在 ACK 台账中的实时投递 | 368270 | 377000 | 745270 |
+
+35 条 ACK 消息理论上应产生 70000 次本轮投递，实际共记录 69265 次，其中 A 端少 735 次。但这不是服务端实际接受的全量；额外 745270 次投递来自“未及时收到 ACK，但服务端已处理”的消息。
+
+## 3. 服务端证据
+
+### 3.1 实际接受和落库
+
+- `im_message_publish_stage_duration_seconds_count{kind="group",stage="save",result="ok"}` 增加 488。
+- `im_kafka_message_persist_total{kind="group",result="batch_ok"}` 增加 488。
+- 群消息 Kafka 批持久化平均约 46.6ms，488 条全部 batch success。
+
+因此，服务端至少接受并落库 488 条，而不是客户端 ACK 台账中的 35 条。其中至少 453 条属于“已接受但 ACK 未在 20 秒内返回”。
+
+### 3.2 队列溢出
+
+| Pod | 日志 | 次数 |
+|---|---|---:|
+| `im-server-2` | `s.publish: sub.broadcast channel full` | 496 |
+| `im-server-2` | `hub: topic's broadcast queue is full` | 1655 |
+| `im-server-1` | `cluster: proxy channel full` | 47 |
+
+群 Topic `grp3Ita5tyBIMs` 的 master 在 `im-server-2`。其 `clientMsg` 队列容量只有 192，proxy 响应队列容量为 128。队列满时会立即返回 503 或丢弃 proxy 响应。
+
+### 3.3 每条群消息的路由放大
+
+`Topic.saveAndBroadcastMessage` 在每条消息中同步执行：
+
+1. `presSubsOffline("msg", ..., offlineOnly=true)` 遍历 `t.perUser` 的 2000 个成员。
+2. 为每个成员构建一条用户 `me` Topic presence 消息。
+3. `routeUserServerMessage` 同时走 Tinode 原生 Cluster 路由和 Redis user fanout。
+4. 最后才向群 Topic 的会话广播 `{data}`。
+
+488 条已接受群消息产生了约 98 万次额外用户路由：
+
+- `realtime_fanout_events_total{stage="publish",target_type="user"}` 增加 979979。
+- `realtime_fanout_events_total{stage="receive",target_type="user"}` 增加 894360。
+- Redis 接收后真正本地投递只有 666 次，`no_local_session` 为 893694。
+- Cluster route 约增加 109 万次。
+
+这证明绝大多数用户 fanout 在当前全员已订阅群 Topic 的场景中完全无效，却阻塞了 Topic master 的串行处理协程。
+
+### 3.4 MySQL 连接等待
+
+3 个 Pod 的 `meeting_im` 连接池在测试窗口中合计：
+
+- 等待次数增加 4011。
+- 等待时间增加约 35399 秒。
+- DB `exec ok` 增加 3453，平均耗时约 501ms。
+
+连接池每 Pod 最大 24 个连接。这不是本轮第一个堵点，但会进一步拖慢群权限检查、未读数更新和其他业务 SQL。仅提高连接数不会消除 O(成员数) 的放大。
+
+## 4. 压测程序口径问题
+
+1. `ctrl_timeout` 和 socket 错误属于发布结果未知，不是明确拒绝。
+2. recorder 能够统计 `unexpected_messages`，但 merge 报告没有汇总该字段，也没有将它加入门禁。
+3. 历史回查只检查 ACK 台账，因此只检查了 35 条，无法单独证明其他超时消息的落库情况。
+4. 群聊应增加“已 ACK”、“已明确拒绝”、“结果未知”、“未 ACK 但已观测广播”和“最终落库”五种状态。
+
+## 5. 改进顺序
+
+### P0
+
+1. 停止在原生 Cluster 已开启时对同一条 user message 再做 Redis user fanout，避免双通道重复路由。
+2. 重构群消息的 unread presence：已订阅该群 Topic 的用户不再生成额外 `me` 通知；未订阅但在线的成员使用节点级批量 fanout，不得在 Topic master 协程中逐人跨 Pod 路由。
+3. 为 Topic `clientMsg`、proxy 响应队列和 session send queue 增加 length/capacity/drop Prometheus 指标。
+4. 压测 merge 报告增加结果未知及 unacked-observed 口径，并把 `unexpected_messages` 纳入失败门禁。
+
+### P1
+
+1. 检查群消息未读数更新和 Push receipt 是否对 2000 人逐人访问 Redis/MySQL，改为批处理或延迟合并。
+2. 为 `CanPost` 的全员禁言和单人禁言结果增加短 TTL 缓存，管理操作时精确失效。
+3. P0 完成后先跑 100、500、1000、2000 人群阶梯，每档检查 ACK P95、Topic 队列水位、Cluster route 数、DB pool wait 和 Kafka lag，不直接重跑全量。
+
+## 6. 本轮验收结论
+
+- 连接建立：通过，2000/2000 READY。
+- 发布成功率：失败。
+- ACK 延迟：失败，已超过 20 秒超时窗口。
+- 实时广播：失败，存在队列丢弃和断线。
+- Kafka 持久化：已处理的 488 条全部成功，但该结论不代表计划的 2000 条均被接受。
+- 总体：失败，必须完成 P0 后按阶梯重测。
+
+## 7. P0 修复实现
+
+本轮分析后的代码修复如下：
+
+1. 群消息的 `{pres what=msg}` 不再由 Topic master 对每个成员逐条跨 Pod 路由。master 将收件人清单合并为一条 `group_unread/users` Redis Pub/Sub 消息；来源 Pod 本地投递一次，其他 Pod 各消费一次。
+2. 每个 Pod 只扫描一次本地 WebSocket：已订阅该群 Topic 的连接依靠正常 `{data}` 广播，不重复发送 `me` presence；同一用户未订阅该群的其他设备仍收到 `me` presence，保留多开语义。
+3. Redis fanout 未启用或批量发布失败时，自动回退到原来的逐用户 Topic 路由，避免静默漏掉未读通知。
+4. 原生 Tinode Cluster 开启时，普通 user message 不再重复发布 Redis user fanout；session control 仍保留 Redis 跨 Pod 广播。
+5. `routeSrv` 改为有界非阻塞写入，队列满时记录错误和指标，不再无限阻塞 Topic 处理链路。
+6. 新增 `im_internal_queue_enqueue_total`、`im_internal_queue_depth`、`im_internal_queue_capacity`，覆盖 `session_topic_publish`、`hub_route_server`、`topic_client`、`topic_server`、`cluster_topic_proxy`。
+
+修复后的复杂度从“每条消息约 2000 次 Cluster route + 2000 次 Redis publish”降为“一次 Redis publish + 每 Pod 一次本地 session 扫描”。2000 人都订阅群 Topic 时，批量 unread 在本地扫描后不会产生重复 WebSocket 帧。
+
+## 8. 复测观测项
+
+复测继续使用 `group2k-r1` 相同发送模型，并重点检查：
+
+```promql
+sum by (queue, result) (rate(im_internal_queue_enqueue_total[1m]))
+
+histogram_quantile(
+  0.95,
+  sum by (le, queue) (rate(im_internal_queue_depth_bucket[1m]))
+)
+
+sum by (stage, kind, target_type, status) (
+  increase(realtime_fanout_events_total[5m])
+)
+```
+
+验收要求：
+
+- `session_topic_publish`、`topic_client`、`topic_server`、`cluster_topic_proxy` 的 `result="full"` 均为 0。
+- `group_unread/users` 的 publish 数应接近服务端实际接受的群消息数，不再乘以群成员数。
+- 群压测窗口内普通 `message/user` Redis publish 不再随群成员数增长。
+- `im_cluster_route_total` 不应再出现每条群消息约 2000 次的线性放大。
+- 2000 条计划消息需分别核对 ACK、未知结果、实时观测和最终落库，不能只按 ACK 台账判断落库率。

docs/test/IM-group2k-r10-双机群聊压测分析与改进-20261004.md

@@ -0,0 +1,159 @@
+# GROUP-2000 R10 双机群聊压测分析与改进
+
+## 1. 测试结论
+
+`group2k-r10-20261004-01` 的 A/B 同步有效，可以作为 2000 人群聊的真实双机容量结论。本轮持久化链路基本正常，但实时扇出已明显超过当前服务容量，整体判定为 **失败**。
+
+- A/B 各建立 1000 个 WS 连接，共 2000/2000 就绪；两机实际开始时间相差约 84ms。
+- 2000 条发送尝试中，1984 条收到 202 ACK，16 条因 socket 中断而结果未知，无显式 403/502/503 拒绝。
+- 数据库最终找到 1999 条，无重复、无字段不一致；仅 `g-a-0098-02` 未落库。
+- 按 1985 条已在服务端确认的消息计算，期望实时投递 3,970,000 次，实际收到 1,979,444 次，到达率 49.86%，实时缺失率 50.14%。
+- 1,990,556 次实时缺失全部可从历史消息查回，说明主要问题是实时投递容量，不是 Kafka/MySQL 丢数据。
+- 负载期间共 152 次 WS 断连：147 次 connection reset、4 次 timeout、1 次 closed connection。
+- ACK P95 为 71.18s，本地实时投递 P95 为 329.68s，已不是普通抖动，而是持续性排队。
+
+JPush 空设备查询放大、MySQL 连接频繁回收和 A/B 起跑错位等 R9 问题在本轮已解决。当前的主要容量瓶颈是大群每条消息的单 Topic 有序处理、跨 Pod multiplex 转发和各 Pod WS 逐连接序列化/写出组合成的实时扇出链路。
+
+## 2. 四层对账
+
+| 层级 | 结果 | 结论 |
+| --- | ---: | --- |
+| 发送尝试 | 2000 | A/B 各 1000 |
+| 即时收到 202 | 1733 | 251 条在超时后迟到 |
+| 最终收到 202 | 1984 | 发送成功率 99.2% |
+| 发送结果未知 | 16 | 全部为 socket 中断，无业务拒绝 |
+| 历史回查 | 1985/1985 | 服务端可确认消息全部可查 |
+| 数据库实际落库 | 1999/2000 | 14 条“结果未知”也已落库 |
+| 真正未落库 | 1 | A 机 `g-a-0098-02` |
+| 实时投递 | 1,979,444/3,970,000 | 到达率 49.86% |
+| 重复 / 乱序 | 0 / 0 | 已收到数据的正确性正常 |
+
+16 条结果未知中，14 条 B 机消息已在数据库找到；A 机 `g-a-0102-02` 被实时观测到且已落库；只有 `g-a-0098-02` 在连接断开前未被服务端处理。因此不能把“客户端未收到 ACK”直接等同于“消息未落库”。
+
+## 3. A/B 表现
+
+| 指标 | 机器 A | 机器 B |
+| --- | ---: | ---: |
+| 就绪连接 | 1000 | 1000 |
+| 发送尝试 | 1000 | 1000 |
+| 最终观测 ACK | 998 | 986 |
+| 结果未知 | 2 | 14 |
+| 收到群消息 | 996,563 | 982,881 |
+| 断连 | 7 | 145 |
+
+B 机的断连明显更多，但 reset 分布在多个公网源 IP，没有单一坏 IP 的证据。机器差异会影响结果，但 A 机同样出现大量投递缺失和长尾，不能将本轮失败只归因于 B 机网络。
+
+## 4. 指标与时间线
+
+- 负载窗口约为 09:21:43–09:26:32。
+- A 机断连集中在 09:23:20–09:25:24；B 机采样到的 reset 集中在 09:24:20–09:25:23。
+- 服务端 `/metrics` 在约 09:23:01–09:25:37 多次超过 10s 采集超时；233 次 im-server 采样中 14 次失败，17 次超过 5s。
+- Kafka consumer lag 和 oldest age 在收敛阶段均为 0。
+- `im_kafka_message_persist_total{kind="group",result="batch_ok"}` 合计 1999，与数据库实际条数一致。
+- `im_push_dispatch_queue_enqueue_total{result="ok"}` 为 1999，未观测到 push queue full/error；推送平均处理约 22ms。
+- Topic group queue wait 未超过 1s，Cluster P2M/route 计数未观测到 full/error。
+- 三个 Pod 的 ACK enqueue/write 指标都在 1s 内。注意该计时从服务端 WS 读循环完成解析后开始，因此客户端几十秒至数分钟的 ACK 延迟，主要发生在服务端 dispatch 之前的读取/调度阶段，或写入 socket 后的网络/客户端接收阶段。
+
+`/metrics` 与 WS 同时出现长时间停顿，说明不只是某个业务队列满，而是 Pod 的 CPU/调度/网络写路径在大规模扇出下被长时间占用。本轮无法通过集群 API 读取 Pod Event 和完整日志，因此不将 CPU throttling、Ingress 和节点网卡中的任何一项单独定为唯一根因。
+
+## 5. 代码链路分析
+
+### 5.1 Topic 主节点
+
+`Topic.broadcastToSessions` 遍历主 Topic 上的本地 session 和远程 Pod multiplex session，为每个目标复制、整理消息并入队。一个 2000 人群的 2000 条消息会生成约 400 万次终端投递。
+
+当 multiplex 队列暂时满时，Topic goroutine 会等待最多 250ms；一个主 Topic 又需要保持消息顺序，所以无法通过对单条消息无界并发来解决。
+
+### 5.2 跨 Pod multiplex
+
+每个远程 Pod 使用一个 multiplex session。它的 drain 为保证 Topic 顺序，对每条 `Cluster.TopicProxy` RPC 同步等待远程返回。这保证了顺序，但对单条 RPC 往返、gob 编解码和远程 proxy Topic 处理的抖动很敏感。
+
+### 5.3 Pod 内 WS 扇出
+
+proxy Topic 收到一条群消息后，仍然遍历本 Pod 上的所有订阅 session，为每个 WS 连接复制消息并入队。每个 WS 只有单个 write loop 串行做序列化和 socket write。当扇出速度超过写出速度，session 队列积压，随后出现连接 reset、客户端重连以及更大的订阅恢复压力。
+
+## 6. 已排除和未排除项
+
+### 已排除为本轮主因
+
+- Kafka 积压或持久化丢失：最终 lag=0，1999 条 batch_ok 与 DB 一致。
+- MySQL 批量落库能力：无重复、无字段不一致，只有 1 条在服务端未接收。
+- JPush 设备查询放大：1999 次异步入队成功，无队列满，平均耗时低。
+- A/B 起跑错位：本轮最终屏障通过，两机实际开始差距小于 100ms。
+- 显式限流或内部队列拒绝：没有 429/502/503，未观测到 Cluster、Topic、push 队列 full/error。
+
+### 仍需补齐证据
+
+- 每个 Topic 单条消息的完整处理耗时和扇出目标数。
+- multiplex 队列等待、RPC 耗时、远程 proxy 接收到入队完成的分段耗时。
+- WS send queue 深度、队列等待 P95/P99、full/purge 和按 Pod 的发生时间。
+- Pod CPU usage/throttling、Go scheduler latency、GC pause、goroutine 数、网卡吞吐/丢包/retransmit。
+- Ingress/LB 上游 reset、upstream response time、连接数和每 Pod 连接分布。
+
+## 7. 改进方案
+
+### P0：先定位每段长尾
+
+1. 增加 Topic 处理总耗时、单条扇出目标数和 `broadcastToSessions` 耗时直方图，区分 master/proxy。
+2. 增加 multiplex 入队等待、队列深度、`Cluster.TopicProxy` RPC 耗时和远程处理耗时。
+3. 补齐 WS send queue P95/P99/max、full、purged，并区分 data/ctrl。ACK 必须能从大量 data 帧中被单独观测。
+4. 增加 WS 读取到 dispatch 前的时间戳，避免现有 ACK 指标忽略服务端读循环前的停顿。
+5. 恢复压测期间的 Pod/Event/CPU 可观测性，指标采集超时不应导致整段监控空白。
+
+### P1：降低实时扇出成本
+
+1. 将 master 到每个 proxy Pod 的多条消息改为有界批量 RPC，批内保持 SeqId 顺序，减少 2000 次同步 RPC 往返、gob 编码和调度开销。
+2. 为每个 Topic-Pod 建立单写者有界队列，允许不同 Pod 并行处理，同一 Pod 内严格按 SeqId 投递；不对单 Topic 做无界 goroutine 并发。
+3. 研究一次序列化、多 session 复用字节的可行性，避免同一条群消息在每个连接重复做等价 JSON 序列化。用户相关 Topic/权限字段必须先完成安全性分类，不可盲目全局复用。
+4. ctrl/ACK 与普通 data 帧分级调度，保证发送者在大群扇出积压时仍能快速获得明确结果。需保持单连接协议语义，不得导致客户端对 data/ctrl 的依赖关系错乱。
+5. 对慢消费 WS 定义明确策略：队列达阈值后记录可追踪原因、主动断开并依靠历史补拉，避免一批慢连接长时间拖住整个 Topic。
+
+## 8. 实施和复测顺序
+
+1. 先完成 P0 指标，用相同 2000 人、2000 条参数复现一轮，定量确认 Topic、multiplex RPC、WS queue 和 socket write 各占多少。
+2. 实施 multiplex 批量化和有界单写者，先做单元测试、顺序测试、队列满/节点断开/重连测试。
+3. 用 500、1000、1500、2000 人阶梯复测，每档至少两轮，不直接只跑最高档。
+4. 最后重复 R10 同参数双机测试，必须同时通过实时、历史、DB 和基础设施门禁。
+
+## 9. 下一轮通过门禁
+
+- 2000/2000 WS 就绪，A/B 实际开始差小于 1s。
+- 2000 条发送全部获得明确 ACK，无 outcome unknown，无 5xx。
+- 数据库精确找到 2000 条，缺失、重复、字段不一致均为 0，Kafka lag 最终归零。
+- 实时投递到达率不低于 99.99%，重复和乱序为 0。
+- ACK P95 小于 2s，投递 P95 小于 5s；本轮已明确不以 500ms 作为阻断门禁。
+- 断连、Topic/multiplex/WS queue full、Pod restart、OOM、liveness failure 均为 0。
+- 负载窗口内 `/metrics` 可持续采集，无连续 10s 超时；CPU throttling、GC、网络 retransmit 和 Ingress reset 有完整记录。
+
+## 10. 产物
+
+- 结果目录：`loadtest/im-pressure/results/group2k-r10-20261004-01/`
+- 汇总报告：`report.json`
+- 数据库核验：`db-verification.json`
+- A/B 明细：`agent-a-summary.json`、`agent-b-summary.json`
+- coordinator 台账：`coordinator.json`
+- 服务指标：`metrics.jsonl`
+- 代码版本：`c46209f`
+
+## 11. 本轮已实施改造
+
+R10 分析后已完成以下代码改造，待发布后进行 R11 复测：
+
+- 普通非频道群消息在每个 Pod 仅执行一次 JSON 序列化，同 Pod 的所有 WS 连接复用同一份不可变字节。权限过滤、`SkipSid`、频道匿名、P2P 别名和非 WS 协议仍保持原路径。
+- 增加 Topic 完整处理耗时、广播耗时和按 websocket/multiplex/other 分类的扇出目标数。
+- 增加 master-to-proxy multiplex 入队深度和排队时间，以及远程 proxy Topic 接收后的队列等待时间。
+- 增加 WS 完成读帧后的 JSON 解析和本地 dispatch 耗时。
+- 新快路仍在 WS write loop 记录原有 `OutgoingMessageSize` 统计，不会因预序列化丢失原有监控口径。
+
+本次没有直接引入新的批量 `net/rpc` 方法。StatefulSet 滚动发布时会短暂出现新旧 Pod 混合，新 RPC 端点与旧 Pod 不兼容，会产生发布窗口风险。R11 先用新增指标确认 multiplex RPC 在优化后是否仍为主瓶颈；若需要批量化，应采用“先发布双协议接收端，再开启批量发送端”的两阶段发布。
+
+新增指标：
+
+- `im_topic_process_duration_seconds`
+- `im_topic_broadcast_duration_seconds`
+- `im_topic_broadcast_targets`
+- `im_topic_shared_serialization_total`
+- `im_cluster_m2p_queue_wait_duration_seconds`
+- `im_cluster_m2p_queue_depth`
+- `im_cluster_proxy_queue_wait_duration_seconds`
+- `im_ws_read_dispatch_duration_seconds`

docs/test/IM-group2k-r11-双机群聊复测分析-20261004.md

@@ -0,0 +1,161 @@
+# GROUP-2000 R11 双机群聊复测分析
+
+## 1. 结论
+
+`group2k-r11-20261004-01` 判定为 **失败且不能作为稳定容量结论**。
+
+本轮确认了 R10 后的群消息共享序列化优化已经生效，正常运行阶段的实时到达率明显高于 R10；但压测末段发生了约 1 分钟的公网入口/上游整体不可用，2000 个连接几乎同时断开。与此同时，Kafka 群消息持久化链路仅落库 1165 条，662 条服务端已确认或已观测消息未落库，暴露出批消费可靠性缺陷。
+
+必须先修复 Kafka 批消费和查清入口整体中断，再重复相同参数。当前不能把 93.83% 到达率当作 2000 人容量通过，也不能继续直接提高压力。
+
+## 2. 核心结果
+
+| 指标 | R11 结果 | 判定 |
+| --- | ---: | --- |
+| WS 就绪 | 2000/2000 | 通过 |
+| A/B 实际起跑差 | 约 290ms | 通过 |
+| 发送尝试 | 2000 | A/B 各 1000 |
+| 最终明确 ACK | 1718 | 85.90% |
+| 发送结果未知 | 282 | 失败 |
+| ACK P95 | 58.37s | 失败 |
+| 期望实时投递 | 3,654,000 | 按 1827 条服务端确认/回查消息计算 |
+| 实际实时投递 | 3,428,697 | 到达率 93.83% |
+| 实时缺失 | 225,303 | 6.17% |
+| 数据库核验 | 1165/1827 | 缺失 662 条 |
+| 重复 / 乱序 | 0 / 0 | 已收到部分正确 |
+| WS 断连 | 2036 | 失败，包含重连后的再次断开 |
+
+R10 的实时到达率为 49.86%，R11 提升到 93.83%，说明共享序列化方向有效；但 R11 同时出现了全局入口故障和持久化缺失，两个结果的运行条件不同，不能据此计算严谨的容量提升比例。
+
+## 3. A/B 分机结果
+
+| 指标 | 机器 A | 机器 B |
+| --- | ---: | ---: |
+| 就绪连接 | 1000 | 1000 |
+| 发送尝试 | 1000 | 1000 |
+| 最终观测 ACK | 919 | 799 |
+| 结果未知 | 81 | 201 |
+| 收到群消息 | 1,816,953 | 1,611,744 |
+| 断连 | 1005 | 1031 |
+| 主要断连原因 | abnormal close 996 | abnormal close 653、reset 378 |
+
+B 的网络表现仍弱于 A，但 A 也几乎全量断开，因此本轮不能归因于单独一台压测机。
+
+## 4. 故障时间线
+
+时间均为北京时间 2026-10-04：
+
+- 10:35:36：A/B 同步开始，2000 个连接全部就绪。
+- 10:35:44 起：公网 `/metrics` 出现高延迟和多次 10s 超时，表明服务在正式断开前已经出现调度或网络拥塞。
+- 10:40:06、10:40:12：`/metrics` 返回 HTTP 521。
+- 10:40:16 起：A 机对三个直连源 IP 的 443 均收到 `connection refused`，随后登录出现 500、WS 握手出现 503。
+- 10:40:17：A 的就绪连接从 1000 降到 8，约 992 个连接集中断开；B 同期发生同类大规模断开。
+- 10:40:48–10:41:03：公网入口持续返回 503。
+- 10:41:09 后：入口恢复，客户端自动重连；A 约在 10:43:37 恢复到 1000 个连接。
+
+直连源 IP 同时拒绝 443，且公网出现 521/503，这不是 Cloudflare DNS 或压测机代理造成的普通客户端故障。采样期间 Tinode cluster 指标仍为 2/2 live peers，没有证据表明原生 cluster 先失联。
+
+2026-10-04 11:31–11:32 重新探测时，三个源 IP 的 443 均已恢复并可通过 `api.118im.com` Host/SNI 返回健康检查 200。三个 IP 返回的是同一张 `TRAEFIK DEFAULT CERT`，SHA-256 指纹均为 `7C:9E:00:6F:56:D6:C9:87:44:62:7D:26:93:D8:92:51:F8:DA:43:66:61:DB:8B:F9:1F:47:17:C8:93:13:C4:8C`，证书 `notBefore` 为 **2026-10-04 10:41:32**。该时间与 R11 的 521/503 和源站拒绝连接恢复窗口精确重合，是 Traefik/入口组件在故障期发生重启、重建或重新初始化的强证据。
+
+目前可以把故障范围收敛到 Traefik/入口层，但仅凭默认证书时间仍不能区分 Traefik Pod 重启、Deployment 滚动、节点重启、配置重载或入口服务重建。
+
+运维已确认 Kubernetes API `216.236.31.189:6443` 按安全策略不对公网开放，只允许集群网络访问；当前调试机超时属于预期行为，不是本轮故障的一部分。Pod Event、Ingress controller 日志和节点事件必须由运维从控制面节点或集群内采集。在这些证据回传前，仍不把某一个基础设施组件写成唯一根因。
+
+## 5. 共享序列化与实时链路
+
+三个 Pod 的 `im_topic_shared_serialization_total` 在采集窗口分别增加约 5392、6664、6831，证明新快路已实际执行。
+
+按采集窗口增量估算：
+
+| 阶段 | 结果 |
+| --- | --- |
+| master Topic broadcast P95 | 不超过 5ms |
+| proxy-0 Topic broadcast P95 | 不超过 5ms |
+| proxy-1 Topic broadcast P95 | 不超过 10ms |
+| master 到 peer-0 的 multiplex 排队 P95 | 不超过 100ms |
+| master 到 peer-1 的 multiplex 排队 P95 | 不超过 250ms |
+| WS read-dispatch P95 | 三个 Pod 均不超过 50ms |
+
+Topic 广播本身已不再呈现分钟级长尾，说明“同一群消息对每个 WS 重复 JSON 序列化”得到明显缓解。当前长尾更多出现在 multiplex 排队、socket/入口可用性以及故障后的重连恢复阶段。WS read-dispatch 仍有少量超过 5s 的样本，三个 Pod 分别约 13、10、18 次，需要保留观察，但不是本轮全量断开的充分解释。
+
+## 6. Kafka 与数据库异常
+
+### 6.1 对账证据
+
+- 1827 条服务端确认或历史回查消息中，数据库精确找到 1165 条，缺失 662 条。
+- `im_kafka_message_persist_total{kind="group",result="batch_ok"}` 观测上限停在 1165，此后不再增长。该 counter 没有 `pod` 标签，公网采样又会随机落到不同 Pod，因此不能直接把它当作集群总数；这里只作为持久化停止推进的旁证。
+- 缺失消息全部来自第二轮：A 缺 339 条，序号 0085–0423；B 缺 323 条，序号 0085–0414。A 是完整连续区间，B 仅有少量间隙，不符合随机单条 MySQL 写失败的形态。
+- 采样结束时 group persist 的 lag 仍显示 0，但 `im_kafka_backlog_oldest_age_seconds` 在一个 Pod 上达到约 1082s。二者互相矛盾，现有 lag 指标不能作为“已消费完成”的依据。
+- 压测结束约 30 分钟后再次直连 MySQL 核验，结果仍为 1165/1827，缺失 662、错配 0、重复 0、额外消息 0。缺失没有后台追平，不能解释为普通消费延迟。
+
+### 6.2 已确认的代码风险一：部分批次被丢弃
+
+`fetchKafkaMessageBatch` 先连续调用 `FetchMessage` 组装批次。如果已经抓到若干消息，后续抓取返回非 `DeadlineExceeded` 错误，函数直接返回 `nil, err`，已经抓到的部分消息不会交给 handler，也不会立即提交。
+
+Kafka reader 的内部读取位置已经前移。恢复后若继续抓取并提交更高 offset，之前被丢弃的消息可能随高 offset 一起被越过。这可以直接造成“生产成功、最终 lag 为 0、数据库却缺少一段连续消息”。
+
+### 6.3 已确认的代码风险二：批量幂等 claim 可能活锁
+
+`handleKafkaMessagePersistBatch` 在真正批量落库前逐条执行 `BeginKafkaConsume`。如果批次中途发生 Redis/基础设施错误，前面已经 claim 的消息不会释放；外层重试从批首重新开始，又会遇到 `processing` 状态。不同 claim 的过期时刻略有差异时，重试还可能反复续上前面的 claim，长期无法走到后面的消息。
+
+这能解释 oldest age 长时间增长且持久化计数停止。当前“失败不提交 offset”的修复方向正确，但还没有覆盖“抓取半批失败”和“准备半批失败”两个边界。
+
+### 6.4 lag 指标口径不可靠
+
+当前指标直接读取 `kafka-go Reader.Stats().Lag`，同时在每次批处理结束后把 oldest age 清零。consumer group 模式下，该 lag 不是可靠的已提交 offset 差值；消息被 reader 抓取但尚未持久化时，也可能显示 0。必须改为按 partition 查询 high watermark 与 committed offset，并分别暴露 fetched、processed、committed offset。
+
+## 7. 优先改进项
+
+### P0：Kafka 持久化可靠性
+
+1. `fetchKafkaMessageBatch` 在抓到部分消息后发生可恢复错误时，应返回已抓取批次供 handler 处理；只有一条都没抓到时才返回 fetch error。
+2. 批量准备阶段不能留下半批 claim。可先完成无副作用的解码与校验，再逐条 claim；claim 冲突时按消息拆分处理，不能让整个批次从头活锁。
+3. offset 只允许在该 partition 对应消息全部持久化成功后提交；增加 fetched/processed/committed offset 和 commit failure 指标。
+4. 增加回归测试：半批 fetch 后网络错误、准备第 N 条失败、Redis 短暂不可用、处理成功但 commit 失败、Pod 在 handler 中重启。
+5. 修复后先执行 2000 条“只验证 Kafka/MySQL”的持久化专项，要求 DB 2000/2000、lag/offset 对账一致，再恢复大群实时压测。
+
+### P0：入口整体中断
+
+1. 从 Ingress controller、Service endpoint、入口节点和云负载均衡拉取 10:40:00–10:41:10 的日志与事件。
+2. 核对是否发生 Ingress reload、endpoint 短暂清空、节点 conntrack/端口耗尽、进程监听中断、liveness 误杀或网络策略更新。
+3. 增加入口黑盒探针：Cloudflare 域名、源站 IP、Service、Pod 四层同时采样 TCP connect、TLS handshake、HTTP status 和耗时。
+4. 把“源站三个 IP 同时 connection refused”设为基础设施门禁，发生时本轮自动标记无效并保留现场。
+
+### P1：实时链路
+
+1. 保留共享序列化实现；从本轮数据看无需回退。
+2. 继续降低 master-to-proxy multiplex 排队，优先考虑兼容发布的有界批量 RPC 或单写者批发送。
+3. 补采 Pod CPU throttling、Go scheduler、GC、网卡 retransmit、Ingress upstream reset，解决 `/metrics` 本身在高压阶段失去可观测性的问题。
+
+## 8. 下一轮顺序
+
+1. 修复 Kafka 两个批消费边界并完成单元/故障注入测试。
+2. 运行持久化专项，确认 2000/2000 精确落库。
+3. 恢复 Kubernetes 与 Ingress 现场采集能力，查清 R11 的入口中断。
+4. 使用 R11 完全相同参数执行 R12，要求连续两轮无入口故障、无 outcome unknown、DB 2000/2000。
+5. 通过后再判断 2000 人容量；不要在问题未清零前提高并发。
+
+## 9. 产物
+
+- 结果目录：`loadtest/im-pressure/results/group2k-r11-20261004-01/`
+- 汇总：`report.json`
+- 数据库核验：`db-verification.json`
+- A/B 明细：`agent-a-summary.json`、`agent-b-summary.json`
+- 协调器台账：`coordinator.json`
+- 指标：`metrics.jsonl`
+- 被测代码：`b05e8f6 perf(group): reduce websocket fanout serialization`
+
+## 10. 分析后已实施修复
+
+已完成以下 Kafka 持久化修复，待发版后先执行持久化专项，再进行 R12：
+
+1. 批量抓取在取得部分消息后遇到 broker/网络错误时，不再丢弃已抓消息；消费者会先处理并提交这部分消息，同时保留错误日志。
+2. 批准备过程中后续消息 claim 失败时，先持久化并完成前面已经 claim 的消息，再将准备错误交给外层重试，避免整批 processing claim 活锁。
+3. 新增半批 fetch error、首次 fetch error、部分 claim 后准备失败、刷盘与准备同时失败等回归测试。
+
+验证结果：
+
+- Kafka 定向单元测试通过。
+- `go test ./server ./server/store/... ./loadtest/im-pressure` 通过。
+- Kafka 定向 `go test -race` 通过。
+- `go vet` 仍报告 `server/internal_cultivate_test.go` 中既有的 `sync.Map` 锁值复制问题，与本次改动无关。

docs/test/IM-group2k-r12-双机群聊复测分析-20261005.md

@@ -0,0 +1,168 @@
+# GROUP-2000 R12 双机群聊复测分析
+
+## 1. 结论
+
+`group2k-r12-20261004-01` 判定为 **失败，2000 人群聊容量仍未通过**。
+
+本轮有一个明确的正向结果：R11 后的 Kafka 部分批次修复已经生效。服务端实际接收并可从投递或历史中确认的 1694 条消息，MySQL 精确找到 1694 条，缺失、错配、重复和额外记录均为 0。
+
+实时链路仍然失败。A/B 虽然均以 1000/1000 条连接起跑，但负载开始约 33 秒后公网 `/metrics` 开始连续超时，随后出现两波大规模 WebSocket reset。最终实时到达率只有 74.739%，ACK P95 为 74.72 秒，包含迟到 ACK 的控制响应 P95 达 407.90 秒。
+
+与 R11 不同，本轮 Pod 没有重启，日志也没有再次出现 CoreDNS 超时。证据表明本轮先发生群 Topic 串行处理积压和入口响应失速，连接被成批 reset 后又触发重连风暴，三个 Pod 的业务库连接池均出现约 9,200-11,350 秒累计等待，最终形成放大回路。
+
+## 2. 核心结果
+
+| 指标 | R12 结果 | 判定 |
+| --- | ---: | --- |
+| WS 起跑就绪 | 2000/2000 | 通过 |
+| A/B 起跑差 | 约 33ms | 通过 |
+| 发送尝试 | 2000 | A/B 各 1000 |
+| 最终明确 ACK | 1501 | 75.05%，失败 |
+| 发送结果未知 | 499 | 失败 |
+| 服务端接收/回查确认消息 | 1694 | 另有 306 条未确认进入服务端 |
+| ACK P95 | 74.72s | 失败 |
+| 含迟到 ACK 的控制响应 P95 | 407.90s | 失败 |
+| 期望实时投递 | 3,388,000 | 1694 x 2000 |
+| 实际实时投递 | 2,532,160 | 到达率 74.739% |
+| 实时缺失 | 855,840 | 丢失率 25.261% |
+| MySQL 精确核验 | 1694/1694 | 通过 |
+| 重复 / 乱序 | 0 / 0 | 已收到部分正确 |
+| WS 断连 | 1257 | 失败 |
+| Pod 重启 | 0 | 无应用容器重启 |
+
+`publish_final_accepted=1501` 只统计客户端最终观察到的 ACK。数据库和消息台账共同证明实际有 1694 条进入服务端，因此其中 193 条属于客户端未拿到 ACK、但服务端已经处理的消息。
+
+## 3. A/B 分机结果
+
+| 指标 | 机器 A | 机器 B |
+| --- | ---: | ---: |
+| 起跑连接 | 1000 | 1000 |
+| 发送尝试 | 1000 | 1000 |
+| 及时 ACK | 547 | 601 |
+| 迟到 ACK | 327 | 26 |
+| 结果未知 | 126 | 373 |
+| 收到群消息 | 1,389,624 | 1,142,536 |
+| 实时缺失 | 304,376 | 551,464 |
+| 断连 | 433 | 824 |
+| 主要断连原因 | reset 413、timeout 20 | abnormal close 405、reset 419 |
+
+B 在第一波连接重置中受影响更重；第二波则同时影响 A/B，不能归因于单台压测机。
+
+## 4. 故障时间线
+
+时间均为 UTC，北京时间加 8 小时：
+
+- 15:57:31：A/B 同步起跑，2000 个连接全部就绪。
+- 15:57:34-15:57:41：公网 `/metrics` 已从亚秒上升到约 2.5 秒。
+- 15:58:04：公网 `/metrics` 首次 10 秒超时；此后连续 28 次超时。
+- 15:58:24-15:58:59：第一波约 394 条服务端连接集中关闭，主要对应 B；B 汇总为 405 条 abnormal close。
+- 16:00:15 起：`im-server-0` 开始出现用户缓存更新队列满，窗口内共 78 次。
+- 16:01:50-16:02:10：第二波约 810 条服务端连接集中关闭；A/B 汇总的 reset 合计为 832 条。
+- 16:02:06 起：大量重连登录出现 `context deadline exceeded`。
+- 16:02:08：`im-server-1` readiness 请求本身超时；期间还出现一次 liveness 超时，但未达到重启阈值。
+- 16:02:39-16:02:47：三个 Pod 均产生 readiness 503 事件。
+- 16:02:48、16:02:50：`im-server-2`、`im-server-1` 恢复 Ready；`im-server-0` 未形成持续 NotReady。
+- 16:05:04：公网 `/metrics` 恢复 200，首次恢复请求仍耗时约 4.6 秒。
+- 16:11:55：A/B 汇总完成。
+
+三个 Pod 的 `restartCount` 均为 0。R11 出现过的 `10.43.0.10:53`、`no such host`、DNS connection refused 在本轮窗口内均未出现，因此不能继续把本轮失败归因于 CoreDNS。
+
+## 5. 容量瓶颈
+
+群 Topic master 位于 `im-server-2`。最终指标显示：
+
+| 指标 | 数值 |
+| --- | ---: |
+| 群发布处理次数 | 1694 |
+| Topic publish 处理总耗时 | 116.59s |
+| 单条平均处理耗时 | 约 68.8ms |
+| Topic 队列等待总耗时 | 2279.92s |
+| 单条平均排队 | 约 1.35s |
+| 队列等待最大桶 | 30s 内 |
+| master 广播总耗时 / 次数 | 21.33s / 4803 |
+| master 单次广播平均耗时 | 约 4.4ms |
+
+按 68.8ms 的串行 Topic 处理耗时估算，单群持续处理能力约为 14.5 条/秒，低于本轮约 20 条/秒的目标发送速率。共享序列化后的广播本身仍然只有毫秒级，不是主要瓶颈；耗时主要位于 Topic publish 的保存、Kafka produce、权限检查和推送准备等关键路径。
+
+这也解释了为何在正式断连前 ACK 已经出现 20-90 秒长尾，并且 `/metrics` 先失去响应。
+
+## 6. 断连与入口
+
+Pod 日志中的两波连接关闭均来自入口上游连接；客户端看到的是三个源站 IP 返回 `connection reset by peer`，不是主动退出压测程序：
+
+- 第一波关闭连接的服务端会话寿命平均约 122 秒，集中影响 B。
+- 第二波同时影响 A/B；旧连接寿命主要集中在约 330 秒和 660 秒，说明它是同一时刻的批量重置，而非每条连接独立超时。
+- 三个源 IP 最终汇聚到同一个入口上游地址的现象仍然存在，入口层缺少副本、连接上限、reload/restart、upstream reset 和节点 conntrack 证据。
+
+应用负载先失速，入口随后批量 reset，因此当前不能只改客户端重连参数来宣告通过。运维仍需补齐 Traefik、入口节点和 Service endpoint 的同窗口证据，判断 reset 是入口进程、节点网络、连接上限还是上游超时策略触发。
+
+## 7. 重连放大与数据库
+
+压测前后业务库连接池增量如下：
+
+| Pod | 新增等待次数 | 新增累计等待 | 平均每次等待 |
+| --- | ---: | ---: | ---: |
+| im-server-0 | 817 | 9956.29s | 约 12.2s |
+| im-server-1 | 770 | 9218.27s | 约 12.0s |
+| im-server-2 | 768 | 11348.20s | 约 14.8s |
+
+每个 Pod 的 `meeting_im` 最大连接数为 24。连接集中断开后，压测端自动重连触发登录、用户状态、IP 白名单和认证版本查询，连接池等待迅速升高；登录进一步超时，readiness 中的数据库检查也随之失败，Pod 被入口摘除，形成反馈回路。
+
+不能简单地只提高连接池上限。下一轮前应先定位连接被长时间占用的 SQL/事务，并为登录重连增加服务端限流、排队和抖动；否则只是把压力转移到 MySQL。
+
+## 8. Kafka 与落库
+
+数据库直连核验结果：
+
+| 项目 | 结果 |
+| --- | ---: |
+| tenant | allrich / tenant_id=8 |
+| 期望消息 | 1694 |
+| 精确找到 | 1694 |
+| 缺失 | 0 |
+| 字段错配 | 0 |
+| 重复行 | 0 |
+| 额外记录 | 0 |
+| 分表 | `im_008_group_messages_202610`、`im_008_messages` |
+
+这证明 R11 的 Kafka 部分批次丢弃问题已修复。最后一次公网指标采样中某个 reader 的本地 `im_kafka_consumer_lag` 仍显示 111，但稍后的数据库核验已经完整；再次说明 `kafka-go Reader.Stats().Lag` 不能作为 consumer group 已提交 offset 的最终依据。
+
+## 9. 改进优先级
+
+### P0：群 Topic 关键路径
+
+1. 对 Topic publish 的 save、Kafka produce、权限查询、推送准备分别补充 P95/P99 和并发占用，确认 68.8ms 的主要组成。
+2. 将不要求阻塞 ACK 的推送准备、通知类工作移出 Topic 单写者关键路径。
+3. 对必须保持顺序的持久化和序列分配设计有界流水线；保持同群顺序和失败可重试，不能重新引入已移除的业务 outbox。
+4. 优化后先跑 10、12、15、18、20 msg/s 阶梯，连续两轮确认 Topic 队列不持续增长，再重新判定 20 msg/s 容量。
+
+### P0：入口批量 reset
+
+1. 由运维提取 15:57:30-16:05:10 的 Traefik Pod 日志、事件、restart、reload、upstream reset 和打开连接数。
+2. 核对三个公网源 IP 是否最终只有一个 Traefik 实例承载；入口至少配置两个副本、反亲和和 PDB。
+3. 同步采集节点 conntrack、TCP retransmit、listen overflow、文件描述符、网卡丢包和 CPU throttling。
+4. 下一轮同时探测公网域名、每个源 IP、Service 和三个 Pod，避免 `/metrics` 单点失明。
+
+### P1：重连保护
+
+1. 客户端维持自动重连，但使用指数退避和随机抖动，避免 2000 条连接同步登录。
+2. 服务端对登录重建增加有界并发和快速过载响应，不让请求无限占用数据库连接池。
+3. 分解登录 SQL 指标，定位连接池长等待对应的查询或事务。
+4. readiness 的数据库检查应使用独立的小连接预算或短路缓存，避免业务池耗尽导致全部 Endpoint 同时被摘除；liveness 继续只检查进程存活。
+
+## 10. 下一轮顺序
+
+1. 先做 2000 连接、0 发消息的 15 分钟稳定性测试，排除入口固定连接寿命和 B 网络路径问题。
+2. 再做单群阶梯：10、12、15、18、20 msg/s，每档 5 分钟，观察 Topic queue 是否线性增长。
+3. 完成入口和数据库现场采集后，重复 R12 原参数两轮。
+4. 通过标准：2000/2000 连接全程稳定、发送成功率不低于 99.99%、实时到达率不低于 99.99%、DB 精确落库、无批量 reset、无持续 Topic/DB 队列增长。
+
+## 11. 产物
+
+- 结果目录：`loadtest/im-pressure/results/group2k-r12-20261004-01/`
+- 汇总：`report.json`
+- 数据库核验：`db-verification.json`
+- A/B 明细：`agent-a-summary.json`、`agent-b-summary.json`
+- 协调器台账：`coordinator.json`
+- 指标：`metrics.jsonl`
+- 被测代码：`965f94f fix(kafka): preserve partially fetched message batches`

docs/test/IM-group2k-r4-群聊复测分析-20260928.md

@@ -0,0 +1,134 @@
+# IM 2000 人群聊 r4 复测分析
+
+日期：2026-09-28
+
+Run ID：`group2k-r4-20260928-01`
+
+场景：机器 A/B 各 1000 个 WebSocket、各发送 1000 条，计划共发送 2000 条群消息。
+
+## 1. 结论
+
+本轮不能按合并报告中的 `14.39%` 实时丢失率直接判定服务端群消息丢失。两台压测机结果存在明显单边故障：
+
+- 机器 B 的 1000 个连接全部稳定，1000 次发送全部收到 ACK，1497000 次 ACK 台账内投递全部到达，断线和实时缺失均为 0。
+- 机器 A 出现 654 次断线、314 次 socket 错误和 189 次 ACK 超时。A 的 TCP 源地址错误中包含 `broken pipe`、`websocket closed`，是本轮 430832 次实时缺失的主要来源。
+- 服务端实际接受并持久化 1601 条消息，其中客户端收到 ACK 1497 条，另外 104 条属于“客户端未收到 ACK，但服务端已接受”。B 恰好多收到 104000 次消息，即 104 条乘以 B 的 1000 个连接，账目完全吻合。
+- ACK 台账内 1497 条消息历史回查全部找到，`persistence_lost=0`；Kafka 群消息消费 lag 在采样点均为 0。
+- 上一轮的 O(群成员数) Redis fanout 放大已经消除：1601 条服务端消息只产生 1601 次 `group_unread/users` publish，每个远端 Pod 各 receive 1601 次，不再产生约 320 万次逐用户 Redis publish。
+- 实时发送与 60 秒收尾阶段没有新增 `topic_server` 或 `cluster_topic_proxy` 满队列。满队列发生在约 5 分钟后的并发历史回查阶段，属于另一项需要优化的问题，不能作为本轮实时丢失的原因。
+
+因此，本轮结论为：**批量群未读 fanout 修复通过；B 侧实时投递通过；数据库持久化通过；A 侧网络稳定性失败；历史回查并发会打满 Topic/Proxy 队列。整体尚不能完成 2000 人群聊验收。**
+
+## 2. 客户端结果
+
+| 指标 | A | B | 合计 |
+|---|---:|---:|---:|
+| READY 连接 | 1000 | 1000 | 2000 |
+| 发送尝试 | 1000 | 1000 | 2000 |
+| 收到 2xx ACK | 497 | 1000 | 1497 |
+| 明确拒绝 | 0 | 0 | 0 |
+| ACK 超时 | 189 | 0 | 189 |
+| socket 结果未知 | 314 | 0 | 314 |
+| 断线 | 654 | 0 | 654 |
+| ACK 台账内应收 | 1497000 | 1497000 | 2994000 |
+| ACK 台账内实收 | 1066168 | 1497000 | 2563168 |
+| ACK 台账内实时缺失 | 430832 | 0 | 430832 |
+| ACK 台账外额外投递 | 68668 | 104000 | 172668 |
+| 重复 / 乱序 | 0 / 0 | 0 / 0 | 0 / 0 |
+| 历史检查 / 找到 | 1497 / 1497 | 0 / 0 | 1497 / 1497 |
+
+合并报告按 ACK 台账计算出的到达率为 `85.61%`，但这只是 A/B 网络条件混合后的观测值，不代表服务端总体投递率。B 单机的 ACK 台账内到达率是 `100%`，A 单机是 `71.22%`。
+
+A 端记录了 160074 个跨机器负延迟样本，说明两机时钟没有达到单向延迟统计要求。本轮不使用跨机器 P95/P99 判断性能，只使用 ACK、到达计数、断线、历史回查和服务端阶段指标判断正确性。
+
+## 3. 未收到 ACK 的 503 条不是服务端拒绝
+
+本轮没有任何明确的 HTTP/Tinode `503` 响应。报告字段 `publish_rejected=503` 实际由以下结果未知项组成：
+
+- `ctrl_timeout=189`
+- `socket=314`
+
+服务端持久化计数增加 1601，而 ACK 只有 1497，说明至少 104 条结果未知消息已被服务端成功接受。B 的 `unexpected_messages=104000` 与这 104 条消息对 1000 个 B 连接的广播数量完全一致。
+
+后续报告应把字段继续显示为 `publish_unknown`，不能把它展示为 `rejected`，否则容易误判服务端主动拒绝。
+
+## 4. 服务端与中间件
+
+### 4.1 Kafka 与数据库落库
+
+- `im_kafka_message_persist_total{kind="group",result="batch_ok"}` 增加 1601。
+- `im.group.message.persist` consumer lag 在采样点均为 0。
+- 1497 条 ACK 台账消息通过历史接口全部找到，持久化缺失为 0。
+- 服务端群消息 `save` 总耗时增加约 26.27s，平均约 16.4ms/条。
+- Kafka produce 总耗时增加约 19.15s，平均约 12.0ms/条。
+
+这证明已接受消息能够及时进入 Kafka 并完成落库。104 条结果未知消息也计入 1601 条 batch success，但当前历史校验只以 ACK 台账为准，下一版应对“已观测但未 ACK”的消息也做 message ID 回查。
+
+### 4.2 Redis fanout 修复验证
+
+1601 条服务端接受消息对应：
+
+- master Pod `group_unread/users publish ok` 增加 1601。
+- 两个远端 Pod 的 `group_unread/users receive ok` 各增加 1601。
+- 普通 `message/user` 在原生 Cluster 开启时继续使用 `skip_native_cluster`，没有恢复逐成员 Redis 发布。
+
+这符合“一条群消息一次 Redis publish、每个 Pod 一次本地扫描”的设计，上一轮每条消息约 2000 次 Redis publish 的放大已经消失。
+
+### 4.3 队列满发生在历史回查阶段
+
+按时间序列拆分：
+
+- `16:25:05Z` 开始发送。
+- `16:28:36Z` 最后一台压测机结束发送，之后进入收尾和历史等待。
+- 截至 `16:34:01Z`，`topic_server/full` 仍停留在测试前基线 1349，`cluster_topic_proxy/full` 仍为 0。
+- `16:34:25Z` 起，历史回查并发开始使 `topic_server/full` 增加。
+- 最终历史阶段新增 `topic_server/full=1355`、`cluster_topic_proxy/full=55`。
+
+因此这些队列丢弃不是实时发送阶段 430832 次缺失的原因。历史回查一次并发拉取大量消息，经 Topic/Proxy 回送时会形成独立洪峰，应限制每机历史校验并发或分页节流，并单独验收历史吞吐。
+
+## 5. A 机器故障判断
+
+A 与 B 使用相同代码、相同公共入口和相同发送模型，但只有 A 发生 654 次断线。A 的错误包含：
+
+- `websocket closed`
+- `write: broken pipe`
+- `ctrl timeout`
+- 到多个公网入口 IP 的 TCP 读写超时
+
+这种强烈单边性不符合服务端全局过载的表现。当前最可能的故障域依次是 A 本机网络/NAT/安全软件、A 到公网 LB 的链路、A 的文件描述符或本地调度压力。由于 Kubernetes Metrics API 被 RBAC 拒绝，本轮没有取得 Pod CPU/内存数据，不能用资源指标进一步排除 Pod 饱和。
+
+## 6. 下一轮执行顺序
+
+1. 先做 A/B 角色互换：B 仍发 1000 条，A 暂时只保持 1000 个连接不发送。若 A 仍大量断线，可确认与服务端发送负载无关。
+2. 在 A 机同步采集 `ping`、TCP retransmit、连接跟踪、文件描述符、CPU、内存和进程调度数据；压测前检查 `ulimit -n`。
+3. 将历史回查改为分页和限并发，或先关闭自动历史回查，仅验证实时阶段；实时阶段结束后再启动独立历史校验。
+4. 修正报告字段，把超时/socket 明确归类为 `publish_unknown`，并把 104 条 unacked-observed 消息纳入历史校验。
+5. 补充 `backend-debug` 对 `metrics.k8s.io/pods` 的只读权限，否则下一轮仍无法采集 Pod CPU/内存。
+6. A 链路稳定后，使用相同 2000 连接、2000 条消息模型重新验收。门禁要求两侧断线为 0、明确拒绝为 0、实时到达率 100%、持久化丢失为 0，并分别报告实时阶段和历史阶段的队列指标。
+
+## 7. 结果文件
+
+本轮原始结果位于：
+
+```text
+loadtest/im-pressure/results/group2k-r4-20260928-01/
+  agent-a-summary.json
+  agent-b-summary.json
+  coordinator.json
+  report.json
+  pre-metrics.log
+  pod-metrics.log
+  post-metrics.log
+```
+
+## 8. 已实施改造
+
+本分析完成后，压测工具已实施以下改造：
+
+1. agent 分开输出 `publish_rejected` 和 `publish_outcome_unknown`；前者只包含服务端明确拒绝，后者包含 ACK 超时和 socket 失败。
+2. A/B 在 drain 后向 coordinator 提交“实时已观测但未 ACK”的消息台账，coordinator 去重合并后将其加入历史落库核验。
+3. 报告新增 `history_unacked_observed_checked` 和 `history_unacked_observed_found`，可直接确认结果未知消息是否最终落库。
+4. r5 复测后，历史回查进一步调整为 1 个 worker、每页 20 条、全局每 500ms 最多发起一次查询，避免核验程序自身制造 Topic/Proxy 洪峰。
+5. 新增 `backend-debug-metrics-rbac.yaml`，为测试环境的 `argocd/backend-debug` ServiceAccount 提供 `metrics.k8s.io/pods` 的 namespace 只读权限。
+
+上述改造只解决统计口径、历史查询压力和资源指标权限。机器 A 的公网连接异常仍需通过下一轮主机与网络观测定位。

docs/test/IM-group2k-r5-群聊复测分析-20260928.md

@@ -0,0 +1,92 @@
+# IM 2000 人群聊 r5 复测分析
+
+日期：2026-09-28
+
+Run ID：`group2k-r5-20260928-01`
+
+## 1. 结论
+
+本轮再次证明服务端对稳定客户端的群消息可靠性没有丢失，失败集中在机器 A 的本地代理/TUN 链路：
+
+- B：1000 次发送全部 ACK，1426000 次 ACK 台账内投递全部到达，断线、重复、乱序和实时缺失均为 0。
+- A：574 次发布结果未知、657 次统计窗口内断线、464596 次 ACK 台账内实时缺失。
+- A 的 broken pipe 全部写向 `198.18.0.81:443`；本机 DNS 也将 `api.118im.com` 解析为 `198.18.0.81`，路由经 `utun19827 -> 172.19.0.1`。`198.18.0.0/15` 是代理/TUN 常用 Fake-IP 网段，不是 API 的真实公网地址。
+- 机器 A 压测进程 CPU 平均占用不高、内存峰值约 150MB，B 在同一服务端负载下完全稳定，不支持“服务端全局过载”解释。
+- 新增观测台账生效：574 条结果未知中，241 条被实时观测并加入历史核验，241 条全部找到。
+- 历史总核验 1667/1667，持久化丢失为 0。
+- 历史回查仍产生 1197 次 `topic broadcast queue full`，但全部发生在历史阶段，不在实时发送阶段。
+
+总体结论：**群消息落库通过，B 侧实时可靠性通过；A 侧 TUN/Fake-IP 链路失败；历史查询限速仍需继续降低。**
+
+## 2. 汇总结果
+
+| 指标 | A | B | 合计 |
+|---|---:|---:|---:|
+| READY | 1000 | 1000 | 2000 |
+| 发送尝试 | 1000 | 1000 | 2000 |
+| ACK | 426 | 1000 | 1426 |
+| 明确拒绝 | 0 | 0 | 0 |
+| ACK 超时 | 444 | 0 | 444 |
+| socket 结果未知 | 130 | 0 | 130 |
+| 断线 | 657 | 0 | 657 |
+| ACK 台账内应收 | 1426000 | 1426000 | 2852000 |
+| ACK 台账内实收 | 961404 | 1426000 | 2387404 |
+| ACK 台账内实时缺失 | 464596 | 0 | 464596 |
+| ACK 台账外额外投递 | 185738 | 241000 | 426738 |
+| 历史核验 | 1667/1667 | 0/0 | 1667/1667 |
+| 未 ACK 观测消息核验 | 241/241 | 0/0 | 241/241 |
+
+服务端实际处理消息至少为 `1426 + 241 = 1667` 条。其余 333 条结果未知既没有 ACK，也没有任何实时观测证据，不能证明服务端接受。
+
+## 3. A 机器故障证据
+
+### 3.1 网络路径
+
+测试结束后的本机检查结果：
+
+```text
+api.118im.com -> 198.18.0.81
+route: 198.18.0.81 -> gateway 172.19.0.1, interface utun19827
+broken pipe remote: 198.18.0.81:443
+```
+
+A 的错误构成为：
+
+- `ctrl_timeout=444`
+- `websocket_closed=103`
+- `broken_pipe=27`
+- 其他 1
+
+连接从 `17:05:12 UTC` 开始下降，随后从 1000 持续降至约 333；B 同期保持 1000 连接。下一轮前必须关闭该代理/TUN，或至少将 `api.118im.com` 设置为 DIRECT，并确认 DNS 不再返回 `198.18.0.0/15` Fake-IP。
+
+### 3.2 本机资源
+
+- 进程 RSS 峰值约 150MB。
+- 压测期间累计 CPU 增量约 75 秒，对约 625 秒窗口而言不构成 CPU 饱和。
+- open FDs 在连接大量断开后仍约为 1011。`WSClient.readLoop` 在读失败返回时没有立即关闭底层连接，虽然进程结束时会统一关闭，但应修复运行期 FD 滞留。
+
+## 4. 服务端和历史核验
+
+实时发送和 drain 阶段没有新增以下错误：
+
+- `sub.broadcast channel full`
+- `cluster: proxy channel full`
+- `topic's broadcast queue is full`
+- Redis fanout publish failure
+
+历史核验约在 `17:13:15 UTC` 开始。`im-server-2` 从 `17:13:22` 到 `17:14:14` 记录 1197 次群 Topic broadcast queue full。当前 1 worker、每页 50 条、100ms 间隔仍会让单次历史回放快速灌入容量为 64 的 Topic 队列。
+
+尽管重试后 1667 条全部找到，历史核验不应持续制造队列丢弃。建议调整为：
+
+- `history_page_size=20`
+- `history_query_interval=500ms`
+- `history_workers=1`
+- 历史超时保持 3 分钟；1667 条约需 42 秒完成首轮查询。
+
+## 5. 下一步
+
+1. 修复 `WSClient.readLoop` 退出时未关闭底层连接的问题。
+2. 将历史分页调整为 20 条、查询间隔 500ms。
+3. 在 A 机关闭 TUN/代理，或配置 `api.118im.com` DIRECT；起压前检查 DNS 和路由不再进入 `198.18.0.0/15`、`utun*`。
+4. 测试环境尚未应用 metrics RBAC，`kubectl auth can-i list pods.metrics.k8s.io` 仍返回 `no`，因此本轮没有 Pod CPU/内存数据。需要将 `backend-debug-metrics-rbac.yaml` 加入实际 ArgoCD overlay。
+5. 完成上述三项后再运行同规模 r6。若 A/B 都稳定，再根据 B 本轮 ACK P95 约 1.14s、同机投递 P95 位于 2s 桶的结果继续做服务端延迟优化。

docs/test/IM-group2k-r6-群聊复测分析-20260928.md

@@ -0,0 +1,93 @@
+# IM 2000 人群聊 r6 复测分析
+
+日期：2026-09-28
+
+Run ID：`group2k-r6-20260928-01`
+
+## 1. 结论
+
+r6 比 r5 有改善，但仍未通过。A 去掉 Fake-IP 后 ACK 数从 426 增加到 758，统计窗口断线从 657 降到 213；然而 `api.118im.com` 的真实公网 IP 仍经 `utun4`，A 在正式开始前就发生 28 次连接抖动，正式开始后继续成批断线。后续排查确认该 `utun4` 由 OpenVPN Connect 的全局路由持有，而不是 LightXtreme。B 也出现 2 次断线和 1 次发布结果未知，不再是完全零错误。
+
+历史落库仍然可靠：ACK 台账和未 ACK 观测台账合计核验 1870/1870，持久化丢失为 0。FD 修复已验证生效，A 的存活连接从 1000 降至 787 时，open FDs 从约 1013 同步降至约 799，不再滞留断开的 socket。
+
+历史限速和退出行为仍会污染服务端队列指标：历史查询阶段约产生 436 次 Topic 队列满；A 结束时一次性关闭大量群订阅连接，又集中产生约 598 次队列满。
+
+总体结论：**落库正确性通过；FD 修复通过；实时可靠性失败；A 的 OpenVPN/TUN 链路仍未绕过；历史回放与集中断连仍需改进。**
+
+## 2. 汇总结果
+
+| 指标 | A | B | 合计 |
+|---|---:|---:|---:|
+| READY | 1000 | 1000 | 2000 |
+| 发送尝试 | 1000 | 1000 | 2000 |
+| ACK | 758 | 999 | 1757 |
+| ACK 超时 | 122 | 0 | 122 |
+| socket/连接结果未知 | 120 | 1 | 121 |
+| 实际明确拒绝 | 0 | 0 | 0 |
+| 断线 | 213 | 2 | 215 |
+| ACK 台账内应收 | 1757000 | 1757000 | 3514000 |
+| ACK 台账内实收 | 1468873 | 1756514 | 3225387 |
+| ACK 台账内实时缺失 | 288127 | 486 | 288613 |
+| ACK 台账外额外投递 | 94965 | 112984 | 207949 |
+| 历史核验 | 1870/1870 | 0/0 | 1870/1870 |
+| 未 ACK 观测消息核验 | 113/113 | 0/0 | 113/113 |
+
+服务端实际处理消息至少为 `1757 + 113 = 1870` 条。其余 130 条结果未知没有 ACK 或实时观测证据，不能证明服务端接受。
+
+## 3. 报告口径修正
+
+合并报告当前显示 91 次明确拒绝和 152 次结果未知，这是错误分类：
+
+- A 的 91 次 `use of closed network connection` 被归类为 `other`。
+- 该错误是连接关闭后的写失败，应该归类为 `socket` 结果未知。
+- 修正后本轮明确拒绝为 0，结果未知为 243。
+
+此外，群历史只由 A 执行。A 已证明全部 1757 条 ACK 消息落库，但 B 的 `realtime_lost_but_persisted` 无法读取 A 的历史结果，因此 B 的 486 次实时缺失没有计入“实时缺失但已落库”。合并报告需要共享全局历史核验结果后再计算该字段。
+
+## 4. A 网络与 FD
+
+本轮 DNS 返回真实地址：
+
+```text
+64.118.158.131
+216.236.31.189
+216.236.31.191
+```
+
+但到真实地址的系统路由仍为：
+
+```text
+gateway: 172.27.240.1
+interface: utun4
+```
+
+这说明 Fake-IP 已关闭，但流量仍进入 VPN/TUN。A 在 barrier 提交前持续掉线重连，正式开始后约 50 秒开始掉线，最终只剩约 787 个连接。后续确认 OpenVPN Connect 下发了 `0/1` 和 `128.0/1` 两条全局路由；LightXtreme 的 DIRECT 规则无法绕过另一套 OpenVPN TUN。r7 前已为 `api.118im.com` 当前三个 IP 添加经 `192.168.1.1/en1` 的 `/32` 主机路由，保留 OpenVPN 内网访问的同时让压测 HTTP/WS 直连。
+
+FD 时间序列证明 read loop 修复有效：
+
+- READY 1000 时 open FDs 约 1013。
+- READY 901 时 open FDs 约 913。
+- READY 787 时 open FDs 约 799。
+
+连接每减少一个，FD 基本同步减少一个。
+
+## 5. Topic 队列满
+
+实时发送和 drain 阶段仍没有 Topic/Proxy 满队列。`im-server-2` 的 1034 次 `topic's broadcast queue is full` 分为：
+
+- `00:35:59–00:36:11 UTC`：约 436 次，发生在历史回查阶段。
+- `00:37:19 UTC`：约 598 次，发生在 A agent 完成后批量关闭连接阶段。
+
+20 条/500ms 虽有改善，但 Topic 历史数据仍以突发方式回送。建议：
+
+1. 历史每页进一步降至 10 条，查询间隔保持 500ms。
+2. 每页请求后等待本页目标消息全部收到或超时，再发送下一页，而不是只按固定时间节流。
+3. agent 退出时按 10–20ms 间隔分批关闭连接，避免 1000 个群订阅同时离线。
+
+## 6. 后续修复
+
+1. 已将 `use of closed network connection` 分类为 socket 结果未知。
+2. 已在 coordinator 共享两机历史命中 ID，使 B 也能正确计算实时缺失但已落库。
+3. 历史回查已改为每页 10 条：同一 Topic 每页完成确认后再请求下一页，不同 Topic 最多 12 路并行。
+4. agent 已改为在 10 秒窗口内渐进关闭 WebSocket。
+5. r7 开始前重新解析 `api.118im.com`，确认每个 IP 都通过 `/32` 主机路由走 `en1`；OpenVPN 重连、DNS 变更或机器重启后必须重新核验。

docs/test/IM-group2k-r9-双机群聊压测分析与改进-20261003.md

@@ -0,0 +1,73 @@
+# GROUP-2000 R9 双机群聊压测分析与改进
+
+## 1. 结论
+
+`group2k-r9-20261003-01` 不能作为 2000 人群聊容量结论。消息最终落库完整，但实时阶段同时发生机器 B 迟到、Pod 重启和集群 DNS 拒绝查询，导致大量连接断开和跨机器投递缺失。
+
+- 发送尝试 2000 条，数据库精确找到 1774 条服务端已确认消息，缺失、重复、字段不一致均为 0。
+- 实时期望投递 3,548,000 次，实际收到 1,384,872 次，到达率约 39.03%。
+- 机器 B 比 coordinator 的计划起跑时间晚约 7 分 55 秒；B 未收到任何 A 消息，本轮并非有效的同步双机负载。
+- `im-server-1` 在负载中退出，容器退出码 137；现有权限无法读取 Event 和 Pod metrics，尚不能把原因唯一归为 OOM、liveness 或节点压力。
+- 三个 Pod 合计约 1715 次依赖域名解析失败，日志包含对集群 DNS `10.43.0.10:53` 的 `connection refused`。
+- JPush 设备查询产生 792 次数据库错误；用户更新队列满 1132 次，属于依赖抖动和连接重建后的次生压力。
+
+Kafka 持久化链路本轮表现正确：各 Pod 批量持久化计数合计 1774，与数据库精确核验一致，之前的失败消息保留修复已生效。
+
+## 2. 根因链路
+
+### 2.1 JPush 查询按群消息放大
+
+JPush 使用 registration ID 模式时，每条群消息都会按全部收件人重新查询 `im_device_push_tokens`。2000 人群和 2000 条消息会形成约 400 万个用户查询输入；测试账号没有推送设备，旧实现仍重复查询空结果。JPush 回执又以无限 goroutine 并发处理，使查询、对象分配和内存压力同时放大。
+
+### 2.2 MySQL 连接每 60 秒回收
+
+旧配置的 `conn_max_lifetime=60` 会在持续压测期间频繁重建连接。每次建连都重新解析 `mysql.118im.com`；当集群 DNS 短时拒绝请求时，业务查询、JPush 查询和 Kafka 持久化会一起失败或等待。
+
+### 2.3 双机只有计划时间，没有最终到达屏障
+
+旧协议在双方 READY 后下发统一时间，但 agent 到达该时间后直接发送。机器 B 晚启动时，机器 A 无法知道对方没有真正进入发送阶段，因此形成两段错开的单机流量并生成无效的跨机器统计。
+
+## 3. 已完成改进
+
+### 3.1 JPush
+
+- 设备查询结果按租户、provider、用户缓存 30 秒，包含“无设备”结果。
+- 并发首次查询被合并，同一批群成员只访问一次数据库。
+- 查询失败后退避 1 秒，已有缓存可在 5 分钟陈旧窗口内继续使用。
+- 缓存定期清理，避免用户集合长期增长。
+- JPush 回执限制为 8 个工作协程，取消无限 goroutine，队列负责形成背压。
+
+该改动不删除在线多端静默推送语义。新注册或更新的设备最迟约 30 秒进入推送查询结果。
+
+### 3.2 MySQL 与 DNS
+
+- 容器默认 `conn_max_lifetime` 从 60 秒提高到 1800 秒，并支持 `MYSQL_CONN_MAX_LIFETIME_SECONDS` 覆盖。
+- 测试环境 GitOps 显式设置 1800 秒，降低持续负载中的连接重建和 DNS 查询频率。
+- 保留现有 `ndots:1`、`timeout:2`、`attempts:2`。
+
+这会显著减少应用制造的 DNS 压力，但不能替代集群 DNS 修复。若复测仍出现 `10.43.0.10:53 connection refused`，需要集群管理员检查 CoreDNS 副本、CPU、转发上游、conntrack，并评估与当前 K3s 网络模式匹配的 NodeLocal DNSCache；不能在未知网络模式下直接套用 DaemonSet。
+
+### 3.3 压测同步
+
+- coordinator 增加最终起跑屏障。
+- A/B 必须在计划时间前后 3 秒内到达，双方都到达后才开始发送。
+- 任一机器迟到时，两边收到同一失败原因并终止本轮。
+- coordinator 输出保存双方实际到达时间和 `start_error`。
+
+### 3.4 诊断权限
+
+`backend-debug` 只读权限增加 Event 和 `metrics.k8s.io/pods`，用于下一轮区分 OOM、探针失败、驱逐和节点资源压力。若集群未安装 metrics-server，Pod metrics 仍不可用，但 Event 读取不受影响。
+
+## 4. 复测门禁
+
+下一轮使用新 `run_id`，A/B 必须更新到包含起跑屏障的同一提交，并在应用和 GitOps 配置都发布后执行。
+
+1. coordinator 输出中 A/B `started` 时间相差不超过 3 秒，`start_error` 为空。
+2. 2000 条发送全部得到明确 ACK；数据库按 `client_mid` 精确匹配，缺失、重复、字段不一致均为 0。
+3. 实时期望 4,000,000 次投递全部到达，重复、乱序和断连均为 0。
+4. JPush 设备查询不再随群消息数线性增长，日志中 `jpush: db error` 为 0。
+5. Pod 不重启，Event 中无 OOM、Unhealthy、Evicted；负载窗口内持续采集 CPU、内存和重启次数。
+6. `10.43.0.10:53`、MySQL、Redis、Kafka 域名解析错误均为 0。
+7. Kafka lag 最终归零，数据库最终消息数与 ACK 台账一致。
+
+若业务正确性通过但 DNS 仍有拒绝请求，本轮仍判基础设施门禁失败，不继续用增加应用重试掩盖 DNS 容量问题。

docs/test/IM-单机60%容量压力测试方案.md

@@ -0,0 +1,191 @@
+# IM 单机 60% 容量压力测试方案
+
+日期：2026-09-29
+
+本方案首轮执行结果见 [IM-单机60%容量压力测试结果-20260929.md](./IM-单机60%容量压力测试结果-20260929.md)。
+
+## 1. 目标与口径
+
+本方案用一台物理压测机完成单聊、群聊和混合场景，容量按双机正式方案全局规模的 60% 计算。
+
+单机不等于只运行一个 agent。为保留现有好友对和投递契约，同一台物理机上同时运行逻辑 agent A 和 agent B，每个 agent 承载 600 个连接，合计 1200 个 WebSocket。Coordinator 仍使用 `expected-agents=2`。
+
+| 项目 | 双机正式方案 | 单机 60% 方案 |
+|---|---:|---:|
+| 物理压测机 | 2 | 1 |
+| 逻辑 agent | 2 | 2 |
+| 每个 agent 连接 | 1000 | 600 |
+| WebSocket 总连接 | 2000 | 1200 |
+| 好友对 | 1000 | 600 |
+| 群成员 | 2000 | 1200 |
+
+## 2. 场景容量
+
+### 2.1 单聊
+
+- 600 对好友，A/B 各 600 人。
+- 每个用户发送 10 条，每秒 1 条。
+- 总发送尝试 12000 条，是双机 20000 条的 60%。
+- 每条 ACK 消息应在配对用户的 WebSocket 到达一次。
+
+### 2.2 群聊
+
+- 1200 个在线群成员。
+- A/B 各取前 300 个用户作为发送者，合计 600 个发送者。
+- 每人发送 2 条，全局每 100ms 一条，合计 1200 条群消息，耗时约 120 秒。
+- 全部发送被 ACK 时，期望实时投递 `1200 x 1200 = 1,440,000` 次。
+
+### 2.3 单聊和群聊混合
+
+- 前 180 对好友互发，每人 5 条，共 1800 条单聊。
+- A/B 各 150 个群发送者，每人 2 条，共 600 条群消息。
+- 群消息期望实时投递 `600 x 1200 = 720,000` 次。
+- 单聊和群聊同时开始，不分两轮单独执行。
+
+工具按 `users_per_machine` 等比计算发送者数量。`users_per_machine=1000` 时保持原双机参数，设为 600 时自动使用上述单机参数。
+
+## 3. 文件隔离
+
+单机方案不复用双机的运行文件，避免把 1200 人结果和 2000 人结果混在一起。
+
+```text
+loadtest/im-pressure/config.single-machine.json
+loadtest/im-pressure/manifest.single-machine.json
+loadtest/im-pressure/results/<RUN_ID>/
+```
+
+从模板生成本地配置：
+
+```bash
+cp loadtest/im-pressure/config.single-machine.example.json \
+  loadtest/im-pressure/config.single-machine.json
+chmod 600 loadtest/im-pressure/config.single-machine.json
+```
+
+修改租户、HTTP/WS 地址和注册手机前缀。A/B endpoint 可以填同一个公网入口；若需确认跨 Pod 投递，应分别填写两个定向入口。
+
+## 4. 一次性数据准备
+
+```bash
+source loadtest/im-pressure/.env.test
+go build -o loadtest/im-pressure/im-pressure ./loadtest/im-pressure
+ulimit -n 100000
+
+./loadtest/im-pressure/im-pressure prepare \
+  -config loadtest/im-pressure/config.single-machine.json \
+  -manifest loadtest/im-pressure/manifest.single-machine.json
+
+./loadtest/im-pressure/im-pressure verify \
+  -config loadtest/im-pressure/config.single-machine.json \
+  -manifest loadtest/im-pressure/manifest.single-machine.json
+```
+
+`verify` 必须输出 1200 个账号、600 对好友和 1200 个群成员。单机 manifest 可以复用已注册的 `lta0001..0600` 和 `ltb0001..0600` 账号，但必须使用独立群 Topic。
+
+## 5. 正式运行
+
+以群聊为例：
+
+```bash
+export RUN_ID='single60-group-r1-YYYYMMDD-01'
+export SCENARIO='group'
+mkdir -p "loadtest/im-pressure/results/${RUN_ID}"
+```
+
+终端 1，启动 coordinator：
+
+```bash
+./loadtest/im-pressure/im-pressure coordinator \
+  -listen :8090 \
+  -run-id "${RUN_ID}" \
+  -scenario "${SCENARIO}" \
+  -expected-agents 2 \
+  -output "loadtest/im-pressure/results/${RUN_ID}/coordinator.json"
+```
+
+终端 2，启动逻辑 agent A：
+
+```bash
+./loadtest/im-pressure/im-pressure agent \
+  -config loadtest/im-pressure/config.single-machine.json \
+  -manifest loadtest/im-pressure/manifest.single-machine.json \
+  -machine a \
+  -coordinator http://127.0.0.1:8090 \
+  -metrics-listen :9105 \
+  -output "loadtest/im-pressure/results/${RUN_ID}/agent-a-summary.json"
+```
+
+终端 3，启动逻辑 agent B：
+
+```bash
+./loadtest/im-pressure/im-pressure agent \
+  -config loadtest/im-pressure/config.single-machine.json \
+  -manifest loadtest/im-pressure/manifest.single-machine.json \
+  -machine b \
+  -coordinator http://127.0.0.1:8090 \
+  -metrics-listen :9106 \
+  -output "loadtest/im-pressure/results/${RUN_ID}/agent-b-summary.json"
+```
+
+两个 agent 都报告 `600/600 READY` 并稳定通过 30 秒屏障后才会开始。任一 agent 未满连接时 coordinator 会撤销开始时间。
+
+固定 drain 结束后，agent 还会等待入站投递连续静默后再生成实时 summary。默认 `delivery_quiet_period=10s`、`delivery_quiet_timeout=3m`；接收计数增长或回调队列不为空都会重置静默窗口，避免公网晚到帧被误判为实时丢失。
+
+## 6. 指标采集
+
+终端 4 在起压前至少 2 分钟启动：
+
+```bash
+./loadtest/im-pressure/im-pressure collect \
+  -duration 20m -interval 5s \
+  -coordinator http://127.0.0.1:8090 \
+  -coordinator-output "loadtest/im-pressure/results/${RUN_ID}/coordinator.json" \
+  -url agent-a=http://127.0.0.1:9105/metrics \
+  -url agent-b=http://127.0.0.1:9106/metrics \
+  -url node=http://127.0.0.1:9100/metrics \
+  -output "loadtest/im-pressure/results/${RUN_ID}/metrics.jsonl"
+```
+
+同时采集 Redis、Kafka、MySQL、Pod CPU/内存/网络、Kafka consumer lag、MySQL 连接池等指标。如本机没有 `node-exporter :9100`，删除 `node` URL，但不影响 agent 指标采集。
+
+发版后必须在服务端 `/metrics` 确认 `im_ws_heartbeat_seconds{setting="ping_period"}=15`、`im_ws_heartbeat_seconds{setting="pong_wait"}=90`，并采集 `im_ws_heartbeat_total{event="pong_received"}` 和 `im_ws_disconnect_total{reason="timeout"}` 的分 Pod 增量。
+
+混合场景还必须采集 `im_ctrl_ack_delivery_duration_seconds{stage="enqueue"}` 和 `im_ctrl_ack_delivery_duration_seconds{stage="write"}`。agent 端同时采集 `im_load_agent_publish_ctrl_observed_total`、`im_load_agent_publish_ctrl_over_20s_total`、`im_load_agent_publish_ctrl_late_total` 和 `im_load_agent_publish_ctrl_unresolved`，用于区分及时 ACK、超过 20 秒的 ACK、超过命令超时后晚到的 ACK 与最终未到 ACK。
+
+## 7. 报告和独立落库核验
+
+```bash
+./loadtest/im-pressure/im-pressure merge \
+  -a "loadtest/im-pressure/results/${RUN_ID}/agent-a-summary.json" \
+  -b "loadtest/im-pressure/results/${RUN_ID}/agent-b-summary.json" \
+  -output "loadtest/im-pressure/results/${RUN_ID}/report.json"
+
+export MYSQL_DSN='readonly:password@tcp(mysql-host:3306)/meeting_im?parseTime=true'
+export TENANT='006' # 必须与 config.single-machine.json 中的 tenant 一致
+./loadtest/im-pressure/im-pressure verify-db \
+  -coordinator "loadtest/im-pressure/results/${RUN_ID}/coordinator.json" \
+  -tenant "${TENANT}" \
+  -dsn-env MYSQL_DSN \
+  -registry-db hotgo \
+  -output "loadtest/im-pressure/results/${RUN_ID}/db-verification.json"
+```
+
+## 8. 验收门禁
+
+- READY 必须是 `1200/1200`，统计窗口内断连为 0。
+- publish 明确拒绝和结果未知均为 0，成功率至少 99.99%。
+- `publish_ctrl_unresolved` 必须为 0；`publish_ctrl_over_20s` 和 `publish_ctrl_late` 作为定位指标单独报告，不与消息丢失混为一项。
+- ACK P95 和投递 P95 保留记录用于趋势对比，不作为当前公网单机容量测试的阻断门禁。
+- 实时缺失、重复、乱序、未知本轮消息均为 0。
+- ACK 台账和无 ACK 但已观测台账的历史回查命中率必须 100%，独立 MySQL 核验丢失、错配、重复均为 0。
+- 实时发送、历史回查和渐进关闭三个阶段分别统计 Topic/Proxy/Session 队列满，不能只看整轮总数。
+
+## 9. 单机特有风险
+
+1. 两个 agent 共用一台机器的 CPU、内存、FD、NAT 和出口带宽，测到的是“单机压测端 + 服务端”综合上限，不能代替双机最终验收。
+2. 正式前做 120/600/1200 连接三档阶梯，观察 agent CPU、`go_goroutines`、FD、接收速率和 Ping/Pong 断连，确认压测端本身没有先饱和。当前工具已将投递观测按 `client_mid` 分片、接收账号顺序状态独立加锁，使用原子延迟直方图，并将数据统计回调从 WebSocket socket 读循环解耦；仍需用指标证明本机有余量。
+3. 两个 agent 必须使用不同指标端口，不能同时绑定 `:9105`。
+4. 压测域名如被 VPN/TUN 接管，起压前必须确认所有当前 IP 的路由都指向物理网卡。
+5. 单机 60% 通过后只能进入双机 100% 验收，不能直接得出 2000 连接容量通过的结论。
+
+断连时同时查看 agent summary 中的 `disconnect_reasons` 和 `disconnect_samples`。前者按 timeout、abnormal close、connection reset 等原因分类计数，后者最多保留 100 条带账号与时间的原始错误样本，用于区分压测端读循环阻塞、网络中断和服务端主动关闭。

docs/test/IM-单机60%容量压力测试结果-20260929.md

@@ -0,0 +1,949 @@
+# IM 单机 60% 容量压力测试结果
+
+日期：2026-09-29
+
+## 1. 结论
+
+本轮使用一台物理压测机同时运行逻辑 agent A/B，每侧 600 个 WebSocket，合计 1200 连接。60% 容量的正确性和性能总验收未通过。
+
+- 单聊实时和持久化正确性通过；ACK P95 和投递 P95 仅记录，不再作为当前公网单机压测的阻断条件。
+- 群聊在 1200 条群消息、144 万设计投递量下出现 ACK 超时、连接重置和分钟级投递延迟。
+- 混合场景明显越过容量拐点，737 个连接断开，仅 44.83% 发送得到 ACK。
+- 独立 MySQL 核验确认：三个场景的所有 ACK 消息均精确落库，0 错配、0 重复；所有“无 ACK 但 WS 已观测”消息也均已落库。
+- 压测工具本轮峰值 RSS 不超过 127 MB，每个 agent 峰值 FD 614，未显示本机内存或 FD 先饱和。
+- 混合实时阶段的群 Topic 所在 `im-server-0` 出现 broadcast queue full，服务端 Topic 处理能力是已证实的瓶颈之一。
+
+## 2. 环境与口径
+
+- 租户：`allrich`
+- HTTP/WS 入口：`api.118im.com`
+- 物理压测机：1 台
+- 逻辑 agent：A/B 各2个中的一个，每侧 600 连接
+- 账号：1200，好友对：600，群成员：1200
+- API 域名当前 3 个 IP 均经 `en1` 和局域网网关直连，未走 VPN/TUN
+- IM Server：3 Pod，无重启；每 Pod request `1 CPU/512Mi`，limit `2 CPU/1Gi`
+- 独立群与 manifest：`loadtest/im-pressure/manifest.single-machine.json`
+
+准备阶段最终验证为 `accounts=1200 pairs=600 group_members=1200`。群批量邀请曾出现入口 502 和幂等任务长时间处理中，工具通过按实际成员补齐缺失用户完成恢复。
+
+## 3. 结果汇总
+
+| 场景 | Run ID | ACK | 实时投递 | 断连 | ACK P95 | 投递 P95 | 独立 DB 核验 | 结果 |
+|---|---|---:|---:|---:|---:|---:|---:|---|
+| 单聊 | `s60-p2p-r2-0929` | 12000/12000 | 12000/12000 | 0 | 1341.555ms | 2000ms | 12000 ACK 全部精确命中 | 正确性通过 |
+| 群聊 | `s60-group-r1-0929` | 1145/1200 | 1350508/1374000 ACK 台账 | 47 | 11207.859ms | 94621.882ms | 1145 ACK + 39 无 ACK 落库 | 未通过 |
+| 混合 | `s60-mixed-r1-0929` | 1076/2400 | 234829/263657 ACK 台账 | 737 | 17491.634ms | 101226.392ms | 1076 ACK + 1017 无 ACK 落库 | 未通过 |
+
+表中群聊和混合的“期望投递”只按有 ACK 的 ledger 计算。发送结果未知的消息不能在没有 seq 时直接加入期望投递分母，因此该分母小于设计投递量。
+
+## 4. 分场景记录
+
+### 4.1 单聊
+
+R1 的历史查询将 `limit=10` 错误地按目标消息数计算，没有计入 P2P Topic 中双方交错的 seq，造成 4619 条假缺失。修复后 R2 结果：
+
+- 12000 条全部 ACK，无结果未知。
+- 12000 次对端投递全部到达，无重复、乱序、断连。
+- 12000 条历史回查全部命中，持久化缺失 0。
+- ACK P95 1341.555ms，同机投递 P95 落在 2000ms 桶；两项作为公网链路观测数据，不影响正确性验收。
+
+### 4.2 群聊
+
+- 发送 1200 条，1145 条 ACK，43 条 ACK 超时，12 条 socket 结果未知，无明确拒绝。
+- 47 个连接断开：22 个 abnormal close，25 个 connection reset by peer。
+- ACK 台账下实时缺失 23492 次，这些消息最终均可从历史查到。
+- 55 条结果未知中，39 条被接收端实时观测，且全部被独立 SQL 确认落库；另 16 条既无 ACK、无 WS 观测，也无数据库记录。
+- 断连发生时间为 `03:40:10Z` 至 `03:41:15Z`，与群实时发送阶段重合。
+
+### 4.3 混合
+
+- 设计发送为 1800 条单聊和 600 条群聊，合计 2400 条。
+- 1076 条 ACK，1324 条结果未知，其中 1036 条 ACK 超时、288 条 socket 失败，无明确拒绝。
+- 737 个连接断开：69 个 abnormal close，668 个 connection reset by peer。
+- ACK 台账下实时缺失 28828 次，其中 28633 次对应消息最终已查到持久化记录。
+- 历史验证 ledger 含 2002 条，命中 1331 条，缺失 671 条全部为 P2P。独立 SQL 确认所有 1076 条 ACK 消息和全部 926 条 WS 已观测的无 ACK 消息均已落库，因此这 671 条是 verifier 连接掉线和 3 分钟总预算造成的验证不完整，不是数据库丢失。
+- 1324 条结果未知中，1017 条实际落库：926 条被 WS 观测，另有 91 条未被 WS 观测但已落库。剩余 307 条无 ACK、无 WS 观测、无数据库记录。
+
+### 4.4 独立 MySQL 核验
+
+核验租户 ID 为 8，消息表为 `im_008_messages` 和 `im_008_group_messages_202609`。
+
+| 场景 | ACK expected | 精确命中 | ACK 缺失 | 错配 | 重复 | 无 ACK 但落库 |
+|---|---:|---:|---:|---:|---:|---:|
+| 单聊 | 12000 | 12000 | 0 | 0 | 0 | 0 |
+| 群聊 | 1145 | 1145 | 0 | 0 | 0 | 39 |
+| 混合 | 1076 | 1076 | 0 | 0 | 0 | 1017 |
+
+`verify-db` 对无 ACK 但落库的行按 unexpected 报告，所以群聊和混合命令会以非零状态结束；这不代表数据错误，而是发送结果未知但服务端已持久化的重要诊断证据。
+
+## 5. 服务端观测
+
+- `im-server-0/1/2` 全部 Running，本轮重启数均为 0。
+- 混合实时阶段 `03:53:00Z..03:53:02Z`，`im-server-0` 记录 55 次 `topic's broadcast queue is full`。
+- 混合渐进关闭末尾 `04:03:45Z`，`im-server-0` 再记录 375 次同类队列满。当前 60 秒 close ramp 仍未完全避免关闭风暴。
+- 同一观测窗口的 `03:45:13Z`，`im-server-2` 在 `serveIMFriendRequestAction` (`server/im_http.go:6256`) 出现一次 nil pointer panic。该端点不属于群实时发送路径，不将其归因为本轮断连，但需单独修复。
+- 当前 kubeconfig 无权读取 metrics-server，未能取得负载窗口的 Pod CPU/内存历史值。
+
+## 6. 压测工具修复
+
+1. 新增单机 60% 配置和执行方案，A/B 各 600 连接。
+2. 群聊和混合发送者按 `users_per_machine` 比例缩放，1000 用户的原参数保持不变。
+3. 投递观测按 `client_mid` 分为 64 片，每个接收账号独立维护 seq，延迟直方图改为原子计数，移除 WS 读循环中的全局锁争用。
+4. summary/report 新增 `disconnect_reasons` 和最多 100 条 `disconnect_samples`。
+5. 群创建后立即 checkpoint manifest；批量邀请失败后重读实际成员，仅邀请缺失用户。
+6. P2P 历史查询 limit 按 seq 区间扩展，上限 200，修复双方消息交错造成的假缺失。
+
+## 7. 已实施改进
+
+1. 好友申请接受和自动接受路径增加 store 空结果保护。底层异常返回 `nil, nil` 时记录租户、申请、操作人和状态并返回 HTTP 500，不再触发进程 panic。
+2. Hub 向已满的 Topic client queue 投递失败时，立即向原发送连接返回 `503 service unavailable`，并记录 topic、tenant、队列长度和容量。客户端可据此重试，压测也不再把这类请求归为等待超时的未知结果。
+3. 群消息权限检查改为复用群设置缓存，并为个人禁言增加 Redis 正向和负向缓存；新增禁言和解除禁言会同步更新缓存，到期禁言会自动淘汰。此改动减少群 Topic 串行处理路径上的 MySQL 查询。
+4. `message_publish_stage_duration_seconds` 新增 `group/permission_check` 和 `*/realtime_fanout` 阶段，下轮可区分权限查询、持久化和实时扩散耗时。
+5. A/B 两个逻辑 agent 按账号顺序交错关闭连接。`close_ramp=60s` 时每个 agent 的本地关闭过程约 120 秒，A/B 相差半个时隙，整体约每 100ms 关闭一个连接，避免两侧同时下线形成双倍尖峰。
+6. 已增加空结果防 panic、Topic queue 满返回 503、双 agent 关闭时隙的自动化测试。
+
+## 8. 复测顺序
+
+1. 发版后先跑单机群聊 60%，验收实时发送阶段和关闭阶段 `topic_client` enqueue failed 均为 0；若仍过载，发送端必须收到 503，不能再出现对应的纯 ACK timeout。
+2. 对比 `permission_check`、`save`、`realtime_fanout` 三阶段的 P50/P95/P99，确认群权限缓存是否消除了数据库检查瓶颈。
+3. 群聊通过后再跑单机混合 60%，要求 ACK、历史和独立 SQL 三方账本一致，连接断开数为 0。
+4. 补齐 Prometheus/metrics-server 权限并同步保存 Pod CPU、内存、网络、Kafka lag、Redis、MySQL 指标；在此之前不进行双机 100% 最终验收。
+
+## 9. 发版后群聊 R2
+
+Run ID：`s60-group-r2-0929`。
+
+本轮开始前 3 个 Pod 均为 Running、0 重启，账号和群成员核验为 `accounts=1200 pairs=600 group_members=1200`。测试完整运行到 A/B 历史验证完成，并执行了错峰关闭和独立 MySQL 核验。
+
+| 指标 | 结果 |
+|---|---:|
+| 发送尝试 / ACK | 1200 / 871 |
+| 结果未知 | 329（222 timeout、107 socket） |
+| 断连 | 360（315 reset、44 abnormal close、1 timeout） |
+| ACK P95 | 16630.441ms |
+| 投递 P95 | 101823.156ms |
+| ACK 台账期望 / 实时收到 | 1045200 / 889777 |
+| 实时缺失 | 155423，最终全部查到持久化 |
+| 历史回查 | 1080 / 1080 |
+| DB：ACK 精确命中 | 871 / 871 |
+| DB：无 ACK 但落库 | 209 |
+| DB：缺失 / 错配 / 重复 | 0 / 0 / 0 |
+
+329 条结果未知中，209 条已被 WS 观测且独立 SQL 确认落库，剩余 120 条数据库中不存在。断连样本主要是公网对端 `connection reset by peer`，且样本连接均指向 `64.118.158.131:443`；本机到域名全部当前 IP 均使用 `en1` 静态直连，没有经过 VPN/TUN。
+
+服务端指标显示群 Topic 所在 `im-server-0` 的 1080 条 `save` 全部低于 100ms，Kafka consumer lag 为 0；但 `topic_server` 队列累计出现 393 次 full。压测客户端 CPU、RSS 不构成瓶颈。
+
+本轮不能作为提交 `75bb448` 的有效回归：Pod 中运行的二进制不包含该提交新增的 `permission_check`、`realtime_fanout` 阶段字符串和好友申请空结果保护日志，Prometheus 也没有相应时序，说明实际部署镜像不是该提交构建结果。必须正确部署 `75bb448` 或后续提交后重跑。
+
+此外，本轮发现 agent 只在正式开始前维护连接，统计窗口内断线后不会恢复，导致历史核验依赖剩余连接。后续已改为持续维护到 A/B 历史验证均完成，并将重连并发限制为每 agent 16，避免恢复风暴；每次计划发送前重新取得当前连接。
+
+## 10. 产物
+
+- 方案：`docs/test/IM-单机60%容量压力测试方案.md`
+- 单聊 R2：`loadtest/im-pressure/results/s60-p2p-r2-0929/`
+- 群聊 R1：`loadtest/im-pressure/results/s60-group-r1-0929/`
+- 混合 R1：`loadtest/im-pressure/results/s60-mixed-r1-0929/`
+- 群聊 R2：`loadtest/im-pressure/results/s60-group-r2-0929/`
+
+结果目录包含 coordinator、A/B summary、合并 report 和 agent 指标 JSONL。
+
+## 12. 精确成员规模诊断复测
+
+为区分“在线连接数”和“群成员总数”的影响，新增 300、600 人独立群复测。每个测试群在起压前均按用户 ID 集合核验，要求实际成员与目标账号完全相等。
+
+| 场景 | Run ID | 在线/群成员 | ACK | 实时投递 | 历史 | DB 精确命中 | ACK P95 | 投递 P95 |
+|---|---|---:|---:|---:|---:|---:|---:|---:|
+| 原 1200 人群、仅 300 人在线 | `s300-group-r1b-0929` | 300/1200 | 45/300 | 13500/13500（按 ACK 台账） | 206/206 | 45 ACK + 210 结果未知全部落库 | 18994ms | 89489ms |
+| 精确 300 人群 | `s300m-group-r1-0930` | 300/300 | 300/300 | 90000/90000 | 300/300 | 300/300 | 235.177ms | 500ms 桶内 |
+| 精确 600 人群 | `s600m-group-r1-0930` | 600/600 | 600/600 | 360000/360000 | 600/600 | 600/600 | 235.177ms | 500ms 桶内 |
+| 精确 900 人群 | `s900m-group-r1-0930` | 900/900 | 890/900 | 800555/801000（按 ACK 台账） | 899/899 | 890 ACK + 9 结果未知落库 | >10s，最大19.272s | >10s，最大55.279s |
+
+三轮均未出现 WS 发送队列满、WS 写失败或 Kafka lag。精确 300、600 人群在实时阶段也没有新增 `session_topic_publish`、`topic_client`、`topic_server` 满队列，说明 WS 写链路在 600 在线规模内不是瓶颈。
+
+原 1200 人群仅 300 人在线时有约 900 个离线成员。群消息处理会在 Topic 串行路径中为每个离线成员逐个调用 Redis presence 查询；上一条消息 ACK 后的推送准备持续占用 Topic goroutine，使后续消息长时间等待，最终表现为 ACK 超时和分钟级投递延迟。精确成员群消除这部分离线成员后，同等 300 在线规模恢复正常，验证了该路径是主要根因。
+
+600 人实时发送通过后，240 秒错峰下线仍使群主 Pod 的 `topic_server full` 从 36 增至 128，净增 92；其他两类内部队列无增量。该问题来自最后会话离线时的 presence 扩散，与消息保存、Kafka 消费和 WS 实时投递无关，仍需在服务端合并或限流离线状态广播。
+
+精确 900 人群出现容量拐点：900 次发送中 890 次 ACK，9 次 ACK 超时、1 次 socket 失败；7 条连接在实时阶段超时断开并自动恢复。按 ACK 台账计算的 445 次实时缺口全部可从历史补回，890 条 ACK 全部精确落库；9 条结果未知实际落库，1 条 socket 失败未落库。因此本轮没有持久化丢失，但实时正确性和延迟门禁未通过。
+
+900 人实时阶段三个内部队列的 full 计数均无增量，Kafka lag 为 0。成功处理的 899 条消息中，`permission_check` P95 不超过 10ms、`save` P95 不超过 50ms、`kafka_produce` P95 不超过 25ms、`realtime_fanout` P95 不超过 5ms；抽样覆盖后半段 575468 次 WS 投递，发送队列等待 P95 不超过 10ms、socket write P95 不超过 0.5ms，且没有发送队列满或 text write 失败。
+
+现有 `realtime_fanout` 指标在 `pushForData` 之前结束。`pushForData` 位于 Topic 串行处理路径中，每条群消息遍历全部成员、构造推送收件人并调用 `sendPush`；即使成员全部在线，900 人规模下这段未计时工作仍可让后续发布在 `topic_client` 中排队。队列未达到容量上限并不代表没有排队，这与 ACK 延迟逐步增长到 19 秒、投递延迟增长到 55 秒的现象一致。下一步应先补充 `push_prepare`、`push_dispatch` 和 Topic client queue wait 指标，再将群推送准备移出 Topic 串行热路径或改为异步批处理。
+
+900 人在 240 秒错峰下线后，群主 Pod 的 `topic_server full` 从 0 增至 379，说明 presence 离线扩散问题随群规模明显放大。压测机两个 agent 的峰值 CPU 分别约 39.5% 和 38.5% 单核，峰值 RSS 各约 76MB、FD 各 460，不是本轮瓶颈。
+
+新增产物：
+
+- 300 人精确群：`loadtest/im-pressure/results/s300-group-members-setup-0929/`
+- 300 人复测：`loadtest/im-pressure/results/s300m-group-r1-0930/`
+- 600 人精确群：`loadtest/im-pressure/results/s600-group-members-setup-0930/`
+- 600 人复测：`loadtest/im-pressure/results/s600m-group-r1-0930/`
+- 900 人精确群：`loadtest/im-pressure/results/s900-group-members-setup-0930/`
+- 900 人复测：`loadtest/im-pressure/results/s900m-group-r1-0930/`
+
+## 13. 容量拐点修复（待发版复测）
+
+针对精确 900 人群暴露的 Topic 串行积压和批量下线 presence 风暴，已完成以下代码改造：
+
+1. `pushForData` 在 Topic goroutine 内只复制成员推送快照，不再逐成员同步查询 Redis，也不再执行跨 Pod 收件人拆分和 user updater 投递。
+2. 新增总容量 4096 的有界异步推送队列和 4 个固定分片 worker。同一 `tenant + topic` 固定进入同一分片，保证同一群的推送和未读更新顺序；不同群可并行处理。
+3. 离线成员 presence 使用一次 Redis pipeline 批量读取，单条消息的 Redis 网络往返由成员数 N 次降为 1 次。
+4. 群离线 presence 遇到 Topic server queue 满时不再直接丢弃。服务端按 `tenant + topic + source user` 合并为最新状态，并在 Topic 队列恢复后重投；待处理集合上限 16384。
+5. 新增 Topic client queue wait、push prepare、push dispatch queue、push dispatch duration、push recipient count、deferred presence 当前深度等指标。
+
+新增重点指标：
+
+- `im_topic_queue_wait_duration_seconds`
+- `im_message_publish_stage_duration_seconds{stage="push_prepare"}`
+- `im_push_dispatch_queue_enqueue_total`
+- `im_push_dispatch_queue_depth`
+- `im_push_dispatch_queue_wait_duration_seconds`
+- `im_push_dispatch_duration_seconds`
+- `im_push_recipient_count`
+- `im_internal_queue_current{queue="topic_presence_pending"}`
+- `im_internal_queue_enqueue_total{queue="topic_presence_deferred"}`
+
+发版后先复测精确 600 人群，确认基线无回归；再复测精确 900 人群。900 人验收要求：900/900 ACK、810000/810000 实时投递、0 断连、0 持久化缺失，`topic_client/topic_server/push_dispatch` 无 full，Topic queue wait P95 不超过 500ms，ACK P95 不超过 500ms，投递 P95 不超过 1s。渐进下线结束后 deferred presence 必须回落到 0，且不得出现 `topic_server full`。
+
+## 14. 异步推送发版后精确 600 人回归
+
+Run ID：`s600m-pushfix-r1-0930`。测试使用精确 600 人群 `grpJZjWbOek928`，A/B 各建立 300 条连接；两端均完整运行至 5 分钟落库沉淀、历史回查和 240 秒交错关闭结束，没有提前终止连接。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 600 / 600 |
+| 发送尝试 / 收到 ACK | 600 / 523 |
+| 发送结果未知 | 77（71 timeout、6 socket） |
+| 服务端实际接收并落库 | 593 / 600 |
+| ACK P95 | 17522.536ms |
+| ACK 台账实时投递 | 308745 / 313800 |
+| 实时到达率 | 98.3891% |
+| 实时缺口 | 5055，全部可从历史补回 |
+| 历史回查 | 593 / 593 |
+| 无 ACK 但历史可查 | 70 / 70 |
+| MySQL 精确命中 | 593 / 593 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| 断连 | 34（21 reset、13 abnormal close） |
+| 重启 | 0 |
+
+异步推送改造本身没有形成服务端队列瓶颈。群主 Pod 处理的 600 次发布 Topic queue wait 全部不超过 50ms；593 次异步推送均成功入队，`push_dispatch` 没有 full，队列等待 P95 不超过 0.5ms，dispatch P95 不超过 10ms、最大不超过 25ms，deferred presence 最终为 0。Kafka lag 仍为 0。
+
+本轮 77 条 ACK 未知中，70 条已被对端 WS 观察并精确落库，剩余 7 条 socket 失败未进入服务端。由此可确认本轮失败发生在客户端连接和 ACK 返回链路，不是消息持久化、Kafka 消费、Topic 排队或异步推送丢弃。
+
+测试期间 3 个 IM Pod 持续收到培养服务文件确认请求，并在 `store.Files.LinkAttachments` 中对 `cvp...` 业务保留键调用 `types.GetTopicCat`，约每 5 秒产生一轮 HTTP panic 和完整堆栈。该接口允许业务保留键，不能按 Tinode Topic 强制分类；持续 panic 日志和并发异常请求污染了本轮环境，因此本轮不能作为异步推送改造的有效 600 人基线。
+
+已完成两项修复：
+
+1. 附件关联仅对 `usr...` 用户引用执行用户 Topic 转换，`cvp...` 等业务保留键直接按普通关联键落库，消除确定性 panic。
+2. `verify-db` 将双机共同观察到的无 ACK 消息与 ACK ledger 合并去重。本轮修正后的独立 SQL 结果为 `expected=593, found_exact=593`，不再把 70 条已落库的 ACK 超时消息误报为 unexpected。
+
+下一轮必须在上述修复发版后重新执行相同的精确 600 人场景。验收前先确认 3 个 Pod 不再出现 `invalid topic type for name 'cvp...'`；随后要求 600/600 ACK、360000/360000 实时投递、MySQL 600/600 精确命中、0 断连，并保持 Topic、push dispatch、Kafka 和数据库指标无积压。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s600m-pushfix-r1-0930/report.json`
+- `loadtest/im-pressure/results/s600m-pushfix-r1-0930/db-verification.json`
+- `loadtest/im-pressure/results/s600m-pushfix-r1-0930/server-metrics/`
+
+## 15. Panic 修复后精确 600 人连续复测
+
+部署提交 `06e08a6` 后，3 个 Pod 使用同一镜像摘要，均为 Ready、零重启。连续观测和三轮压测期间不再出现 `invalid topic type for name 'cvp...'` 或对应 HTTP panic，确认培养文件关联修复生效。
+
+为区分代码回归与公网瞬态，使用同一配置和精确 600 人群连续执行 R2、R3、R4。每轮 A/B 各 300 连接，保持到 5 分钟沉淀、历史验证和 240 秒交错关闭全部完成。
+
+| 指标 | R2 | R3 | R4 |
+|---|---:|---:|---:|
+| ACK | 600 / 600 | 600 / 600 | 600 / 600 |
+| 实时投递 | 359400 / 360000 | 360000 / 360000 | 360000 / 360000 |
+| 断连 | 1 次 timeout | 0 | 0 |
+| 历史回查 | 600 / 600 | 600 / 600 | 600 / 600 |
+| MySQL 精确命中 | 600 / 600 | 600 / 600 | 600 / 600 |
+| MySQL 缺失 / 错配 / 重复 | 0 / 0 / 0 | 0 / 0 / 0 | 0 / 0 / 0 |
+| ACK P95 | 314.530ms | 1555.109ms | 6228.311ms |
+| 投递 P95 | 500ms 桶内 | 2000ms 桶内 | 10000ms 桶内 |
+
+R2 唯一异常是 `lta0259` 到 `216.236.31.189:443` 的一次客户端读超时。该连接在发送阶段开始后自动恢复，因此该账号错过 600 条实时消息；600 条均可从历史补回，服务端和 MySQL 没有丢失。R3、R4 均达到消息正确性全通过：零断连、零实时缺失、零重复、零乱序、零持久化缺失。
+
+R3、R4 的延迟门禁没有通过，但服务端分段指标未出现同步恶化：
+
+- Topic queue wait P95 不超过 0.5ms。
+- 消息保存 P95 不超过 25ms。
+- push dispatch P95 不超过 10ms，队列无 full，完成后深度为 0。
+- WS send queue wait P95 约 3ms，socket write 超过 99% 不超过 0.5ms。
+- deferred presence 当前深度为 0。
+- 600 条历史和数据库记录全部精确命中，Kafka 未出现消费积压。
+
+ACK 延迟按 3 个拨号 IP 分组后同步上升，不集中于单一入口。R2 三个 IP 的 ACK P95 为 302–372ms，R3 为 1536–1643ms，R4 为 5999–6559ms，说明延迟发生在服务端 socket write 之后的共享公网、负载均衡或压测机接收链路。
+
+压测结束后的网络基线同样异常：
+
+| 入口 IP | TCP connect 平均 | HTTPS TTFB 平均 | ICMP 丢包 | ICMP RTT |
+|---|---:|---:|---:|---:|
+| `216.236.31.189` | 179ms | 623ms | 10% | 平均 256ms，最大 511ms |
+| `216.236.31.191` | 178ms | 543ms | 10% | 平均 154ms |
+| `64.118.158.131` | 178ms | 588ms | 0% | 平均 168ms |
+
+三条静态路由均经 `en1` 和网关 `192.168.1.1` 直连，没有经过 VPN/TUN。当前公网 RTT、丢包和 HTTPS TTFB 已高于或接近 500ms ACK 门禁，TCP 重传会进一步放大 WebSocket 队头等待。因此本组结果可证明精确 600 人下服务端消息正确性和持久化能力通过，但不能证明公网端到端延迟 SLA 通过。
+
+后续在进入精确 900 人测试前，应先满足以下任一条件：
+
+1. 使用与测试集群同地域、低丢包的压测机，并保留当前 500ms/1s 延迟门禁。
+2. 取得 Ingress/LB 的 upstream、出站带宽、连接 reset 和重传指标，将公网延迟与服务端处理延迟分开验收。
+3. 双机正式压测时分别记录本机到 3 个入口的 RTT、丢包和 HTTPS TTFB；网络基线不合格时只验收正确性，不输出容量延迟结论。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s600m-pushfix-r2-0930/`
+- `loadtest/im-pressure/results/s600m-pushfix-r3-0930/`
+- `loadtest/im-pressure/results/s600m-pushfix-r4-0930/`
+
+## 16. 异步推送发版后精确 900 人复测
+
+Run ID：`s900m-pushfix-r2-0930`，精确群成员 900 人，A/B 各 450 条 WebSocket 连接。两端均完整运行至 5 分钟沉淀、历史回查和 240 秒渐进关闭结束，没有提前终止。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / 收到 ACK | 900 / 590 |
+| 发送结果未知 | 310（186 条已被对端 WS 观察，124 条未入服） |
+| 服务端实际接收并落库 | 776 / 900 |
+| ACK P95 | 17075.685ms |
+| ACK 台账实时投递 | 381424 / 531000 |
+| ACK 台账实时到达率 | 71.8313% |
+| 实时缺口 | 149576，全部可从历史补回 |
+| 重复 / 乱序 | 0 / 0 |
+| 历史回查 | 776 / 776 |
+| MySQL 精确命中 | 776 / 776 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| 断连 | 410（322 reset、88 abnormal close） |
+| Pod 重启 | 0 |
+
+本轮消息正确性结论很明确：590 条有 ACK，186 条虽然 ACK 超时或 socket 失败，但已被其他 WS 客户端观察到；这 776 条全部能从历史查到，且 MySQL 精确落库 776 条。服务端已接收消息的持久化丢失率为 0，无重复、无字段错配。余下 124 条在连接断开期间未进入服务端，不属于服务端落库后丢失。
+
+服务端在 776 条实际入服消息上没有出现容量积压：
+
+- Topic queue wait P95 不超过 10ms，95.7% 不超过 10ms。
+- push dispatch 776/776 成功入队，无 full；队列等待 P95 不超过 5ms，dispatch P95 不超过 25ms。
+- WS send queue 等待 P95 不超过 5ms，socket text write P95 不超过 0.5ms；1177345 次成功写入，16 次写入失败均是对端已关闭连接。
+- 3 个 Pod 的 Kafka consumer lag 和 oldest backlog age 始终为 0，无 Topic、push dispatch 或 WS send queue full。
+- 渐进关闭后 push dispatch 和 WS send queue 深度均为 0，`topic_presence_pending` 回落为 0。
+
+压测期间客户端记录 410 次非预期断连，服务端指标同期新增 412 次 WS timeout，三个 Pod 分别为 135、133、144 次，并非单一 Pod 故障。客户端 reset 样本同样均匀分布在三个公网 IP。压测 agent A/B 峰值 CPU 约为 20.8%/22.0% 单核，峰值 RSS 约为 108/101MiB，FD 均为 460，本机进程没有出现 CPU、内存或 FD 容量耗尽。结合本章前已观测到的高 RTT、ICMP 丢包和 HTTPS TTFB，本轮只能判定“当前端到端公网路径下 900 长连接门禁失败”，具体故障点可能在压测机网络、NAT/ISP、Ingress/LB 或其间 TCP 链路，不能据此判定 IM 服务端在 900 人处理容量上失败。
+
+下一次 900 人容量验收必须改为集群同地域压测机，或先取得 Ingress/LB 的 reset、TCP 重传、出站带宽和 upstream 时延指标。网络基线不合格时，继续从当前机器反复施压只会重复得到链路上限，无法给出服务端容量上限。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-pushfix-r2-0930/report.json`
+- `loadtest/im-pressure/results/s900m-pushfix-r2-0930/db-verification.json`
+- `loadtest/im-pressure/results/s900m-pushfix-r2-0930/server-metrics/`
+
+## 17. 900 连接心跳容错与压测端解耦（待发版复测）
+
+针对 R2 在约一个心跳超时窗口后出现的 410 次断连，已完成三项改造：
+
+1. WebSocket Ping 周期和 Pong 等待时间从硬编码中拆出，支持 `ws_ping_period_seconds` 和 `ws_pong_wait_seconds` 配置。默认为 15 秒 Ping、90 秒 Pong 容错，不再复用 45 秒业务 idle timeout。
+2. 新增 `im_ws_heartbeat_seconds` 和 `im_ws_heartbeat_total{event="pong_received"}`，用于核对每个 Pod 的有效心跳配置和 Pong 接收数；测试环境 ArgoCD patch 显式设置 15/90 秒。
+3. 压测客户端为每条连接新增有序数据回调队列。Socket 读循环不再同步执行消息去重、顺序和延迟统计，避免统计锁竞争阻塞 ACK、Ping 和 Pong 读取。
+
+发版后仍使用同一精确 900 人群复测。起压前先确认三个 Pod 的 heartbeat gauge 均为 15/90；验收时对比 Pong 增量、timeout 增量、agent 断连和入服/落库数。若仍然同时批量 timeout，下一步必须取得 Ingress/LB TCP 指标或改用同地域压测机，不再继续放大应用心跳窗口。
+
+## 18. 90 秒心跳发版后精确 900 人复测
+
+Run ID：`s900m-heart-r1-0930`。三个 Pod 发版后均为 Ready、零重启，指标确认有效心跳配置均为 `ping_period=15`、`pong_wait=90`。使用与上一轮相同的精确 900 人群，A/B 各 450 条连接，完整运行至历史回查和渐进关闭结束。
+
+| 指标 | 本轮 | 改造前 R2 |
+|---|---:|---:|
+| 发送尝试 | 900 | 900 |
+| 收到 ACK | 854 | 590 |
+| ACK 超时 / socket 错误 | 45 / 0 | 310 条结果未知，其中 124 条未入服 |
+| 明确失败 | 1 条 `500 internal error` | 0 |
+| 服务端实际接收并落库 | 899 / 900 | 776 / 900 |
+| 断连 | 11 | 410 |
+| ACK P95 | 11475.912ms | 17075.685ms |
+| ACK 台账实时投递 | 765336 / 768600 | 381424 / 531000 |
+| ACK 台账实时到达率 | 99.5753% | 71.8313% |
+| 重复 / 乱序 | 0 / 0 | 0 / 0 |
+| 历史回查 | 899 / 899 | 776 / 776 |
+| MySQL 精确命中 | 899 / 899 | 776 / 776 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 | 0 / 0 / 0 / 0 |
+
+心跳容错和压测端读循环解耦有明显效果：断连从 410 次降到 11 次，降幅约 97.3%；未入服数从 124 降到 1。负载期三 Pod 累计成功发送约 14554 次 Ping，已观察到约 14472 次 Pong。11 次断连仍在 90 秒窗口附近发生，客户端全部自动重连。当前心跳仅在 Pong 回调时续期；下一步应将有效的客户端 Ping 和业务入站帧同样视为连接活动，而不是继续扩大 Pong 窗口。
+
+45 条 ACK 超时消息全部被对端 WS 观察，且 899 条实际入服消息全部历史可查、MySQL 精确命中，证明已入服消息仍为零持久化丢失。唯一未入服消息已定位到 `10:07:58` 群主 Pod 的 MySQL `invalid connection`：同时出现群禁言策略查询失败和消息保存失败，客户端收到 `500 internal error`。需要对失效 MySQL 连接进行识别、丢弃并安全重试。
+
+服务端分段指标中，899 条成功消息的 permission check P95 不超过 25ms、save P95 不超过 50ms、Kafka produce P95 不超过 25ms、realtime fanout P95 不超过 5ms、push prepare 和 push queue wait P95 不超过 10ms、push dispatch P95 不超过 25ms，无任何内部队列 full，Kafka lag 为 0。但 Topic queue wait P95 为 5s，最后 124 条在连接 timeout 与 presence 处理同期等待 0.1–10s，使 ACK P95 仍未过门禁。
+
+压测 agent 峰值 CPU 约为 28.8%/22.8% 单核，RSS 约 121MiB，FD 各 460，进程资源未饱和。但异步数据回调队列尚未暴露当前深度和等待时间，因此本轮 98 秒投递 P95 包含网络、socket 读取和压测统计队列三段时间，不能单独作为服务端投递 SLA。下一轮前需增加压测回调队列深度/等待指标，并减少 recorder 在同一 `client_mid` 上的锁竞争。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-heartbeat-r1-0930/report.json`
+- `loadtest/im-pressure/results/s900m-heartbeat-r1-0930/db-verification.json`
+- `loadtest/im-pressure/results/s900m-heartbeat-r1-0930/server-metrics/`
+
+## 19. 900 人复测后第二轮修复
+
+针对第 18 节剩余的 11 次 timeout、1 条 MySQL `invalid connection` 和压测端回调排队不可观测问题，已完成以下修复：
+
+1. 服务端收到有效客户端 Ping 时立即续期读截止时间并回 Pong；成功读取业务帧时也续期读截止时间。连接活跃判定不再只依赖服务端 Ping 对应的 Pong，新增 `im_ws_heartbeat_total{event="ping_received"}` 观测客户端心跳。
+2. MySQL 只读查询遇到 `ErrInvalidConn` 时向 `database/sql` 返回 `ErrBadConn`，使连接池丢弃坏连接并在新连接上重试。个人消息仅在存在 `client_msg_id` 唯一键保护时重试一次；群消息由 `message_id` 和 `client_msg_id` 唯一键保护，整个保存操作可安全重试一次。新增 `im_db_invalid_connection_retry_total{operation,outcome}`。
+3. recorder 的群消息接收位图改为原子 CAS。同一 `client_mid` 只在首次创建 observation 时使用 shard 锁，后续数百个收件人不再串行争用同一把写锁。
+4. agent 新增回调队列当前深度、处理数、峰值、入队/完成数、累计等待和最大等待指标，并将快照写入 `summary.json` 的 `callback_queue`。生成实时到达率前会等待排队及正在处理的回调全部完成，避免统计尚未落入 recorder 时产生假丢失。
+
+下一轮仍使用精确 900 人群复测。除原有正确性门禁外，重点检查：
+
+- `im_ws_heartbeat_total{event="ping_received"}` 有持续增量，服务端 timeout 和客户端断连进一步下降。
+- `im_db_invalid_connection_retry_total` 若出现，结果应为 `discard` 或 `recovered`，客户端不再收到对应 500。
+- `callback_queue.current` 和 `callback_queue.processing` 在结算时均为 0；结合 `maximum`、`wait_seconds_total / completed` 和 `wait_seconds_max` 区分压测端排队与服务端投递延迟。
+
+## 20. 第二轮修复后精确 900 人复测
+
+Run ID：`s900m-activity-r1-0930`，部署提交 `36129e3`。复用精确 900 人群 `grpQ5_hPdAz3cE`，A/B 各 450 条 WebSocket 连接。两个 agent 均通过 30 秒满连接屏障，并一直运行至实时投递、5 分钟沉淀、历史回查、MySQL 校验和 120 秒渐进关闭全部完成。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / 收到 ACK | 900 / 899 |
+| 结果未知 | 1 条 ACK 超时，socket 错误 0 |
+| 服务端实际接收并落库 | 900 / 900 |
+| 实际实时投递 | 810000 / 810000 |
+| 实时到达率 | 100% |
+| 重复 / 乱序 | 0 / 0 |
+| 压测期非预期断连 | 0 |
+| 服务端 WS timeout | 0 |
+| 历史回查 | 900 / 900 |
+| MySQL 精确命中 | 900 / 900 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| ACK P95 | 4748.423ms |
+| 投递 P95 | 10000ms 桶内 |
+
+唯一 ACK 超时为 `s900m-activity-r1-0930-g-b-0121-01`。该消息虽然 20 秒内没有收到 ctrl ACK，但 A/B 均实时观察到，服务端分配 seq `3714`，历史可查且 MySQL 精确命中；因此是 ACK 返回链路超时，不是消息未入服或丢失。报告中的 `unexpected_messages=900` 正是该条没有进入 ACK ledger、但被 900 个连接实际收到的消息。
+
+本轮连接活跃改造生效。三 Pod 均持续记录 `ping_received` 和 `pong_received`，负载阶段没有 WS timeout；两个 agent 全程 450/450 在线且断连为 0。与上一轮 11 次断连相比，客户端 Ping 和业务帧续期后已消除本轮心跳误断。
+
+压测端回调队列指标证明 recorder 不再构成秒级延迟：
+
+| agent | 入队 / 完成 | 峰值等待数 | 最大等待 | 平均等待 | 结算时等待 / 处理中 |
+|---|---:|---:|---:|---:|---:|
+| A | 405000 / 405000 | 106 | 11.353ms | 约 0.022ms | 0 / 0 |
+| B | 405000 / 405000 | 98 | 5.075ms | 约 0.020ms | 0 / 0 |
+
+服务端内部处理也没有出现容量积压：
+
+- Topic queue wait P95 不超过 50ms，全部 900 条不超过 250ms。
+- permission check P95 不超过 25ms，消息保存 P95 不超过 50ms，realtime fanout P95 不超过 5ms，push prepare P95 不超过 10ms。
+- WS send queue wait P95 不超过 25ms，socket text write P95 不超过 0.5ms。
+- push dispatch queue 无 full，Kafka consumer lag 和 oldest backlog age 均为 0。
+- 没有 `invalid connection`、消息保存失败、内部队列 full、panic 或 Pod 重启；关闭后 push 队列和 `topic_presence_pending` 均回落为 0。
+
+因此本轮消息正确性和持久化门禁已经通过，但端到端延迟门禁仍未通过。测试结束后的三入口公网 RTT 为 153–189ms，HTTPS TTFB 为 0.50–1.04s；三条路由均经 `en1` 和网关 `192.168.1.1` 直连。服务端从 Topic 排队到 socket write 的 P95 远低于端到端 ACK/投递 P95，压测回调队列最大等待也只有 11ms，剩余延迟主要位于服务端 socket 写入之后的 Ingress/LB、公网 TCP、NAT 或压测机网络路径。后续服务端容量验收应在集群同地域压测机执行，并同时采集 Ingress/LB 出站带宽、TCP 重传、reset 和 upstream 指标。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-activity-r1-0930/report.json`
+- `loadtest/im-pressure/results/s900m-activity-r1-0930/db-verification.json`
+- `loadtest/im-pressure/results/s900m-activity-r1-0930/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-activity-r1-0930/server-metrics/`
+
+## 21. 精确 900 人混合场景测试
+
+混合场景使用 900 条 WebSocket、135 对单聊用户和 224 个群发送者。单聊双方各发 5 条，共 1350 条；群发送者各发 2 条，共 448 条；总发送尝试 1798 条。每个 agent 理论应观察 201600 次群投递和 1350 次单聊发送方回显/接收方投递，共 202950 次唯一回调。
+
+### 21.1 R1：发现结算窗口过早
+
+Run ID：`s900m-mixed-r1-1001`。
+
+- 1798 条消息全部进入服务端，历史 1798/1798，MySQL 1798/1798，缺失、错配、重复和额外记录均为 0。
+- 收到 ACK 1411 条，387 条 ctrl ACK 超时；ACK P95 为 15756.928ms。
+- A/B 负载期均为 450 条连接且断连为 0。
+- 固定 60 秒 drain 结束时，A 的 summary 记录 202867/202950，误报 83 次实时缺口；summary 生成后指标继续增长至 202950/202950，说明这些帧是公网链路中的晚到帧，并未丢失。
+- B 为 202950/202950。回调队列最大等待分别约 98ms/92ms，结算时等待和处理中均为 0。
+- 发现 1 次单聊顺序回退：接收方 A-27 在同一 P2P Topic 上先收到 seq 245、后收到 seq 244。
+
+本轮证明只等待“回调队列瞬时为空”不够：帧可能仍位于服务端 socket、Ingress/LB、TCP 或客户端 socket 缓冲区。压测程序已增加 `delivery_quiet_period` 和 `delivery_quiet_timeout`。固定 drain 后，接收计数和回调队列必须连续静默 10 秒才允许生成实时 summary；任意晚到帧都会重置静默窗口，最长等待 3 分钟。
+
+同时修正实时统计口径：无 ACK 但已被任一 WebSocket 观察到的消息会与 ACK ledger 合并后参与全部收件人的实时到达率和“实时缺失但已落库”计算，不再被记为 `unexpected_messages`。该口径从后续轮次开始生效；R1/R2 原始报告仍保留当时输出，以上结论已按全量唯一回调和历史/MySQL 结果校正。
+
+### 21.2 R2：静默结算修复验证
+
+Run ID：`s900m-mixed-r2-1001`。本轮使用修复后的压测程序，静默等待在 A/B 均正常执行并完成后才生成 summary。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / ACK | 1798 / 1760 |
+| ACK 超时 / socket 错误 | 37 / 1 |
+| 压测期断连 | 14，全部为 timeout，A/B 各 7 |
+| A 唯一实时回调 | 202535 / 202950 |
+| B 唯一实时回调 | 202787 / 202950 |
+| 全量唯一实时回调 | 405322 / 405900，约 99.8576% |
+| ACK 台账实时缺口 | 566，全部已落库 |
+| 重复 / 乱序 | 0 / 0 |
+| 历史回查 | 1798 / 1798 |
+| MySQL 精确命中 | 1798 / 1798 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| ACK P95 | 14317.159ms |
+| 投递 P95 | 46622.373ms |
+
+R2 的 A/B 各 7 条连接在负载期超时断开，随后全部自动恢复至 450/450。实时缺口与断连窗口一致，静默窗口结束后接收计数不再增长，因此不是 R1 那种过早结算。所有实时缺口均可由历史补回，MySQL 独立校验证明服务端持久化零丢失。
+
+两个 agent 的回调队列最大等待约 10ms，结算时 current/processing 均为 0，压测 recorder 不是本轮瓶颈。服务端 1350 条 P2P 消息全部处理完成，P2P Topic queue P95 位于 250–500ms，relationship check P95 位于 100–250ms；Kafka lag 为 0，未出现 MySQL invalid connection、内部队列 full 或 Pod 重启。关闭后 push 队列和 deferred presence 均回落为 0。
+
+混合场景在当前公网压测机上未通过实时和延迟门禁，但持久化门禁通过。下一步不应直接扩大到 1200 人，应先在集群同地域压测机重复 900 人混合场景；若同地域仍出现乱序或实时缺口，再分别处理跨 Pod P2P 顺序和 WS 投递路径。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r1-1001/`
+- `loadtest/im-pressure/results/s900m-mixed-r2-1001/`
+
+### 21.3 R3：零断连、零实时丢失，但仍有 ctrl ACK 超时
+
+Run ID：`s900m-mixed-r3-1001`。本轮沿用 900 条 WebSocket、135 对单聊用户和 224 个群发送者，共发送 1350 条单聊和 448 条群消息。端到端 P95 延迟按最新口径仅作观测，不参与通过判定。
+
+| 指标 | R3 | R2 |
+|---|---:|---:|
+| 就绪连接 | 900 / 900 | 900 / 900 |
+| 发送尝试 / ACK | 1798 / 1751 | 1798 / 1760 |
+| ctrl ACK 超时 / socket 错误 | 47 / 0 | 37 / 1 |
+| 压测期非预期断连 | 0 | 14 |
+| 两端唯一 WS 回调 | 405900 / 405900 | 405322 / 405900 |
+| 实时缺口 | 0 | 578 次底层回调，ACK 台账折算缺口 566 |
+| 重复 / 乱序 | 0 / 0 | 0 / 0 |
+| 历史回查 | 1798 / 1798 | 1798 / 1798 |
+| 无 ACK 但已观察消息的历史命中 | 47 / 47 | 38 / 38 |
+| MySQL 精确命中 | 1798 / 1798 | 1798 / 1798 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 | 0 / 0 / 0 / 0 |
+| ACK P95（仅观测） | 14020.142ms | 14317.159ms |
+| 投递 P95（仅观测） | 52784.346ms | 46622.373ms |
+
+R3 的消息正确性明显好于 R2：A/B 各收到 202950/202950 个唯一回调，包括每端 201600 次群投递、675 次单聊对端投递和 675 次发送方回显。固定 drain 后又经过连续 10 秒静默窗口，计数未再变化，本轮没有过早结算。
+
+47 条 ctrl ACK 超时中，单聊 26 条、群聊 21 条，A/B 分别为 22/25 条。它们全部被 WS 实时观察，47/47 历史可查，并被 MySQL 独立校验纳入 1798/1798 精确命中，所以不是消息未入服或持久化丢失。但客户端在 20 秒内未收到 ctrl ACK，仍是独立的发送协议问题，不属于已取消的 500ms 延迟门禁。因此本轮应判定为：
+
+- 实时到达、重复、顺序、断连、历史和落库正确性通过。
+- 混合场景总验收仍未通过，唯一阻断为 47 条 `command_timeout=20s` 的 ctrl ACK 超时。
+- ACK P95 和投递 P95 保留在报告中，不影响上述判定。
+
+服务端负载期没有 Topic/WS 发送队列 full，WS send queue 结算时均为 0，所有 Kafka consumer lag 为 0，三个 Pod 均为 Ready 且零重启。连接渐进关闭后，三 Pod 连接数从 518/373/550 回落至 7/2/7，与起压前 8/3/6 基本一致。Pod 2 增加了 1 次 `Cluster.Route` 和 1 次 `Cluster.UserCacheUpdate` 瞬时 error，均不足 1ms，最近日志无对应错误，且未影响本轮投递与落库。
+
+压测端回调队列在结算时均为 0；A/B 队列峰值为 355/174，最大等待仅为 37.054ms/25.036ms，不是 20 秒 ACK 超时或 52 秒投递 P95 的原因。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r3-1001/report.json`
+- `loadtest/im-pressure/results/s900m-mixed-r3-1001/db-verification.json`
+- `loadtest/im-pressure/results/s900m-mixed-r3-1001/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-mixed-r3-1001/server-metrics/`
+
+### 21.4 R3 ctrl ACK 超时原因分析
+
+#### 21.4.1 代码路径
+
+服务端的消息发布顺序为：Topic 队列出队、权限/关系校验、持久化、生成 `NoErrAccepted` ctrl ACK 并调用 `queueOut`，然后才做当前消息的 Topic 广播、跨 Pod 实时 fanout 和离线推送准备。因此，当前消息的大规模 fanout 不会阻塞同一条消息的 ACK 生成。
+
+但所有 ctrl 和 data 最终共用用户的同一个 WebSocket/TCP 有序字节流。ACK 可以在当前消息的 data 之前入队，但无法超过已经写入 socket 或正在 Ingress/LB/公网 TCP 中传输的早先 data 帧。混合场景中发送者同时也是 900 人群的收件人，因此每条发送连接在等待自己 ACK 时，前面可能已有数百条群 data 帧。
+
+#### 21.4.2 服务端分段证据
+
+按起压前与负载结束 Prometheus 快照计算本轮增量：
+
+| 阶段 | 增量样本 | P95 |
+|---|---:|---:|
+| P2P Topic 队列等待 | 1350 | 100ms 桶内 |
+| P2P 关系校验 | 1350 | 100ms 桶内 |
+| P2P 保存 | 1350 | 50ms 桶内 |
+| 群 Topic 队列等待 | 448 | 25ms 桶内 |
+| 群权限校验 | 448 | 25ms 桶内 |
+| 群保存 | 448 | 50ms 桶内 |
+| Cluster TopicMaster RPC | 2495 | 3至5ms 桶内 |
+| Cluster proxy 队列深度 | 7988 | P95=1 |
+| WS 发送队列深度 | 817924 | P95=0 |
+| WS 发送队列等待 | 817924 | 10ms 桶内 |
+| WS text frame 写入 | 817946 | 0.5ms 桶内 |
+
+本轮三 Pod 共成功写出约 81.8 万个文本帧、193.6MB。服务端应用层队列、保存、Cluster RPC 和 socket write 均远低于 20 秒；压测时间窗内无 queue full、write timeout、数据库错误、Pod 重启或 panic。因此没有证据支持“业务处理或服务端应用队列阻塞 20 秒”。
+
+#### 21.4.3 超时分布证据
+
+- 47 条超时全部发生在起压后 20至40 秒，正好是每条连接已经接收约 200至400 条群广播帧的区间。
+- 40/47 是同一用户的第 2 条消息，5 条是第 3 条，只有 2 条是第 1 条；超时不是随机散布在整个测试周期。
+- 三个入口 IP 分别有 16/16/15 条超时，排除单一 Ingress IP 热点。
+- 压测端回调队列最大等待只有 37ms，数据回调已与 socket 读循环解耦；超时不是 recorder 锁竞争或回调队列堵塞。
+- 测试后三个入口的当前 ICMP RTT 约为 167至197ms，HTTPS TTFB 约为 0.49至0.61 秒；路由均经 `en1` 直连，未经 VPN/TUN。
+
+综合上述证据，当前根因判断为：**高置信度的 WebSocket/TCP 单流队头阻塞，延迟主要发生在服务端完成 socket write 之后的 Ingress/LB、公网 TCP、NAT 和压测机接收路径。**这个结论可以解释“服务端已快速保存且客户端最终收到全部 data，但部分 ctrl 在 20 秒窗口内未被读到”。
+
+尚未完全证明的环节是：当前压测程序在 ctrl 超时后删除 wait entry，晚到 ctrl 会被静默忽略；服务端 WS 写指标也没有区分 ctrl 和 data。因此现有数据无法逐条证明 47 个 ACK 全部在 20 秒后到达，只能证明对应消息全部已被服务端接受、投递和持久化。
+
+#### 21.4.4 处理建议
+
+1. 压测端增加 late ctrl 台账：ctrl 超时后保留 ID 和发送时间 10 分钟，记录晚到 ACK 数、最终延迟和完全未到数。
+2. 服务端将 WS 出站指标按 `ctrl/data/pres/info` 分类，新增从客户端请求时间到 ctrl ACK 入队、实际 socket write 完成的直方图；跨 Pod 时再记录 master-to-proxy ctrl 延迟。
+3. 下一轮保持完全相同的 900 人混合负载，将 `command_timeout` 改为 90 秒，但单独统计超过 20 秒的 ACK。若 47 类消息都在 90 秒内到达，且服务端 ctrl write 延迟仍在毫秒级，则队头阻塞结论得到直接验证。
+4. 当前业务不对端到端延迟设阻断门禁，因此不建议现在改造独立控制连接或破坏 WebSocket 有序性。应先补齐上述观测，并将“消息已实时观测且历史/MySQL 命中”与“20 秒内收到 ctrl ACK”分开报告。
+5. 另有一项与 ACK 超时无关的独立缺陷：负载结束后 Pod 2 记录 `gob: type not registered for interface: []map[string]interface {}`，影响另一个群 Topic 的 Cluster Route。当前 cluster gob 已注册 `[]any` 和 `map[string]any`，但未注册 `[]map[string]any`，应单独补注册和编解码回归测试。
+
+#### 21.4.5 观测改造完成情况与 R4 口径
+
+上述观测缺口已补齐：
+
+- 压测端会统计 `publish_ctrl_observed`、`publish_ctrl_over_20s`、`publish_ctrl_late`、`publish_ctrl_unresolved` 和 `publish_ctrl_p95_ms`，并保留最多 1000 条超过 20 秒或晚到的样本。
+- agent Prometheus 新增 `im_load_agent_publish_ctrl_observed_total`、`im_load_agent_publish_ctrl_over_20s_total`、`im_load_agent_publish_ctrl_late_total` 和 `im_load_agent_publish_ctrl_unresolved`。
+- 服务端 Prometheus 新增 `im_ctrl_ack_delivery_duration_seconds{stage="enqueue|write"}`，按 Pod 记录从请求进入到 ACK 进入 WS 发送队列、以及完成 socket write 的时间。
+- Cluster gob 已注册 `[]map[string]any`，并用真实系统消息结构补了编解码回归测试。
+
+R4 保持 R3 的 900 连接混合负载，仅将 `command_timeout` 从 `20s` 改为 `90s`。验证时必须同时满足：`publish_ctrl_unresolved=0`、消息实时与历史/MySQL 零丢失，并对比服务端 `enqueue`/`write` P95 与客户端 ctrl P95。如服务端两阶段仍为毫秒级，但 `publish_ctrl_over_20s>0`，则可将超过 20 秒的部分定位在 socket write 之后的网络/TCP 接收路径。
+
+## 22. 精确 900 人全量单聊测试
+
+Run ID：`s900m-p2p-r1-1001`。900 条 WebSocket 连接组成 450 对好友，A/B 各承担 450 个用户。每个用户以 1 秒间隔发送 10 条消息，共尝试发送 9000 条。两个 agent 均完整运行至实时静默判定、5 分钟沉淀、历史回查、MySQL 校验和 120 秒渐进关闭结束，没有提前终止。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / ACK | 9000 / 9000 |
+| 明确拒绝 / 结果未知 | 0 / 0 |
+| 对端实时投递 | 9000 / 9000 |
+| 发送方回显 | 9000 / 9000 |
+| WS 唯一回调总数 | 18000 / 18000 |
+| 实时到达率 / 丢失率 | 100% / 0% |
+| 重复 / 乱序 / 非预期消息 | 0 / 0 / 0 |
+| 压测期非预期断连 | 0 |
+| 历史回查 | 9000 / 9000 |
+| MySQL 精确命中 | 9000 / 9000 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| ACK P95 / 最大值 | 854.385ms / 1324.17ms |
+| 实时投递 P95 / 最大值 | 1000ms 桶内 / 1324.255ms |
+| 服务端 Pod 重启 | 0 |
+
+报告的 `expected_deliveries=9000` 只统计对端投递，不包含发送方自身回显。A/B 各收到 4500 次对端投递和 4500 次本地回显，因此底层唯一 WS 数据回调合计为 18000 次，不是重复消息。
+
+本轮单聊正确性和持久化门禁完整通过：9000 条发送全部收到 ACK，所有收发双方均实时收到应有消息，历史接口与 `im_008_messages` 都精确命中 9000 条。没有发生 ACK 超时、socket 错误、重复、乱序、实时丢失或持久化丢失。
+
+压测端的回调处理没有构成瓶颈：
+
+| agent | 回调入队 / 完成 | 队列峰值 | 最大等待 | 结算时等待 / 处理中 |
+|---|---:|---:|---:|---:|
+| A | 9000 / 9000 | 7 | 16.317ms | 0 / 0 |
+| B | 9000 / 9000 | 9 | 13.004ms | 0 / 0 |
+
+服务端运行状态稳定：
+
+- 三个 Pod 均为 Ready、0 重启，单 Pod 资源配置为 `requests=1 CPU/512Mi`、`limits=2 CPU/1Gi`。
+- 负载结束时 WS 连接分布为 527/373/544；压测连接渐进关闭后回落至 1/0/2，剩余为环境常驻连接，未再出现压测 agent FD 不释放。
+- 三个 Pod 的 WS send queue 结算时均为 0；Kafka 的消息持久化、群消息持久化、管理命令、配置事件、缓存失效、死信和工作台 consumer lag 均为 0。
+- 关闭过程中的少量 `ping closed` 累计指标来自客户端主动渐退，本轮 agent 记录的负载期非预期断连为 0。
+
+按最新验收口径，ACK P95 和投递 P95 仅用于趋势对比，不作为当前公网单机容量测试的阻断条件。重新合并后本轮 `passed=true`：单聊消息正确性、实时到达、顺序性、连接稳定性和落库均通过。ACK P95 854.385ms 和投递 P95 1000ms 仍保留在报告中，但不影响本轮通过结论。
+
+全量单聊已通过，无需为 500ms 延迟门禁单独重复 R2。下一步可进入更高风险的群聊或混合场景复测，仍以零丢失、零重复、零乱序、零断连和全量落库为通过条件。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-p2p-r1-1001/report.json`
+- `loadtest/im-pressure/results/s900m-p2p-r1-1001/db-verification.json`
+- `loadtest/im-pressure/results/s900m-p2p-r1-1001/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-p2p-r1-1001/server-metrics/`
+
+## 23. 900 人混合 R4 长 ACK 观测复测
+
+Run ID：`s900m-mixed-r4-1001`。负载与 R3 相同：900 条 WebSocket、135 对单聊用户和 224 个群发送者，共发送 1350 条单聊和 448 条群消息。本轮仅将 `command_timeout` 改为 90 秒，并启用 ctrl ACK 晚到台账和服务端 `enqueue/write` 分段指标。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / ACK | 1798 / 1798 |
+| 明确拒绝 / 结果未知 | 0 / 0 |
+| 超过 20 秒的 ACK | 118 |
+| 90 秒超时 / 晚到 / 最终未到 | 0 / 0 / 0 |
+| ACK P95 / 最大值 | 23425.942ms / 68730.192ms |
+| 单聊对端实时投递 | 1350 / 1350 |
+| 群聊实时投递 | 403200 / 403200 |
+| 实时到达率 / 丢失率 | 100% / 0% |
+| 重复 / 乱序 / 断连 | 0 / 0 / 0 |
+| 历史回查 | 1798 / 1798 |
+| MySQL 精确命中 | 1798 / 1798 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| Pod Ready / 重启 | 3 / 3，0 重启 |
+
+118 条慢 ACK 的精确延迟范围为 20.317 至 68.731 秒，中位数约 27.062 秒，慢样本 P95 约 39.465 秒。两个 agent 分别有 56 和 62 条超过 20 秒的 ACK，但全部在 90 秒内返回。R4 直接证明同负载下存在“20 秒后才到、但未丢失”的 ACK，强力支持 R3 的 47 条超时属于同类晚 ACK，而非服务端拒绝或消息丢失。
+
+服务端三个 Pod 的 ctrl ACK 指标共有 1801 个自 Pod 启动后的样本，与本轮 1798 条发送只相差 3 条环境流量：
+
+| Pod | enqueue 平均 | write 平均 | enqueue/write P95 |
+|---|---:|---:|---:|
+| im-server-0 | 49.672ms | 50.059ms | 均在 250ms 桶内 |
+| im-server-1 | 51.612ms | 52.176ms | 均在 250ms 桶内 |
+| im-server-2 | 48.051ms | 48.358ms | 均在 250ms 桶内 |
+
+ACK 从 WS 队列入队到 socket write 完成只增加约 0.3至0.6ms，而客户端有 118 条超过 20 秒。因此可确认长延迟发生在服务端 socket write 完成之后的 Ingress/LB、公网 TCP/NAT 或压测机接收路径，不在 Topic、持久化、Cluster RPC 或 WS 应用发送队列内。
+
+本轮底层共处理 405900 个匹配的 WS data 回调，A/B 的回调队列峰值为 120/149，最大等待仅 9.603/9.199ms，结算时全部排空。Kafka 各 consumer lag 均为 0，未出现 Topic、Cluster proxy 或 WS send queue full；渐进关闭后只有 4 次预期的 ping closed 写错误。
+
+报告中 `ack_p95_ms=23425.942` 是基于 1798 条 ACK 原始时间戳的精确值。本轮二进制的 ctrl 直方图上界仅到 10 秒，使 `publish_ctrl_p95_ms` 在 `+Inf` 桶中退化为最大值 68731.141ms，该字段本轮不作为 P95 使用。直方图已增加 20、30、45、60、90 和 120 秒桶及回归测试，下轮会输出正确的长延迟分位桶。
+
+服务端日志还发现两次与本轮 Topic 无关的 Cluster Route 失败：`gob: type not registered for interface: types.KVMap`。`types.KVMap` 是命名 map 类型，不会被 `map[string]any` 的 gob 注册覆盖。已补充 `types.KVMap` 和 `[]types.KVMap` 注册，并扩展 Cluster gob 回归测试；该修复需要再发版。
+
+本轮 `report.json` 最终 `passed=true`。混合场景的消息正确性、实时到达、顺序、连接稳定性、历史回查和 MySQL 落库均通过；长 ACK 已被定位为 socket write 之后的端到端队头阻塞，不再阻断当前容量验收。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r4-1001/report.json`
+- `loadtest/im-pressure/results/s900m-mixed-r4-1001/db-verification.json`
+- `loadtest/im-pressure/results/s900m-mixed-r4-1001/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-mixed-r4-1001/server-metrics/`
+- `loadtest/im-pressure/results/s900m-mixed-r4-1001/im-server-{0,1,2}.log`
+
+## 24. 900 人混合 R5 顺序复测
+
+Run ID：`s900m-mixed-r5-1001`。本轮在 R4 相同的 900 条 WebSocket、135 对单聊用户和 224 个群发送者负载下，验证长延迟直方图、Cluster gob 类型修复及消息顺序。
+
+| 指标 | 结果 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / 90 秒命令窗口内 ACK | 1798 / 1797 |
+| 晚到 2xx / 最终接受 | 1 / 1798 |
+| 明确拒绝 / 最终未知 | 0 / 0 |
+| 超过 20 秒的 ACK | 375 |
+| ctrl ACK P95 桶 / 精确 ACK P95 | 45s / 41746.854ms |
+| 单聊对端实时投递 | 1350 / 1350 |
+| 群聊实时投递 | 403200 / 403200 |
+| 实时总投递 / 丢失 | 404550 / 404550，0 丢失 |
+| 重复 / 乱序 / 断连 | 0 / 1 / 0 |
+| 历史回查 | 1798 / 1798 |
+| 无及时 ACK 消息历史命中 | 1 / 1 |
+| MySQL 精确命中 | 1798 / 1798 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| Pod Ready / 重启 | 3 / 3，0 重启 |
+
+唯一超时消息 `s900m-mixed-r5-1001-g-a-0136-02` 在 95.028 秒收到 202，因此属于晚到成功，不是拒绝或丢失。压测报告已区分 `publish_accepted`（命令等待窗口内）与 `publish_final_accepted`（包含晚到 2xx）；用新口径重算后发送成功率为 100%，报告只因真实乱序而失败。长延迟直方图的 P95 正确落在 45 秒桶，不再退化为最大值。
+
+本轮唯一乱序发生在 A 机 97 号连接的同一单聊 Topic：客户端先收到 seq=322，后收到 seq=321。两条消息由会话两端在几乎同一时刻发送，服务端均实时投递并精确落库，所以问题不在 MySQL、Kafka 或历史回查，而在 Topic master 到 proxy Pod 的实时转发顺序。
+
+代码检查确认，同一个 multiplex session 每次入队都会调度 `clusterWriteLoop`；此前没有排他状态，多个 worker 可以同时消费同一个 `send` channel。随后使用 fire-and-forget RPC 时，先取出的 seq=321 与后取出的 seq=322 会在远端并发执行，导致 seq=322 先进入 proxy Topic。该竞态与本轮现象完全一致。
+
+修复内容：
+
+1. multiplex session 增加原子调度所有权，同一 session 同时只允许一个 Cluster 写任务排空；释放所有权时再次检查队列，覆盖入队与退出之间的竞态。
+2. Master 到 Proxy 的同一 Topic 响应改为逐条等待 RPC 完成，保证远端处理完 seq=N 后才发送 seq=N+1；不同 Topic 仍由 worker pool 并行处理。
+3. 新增本地 RPC 回归测试，故意延迟 seq=1 的处理并重复调度同一 session，验证接收顺序始终为 1、2；该测试在 `go test -race` 下通过。
+4. 压测工具新增晚到 2xx 最终接受计数，已解决“最终已 202 但报告仍算发送失败”的重复判错。
+
+服务端三个 Pod 共记录 1798 条 ctrl ACK，分布为 574/611/613；enqueue/write 平均约 60至66ms，P95 均不超过 250ms。未出现 Topic、Cluster proxy、WS send queue full、Kafka 错误、WS text write 错误或 Pod 重启。A/B 回调队列峰值为 253/290，最大等待 10.703/5.929ms，结算时均已排空。完整 Pod 日志中未再出现 `types.KVMap` 或其他 gob 注册错误，证明 R4 后的 Cluster gob 修复已生效。
+
+本轮 MySQL 校验覆盖 `im_008_group_messages_202610` 与 `im_008_messages`，1798 条业务消息全部精确命中。结论是持久化、实时到达、长 ACK 统计和 gob 修复均通过，当前唯一阻断项为已完成代码修复但尚待发版复验的跨 Pod 顺序竞态。
+
+下一步发版后执行完全相同的 900 人混合 R6。R6 通过条件为：最终接受 1798/1798、实时投递 404550/404550、重复/乱序/断连均为 0、历史和 MySQL 均为 1798/1798；ACK 延迟继续观测但不作为阻断门禁。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r5-1001/report.json`
+- `loadtest/im-pressure/results/s900m-mixed-r5-1001/db-verification.json`
+- `loadtest/im-pressure/results/s900m-mixed-r5-1001/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-mixed-r5-1001/server-metrics/`
+- `loadtest/im-pressure/results/s900m-mixed-r5-1001/im-server-{0,1,2}.log`
+
+## 25. 900 人混合 R6/R7 顺序修复发版复验
+
+### 25.1 R6：顺序修复通过，公网瞬时断连导致整轮失败
+
+Run ID：`s900m-mixed-r6-1001`。本轮首次验证同步 Master-to-Proxy 顺序投递版本，跨 Pod 乱序已从 R5 的 1 次降为 0，但压测机在 15:42:13 至 15:42:18 UTC 同时对两个入口 IP 发生 TCP 写超时。
+
+| 指标 | R6 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / ACK | 1798 / 1785 |
+| socket 结果未知 | 13 |
+| 压测期断连 | 11，均为 write timeout |
+| 实时投递 | 401361 / 404542 |
+| 实时缺口 | 3181，全部历史可查 |
+| 重复 / 乱序 | 0 / 0 |
+| 历史回查 | 1790 / 1790 |
+| MySQL 精确命中 | 1790 / 1790 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+
+11 次断连分布在 `216.236.31.189` 和 `216.236.31.191` 两个入口，并集中于约 5 秒窗口；三个服务 Pod 均 Ready、零重启，负载期无 Topic/Cluster/WS 队列满、Kafka 错误或 gob 错误。13 条 socket 结果未知中有 5 条被对端观察并精确落库，另外 8 条未落库且未形成额外数据，符合请求在进入服务端前失败的特征。
+
+R6 的顺序修复目标已通过，但整轮因断连、发送未知和实时缺口判定失败。三条目标 IP 路由复查均为 `en1` 直连，未经过 VPN/TUN。为排除一次性公网抖动，随即执行相同参数的 R7。
+
+### 25.2 R7：消息业务门禁全部通过
+
+Run ID：`s900m-mixed-r7-1001`。运行前对三个入口 IP 的 HTTPS 预检均返回 200，TLS 总耗时约 1.0 至 1.1 秒。
+
+| 指标 | R7 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / 最终接受 | 1798 / 1798 |
+| 明确拒绝 / 结果未知 | 0 / 0 |
+| 超过 20 秒 / 晚到 / 最终未到 ACK | 74 / 0 / 0 |
+| 精确 ACK P95 | 16795.372ms |
+| 单聊对端实时投递 | 1350 / 1350 |
+| 群聊实时投递 | 403200 / 403200 |
+| 实时总投递 | 404550 / 404550 |
+| WS 匹配回调总数（含单聊回显） | 405900 / 405900 |
+| 重复 / 乱序 / 断连 | 0 / 0 / 0 |
+| 历史回查 | 1798 / 1798 |
+| MySQL 精确命中 | 1798 / 1798 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| Pod Ready / 重启 | 3 / 3，0 重启 |
+
+R7 的 `report.json` 为 `passed=true`。R5 暴露的同 Topic 跨 Pod 乱序在 R6 和 R7 连续两轮均为 0，证明单 session 排他 drain 与同步 RPC 顺序修复有效。压测端 A/B 回调队列峰值为 156/150，最大等待 13.281/25.038ms，结算时均为 0。
+
+按 R7 起压前和负载结束快照计算增量：服务端新增 1798 条 ctrl ACK，enqueue/write 平均约 82.43/82.89ms，P95 均在 500ms 桶内；`Cluster.TopicProxy` 新增 7943 次调用，平均约 2.27ms、P95 在 10ms 桶内。负载期无新增 RPC error、内部队列失败、Kafka lag、queue full、gob 错误或 Pod 重启，说明同步 RPC 没有形成负载期瓶颈。关闭后服务端 active WS 回落为 0，压测进程和 FD 均完全释放。
+
+### 25.3 关闭阶段 multiplex 队列竞态
+
+R6 和 R7 均在最后一批连接关闭后记录 1 次 `s.queueOut: session's send queue full 8:grpQ5_hPdAz3cE-im-server-0`。该事件发生在业务发送、实时静默、历史回查和 summary 生成之后，没有影响上述消息结果，但违反“渐进关闭阶段也不得队列满”的严格运维门禁。
+
+根因是 proxy stop/detach 后 multiplex worker 已退出并从 SessionStore 删除，而 Topic 的异步 unsubscribe 尚未完成，短时间内仍可能通过旧指针调用 `queueOut`。旧 session 未标记 terminating，消息进入无人消费的 send channel 并最终填满。修复已在本地完成：Cluster session 清理开始时先原子标记 terminating，并排空残留 channel；后续对旧指针的写入会被直接丢弃，不再进入失去 drain owner 的队列。新增关闭竞态测试和顺序测试均在普通模式连续 20 次、race 模式连续 10 次通过。
+
+因此当前结论分为两层：
+
+- 900 人混合消息业务门禁已经通过，跨 Pod 顺序修复有效。
+- 完整运维门禁还需发布关闭竞态补丁后做一次 R8，重点验证业务指标继续全绿且渐进关闭阶段 `queue full=0`。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r6-1001/`
+- `loadtest/im-pressure/results/s900m-mixed-r7-1001/`
+
+## 26. 900 人混合 R8 关闭竞态补丁复验
+
+Run ID：`s900m-mixed-r8-1002`。本轮使用与 R7 完全相同的 900 条 WebSocket、135 对单聊用户和 224 个群发送者负载，重点验证关闭竞态补丁发布后，业务负载期和 120 秒渐进关闭全过程不再出现 `send queue full`。
+
+| 指标 | R8 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 计划发送 / 实际尝试 | 1798 / 1798 |
+| 最终接受 / socket 结果未知 | 1796 / 2 |
+| 明确拒绝 / ACK 超过 20 秒 | 0 / 0 |
+| 精确 ACK P95 / 最大值 | 1041.578ms / 2055.915ms |
+| 单聊对端实时投递 | 1350 / 1350 |
+| 已接受群消息应投 / 实投 | 401400 / 400954 |
+| 已接受消息实时总投递 | 402750 / 402304 |
+| 实时缺口 | 446，全部可持久化回查 |
+| 重复 / 乱序 | 0 / 0 |
+| 压测期非预期断连 | 1，公网读超时后自动重连 |
+| 历史回查 | 1796 / 1796 |
+| MySQL 精确命中 | 1796 / 1796 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| 负载期 / 关闭期 queue full | 0 / 0 |
+| Pod Ready / 重启 | 3 / 3，0 重启 |
+
+### 26.1 严格业务门禁结论
+
+本轮 `report.json` 为 `passed=false`。失败由 A 机第 231 个连接的一次公网读超时引起：
+
+```text
+read tcp 192.168.1.135:57717->216.236.31.191:443: read: operation timed out
+```
+
+断连发生于 `2026-10-02T06:31:53.391465Z`，客户端约 1.5 秒后报告连接恢复。该用户的两条群发送 `s900m-mixed-r8-1002-g-a-0231-01/02` 分别得到 `websocket closed` 和 `websocket connection unavailable`，未进入服务端，MySQL 中也没有对应额外行。因此实际被服务端接受的业务消息为 1796 条，不能把这两条计为服务端持久化丢失。
+
+同一连接在群消息阶段漏收 446 条已接受群消息，形成 446 次实时投递缺口；这些消息全部可通过历史回查获得。其余连接的群投递、全部 1350 次单聊对端投递、重复和顺序检查均正确。按严格验收标准，本轮仍因 `disconnects=1`、`publish_outcome_unknown=2` 和实时缺口判定失败，不能替代 R7 的业务全绿结论。
+
+服务端三个 Pod 在超时窗口均保持 Ready、零重启、Kafka lag 为 0，也没有 Topic、Cluster、WS 队列满、RPC error、gob 或持久化错误。证据更符合压测机到单个公网入口的瞬时网络读超时，不支持服务端容量拐点或队列阻塞判断。
+
+### 26.2 关闭竞态补丁结论
+
+关闭竞态补丁的专项验收通过。两个 agent 均完成实时静默、5 分钟沉淀、历史回查、summary 生成和 120 秒渐进关闭，并以退出码 0 结束；没有提前停止进程。从负载开始到全部压测连接关闭后的完整 Pod 日志中：
+
+- `s.queueOut: session's send queue full` 为 0；
+- Cluster P2M `queue_full` 增量为 0；
+- WS send queue `queue_full` 增量为 0，三个 Pod 结算队列深度均为 0；
+- 未出现旧 multiplex session 无消费者却继续积压消息的现象；
+- 三个 Pod 均保持 Ready、0 重启，Cluster peer 均为 2/2。
+
+这证明“清理 Cluster session 前先标记 terminating 并 purge channel”的修复已经消除 R6/R7 关闭末尾出现的孤儿发送队列积压。关闭期日志仅有 1 次客户端渐退附近的 `close 1006 unexpected EOF`，没有引发队列堆积或 Pod 状态异常。
+
+### 26.3 服务端与压测端观测
+
+按起压前和负载结束快照计算增量：
+
+| 指标 | 结果 |
+|---|---:|
+| `Cluster.TopicProxy` | 8227 次，平均 2.285ms，P95 在 10ms 桶内 |
+| ctrl ACK enqueue | 1798 次，平均 62.11ms，P95 在 250ms 桶内 |
+| ctrl ACK write | 1798 次，平均 62.43ms，P95 在 250ms 桶内 |
+| Cluster P2M queue full | 0 |
+| WS send queue full | 0 |
+| Kafka consumer lag | 全部为 0 |
+
+A/B 回调队列峰值为 63/47，最大等待为 9.865/10.031ms，结算时等待和处理中均为 0。客户端回调处理没有形成瓶颈。MySQL 校验覆盖 `im_008_group_messages_202610` 与 `im_008_messages`，1796 条服务端已接受消息全部精确命中。
+
+本轮结论应分开使用：**关闭竞态修复已通过专项复验；R8 整体业务门禁因一次公网断连失败。**如需获得“修复版本下业务与关闭运维门禁同时全绿”的单轮证据，应保持参数不变再执行 R9；无需因本轮结果继续修改服务端队列代码。
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r8-1002/report.json`
+- `loadtest/im-pressure/results/s900m-mixed-r8-1002/db-verification.json`
+- `loadtest/im-pressure/results/s900m-mixed-r8-1002/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-mixed-r8-1002/server-metrics/`
+- `loadtest/im-pressure/results/s900m-mixed-r8-1002/im-server-{0,1,2}.log`
+
+## 27. 900 人混合 R9 全量复验
+
+Run ID：`s900m-mixed-r9-1002`。本轮保持 R8 的配置、账号、消息量和验收口径不变。起压前三个公网入口均返回 200，HTTPS 总耗时约 0.48 至 0.56 秒；三个 Pod 使用相同镜像，均为 Ready、0 重启。
+
+| 指标 | R9 |
+|---|---:|
+| 就绪连接 | 900 / 900 |
+| 发送尝试 / 最终接受 | 1798 / 1798 |
+| 明确拒绝 / 结果未知 | 0 / 0 |
+| 超过 20 秒的 ACK | 10 |
+| 精确 ACK P95 | 11417.014ms |
+| 单聊对端实时投递 | 1350 / 1350 |
+| 群聊实时投递 | 403200 / 403200 |
+| 实时总投递 | 404550 / 404550 |
+| WS 匹配回调总数（含单聊回显） | 405900 / 405900 |
+| 实时到达率 / 丢失率 | 100% / 0% |
+| 重复 / 乱序 / 断连 | 0 / 0 / 0 |
+| 历史回查 | 1798 / 1798 |
+| MySQL 精确命中 | 1798 / 1798 |
+| MySQL 缺失 / 错配 / 重复 / 额外 | 0 / 0 / 0 / 0 |
+| 负载期 queue full | 0 |
+| 渐进关闭期 queue full | 1 |
+| Pod Ready / 重启 | 3 / 3，0 重启 |
+
+### 27.1 业务门禁通过
+
+本轮 `report.json` 为 `passed=true`。1798 条发送全部得到最终 ACK，404550 次对端投递全部实时到达；没有发送未知、实时丢失、重复、乱序或非预期断连。A/B 各收到 202950 次匹配回调，其中包含 675 次单聊发送方回显，因此底层回调总数为 405900。
+
+历史接口和 MySQL 均精确命中 1798/1798。数据库校验覆盖 `im_008_group_messages_202610` 与 `im_008_messages`，缺失、错配、重复和额外行均为 0。Kafka consumer lag 全部为 0，三个 Pod 全程 Ready、0 重启。
+
+A/B 回调队列峰值为 218/210，结算时均完全排空。按起压前和负载结束快照计算，服务端 `Cluster.TopicProxy` 新增 7857 次调用，平均 1.752ms、P95 在 5ms 桶内；ctrl ACK enqueue/write 各 1798 次，平均 72.513/72.812ms，P95 均在 500ms 桶内。负载期没有 Topic、Cluster、WS 队列满、RPC 失败、gob 或持久化错误。
+
+因此 R9 已取得修复版本下完整的消息业务全绿证据，并再次验证跨 Pod 顺序修复有效。10 条超过 20 秒的 ACK 均在 90 秒命令窗口内返回，继续按既定口径只做趋势观测。
+
+### 27.2 关闭期仍有一个低概率队列满
+
+在最后一批连接退出时，Pod `im-server-1` 于 `2026-10-02T07:23:16Z` 记录：
+
+```text
+s.queueOut: session's send queue full 8:grpQ5_hPdAz3cE-im-server-2
+topic[grpQ5_hPdAz3cE]: connection stuck, detaching - 8:grpQ5_hPdAz3cE-im-server-2
+cluster: session proxy closed 8:grpQ5_hPdAz3cE-im-server-2
+```
+
+该事件发生在 summary 已生成、1798 条历史核验完成之后，没有影响消息正确性和持久化。结算时三个 Pod 的 WS send queue 与 Cluster P2M queue 深度均为 0，Kafka lag 为 0。
+
+R9 证据修正了 R6/R7 时的部分根因判断。此次队列满发生时，`grp...-im-server-2` multiplex session 尚未终止；日志顺序是先队列满、Topic 判定连接卡住并 detach，最后 session 才关闭。因此 R8 发布的 `terminating + purgeChannels` 补丁只能防止“已进入终止流程的旧 session 被继续写入”，不能处理仍存活 multiplex session 在大量连接关闭时的瞬时响应突发。
+
+当前 multiplex `send` channel 容量为 `sendQueueLimit + 32 = 160`。Cluster 写任务采用排他调度和同步 Master-to-Proxy RPC；正常负载期吞吐稳定，但关闭阶段多个 unsubscribe/presence 响应可在 drain worker 获得调度前快速填满 160 个槽位。R8 未复现、R9 复现 1 次，符合低概率调度竞态，而不是持续消费能力不足：R9 关闭阶段 `Cluster.TopicProxy` 仍完成 3195 次调用，平均约 0.9ms、P95 在 3ms 桶内。
+
+后续修复不应只继续增加 terminating 判断。建议为 MULTIPLEX 出站队列增加一个很短的有界背压重试：首次非阻塞入队失败时确保 drain 已调度，并等待最多约 250ms 获取队列槽位；超时后才维持现有的 `queue full -> detach` 保护。这样可以吸收调度抖动和关闭突发，同时避免永久阻塞 Topic goroutine。需要增加“队列已满但 worker 很快释放槽位”与“worker 永久不消费时按时失败”两类回归测试，发版后再执行 R10 专项复验。
+
+上述修复已在 R9 后完成：MULTIPLEX 出站队列首次满时会确保 Cluster drain 已调度，并在 250ms 有界窗口内等待一个槽位；只有持续无消费超过窗口才沿用原来的失败和 detach 保护。新增的 `clusterQueueMu` 将 terminating 检查与入队、以及终止标记与 channel 清理串行化，防止等待期间 session 恰好终止后消息重新进入已清空队列。普通 WebSocket、gRPC 和长轮询队列仍保持原有非阻塞语义，不受此次改动影响。
+
+回归测试覆盖短暂队列满后恢复、持续不消费按时失败、等待期间 session 终止不残留消息，以及原有跨 Pod 顺序与终止拒绝写入场景。针对性测试普通模式连续 20 次、race 模式连续 10 次通过，`go test ./server ./loadtest/im-pressure` 全部通过。该修复尚待发版并执行 R10 复验。
+
+本轮最终结论：**消息业务门禁通过；完整运维门禁仍因关闭期 1 次 multiplex queue full 未通过。**
+
+新增产物：
+
+- `loadtest/im-pressure/results/s900m-mixed-r9-1002/report.json`
+- `loadtest/im-pressure/results/s900m-mixed-r9-1002/db-verification.json`
+- `loadtest/im-pressure/results/s900m-mixed-r9-1002/metrics.jsonl`
+- `loadtest/im-pressure/results/s900m-mixed-r9-1002/server-metrics/`
+- `loadtest/im-pressure/results/s900m-mixed-r9-1002/im-server-{0,1,2}.log`

docs/test/IM-单聊压测Pod日志根因分析与改进方案-20260927.md

@@ -297,3 +297,219 @@ Run ID：`p2p-200-20260927-01`，A/B 两台压测机各模拟 200 个用户，
 - ACK P95 和到达 P95 均落在 2 秒直方图上界，未达 500ms / 1s 门槛。
 - ArgoCD 已将 StatefulSet 资源回滚为 `request 100m/128Mi`、`limit 500m/256Mi`，且 liveness 仍使用 `/healthz`。压测期间存在 CPU throttling 累计，部署配置必须在 GitOps 声明源中固化，否则应用后仍会被回滚。
 - 403 修复发布后应重跑 200 对；只有 ACK 成功率、实时到达率、MySQL 精确落库均达标，才进入 500 对档位。
+
+## 12. 200 对第三轮复测结果
+
+Run ID：`p2p-200-20260927-03`。压测前修复了压测工具复用固定 `Idempotency-Key` 而跳过好友关系校验的问题，并重新核对、修复 200 对测试账号。
+
+| 指标 | 结果 |
+|---|---:|
+| WS Ready | 400/400 |
+| Publish 尝试 / ACK | 4000 / 4000 |
+| Publish 拒绝 / 403 / 502 / 503 | 0 / 0 / 0 / 0 |
+| ACK 后应到达 / 实际到达 | 4000 / 4000 |
+| 实时到达率 | 100% |
+| 历史查询 | 4000/4000 |
+| MySQL 精确匹配 | 4000/4000 |
+| MySQL 缺失 / 错配 / 重复 / 非 ACK 落库 | 0 / 0 / 0 / 0 |
+| 丢失 / 重复 / 断连 | 0 / 0 / 0 |
+| 乱序 | 1 |
+| Cluster 队列采样最大值 | 0 |
+| Kafka 峰值 lag / 最旧 backlog age / 最终 lag | 3028 / 92.624s / 0 |
+
+结论：跨 Pod 发送、ACK 后实时投递、Kafka 最终消费和 MySQL 落库的数据正确性已通过 200 对验证。结果报告仍为不通过，原因是 B 端记录 1 次单连接 Topic seq 回退，以及 ACK P95 和投递 P95 均落入 1-2s 区间。
+
+资源采样显示，三个 Pod 峰值内存低于 94MiB，但 Pod 0/1/2 在本轮窗口内的 CPU throttled 增量约为 7.62s / 0.78s / 8.51s。实际 StatefulSet 仍是 `request 100m/128Mi`、`limit 500m/256Mi`，且 liveness 仍是 `/healthz`。因此延迟和 Kafka 追平速度尚不能作为扩容到 500 对的验收基线。
+
+已增加 `deploy/argocd/im-server-test/statefulset-performance-patch.yaml`，要求 ArgoCD 声明源固化 `request 1C/512Mi`、`limit 2C/1Gi`和 `/livez` liveness。部署流水线改为等待 ArgoCD 回写后严格校验，如果再被回滚则直接失败。压测工具保留乱序为失败门禁，并新增最多 100 条 `receiver/topic_hash/previous_seq/current_seq/client_mid` 明细，用于下轮精确定位。
+
+## 13. GitOps 资源生效后的第四轮复测
+
+Run ID：`p2p-200-20260927-04`。ArgoCD Application `im-server-test` 的真实配置仓库已固化 `request 1C/512Mi`、`limit 2C/1Gi` 和 `/livez`，三个 Pod 完成滚动后均为 Ready、零重启。
+
+| 指标 | 结果 |
+|---|---:|
+| WS Ready | 400/400 |
+| Publish 尝试 / ACK | 4000 / 4000 |
+| Publish 拒绝 / 403 / 502 / 503 | 0 / 0 / 0 / 0 |
+| ACK 后应到达 / 实际到达 | 4000 / 4000 |
+| 实时丢失 / 重复 / 乱序 / 断连 | 0 / 0 / 0 / 0 |
+| 历史查询 | 4000/4000 |
+| MySQL 精确匹配 | 4000/4000 |
+| MySQL 缺失 / 错配 / 重复 / 非 ACK 落库 | 0 / 0 / 0 / 0 |
+| 精确 ACK P50 / P95 / P99 / Max | 368.189 / 566.683 / 725.654 / 1600.975 ms |
+| 投递 P95 直方图上界 | 1000 ms |
+| Cluster 队列采样最大值 | 0 |
+| Kafka message persist 峰值 lag / 归零耗时 | 2946 / 发送结束后 113s |
+| Pod 0/1/2 CPU throttled 增量 | 0 / 0 / 0 usec |
+| Pod 0/1/2 峰值内存 | 87.86 / 80.80 / 85.18 MiB |
+
+结论：消息正确性全部通过，第三轮出现的 1 条 seq 回退没有复现。资源扩容完全消除了本轮 CPU throttling，证明旧的 500m CPU limit 是延迟放大因素之一；精确 ACK P95 从第三轮的 1006.288ms 降至 566.683ms，下降约 43.7%，但仍比 500ms 门槛高约 13.3%，因此报告只因 ACK 延迟门禁判定失败。
+
+Kafka `im-server.message_persist` lag 在发送后峰值为 2946，并在发送结束后约 113 秒归零，超过 60 秒目标。历史 API 和 MySQL 最终均确认 4000 条完整落库，说明这是落库延迟而不是消息丢失。进入 500 对测试前，应优先检查 message persist consumer 的批量写入、worker/partition 并行度和 MySQL 写入耗时。
+
+连接集中关闭期间，三个 Pod 分别记录 10、14、22 次 `failed to close login audit ... Deadlock found`，共 46 次。该问题未影响消息表，但会导致登录审计结束状态不完整。登录审计关闭更新应增加 MySQL 1213/1205 有界重试，并检查更新条件和索引以缩小锁范围。
+
+## 14. 持久化并行与审计死锁修复后的第五轮复测
+
+Run ID：`p2p-200-20260927-05`。本轮已将 `im.message.persist` 和 `im.group.message.persist` 固化为 3 分区、3 副本；同一 Topic 继续作为 Kafka key，保证会话内顺序。服务端同时按 batch 内最大 Seq 合并 Topic 和发送者已读位点更新，并为登录审计关闭增加复合索引和 MySQL 死锁重试。
+
+| 指标 | 结果 |
+|---|---:|
+| WS Ready | 400/400 |
+| Publish 尝试 / ACK | 4000 / 4000 |
+| ACK 后应到达 / 实际到达 | 4000 / 4000 |
+| 丢失 / 重复 / 乱序 / 断连 | 0 / 0 / 0 / 0 |
+| 历史查询 / MySQL 精确匹配 | 4000/4000 / 4000/4000 |
+| MySQL 缺失 / 错配 / 重复 / 非 ACK 落库 | 0 / 0 / 0 / 0 |
+| 总体精确 ACK P50 / P95 / P99 / Max | 375.314 / 547.516 / 670.317 / 2845.347 ms |
+| A 机精确 ACK P95 | 408.155 ms |
+| B 机精确 ACK P95 | 594.533 ms |
+| Pod 0/1/2 Kafka 峰值 lag | 676 / 251 / 143 |
+| 最慢 Kafka 分区归零时间 | 发送结束后约 52.5s |
+| Cluster 队列峰值 / CPU throttled 增量 | 0 / 三 Pod 均为 0 |
+| 登录审计关闭死锁 | 三 Pod 均为 0 |
+| Kafka batch failure / Pod 重启 | 0 / 0 |
+
+结论：三分区已由三个 Pod 实际并行消费，单 Pod 峰值 lag 从第四轮的 2946 降至 676，最慢消费者在 60 秒门槛内归零。消息正确性、最终落库、会话内顺序、CPU 限流和登录审计死锁均通过。
+
+报告仍因 ACK P95 门禁显示失败。直方图只能给出 1000ms 上界，按 4000 条 ACK 原始时间戳和 nearest-rank 口径计算的实际 P95 为 547.516ms。A 机已经低于 500ms，而 B 机为 594.533ms，且 B 机存在 2.845s 最大长尾；两台机器使用相同公共入口和相同服务端版本，因此继续修改服务端前，应先采集 B 机到 `api.118im.com` 的 DNS、TCP、TLS、WebSocket RTT 与时钟偏差，并使用定向 Pod 入口做 A/B 对照，区分公网链路长尾和服务端处理耗时。
+
+## 15. 500 对第一轮容量测试
+
+Run ID：`p2p-500-20260927-01`。A/B 各建立 500 条 WebSocket，共 500 对、1000 条连接和 10000 次 Publish。正式发压前补齐了第 201–500 对中缺失的 9 对好友权限，两端预检和 Ready 均通过。
+
+| 指标 | 结果 |
+|---|---:|
+| WS Ready | 1000/1000 |
+| Publish 尝试 / ACK | 10000 / 9946 |
+| Publish 失败 | 54（44 条服务端 500/other，10 条 socket error） |
+| Publish 成功率 | 99.46% |
+| ACK 后应到达 / 实际到达 | 9946 / 9936 |
+| 实时丢失 / 重复 / 乱序 / 断连 | 10 / 0 / 0 / 1 |
+| 实时到达率 | 99.8995% |
+| 总体精确 ACK P95 / Max | 2429.954 / 3636.045 ms |
+| 压测期历史回查 | 8580/9946 |
+| Kafka 完全排空后 MySQL 精确匹配 | 9946/9946 |
+| MySQL 缺失 / 错配 / 重复 / 非 ACK 落库 | 0 / 0 / 0 / 0 |
+| Pod 0/1/2 Kafka 峰值 lag | 2490 / 3234 / 2745 |
+| Kafka 归零时间 | 发送结束后约 4 分钟 |
+| Pod 0/1/2 峰值内存 | 148.1 / 130.5 / 122.4 MiB |
+| Pod 0/1/2 CPU throttled 增量 | 0 / 0 / 0 |
+| Pod 重启 | 0 |
+
+本轮不通过，不得升级到 1000 对。根因是 MySQL 连接容量与 IM Server 连接池上限不匹配：
+
+- MySQL `max_connections=170`，本轮 `Max_used_connections=172`，`Connection_errors_max_connections=27`。
+- IM Server 每 Pod `max_open_conns=64`，3 个 Pod 的理论连接池上限已达 192，还未计入 admin server、其他服务和运维连接。
+- 本轮 Pod 0/1 分别记录 153/19 次 `Error 1040: Too many connections`，包括 50 次 `failed to save message`和 44 次 P2P 关系检查失败；这些错误与 44 条服务端 500 同时出现。
+- A 机用户 190 的 WebSocket 断开，产生 10 次 socket error，并导致对端已 ACK 的 10 条消息未能实时投递到该连接。
+- 压测结束阶段 Pod 2 记录 282 次群 Topic broadcast queue full，发生在大量会话同时清理期，需要与消息发送链路分开处理。
+
+压测阶段的 `history_found=8580`不是最终丢库：历史回查结束时 Kafka 仍在积压，等 lag 归零后从 Pod 内使用 ACK ledger 独立查询 `im_008_messages`，9946 条全部精确匹配。因此当前是“已接受消息最终零丢失，但持久化延迟超标”。
+
+下一轮 500 对复测前必须先完成：
+
+1. 统一规划 MySQL 全局连接预算，覆盖 IM Server、admin server 及其他共库服务；单个服务的连接池上限不能独立设置到总库容量。
+2. 修正 IM Server 每 Pod 的 `max_open_conns/max_idle_conns`，或在验证 MySQL CPU、内存、线程和 PXC 限制后提高 `max_connections`；必须保留至少 20% 全局余量。
+3. 压测中增加 DB pool `OpenConnections/InUse/Idle/WaitCount/WaitDuration`和 MySQL `Threads_connected/Threads_running/Max_used_connections/Connection_errors_max_connections` 指标。
+4. 复测要求 Publish ACK 10000/10000、实时丢失和断连为 0、Kafka 60 秒内归零、MySQL 1040 和清理期 queue full 为 0，然后才能进入 1000 对。
+
+### 15.1 为什么 Kafka 可以积压，但本轮仍会报错
+
+Kafka 积压只能保护“已经成功写入 Kafka”的消息。正常情况下，consumer 落库变慢只会使 lag 上升，消息会在 Kafka 中等待，不应导致 Publish 报错。本轮的 54 条失败发生在 Kafka 之前：
+
+1. 普通文本消息先同步查询青少年模式设置，但当前规则无论查询结果都允许消息继续进入内容审核。
+2. P2P 发布在写 Kafka 前调用 `CanSendP2P`，旧实现即使 Redis 已命中好友关系，仍会读取 MySQL 用户和好友记录。
+3. 入口校验、Kafka consumer、历史查询和登录审计共用 MySQL 连接预算。连接耗尽后，入口校验直接返回 500，这些消息没有进入 Kafka，因此无法通过“后续慢慢消费”恢复。
+
+### 15.2 IM 侧改造
+
+2026-09-27 已完成以下修复：
+
+- 普通消息不再读取青少年模式表；通话的夜间禁用规则仍保留数据库查询。
+- P2P 热路径先查双向黑名单缓存，再使用好友正缓存；缓存未命中或 Redis 异常时才回源 MySQL。新增拉黑会同时清理双向好友正缓存，避免安全状态陈旧。
+- `meeting_im` 每 Pod 连接池设为 `max_open=24/max_idle=8`，`hotgo` 注册表库独立设为 `max_open=4/max_idle=2`。3 个 Pod 的 IM 理论总上限由 384 降为 84；结合 Workbench 30、Manager 20 的上限，整套服务理论上限为 134，在当前 MySQL 170 连接上限下保留 36 条全局余量。
+- 连接池参数改为环境变量，并同时固化到应用仓库及 ArgoCD 真实配置源。发布流水线会在 ArgoCD 回写后校验四个连接池参数。
+- 新增 `im_db_pool_*` 指标，包括 max/open/in-use/idle/wait count/wait duration/关闭计数，并为连接池 85%/95% 使用率配置预警和严重告警。
+
+这些修复的目标是先让入口稳定完成缓存校验和 Kafka enqueue，把 MySQL 慢转化为可观测、可恢复的 Kafka lag，而不是 Publish 500。如果复测时 `im_db_pool_wait_total` 持续增长或 Kafka 仍无法在 60 秒内归零，再根据 PXC 的 CPU/内存/线程容量将 MySQL `max_connections` 持久化提高到 300–400，不使用临时 `SET GLOBAL`代替配置源。
+
+## 16. 500 对连接池改造后复测
+
+Run ID：`p2p500-fix-20260927-02`。A/B 各建立 500 条 WebSocket，共 500 对、1000 条连接和 10000 次 Publish。三个 IM Pod 均已使用 `meeting_im=24/8`、`hotgo=4/2` 的连接池配置。
+
+| 指标 | 改造前 | 本轮 |
+|---|---:|---:|
+| WS Ready | 1000/1000 | 1000/1000 |
+| Publish ACK | 9946/10000 | 10000/10000 |
+| 服务端 500 / socket error | 44 / 10 | 0 / 0 |
+| 实时到达 | 9936/9946 | 10000/10000 |
+| 实时丢失 / 重复 / 乱序 / 断连 | 10 / 0 / 0 / 1 | 0 / 0 / 0 / 0 |
+| ACK P50 / P95 / P99 / Max | - / 2429.954 / - / 3636.045 ms | 662.062 / 1567.569 / 2620.878 / 3156.025 ms |
+| 压测期历史回查 | 8580/9946 | 6738/10000 |
+| Kafka 排空后 MySQL 精确匹配 | 9946/9946 | 10000/10000 |
+| MySQL 缺失 / 错配 / 重复 / 非 ACK 落库 | 0 / 0 / 0 / 0 | 0 / 0 / 0 / 0 |
+| Pod 0/1/2 Kafka 峰值 lag | 2490 / 3234 / 2745 | 2259 / 2875 / 2326 |
+| Kafka 最慢归零 | 约 4 分钟 | 发送结束后约 4 分 30 秒 |
+| MySQL 1040 | 172 次 Pod 日志记录 | 0 |
+| Pod 重启 | 0 | 0 |
+
+结论分为两部分：
+
+1. 入口和实时正确性修复有效。10000 次 Publish 全部被接受，实时投递、最终落库、顺序、重复和断连门禁全部通过；连接池上限把全局 MySQL 连接耗尽转化成了进程内排队，没有再出现 `Too many connections`。
+2. 容量门禁仍未通过，暂不升级到 1000 对。ACK P95 仍为 1567.569ms，Kafka 未在 60 秒内归零，压测期历史回查因落库未追平只看到 6738 条。
+
+本轮新增指标进一步定位出两个瓶颈：
+
+- 发送阶段 `hotgo` 注册库连接池出现 5841 次新增等待，累计等待约 210.25 秒。`TenantAdapterFor` 当前在命中已创建的租户 adapter 之前仍执行 `tenantByID`，使共库路由的高频操作重复查询 `im_tenant`；4 条注册库连接因此成为 ACK 热路径瓶颈。
+- 发送结束 30 秒后，两台 agent 同时以默认 48 worker 执行历史核验，形成 96 路历史查询。三个 `meeting_im` 连接池随后全部达到 24/24；主库新增 6780 次连接等待，累计等待约 11010.16 秒。历史查询与 Kafka persistence 共用连接池，直接延长了 lag 排空时间。
+- Pod 2 有一个 100 条批次因 `context deadline exceeded` 降级为逐条写入，100 条最终均成功；三个 Pod 共记录 8 个数据库超时相关日志，没有死信，最终数据库精确核验为 10000/10000。
+
+下一轮前应完成：
+
+1. 为租户元数据增加带失效机制的进程内缓存；`TenantAdapterFor` 命中有效缓存时不得每次读取 `hotgo.im_tenant`，租户停用或配置变更通过现有配置事件主动失效，并保留短 TTL 兜底。
+2. 压测程序把实时发压和持久化核验拆成两个阶段：先观察 Kafka 自然排空，再以每机 8–16 个 worker 执行历史核验，避免核验流量反向干扰被测落库吞吐。同时另设“历史读取并发压测”场景验证读写混合容量。
+3. persistence 与在线历史查询至少增加独立并发预算；若继续共用连接池，应为 persistence 保留连接或限制历史查询并发，避免读请求耗尽全部 24 条连接。
+4. 完成上述改造后仍以 500 对复测，门禁保持 ACK 10000/10000、实时错误为 0、Kafka 60 秒内归零、最终数据库 10000/10000，再决定是否升级到 1000 对。
+
+### 16.1 路由缓存和分阶段核验改造
+
+2026-09-27 已完成下一轮复测所需代码调整：
+
+- MySQL `TenantAdapterFor` 增加 1 分钟租户路由有效期；有效期内直接复用 tenant adapter，不再读取 `hotgo.im_tenant`。
+- 同一租户的缓存刷新使用 singleflight 合并，TTL 到期瞬间最多执行一次注册库查询，避免并发击穿。
+- `tenant.updated`、`tenant.status.changed`、`tenant.limits.updated`、`tenant.features.updated` 和 `cache.tenant.invalidate` 继续使用现有 Kafka 广播事件；`InvalidateTenantConfigCache` 现在同时使数据库路由缓存失效。失效与刷新并发时通过 generation 校验阻止旧查询重新写入有效缓存。
+- 压测配置新增 `history_settle`，默认 5 分钟。实时 drain 完成后先等待该窗口，再发起历史查询，从而单独测量 Kafka 自然排空时间。
+- 历史查询默认并发从每机 48 降为 12；历史读取高并发能力后续使用独立读写混合场景验证，不再污染消息落库吞吐结果。
+
+## 17. 路由缓存发布后 500 对复测与延迟改造
+
+Run ID：`p2p500-r3-20260927-03`。A/B 各 500 条 WebSocket、每人发送 10 条消息，总计 10000 次 Publish。
+
+| 指标 | 结果 |
+|---|---:|
+| WS Ready | 1000/1000 |
+| Publish ACK | 10000/10000 |
+| 实时到达 / 丢失 | 10000/10000 / 0 |
+| 历史回查 / 落库丢失 | 10000/10000 / 0 |
+| 重复 / 乱序 / 断连 | 0 / 0 / 0 |
+| 总体精确 ACK P95 | 1308.150 ms |
+| A / B 精确 ACK P95 | 1121.2 / 1519.2 ms |
+| 原报告投递 P95 | 2000 ms（受双机时钟偏差污染） |
+| Kafka 最终 lag | 0 |
+| `hotgo` pool wait | 0 |
+
+租户路由缓存已经消除 `hotgo` 热路径等待，消息正确性和最终落库全部通过。剩余 ACK 延迟集中在消息 4–6 的突发积压阶段。发压窗口内，`meeting_im` 连接池出现明显等待；同时 Kafka persistence consumer 正在使用同一连接池。Cluster Route RPC 平均约 1–2ms，P2M 队列始终为 0，因此跨 Pod RPC 不是秒级延迟来源。
+
+原投递 P95 不能作为服务端结论：压测程序使用发送机绝对时间戳在接收机计算单向耗时。A 只接受了 5777 个非负样本，而 B 接受了全部 10000 个样本，说明 B 时钟领先 A；A 丢弃负值，B 则把时钟偏差计入延迟。
+
+本次完成以下改造：
+
+1. 压测程序新增同机与跨机两个投递直方图；`delivery_local_p95_ms` 作为门禁，跨机负延迟计入 `cross_machine_negative_latency_samples`，不再静默丢弃后继续生成误导性 P95。
+2. 压测消息显式携带 `sender_machine`，旧消息仍可从 `client_mid` 兼容识别来源。
+3. 好友关系首次数据库确认后双向回填 Redis，减少双向聊天后续回源。
+4. 新增 `im_message_publish_stage_duration_seconds{kind,stage,result}`，覆盖 `relationship_check`、`redis_idempotency`、`redis_sequence`、`kafka_produce` 和整体 `save` 阶段。
+5. 新增 `log_client_packets` 配置，默认关闭逐包 INFO 日志，避免每条消息额外 JSON 解析和容器 stdout I/O；需要诊断时才短期开启。
+
+下一轮仍使用 500 对复测。重点比较 `relationship_check`、`kafka_produce` 和 `save` 的 P95，并以 `delivery_local_p95_ms` 判断投递延迟；跨机延迟只有在 chrony/NTP 偏差确认小于 5ms 后才用于验收。数据库连接池暂不扩大，避免再次超过 MySQL 全局 170 连接预算；若 `relationship_check` 已稳定但 pool wait 与 Kafka lag 仍持续增长，再设计 persistence 独立连接预算或批量更新方案。

docs/third/IM-MinIO存储切换说明.md

@@ -0,0 +1,29 @@
+# IM 文件存储切换（OSS / MinIO）
+
+IM Server 继续提供 `/v0/file/u/` 上传和 `/v0/file/s/` 鉴权下载接口。客户端不直连对象存储。后台 `hotgo.hg_sys_config` 的 `im_third_party.media_handler` 是存储开关：`oss` 写阿里云 OSS，`minio` 写自建 MinIO。部署配置中的 `media.use_handler` 必须为 `sys_config`（`server/meetingim.conf` 已如此配置）；开关在服务启动时读取，修改后滚动重启 IM Server。
+
+## 后台配置
+
+先在 `hotgo` 执行 [IM-MinIO存储配置.sql](IM-MinIO存储配置.sql)，再通过后台填写：
+
+| 配置 key | 值或用途 |
+| --- | --- |
+| `media_handler` | `oss` / `minio`，默认保留现有值 |
+| `minio_endpoint` | `https://minio.118im.com`；容器内如有可达的 HTTPS 内网地址，可改用内网地址 |
+| `minio_bucket` | `xgjs`，需预先创建 |
+| `minio_region` | `us-east-1` |
+| `minio_access_key_id` | MinIO Access Key，后台敏感配置 |
+| `minio_secret_access_key` | MinIO Secret Key，后台敏感配置 |
+
+阿里云 OSS 的 `oss_*` 配置需继续保留，用于读取切换前的文件。回切 OSS 后，MinIO 的配置也需保留。新写入的 MinIO 对象在文件记录中保存为 `minio://<bucket>/<key>`；原有 OSS 文件位置不改。下载和清理按文件位置选择存储后端，不会因为切换开关迁移已有对象。
+
+## 上线顺序
+
+1. 确认 IM Server Pod 能访问 MinIO S3 API，且 `xgjs` 桶及访问密钥可用；不要使用 Console URL 作为 API endpoint。
+2. 执行配置 SQL 并在后台填写密钥；保留 `media_handler=oss`，发布包含 MinIO handler 的 IM Server。
+3. 将 `media_handler` 改为 `minio`，滚动重启 IM Server，在客户端做小文件上传、下载、Range 下载、删除和历史 OSS 文件下载验证。
+4. 回切时将 `media_handler` 改为 `oss` 并滚动重启；已有 MinIO 文件继续从 MinIO 读取。
+
+MinIO 对象默认按私有文件处理。示例中的直连公网 URL 只有在桶策略允许公开读取时才可访问；IM 客户端应使用服务返回的文件 URL。当前阿里云内容安全接口接受阿里云 OSS 对象参数，MinIO 文件的第三方审核任务需另行接入可用的文件提交方式，不能把 MinIO 对象直接当 OSS 对象提交。
+
+2026-10-17：本地和测试环境的 `hotgo` 均已加入 MinIO 字典与配置项，凭据已分别填入数据库，`media_handler` 仍为 `oss`。MinIO 公网 S3 API 的独立上传、读取、删除冒烟测试已通过；切换后仍需从测试环境 IM Server Pod 验证完整客户端上传链路。

docs/third/IM-MinIO存储配置.sql

@@ -0,0 +1,44 @@
+-- 在 hotgo 后台库执行。只增加配置项，不切换当前存储后端。
+USE hotgo;
+
+INSERT INTO hg_sys_dict_type
+    (`pid`, `name`, `type`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT 0, 'IM 存储服务商', 'im_storage_provider', 210, 'IM 文件存储 provider 字典', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_type WHERE `type` = 'im_storage_provider');
+
+INSERT INTO hg_sys_dict_data
+    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT 'MinIO', 'minio', 'string', 'im_storage_provider', 'info', 0, 20, '自建 MinIO 对象存储', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_storage_provider' AND `value` = 'minio');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_third_party', 'MinIO Endpoint', 'string', 'minio_endpoint', 'https://minio.118im.com', 'https://minio.118im.com', 22, 'MinIO S3 API 地址；优先使用内网 HTTPS 地址', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'minio_endpoint');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_third_party', 'MinIO Bucket', 'string', 'minio_bucket', 'xgjs', 'xgjs', 23, 'MinIO 已创建的存储桶', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'minio_bucket');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_third_party', 'MinIO Region', 'string', 'minio_region', 'us-east-1', 'us-east-1', 24, 'MinIO 签名地域', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'minio_region');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_third_party', 'MinIO Access Key', 'string', 'minio_access_key_id', '', '', 25, '敏感配置；后台脱敏展示', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'minio_access_key_id');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_third_party', 'MinIO Secret Key', 'string', 'minio_secret_access_key', '', '', 26, '敏感配置；后台脱敏展示', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'minio_secret_access_key');
+
+UPDATE hg_sys_config SET `tip`='IM 文件存储开关：oss 或 minio；修改后滚动重启 IM Server'
+WHERE `group`='im_third_party' AND `key`='media_handler';
+
+-- 核验上传、下载、旧 OSS 文件读取后再执行：
+-- UPDATE hg_sys_config SET `value`='minio', updated_at=NOW()
+-- WHERE `group`='im_third_party' AND `key`='media_handler';

docs/third/IM-文件安全第三方接入记录.md

@@ -45,6 +45,8 @@ tenants/{tenantID}/{yyyy}/{mm}/{fileID}
 | `verify_bucket` | 启动时是否联网校验 Bucket 存在 |
 | `use_sys_config` | 为 `true` 时从 `hotgo.hg_sys_config` 读取 OSS 配置 |
 
+OSS endpoint 填写 `https://oss-cn-shenzhen.aliyuncs.com`。IM Server 初始化 OSS handler 时也会给裸域名补 HTTPS，并将阿里云 OSS 的显式 HTTP endpoint 改为 HTTPS。修改后台 `im_third_party.oss_endpoint` 后需重启 IM Server；发布后用真实文件上传验证 `POST /v0/file/u/`，确认 Pod 到 OSS 走 443 端口且不再出现 TCP 写超时。若 HTTPS 仍超时，继续检查 Pod 到 OSS 的出网链路。
+
 当前 `server/tinode.conf` 仍默认使用 `fs`。切换 OSS 时，将 `media.use_handler` 改为 `oss`，并在 `media.handlers.oss` 中设置 `use_sys_config=true` 后，运行时会从后台库 `hotgo.hg_sys_config` 的 `im_third_party` 分组读取 OSS 配置。
 
 代码入口：

docs/third/IM-第三方配置与文件安全SQL.sql

@@ -142,7 +142,7 @@ WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' A
 
 INSERT INTO hg_sys_config
     (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
-SELECT 'im_third_party', 'OSS Endpoint', 'string', 'oss_endpoint', '', '', 12, '例如 oss-cn-shenzhen.aliyuncs.com，禁止写 AccessPoint endpoint', 1, 1, NOW(), NOW()
+SELECT 'im_third_party', 'OSS Endpoint', 'string', 'oss_endpoint', '', '', 12, '例如 https://oss-cn-shenzhen.aliyuncs.com；阿里云 OSS 上传使用 HTTPS，禁止写 AccessPoint endpoint', 1, 1, NOW(), NOW()
 WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'oss_endpoint');
 
 INSERT INTO hg_sys_config

docs/对接文档最新/IM-前后端对接文档.md

@@ -60,9 +60,35 @@ API Key 可以被客户端应用提取，因此不能把它当成用户密码或
 | WebSocket（支持自定义 Header 的原生客户端） | `wss://{host}/{api_path}v0/channels` | Upgrade Header `X-MeetingIM-APIKey` | 同上 |
 | 产品 HTTP | `https://{host}/{api_path}v1/im/*` | `Authorization: Bearer <params.token>` | 好友、群、收藏、搜索、工作台和设置 |
 | 文件 HTTP | `POST /v0/file/u/`、`GET /v0/file/s/{file_id}` | 当前用 `X-MeetingIM-Auth: token <base64_token>` | 文件上传下载；禁止 Query 传 Token |
+| 用户条款 | `https://{host}/legal/user-terms` | 无需认证、无需 API Key | 登录、注册页通过浏览器或 WebView 打开 |
+| 隐私政策 | `https://{host}/legal/privacy-policy` | 无需认证、无需 API Key | 登录、注册及设置页通过浏览器或 WebView 打开 |
 
 HTTP 请求统一通过 `X-MeetingIM-APIKey` 携带。浏览器 WebSocket 无法设置自定义 Upgrade Header 时才使用 `apikey` Query；日志和监控必须对该参数脱敏。产品 HTTP 还必须带 `X-IM-Schema: 1` 和 `X-Request-ID`；写操作带 `Idempotency-Key`。生产环境只允许 HTTPS/WSS。Token、密码、验证码、证件号不得写入 URL、普通日志、埋点或崩溃报告。
 
+#### 0.2.3 用户条款与隐私政策公开页面
+
+客户端不解析或内置协议正文，只保存以下 HTTPS 地址并直接打开：
+
+| 页面 | 通用地址 | 测试/生产域名示例 |
+| --- | --- | --- |
+| 用户条款 | `https://{host}/legal/user-terms` | `https://api.118im.com/legal/user-terms` |
+| 隐私政策 | `https://{host}/legal/privacy-policy` | `https://api.118im.com/legal/privacy-policy` |
+
+两个页面支持 `GET`、`HEAD`，返回 `text/html; charset=utf-8`，不要求 `X-MeetingIM-APIKey`、`X-IM-Schema` 或用户 Token。客户端登录前即可访问；链接应使用系统浏览器或支持 HTTPS 的 WebView 打开，不要把协议正文缓存为业务数据。服务端通过 ETag 和短时公共缓存控制版本刷新，协议更新并重新发布服务后客户端仍使用同一 URL。
+
+客户端不需要硬编码协议域名。`POST /v1/im/tenants/resolve` 的 `data.endpoints` 会同步返回：
+
+```json
+{
+  "legal": {
+    "user_terms": "https://api.example.com/legal/user-terms",
+    "privacy_policy": "https://api.example.com/legal/privacy-policy"
+  }
+}
+```
+
+登录、注册页点击对应文字时直接打开上述 URL，不附加 Token、API Key 或租户参数，并允许用户滚动、缩放和返回。
+
 WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。缺少或无效时不会建立 WebSocket，直接返回 HTTP 403：
 
 ```json
@@ -128,6 +154,12 @@ WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。
 
 客户端只使用稳定的 `reason` 分支和本地化文案，不解析 `message`。ID、Topic、Seq 游标在客户端均按字符串处理；时间统一为 UTC RFC3339 毫秒。分页统一使用 `limit` 与不透明 `cursor`，返回 `items`、`next_cursor`、`has_more`。
 
+资源不存在类错误统一语义（2026-09-29 修订）：
+
+- 好友申请 `accept/reject` 在申请不存在时统一返回 `404/20004 RESOURCE_NOT_FOUND`，两个入口语义一致。
+- 群类接口（`DELETE /v1/im/groups/{topic}`、`POST /v1/im/groups/{topic}/leave`、`POST /v1/im/groups/{topic}/qrcodes`、`PUT /v1/im/groups/{topic}/members/me/profile`、`GET/PATCH /v1/im/groups/{topic}/settings` 等经群成员校验的路径）在群不存在时返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散时返回 `410/30004 GROUP_DISSOLVED`；群存在但当前用户非成员仍是 `403/30005 PERMISSION_DENIED`。
+- 服务端对不存在的资源不再返回 5xx 或网关错误。
+
 ### 0.5 WebSocket 建连、登录和恢复顺序
 
 #### 0.5.1 现有服务端可直接执行的冷启动流程
@@ -210,8 +242,22 @@ WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。
 {"sub":{"id":"sub-topic-1","topic":"grp...","get":{"what":"desc sub data del","data":{"since":125,"limit":50},"del":{"since":1,"limit":50}}}}
 ```
 
+**向上翻页（加载更早历史）最终参数约定（后端已确认，2026-09-29）**：复用同一 `get data`，最终参数为 `before`（排他上界，返回 `seq < before`），**没有 REST cursor 语义**。聊天页滚动到顶部时发 `data:{"before":<当前已加载最小 seq>,"limit":50}`（`since` 可省略，默认 0）。服务端返回该锚点之前**最接近 `before` 的 `limit` 条**，`{data}` 按 `seq` 从大到小下发（首条即锚点前最新一条）；收到 `ctrl 204 no content`（`params.what=="data"`）表示已到会话顶部。`data` 参数全集：`since`（含下界）、`before`（排他上界）、`limit`、`ranges`。P2P 与群聊（含热缓存 fallback）语义一致。REST `GET /v1/im/conversations/{topic}/messages` 当前为空占位（见 4.21.1），不得用于历史分页。
+
 订阅成功后才允许 `{pub}`、`note read/recv` 等会话操作。断线恢复必须重新执行 `WebSocket Upgrade -> hi -> token login -> sub me -> 恢复 Topic`，同一连接内不得跳过 `hi` 或切换企业码。
 
+##### 0.5.1.1 WebSocket 心跳与在线状态
+
+当前 IM 长连接心跳使用 WebSocket 协议层 Ping/Pong，不使用业务 JSON 消息做保活。服务端每 15 秒发送一次 WebSocket Ping 帧（`pingPeriod=15s`），并期望客户端在 45 秒读超时窗口内返回 Pong（`idleSessionTimeout=45s`）；如果没有收到 Pong，或底层读写失败，服务端会关闭当前 Session。
+
+客户端要求：
+
+1. 使用系统 WebSocket 库时，必须确认库会自动回复 Pong；如果库不会自动回复，需要在收到 Ping 时显式发送 Pong。
+2. 不要把 `{"note":{"what":"kp"}}` 当作心跳。`kp/kpa/kpv` 只是“正在输入/正在录音/正在视频输入”等 UI 状态通知，不落库，也不能替代 WebSocket Pong。
+3. 连接关闭或报错后，客户端本地应立即把 IM 长连接视为离线，并按指数退避重连。重连成功后完整执行 `WebSocket Upgrade -> hi -> token login -> sub me -> sub topics -> get data/del`，用本地最后完整持久化的 `seq + 1` 增量补消息。
+4. 服务端收到任意客户端上行 JSON 消息或 WebSocket Pong 后，都会刷新在线状态。当前在线状态写入 Redis，默认 TTL 为 120 秒，用于好友在线状态、群成员在线状态等展示。
+5. iOS/Android 进入后台后系统可能挂起 WebSocket。后台场景以推送唤醒和前台重连补偿为主，不要求客户端在后台无限重连。
+
 #### 0.5.2 Long Polling 兼容流程：先取得的是 sid
 
 如果客户端无法使用 WebSocket，可以使用现有 `/v0/channels/lp`。该模式确实需要“先请求取得一个值”，但取得的是短期 Session ID `sid`，API Key 仍然必须由客户端预先持有。
@@ -284,11 +330,13 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 租户握手 `hi` | `{"hi":{"id":"hi-1","ver":"0.25","ua":"Tinodios/1","platf":"ios","lang":"zh-CN","tenant":"default"}}` | `{"ctrl":{"id":"hi-1","code":201,"text":"created","params":{"ver":"0.25","tenant":{"code":"default","name":"Default Tenant"},"maxMessageSize":4194304,"maxFileUploadSize":33554432,"maxSubscriberCount":128}}}` |
 | 账号密码登录 | `{"login":{"id":"login-1","scheme":"basic","secret":"base64(username:password)"}}` | `{"ctrl":{"id":"login-1","code":200,"text":"ok","params":{"user":"usr...","username":"alice","authlvl":"auth","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
 | Token 登录 | `{"login":{"id":"login-2","scheme":"token","secret":"上次登录返回的 token 原文"}}` | `{"ctrl":{"id":"login-2","code":200,"text":"ok","params":{"user":"usr...","authlvl":"auth","token":"new_token...","expires":"2026-09-03T09:00:00Z"}}}` |
-| 用户名注册 | `{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"","invite_code":"AbCdE","secret":"base64(alice:password)","login":true,"desc":{"public":{"fn":"alice"}}}}` | `{"ctrl":{"id":"acc-1","code":200,"text":"ok","params":{"user":"usr...","username":"alice","authlvl":"auth","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
-| 手机号注册 | `{"acc":{"id":"acc-2","user":"new","scheme":"basic","username":"alice","phone":"15500000000","secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"15500000000","resp":"verification_token","params":{"challenge_id":"chg_123"}}],"desc":{"public":{"fn":"alice"}}}}` | `{"ctrl":{"id":"acc-2","code":200,"text":"ok","params":{"user":"usr...","username":"alice","authlvl":"auth","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
+| 邀请码注册 | `{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"138...","registration_type":1,"secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"138...","resp":"AbCdE","params":{"challenge_id":"challenge-id"}}],"desc":{"public":{"fn":"alice"}}}}` | `{"ctrl":{"id":"acc-1","code":200,"text":"ok","params":{"user":"usr...","username":"alice","authlvl":"auth","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
+| 手机号注册 | `{"acc":{"id":"acc-2","user":"new","scheme":"basic","username":"alice","phone":"15500000000","registration_type":1,"secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"15500000000","resp":"verification_token","params":{"challenge_id":"chg_123"}}],"desc":{"public":{"fn":"alice"}}}}` | `{"ctrl":{"id":"acc-2","code":200,"text":"ok","params":{"user":"usr...","username":"alice","authlvl":"auth","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
 | 登录失败 | `{"login":{"id":"login-bad","scheme":"basic","secret":"base64(alice:wrong)"}}` | `{"ctrl":{"id":"login-bad","code":401,"text":"authentication failed","params":{"reason":"AUTH_FAILED"}}}` |
 | 租户不匹配 | `{"login":{"id":"login-tenant","scheme":"token","secret":"其他租户 token"}}` | `{"ctrl":{"id":"login-tenant","code":403,"text":"tenant mismatch","params":{"reason":"TENANT_MISMATCH"}}}` |
 
+**注册 `username` 规则（服务端强校验，2026-10-14 确认）**：3~10 个字符，仅允许小写字母 `a-z` 和数字 `0-9`；不允许大写、下划线、点、汉字及任何符号。不传 `username` 只传 `phone` 时服务端自动生成随机用户名（此时 `secret` 使用 `base64(手机号:密码)`）。违规表现：过短返回 `422 policy violation, params.what=auth`（本次联调实测，用户名 `zz` 即此情形）；超长或含非法字符返回 `422, params.what=username, reason=USERNAME_INVALID_FORMAT`。最小长度来自部署配置 `basic` 认证的 `min_login_length`（当前部署模板为 3），服务端代码上限为 10。
+
 ##### 0.5.4.2 启动订阅、会话列表和增量恢复
 
 | 场景 | 客户端发送 | 服务端返回示例 |
@@ -305,6 +353,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 类型 | 客户端发送 | 服务端返回/下行示例 |
 | --- | --- | --- |
 | 文本消息 | `{"pub":{"id":"pub-text-1","topic":"p2p...","noecho":false,"head":{"mime":"application/json","x-im-schema":1,"x-im-type":"text","x-im-client-mid":"mid_1"},"content":{"text":"你好"}}}` | 发送方收到 `{"ctrl":{"id":"pub-text-1","code":202,"text":"accepted","params":{"seq":12}}}`；订阅者收到 `{"data":{"topic":"p2p...","seq":12,"from":"usr...","head":{"x-im-type":"text","x-im-client-mid":"mid_1"},"content":{"text":"你好"}}}` |
+| 引用回复文本 | `{"pub":{"id":"pub-reply-1","topic":"p2p...","head":{"mime":"application/json","x-im-schema":1,"x-im-type":"text","x-im-client-mid":"mid_reply_1","x-im-reply":{"seq":128,"type":"text","text":"今天晚上一起吃饭吗？","from":"usr..."}},"content":{"text":"好啊"}}}` | `x-im-reply` 必须保留在 `head` 中；服务端不解析业务语义，入库、实时下行和历史读取均原样返回 |
 | 图片消息 | `{"pub":{"id":"pub-img-1","topic":"grp...","head":{"mime":"application/json","x-im-schema":1,"x-im-type":"image","x-im-client-mid":"mid_img_1"},"content":{"file_id":"file_img","thumbnail_file_id":"file_thumb","name":"a.jpg","size":12345,"mime":"image/jpeg","width":1080,"height":720}}}` | `{"ctrl":{"id":"pub-img-1","code":202,"params":{"seq":13}}}` |
 | 语音消息 | `{"pub":{"id":"pub-voice-1","topic":"grp...","head":{"mime":"application/json","x-im-schema":1,"x-im-type":"voice","x-im-client-mid":"mid_voice_1"},"content":{"file_id":"file_voice","duration_ms":8000,"size":4096,"mime":"audio/aac","waveform":[1,3,5,2]}}}` | `{"ctrl":{"id":"pub-voice-1","code":202,"params":{"seq":14}}}` |
 | 文件消息 | `{"pub":{"id":"pub-file-1","topic":"grp...","head":{"mime":"application/json","x-im-schema":1,"x-im-type":"file","x-im-client-mid":"mid_file_1"},"content":{"file_id":"file_pdf","name":"方案.pdf","size":102400,"mime":"application/pdf","extension":"pdf","checksum":"sha256:..."}}}` | `{"ctrl":{"id":"pub-file-1","code":202,"params":{"seq":15}}}` |
@@ -316,7 +365,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 ##### 0.5.4.3.1 会话内系统提示和可点击动作消息
 
-截图中的灰色提示、入群邀请说明、好友已添加提示等属于会话内系统消息，必须进入对应 P2P 或群 Topic 的消息流，占用 `seq`，参与历史拉取、重连补偿和多端同步。它们不是 `info` 实时业务事件，也不是系统通知列表记录；`info` 只负责触发刷新，真正需要在聊天窗口长期展示的内容必须以 `{data}` 下发并入库。
+截图中的灰色提示、群内邀请确认说明、好友已添加提示等属于会话内系统消息，必须进入对应 P2P 或群 Topic 的消息流，占用 `seq`，参与历史拉取、重连补偿和多端同步。它们不是 `info` 实时业务事件，也不是系统通知列表记录；`info` 只负责触发刷新，真正需要在聊天窗口长期展示的内容必须以 `{data}` 下发并入库。发给被邀请人的“加入群聊”邀请卡片不写入邀请人与被邀请人的 P2P 会话，展示以 `GET /v1/im/system-notifications` 返回的系统通知记录为准。
 
 客户端不得主动发送 `system_notice`、`system_action`；这两类消息只能由服务端受控身份生成。服务端下发时 `data.from` 可以为空，客户端以 `head.x-im-from="system"` 判断系统身份，不依赖真实用户头像。客户端收到未知 `template` 或未知 `action.type` 时，展示 `content.text`，忽略不可识别动作，不允许执行任意 URL、脚本或非白名单路由。
 
@@ -357,6 +406,16 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 删除单条/多条消息 | `{"del":{"id":"del-1","topic":"grp...","what":"msg","delseq":[{"low":12,"hi":13}],"hard":false}}` | `{"ctrl":{"id":"del-1","code":200,"text":"ok","params":{"del":3}}}`；其他端可能收到 `{"pres":{"topic":"grp...","what":"del","seq":3}}` |
 | 清空当前用户视图 | `{"del":{"id":"del-all-1","topic":"p2p...","what":"msg","delseq":[{"low":1,"hi":126}],"hard":false}}` | `{"ctrl":{"id":"del-all-1","code":200,"text":"ok","params":{"del":4}}}` |
 
+`kp/kpa/kpv` 只表示输入态、录音态、视频输入态等短暂 UI 状态，不能作为长连接心跳。长连接保活必须依赖 0.5.1.1 中的 WebSocket Ping/Pong。
+
+**单聊已读/已收回执协议约定（服务端已验证，2026-09-29）：**
+
+1. **在线下行形态**：`info.topic` 为话题名（如 `p2p...`），`info.from` 为报读者，`info.what` 为 `recv`/`read`，`info.seq` 为水位。服务端跳过上报会话自身，推送给对端及本人其他在线设备（多 Pod 部署经 Kafka 同步，各 Pod 均会下发）。
+2. **离线补发形态**：接收方离线时收到 `{"info":{"topic":"me","src":"p2p...","from":"usr...","what":"recv","seq":12}}`，即 `topic` 固定为 `me`、`src` 才是话题名。客户端必须同时兼容上述两种形态。
+3. **序号单调递增**：服务端丢弃 `seq` 不大于当前水位的回执（`read`、`recv` 各自独立判断），`read` 回执会同步抬升 `recv`，恒有 `read ≥ recv`。客户端渲染一律取服务端最大游标，禁止用本地计数覆盖服务端值。
+4. **断线重连恢复**：`sub`/`get desc` 响应的 `desc` 中包含 `seq`、`read`、`recv`、`clear` 四个游标；`get {"what":"sub"}` 也返回各成员的 `read/recv`。重连后以这些游标恢复本地状态，不要依赖进程内存。
+5. **换设备登录**：回执水位按「用户 × 话题」在服务端持久化，与设备无关；新设备订阅后 `desc` 同时返回自己与对端的最新 `read/recv`，可完整恢复对方"已读/已收"状态。发送者自身的 `read/recv` 由服务端自动推进到其最新发出的 `seq`。
+
 ##### 0.5.4.5 Topic 资料、个人群设置和标签
 
 | 场景 | 客户端发送 | 服务端返回/下行示例 |
@@ -398,7 +457,9 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
     "event": "group.member.joined",
     "payload": {
       "topic": "grp_xxx",
-      "user_id": "usr_xxx"
+      "user_id": "usr_xxx",
+      "member_sync": "single",
+      "visibility": "all_members"
     },
     "ts": "2026-08-25T10:00:00Z"
   }
@@ -415,7 +476,10 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 修改好友备注 | 操作人本人 | `{"info":{"topic":"usr_actor","from":"usr_actor","what":"im","event":"friend.remark.updated","payload":{"user_id":"usr_actor"}}}` | 刷新好友列表和会话头显示名 |
 | 消息撤回 | Topic 在线成员 | `{"info":{"topic":"p2p_or_grp","from":"usr_actor","what":"im","event":"message.recalled","payload":{"topic":"p2p_or_grp","seq":12,"version":2}}}` | 按 `topic+seq+version` 重新拉取或本地标记已撤回 |
 | 消息编辑 | Topic 在线成员 | `{"info":{"topic":"p2p_or_grp","from":"usr_actor","what":"im","event":"message.edited","payload":{"topic":"p2p_or_grp","seq":12,"version":2}}}` | 按 `topic+seq+version` 重新拉取消息详情或修订记录 |
-| 群业务变化 | 群 Topic 在线成员 | `{"info":{"topic":"grp...","from":"usr_actor","what":"group","event":"group.member.joined","payload":{"topic":"grp...","user_id":"usr_xxx"}}}` | 按事件刷新群详情、成员列表、入群申请、公告、禁言或角色权限；除操作人外当前会写系统通知 |
+| 单聊消息变更脏标记 | P2P 双方在线会话 | `{"info":{"topic":"usr_target","from":"usr_actor","what":"im","event":"message.mutation","payload":{"topic":"p2p...","seq":12,"version":2,"event":"message.recalled"}}}` | 当前未订阅该 P2P 也要标记会话脏，并调用 `message-mutations` 做补偿同步 |
+| 成员加入 | 群 Topic 在线成员 | `{"info":{"topic":"grp...","from":"usr_actor","what":"group","event":"group.member.joined","payload":{"user_id":"usr_xxx","member_sync":"single","visibility":"all_members"}}}` | 全体成员可见；调用 `GET /v1/im/groups/{topic}/members/{user_id}` 刷新单个成员。加入事件同时写入群消息，离线后可按 Topic seq 补拉 |
+| 成员退出/移除、角色或禁言变化 | 群主、管理员和被操作人 | `{"info":{"topic":"grp...","from":"usr_actor","what":"group","event":"group.member.left","payload":{"user_id":"usr_xxx","member_sync":"remove","visibility":"admins_and_affected"}}}` | 普通成员不可见；`single` 拉取单成员，`remove` 本地删除，`full` 重新分页拉取全部成员 |
+| 其他群业务变化 | 按具体事件授权范围 | `info.what="group"` | 刷新群详情、入群申请、公告或治理权限 |
 | 会议变化 | 会议参会人 | `{"info":{"topic":"usr_target","from":"usr_actor","what":"im","event":"meeting.updated","payload":{"meeting_id":"mtg_1","version":2,"state":"scheduled"}}}` | 刷新会议列表/详情；除操作者外当前会写系统通知 |
 | 安全风险确认 | 操作人本人 | `{"info":{"topic":"usr_actor","from":"usr_actor","what":"im","event":"security.risk.continue","payload":{"risk_challenge_id":"risk_1","decision":"continue"}}}` | 刷新安全验证页面；当前会写系统通知 |
 
@@ -453,16 +517,20 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 客户端侧要求：
 
 - App 集成 JPush SDK，初始化使用极光 `AppKey`，不接触 `MasterSecret`。
-- 登录 IM 后将极光 alias 绑定为当前 `user_id`，例如 `usr...`；同一用户多设备允许绑定同一个 alias。
-- SDK 返回 `registration_id` 后调用 `PUT /v1/im/devices/{device_id}/push-token` 上报，`provider` 固定传 `jpush`。
+- 当前测试环境使用 `registration_id` 模式，服务端配置 `jpush_use_alias=0`，不依赖客户端 alias；alias 绑定可保留但不是投递依据。
+- SDK 返回 `registration_id` 后调用 `PUT /v1/im/devices/{device_id}/push-token` 上报，`provider` 固定传 `jpush`。`device_id` 必须稳定，同一台设备不要每次启动变化。
+- 切换账号、切换租户、清登录态后必须重新上报 Push Token；客户端本地的 `user_id/token/registration_id` 去重缓存必须按 `tenant_code + user_id + device_id + registration_id` 隔离，避免把设备继续绑在旧账号上。
+- 若后续切回 alias 模式，登录 IM 后将极光 alias 绑定为当前 `user_id` 的安全别名：`user_id.replace("-", ".").replace("_", "|")`，例如 `usrd6Ag5opa-ww` 绑定为 `usrd6Ag5opa.ww`；同一用户多设备允许绑定同一个 alias。
 - 点击 Push 后按 `extras.type` 跳转，再按服务端数据补偿，不能只凭 Push payload 渲染最终状态。
 
 服务端侧要求：
 
 - `jpush_master_secret` 只保存在后台配置 `im_jpush` 分组，IM Server 通过内部配置接口读取并调用极光 REST API。
+- 当前测试环境按 `registration_id` 投递：服务端从 `im_device_push_tokens` 按目标 `user_id + provider=jpush` 查询设备 token，并调用极光 `audience.registration_id`。
 - 用户在线时优先 WebSocket 实时投递；用户离线、后台或不可投递时生成 Push 任务。
 - 万人大群实时 fanout 不靠 Push；离线只对需要提醒的成员生成极光 Push，客户端重连后按 Topic seq 拉取补偿。
 - Push payload 默认不带敏感正文，通知栏文案按用户隐私设置降级。
+- iOS 测试环境固定使用 `options.apns_production=false`；客户端包也必须是开发 APNs 环境。TestFlight/App Store 生产包需要后端与客户端同时切到生产 APNs。
 
 极光 Push extras 统一格式：
 
@@ -481,7 +549,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | --- | --- | --- |
 | `im_message` | `tenant_code,topic,seq` | 打开会话，按本地最后 seq 补齐消息并定位。 |
 | `group_mention` | `tenant_code,topic,seq,sender_id` | 打开群会话并定位被 @ 消息。 |
-| `call_invite` | `tenant_code,topic,seq,call_id,call_type,caller_id` | 打开来电页前先登录 IM 并确认通话仍为有效来电。 |
+| `call_invite` | `tenant_code,topic,seq,call_id,call_type,caller_id,caller_display,expires_at` | 打开来电页前先登录 IM 并确认通话仍为有效来电。 |
 | `call_missed` | `tenant_code,topic,call_id` | 打开通话记录或对应会话。 |
 | `system_notification` | `tenant_code,notification_id` | 打开系统消息列表并刷新详情。 |
 | `friend_request` | `tenant_code,request_id` | 打开新朋友列表并刷新未处理数。 |
@@ -491,22 +559,11 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 ```json
 {
-  "platform": "all",
+  "platform": "ios",
   "audience": {
-    "alias": ["usr_target"]
+    "registration_id": ["161a3797c95ee4a8bd3"]
   },
   "notification": {
-    "alert": "你收到一条新消息",
-    "android": {
-      "title": "MeetingIM",
-      "alert": "你收到一条新消息",
-      "extras": {
-        "type": "im_message",
-        "tenant_code": "default",
-        "topic": "p2p...",
-        "seq": "128"
-      }
-    },
     "ios": {
       "alert": {
         "title": "MeetingIM",
@@ -534,25 +591,11 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 ```json
 {
-  "platform": "all",
+  "platform": "ios",
   "audience": {
-    "alias": ["usr_callee"]
+    "registration_id": ["161a3797c95ee4a8bd3"]
   },
   "notification": {
-    "alert": "收到一通语音通话",
-    "android": {
-      "title": "语音通话",
-      "alert": "张三邀请你语音通话",
-      "extras": {
-        "type": "call_invite",
-        "tenant_code": "default",
-        "topic": "p2p...",
-        "seq": "30",
-        "call_id": "call_01K...",
-        "call_type": "audio",
-        "caller_id": "usr_caller"
-      }
-    },
     "ios": {
       "alert": {
         "title": "语音通话",
@@ -560,6 +603,8 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
       },
       "sound": "default",
       "badge": "+1",
+      "category": "im_call",
+      "content-available": 1,
       "extras": {
         "type": "call_invite",
         "tenant_code": "default",
@@ -567,18 +612,22 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
         "seq": "30",
         "call_id": "call_01K...",
         "call_type": "audio",
-        "caller_id": "usr_caller"
+        "caller_id": "usr_caller",
+        "caller_display": "张三",
+        "expires_at": "2026-09-18T10:00:30Z"
       }
     }
   },
   "options": {
-    "time_to_live": 60,
+    "time_to_live": 30,
     "apns_production": false,
     "classification": 1
   }
 }
 ```
 
+来电推送必须走普通 APNs/极光 alert 通知，不使用 PushKit VoIP topic；iOS `notification.ios.category` 固定为 `im_call`，用于客户端通知按钮，同时带 `content-available: 1` 唤醒后台 App 拉取 `topic/seq` 并启动 Live Activity。`time_to_live` 和 `expires_at` 以 30 秒左右短有效期为准，过期后服务端不再投递。
+
 #### 0.5.5 Long Polling 与文件基础示例
 
 ##### 0.5.5.1 WebSocket 与文件基础接口
@@ -587,10 +636,17 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | --- | --- | --- |
 | `GET /v0/channels?apikey={api_key}` | WebSocket Upgrade 后首帧 `{"hi":{"id":"hi-1","ver":"0.25","ua":"ios/1.0","lang":"zh-CN","tenant":"default"}}` | `{"ctrl":{"id":"hi-1","code":201,"text":"created","params":{"tenant":{"code":"default","name":"Default Tenant"},"ver":"0.25","maxMessageSize":4194304}}}` |
 | WebSocket `login basic` | `{"login":{"id":"login-1","scheme":"basic","secret":"base64(username:password)"}}` | `{"ctrl":{"id":"login-1","code":200,"params":{"user":"usr...","token":"token...","expires":"2026-09-03T09:00:00Z","authlvl":"auth"}}}` |
-| WebSocket `acc new` | `{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"15500000000","secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"15500000000","resp":"verification_token","params":{"challenge_id":"chg_123"}}]}}` | `{"ctrl":{"id":"acc-1","code":200,"params":{"user":"usr...","username":"alice","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
+| WebSocket `acc new` | `{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"15500000000","registration_type":1,"secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"15500000000","resp":"verification_token","params":{"challenge_id":"chg_123"}}]}}` | `{"ctrl":{"id":"acc-1","code":200,"params":{"user":"usr...","username":"alice","token":"token...","expires":"2026-09-03T09:00:00Z"}}}` |
 | `POST /v0/channels/lp` | Long Polling 首包 `{"hi":{"id":"hi-1","ver":"0.25","tenant":"default"}}` | `{"ctrl":{"id":"hi-1","code":201,"params":{"sid":"lp_sid_123"}}}` |
-| `POST /v0/file/u/` | Multipart 文件；Header `X-MeetingIM-Auth: token <base64_token>`；业务表单可带 `purpose=chat_file&topic=grp...` | `{"ctrl":{"code":200,"params":{"url":"/v0/file/s/file123","name":"a.pdf","size":1024,"mime":"application/pdf"}}}` |
-| `GET /v0/file/s/{file_id}` | Header `X-MeetingIM-Auth: token <base64_token>`，可带 `Range: bytes=0-` | 返回文件字节流；失败返回 `FILE_FORBIDDEN` 或 `FILE_UNAVAILABLE` |
+| `POST /v0/file/u/` | Multipart 文件；Header `X-MeetingIM-Auth: token <base64_token>`；聊天附件必须带 `topic=<消息所在会话 topic>`（`p2p.../grp...`），可选 `purpose=chat_file`、`id=<幂等ID>` | `{"ctrl":{"code":200,"params":{"expires":"2026-10-13T06:21:20Z","file_id":"s6yhMyiOfaU","url":"/v0/file/s/s6yhMyiOfaU.txt"}}}` |
+| `GET /v0/file/s/{file_id}` | Header `X-MeetingIM-Auth: token <base64_token>`，可带 `Range: bytes=0-`；URL 可带文件扩展名（服务端自动剥离） | 对象存储模式下鉴权通过后返回 302 到短期签名 URL；客户端跟随 Location 获取文件 |
+
+**文件上传/下载鉴权与回收规则（已实现，客户端必须遵守）：**
+
+1. 上传聊天附件（图片/视频/语音/文件）必须携带 `topic=<消息将要发送到的会话 topic>`。服务端校验上传者是该 `p2p`/`grp` 会话的订阅成员（`modewant`/`modegiven` 含读权限），不是成员返回 `403 permission denied`；校验通过则在服务端建立「文件-会话」引用，该会话全体成员凭有效 Token 即可下载。
+2. 不带 `topic` 的上传只有上传者本人可下载。任何文件若一直未被任何会话/消息引用，服务端在创建 1 小时后由后台任务物理回收；上传后必须及时发送消息或携带 `topic`，否则对端将拿到 404。用户头像/资料类文件不受此限：客户端设置头像（PATCH `avatar_file_id`）时服务端自动写入文件引用，该文件不会被回收。
+3. 下载放行范围（2026-10-14 更新）：上传者本人、文件所属会话成员、消息级引用可见者（未撤回未删除且未被执行删除）、群成员、好友关系、收藏引用、**用户头像/资料文件（对任何登录用户放行，2026-10-14 修复：此前仅上传者可读，群成员拉取他人头像 403）**。非授权返回 `403 permission denied`（即 `FILE_FORBIDDEN`），客户端不自动重试。
+4. `avatar_url` 统一回填规则（2026-10-14 起，所有返回用户/群摘要的接口一致）：`avatar_file_id` 为完整 URL 时 `avatar_url` 原样返回；为裸 file_id 时返回 `"/v0/file/s/{file_id}"`（可直接下载，无需客户端拼接）；头像为空时回落默认头像 URL（男/女按性别，`avatar_file_id` 与 `avatar_url` 同值）。涉及接口：`/v1/im/groups/{topic}/members`、`/members/{userId}/profile`、`/v1/im/users/{id}/profile`、`/v1/im/me/profile`、转发目标列表等。
 
 ### 0.6 Topic 与产品消息
 
@@ -617,6 +673,8 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 `x-im-client-mid` 由客户端生成 ULID/UUID，作用域为“租户 + 发送人”，断线重试必须复用；服务端目标实现应返回第一次写入的同一 `seq`。未知 `x-im-type` 显示“暂不支持的消息”，不得崩溃或删除消息。
 
+引用回复使用 `head.x-im-reply` 承载客户端生成的轻量快照，字段为 `seq:number`、`type:string`、`text:string`，可选 `from:string`。该对象必须放在 `head`，不能放入 `content`；服务端只负责把未知 `head` 字段随消息存储、实时转发、历史拉取和 HTTP 查询一起原样返回，不对被引用消息做二次查询或语义校验。客户端兼容历史服务端将 `x-im-reply` 作为 JSON 字符串返回的情况，但新版本客户端发送时必须使用 JSON 对象。
+
 消息类型首版固定为：`text`、`image`、`video`、`voice`、`file`、`contact_card`、`link`、`forward_bundle`、`call`、`system_notice`、`system_action`、`system_event`。自定义表情启用后追加 `sticker`。媒体内容只保存 `file_id`、文件元数据和缩略图 ID，不保存可长期绕过鉴权的公共 URL。`system_notice` 和 `system_action` 只能由服务端生成，普通用户构造后发送必须被服务端拒绝。
 
 ### 0.7 HTTP 幂等、重试和安全
@@ -649,7 +707,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 - 成功数据：`tenant{code,name,tenant_desc,branding}`、`endpoints{websocket,api,file}`、`auth_methods`、`password_policy`、`app_update`。不得返回 `tenant_id` 或 `tenant_ticket`。
 - 后续：该接口仅用于服务发现、品牌配置或历史企业入口；当前登录页和注册页不依赖它完成主流程。调用方即使解析成功，仍然必须发送 0.5 节的 `hi(tenant)` 做最终租户绑定。
 - 目标失败协议：企业不存在、停用或不允许登录统一返回 `TENANT_UNAVAILABLE`；客户端不得区分不存在和停用。网络失败保留输入并允许重试。
-- 个人登录不通过企业码入口解析 `default`，由个人用户入口提交 `login_type=1` 并内部使用 `tenant_code=default`；企业登录提交 `login_type=0`，如果企业码为 `default`，服务端拒绝并统一提示“企业不存在或不可用”。个人注册必须提交 `registration_type=1`，由该字段进入 `default` 注册链路。详见 [IM-个人无企业码注册前后端对接说明.md](../IM-个人无企业码注册前后端对接说明.md)。
+- 个人登录不通过企业码入口解析 `default`，由个人用户入口提交 `login_type=1` 并内部使用 `tenant_code=default`；企业登录提交 `login_type=0`，如果企业码为 `default`，服务端拒绝并统一提示“企业不存在或不可用”。个人注册必须提交 `registration_type=1`，由该字段进入 `default` 注册链路。详见 [IM-个人无企业码注册前后端对接说明.md](IM-个人无企业码注册前后端对接说明.md)。
 
 成功响应示例：
 
@@ -659,7 +717,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
   "data": {
     "tenant": {"code": "acme", "name": "示例企业", "tenant_desc": null, "branding": {}},
     "endpoints": {
-      "websocket": "wss://im.example.com/v0/channels",
+      "websocket": "wss://im.example.com/v0/channels?apikey=AQ...",
       "api": "https://im.example.com/v1/im",
       "file": "https://im.example.com/v0/file"
     },
@@ -824,20 +882,21 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 <img src="images/注册页面.png" alt="注册页面" width="360">
 
-**状态：注册原型和服务端注册分流均已完成；用户名和手机号为独立字段，服务端已接入 username、邀请码和短信开关逻辑。**
+**状态：注册原型和服务端注册分流均已完成；邀请码不再使用独立输入框，与短信验证码共用同一输入框。**
 
 - 页面规则：用户名和手机号是独立输入。用户名非空时必须保存为 `im_users.username`；手机号非空时必须保存为规范化后的 `im_users.phone`。两个字段同时为空时拒绝注册。
 - 注册类型规则：注册页必须提交 int 字段 `registration_type`，`0` 表示企业注册、`1` 表示个人注册；后端按该字段区分个人注册和企业注册，不能通过企业码是否为空推断。`registration_type=1` 时企业码为空，服务端内部使用 `tenant_code=default`；`registration_type=0` 时企业码必填。前端不做企业码拦截，不单独调用 `/v1/im/tenants/resolve`，获取验证码和提交注册时带上 `registration_type=0` 与用户输入的企业码，由后端在注册链路中校验存在且可用；失败统一显示“企业不存在或不可用”。
 - 用户名格式：普通用户名必须匹配 `^[a-z0-9]{1,10}$`，即 1～10 位小写英文字母或数字；允许纯数字，不允许大写、中文、空格、点、下划线和其他符号。前端限制输入，服务端按原始值再次校验，失败返回 `USERNAME_INVALID_FORMAT`。
-- 邀请码格式：非空时必须匹配 `^[A-Za-z]{5}$`，固定 5 位大小写英文字母并区分大小写；客户端不得自动转换大小写。服务端在当前租户内按明文精确查询。
+- 统一验证码输入：输入 5 位大小写英文字母时按邀请码处理；输入 6 位数字时按短信验证码处理。其他格式直接提示输入无效，客户端不得自动转换邀请码大小写。
+- 邀请码格式：必须匹配 `^[A-Za-z]{5}$`，服务端在当前租户内按明文精确查询。邀请码有效时允许注册并建立邀请码与新用户的推荐使用关系。
 - 邀请码可复用：同一有效邀请码可以供多个用户注册，使用后仍保持 `active`；服务端为每个注册用户记录邀请来源。只有到期或管理员撤销后才不可继续使用。
 - 邀请码主数据位于 HotGo 控制库并按 `tenant_id` 隔离；注册使用明细位于当前租户业务库。客户端契约不受分库影响，仍只提交完整 5 位邀请码。
-- 用户名方式：手机号为空时提交用户名、密码和邀请码，不发送短信。邀请码必须有效，注册后 `im_users.username` 保存用户名，`im_users.phone=NULL`。
+- 旧版独立 `invite_code` 字段仅保留协议兼容，新客户端不得再展示独立邀请码输入框。
 - 找回提示：用户名方式提交注册前，客户端明确提示“未绑定手机号时无法自助找回密码，忘记密码需联系企业管理员重置”。
 - 手机号方式：前端只接受 11 位数字。调用 `POST /v1/im/auth/verification-codes`，Body `{"scene":"register","phone":"138..."}`；后端补 `+86` 后发送，成功返回 `challenge_id`、`expires_in_seconds`、`resend_after_seconds`。当前测试环境短信供应商未接入，注册、找回密码和敏感操作验证码固定填写 `123456`，用它调用 verify 接口换取一次性 `verification_token` 或 `action_token`；生产接入短信供应商后不得继续使用固定验证码。
-- 短信开关开启：手机号非空时必须完成验证码验证，邀请码不能绕过短信验证；验证成功后 `username` 保存用户填写的用户名，`phone` 保存规范化的 E.164 手机号。若用户未填写用户名，则服务端随机生成 3 位小写字母 + 6 位数字的 username。
-- 短信开关关闭：发码接口仍返回正常倒计时但不调用短信服务商。手机号非空时提供有效邀请码后可无验证码注册；`username` 保存用户填写的用户名，`phone` 保存规范化手机号。若用户未填写用户名，则服务端随机生成 3 位小写字母 + 6 位数字的 username。不建立已完成的 `tel credential`。
-- 提交注册：`{acc}` 增加独立的 `username`、`phone` 和 `invite_code`。短信验证成功后调用 `POST /v1/im/auth/verification-codes/{challenge_id}/verify` 获得一次性 `verification_token`。`username` 非空时，`secret` 使用 `username:password`；仅手机号注册且 username 为空时，客户端仍使用规范化手机号与密码生成 `secret`，服务端创建后返回随机 username。
+- 短信验证码方式：校验成功后返回一次性 `verification_token`，注册成功时建立已完成的 `tel credential`。
+- 邀请码方式：校验成功返回 `verification_mode=invite_code`；注册时把原始邀请码放在 `cred[].resp`，不提交独立 `invite_code`。该方式保存手机号但不建立已完成的 `tel credential`，同时写入邀请码推荐使用关系。
+- 提交注册：`username` 非空时，`secret` 使用 `username:password`；仅手机号注册且 username 为空时，客户端仍使用规范化手机号与密码生成 `secret`，服务端创建后返回随机 username。
 - 服务端判定：`username` 非空时校验 `^[a-z0-9]{1,10}$` 并要求 `secret` 登录名与 username 一致；`username` 为空且 `phone` 非空时要求 `secret` 登录名与规范化手机号一致，随后生成随机 username。普通用户名允许纯数字，因此不能只根据 `secret` 是否为 11 位数字推断注册方式。
 - 账户昵称：注册创建资料时，昵称暂时默认等于最终 username。填写用户名时昵称等于该用户名；仅手机号注册时昵称等于服务端随机 username，不使用手机号作为昵称。
 - 禁止客户端提交 `tags`；手机号方式始终写入 `im_users.phone`，只有短信验证成功时才建立已完成的电话凭证。
@@ -845,19 +904,19 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 用户名方式：
 
 ```json
-{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"","secret":"base64(alice:password)","invite_code":"AbCdE","login":true,"cred":[]}}
+{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"138...","registration_type":1,"secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"138...","resp":"AbCdE","params":{"challenge_id":"challenge-id"}}]}}
 ```
 
 手机号验证方式：
 
 ```json
-{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"138...","secret":"base64(alice:password)","invite_code":"","login":true,"cred":[{"meth":"tel","val":"138...","resp":"verification_token","params":{"challenge_id":"challenge-id"}}]}}
+{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"alice","phone":"138...","registration_type":1,"secret":"base64(alice:password)","login":true,"cred":[{"meth":"tel","val":"138...","resp":"verification_token","params":{"challenge_id":"challenge-id"}}]}}
 ```
 
 仅手机号注册方式：
 
 ```json
-{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"","phone":"138...","secret":"base64(+86138...:password)","invite_code":"","login":true,"cred":[{"meth":"tel","val":"138...","resp":"verification_token","params":{"challenge_id":"challenge-id"}}]}}
+{"acc":{"id":"acc-1","user":"new","scheme":"basic","username":"","phone":"138...","registration_type":1,"secret":"base64(+86138...:password)","login":true,"cred":[{"meth":"tel","val":"138...","resp":"verification_token","params":{"challenge_id":"challenge-id"}}]}}
 ```
 - 成功：返回新 `user`、最终 `username` 和登录 Token；客户端保存 `params.token`，随后执行 `sub me` 和会话恢复。创建用户前原子校验 `im_tenant_config.max_users`，超限返回 `TENANT_USER_QUOTA_EXCEEDED`。
 - 安全：用户名、手机号分别在租户内唯一；验证码票据单次消费，邀请码在有效期内可重复使用；密码按服务端策略校验并使用强哈希保存。
@@ -893,11 +952,11 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 **状态：新增。**
 
-- 敏感操作先调用 `POST /v1/im/security/challenges`；开启青少年模式设置独立密码时 Body 为 `{"scene":"set_independent_password","channel":"sms"}`，关闭青少年模式时 Body 为 `{"scene":"close_youth_mode","channel":"sms"}`。手机号由登录身份读取，客户端不提交目标手机号。
+- 敏感操作先调用 `POST /v1/im/security/challenges`；开启青少年模式设置独立密码时 Body 为 `{"scene":"set_independent_password","channel":"sms"}`，关闭青少年模式时 Body 为 `{"scene":"close_youth_mode","channel":"sms"}`；群主转让使用 `{"scene":"group_owner_transfer","channel":"sms"}`；解散群聊使用 `{"scene":"group_dissolve","channel":"sms"}`；注销账号使用 `{"scene":"delete_account","channel":"sms"}`。手机号由登录身份读取，客户端不提交目标手机号。
 - 发码/校验：服务端返回 `challenge_id` 和脱敏手机号；提交 `POST /v1/im/security/challenges/{id}/verify`，Body `{"code":"..."}`。
 - 重复发码：同一用户、同一手机号、同一敏感场景存在未过期 challenge 且仍在 `resend_after_seconds` 冷却期内时，服务端返回 HTTP `429 VERIFICATION_RATE_LIMITED`，`details` 带 `challenge_id` 和 `retry_after_seconds`。客户端应复用该 `challenge_id` 继续倒计时，不要当成接口不可达或重新登录。
 - 小时限流：超过一小时创建次数上限时同样返回 HTTP `429 VERIFICATION_RATE_LIMITED`，`details.retry_after_seconds` 可能大于 60 秒且不一定带 `challenge_id`。客户端只展示倒计时，倒计时结束后允许用户重新获取验证码。
-- 成功返回 `action_token`、`action`、`expires_at`；Token 只能用于指定动作且单次消费。设置独立密码接口通过 Body `action_token` 携带；关闭青少年模式接口通过 Header `X-Action-Token` 携带。
+- 成功返回 `action_token`、`action`、`expires_at`；Token 只能用于指定动作且单次消费。设置独立密码接口通过 Body `action_token` 携带；关闭青少年模式、群主转让、解散群聊接口通过 Header `X-Action-Token` 携带。
 - 错误：`VERIFICATION_RATE_LIMITED`、`CHALLENGE_EXPIRED`、`CODE_INVALID`、`TOO_MANY_ATTEMPTS`；前端不得把短信验证码或 action token 落普通存储。
 
 ### 1.8 实名认证.png
@@ -919,7 +978,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 - 页面只调用 `GET /v1/im/security/realname`。`verified` 时返回如 `masked_name:"张*"`、`masked_id_number:"110***********1234"`、`verified_at`。
 - 前端只读展示，不缓存原始证件信息，不提供直接修改接口。
-- 更正信息使用独立申诉 `POST /v1/im/security/realname/appeals`，需二次身份验证；不复用本页保存按钮。
+- 更正信息使用独立申诉 `POST /v1/im/security/realname/appeals`，Body `{"reason":"...","attachments":[]}`（`reason` 必填、≤500 字；`attachments` 最多 9 个 file_id），Bearer 即可，当前无需二次身份验证；不复用本页保存按钮。
 
 ### 1.10 实名认证（安卓）.png
 
@@ -957,18 +1016,19 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 | 接口 | 输入示例 | 成功 `data` 示例 |
 | --- | --- | --- |
-| `POST /v1/im/tenants/resolve` | Header `X-Tenant-Code: acme`；Body `{"tenant_code":"acme","platform":"ios","app_version":"1.0.0"}` | `{"tenant":{"code":"acme","name":"示例企业","tenant_desc":null,"branding":{}},"endpoints":{"websocket":"wss://api.118im.com/v0/channels","api":"https://api.118im.com/v1/im","file":"https://api.118im.com/v0/file"},"auth_methods":["password","sms"],"password_policy":{"min_length":8,"max_length":64},"app_update":{"type":"none"}}` |
+| `POST /v1/im/tenants/resolve` | Header `X-Tenant-Code: acme`；Body `{"tenant_code":"acme","platform":"ios","app_version":"1.0.0"}` | `{"tenant":{"code":"acme","name":"示例企业","tenant_desc":null,"branding":{}},"endpoints":{"websocket":"wss://api.118im.com/v0/channels?apikey=AQ...","api":"https://api.118im.com/v1/im","file":"https://api.118im.com/v0/file"},"auth_methods":["password","sms"],"password_policy":{"min_length":8,"max_length":64},"app_update":{"type":"none"}}` |
 | `POST /v1/im/public/uploads` 企业注册/反馈附件上传 | Multipart `purpose=enterprise_license\|tenant_entry_feedback`、`file=@license.png` | `{"file_id":"file_01K...","purpose":"enterprise_license","mime_type":"image/png","size":1024000,"expires_at":"2026-08-25T08:30:15Z"}` |
 | `POST /v1/im/tenant-applications` 企业注册申请 | `{"credit_code":"91310000MA1K000000","enterprise_email":"admin@example.com","license_file_id":"file_01K...","tenant_code_hint":"acme","client_context":{"platform":"android","app_version":"1.0.0"}}` | `{"application_id":"entapp_01K...","status":"received","estimated_review_hours":24,"submitted_at":"2026-08-24T08:30:15.123Z"}` |
 | `POST /v1/im/tenant-entry-feedback` 企业入口问题反馈 | `{"description":"企业码 acme 提示不可用，无法进入企业。","contact":"user@example.com","tenant_code_hint":"acme","screenshot_file_ids":["file_01K..."],"client_context":{"platform":"ios","app_version":"1.0.0"}}` | `{"feedback_id":"entryfb_01K...","status":"received","submitted_at":"2026-08-24T08:35:15.123Z"}` |
 | `POST /v1/im/auth/verification-codes` 注册发码 | `{"scene":"register","phone":"15500000000"}` | `{"challenge_id":"chg_123","phone_mask":"+861****000","expires_in_seconds":300,"resend_after_seconds":60}` |
 | `POST /v1/im/auth/verification-codes/{challenge_id}/verify` | `{"code":"123456"}` | `{"verification_token":"verify_token_123","expires_in_seconds":300}` |
+| `POST /v1/im/auth/verification-codes/{challenge_id}/verify` 邀请码 | `{"code":"AbCdE"}` | `{"verification_mode":"invite_code","invite_accepted":true}` |
 | `POST /v1/im/auth/verification-codes` 找回密码发码 | `{"scene":"reset_password","phone":"15500000000"}` | `{"challenge_id":"chg_reset_123","phone_mask":"+861****000","expires_in_seconds":300,"resend_after_seconds":60}` |
 | `POST /v1/im/auth/password-reset/challenges/{challenge_id}/verify` | `{"code":"123456"}` | `{"reset_token":"reset_token_123","expires_in_seconds":300}` |
 | `POST /v1/im/auth/password-reset/confirm` | `{"reset_token":"reset_token_123","new_password":"NewPass123"}` | `{"status":"ok"}` |
 | `POST /admin/v1/tenant/users/{user_id}/reset-password` 管理后台 | `{"new_password":"AdminReset123","reason":"用户无手机号无法自助找回"}` | `{"user_id":"usr...","status":"reset","auth_version":2}` |
-| `POST /v1/im/auth/logout` 待实现 | `{}` | `{"status":"ok"}` |
-| `GET /v1/im/app/releases/latest?platform=ios\|android\|web&current_version=1.0.0&channel=stable` | Query only | `{"platform":"web","channel":"stable","latest_version":"1.0.0","min_supported_version":"1.0.0","update_type":"none","package_url":"","store_url":"","release_notes":"当前已是最新版本。","remind_after_seconds":0}` |
+| `POST /v1/im/auth/logout` | `{}` | `{"status":"ok"}` |
+| `GET /v1/im/app/releases/latest?platform=ios\|android\|web&current_version=1.0.0&channel=stable` | Query only | `{"current_version":"1.0.0","has_update":true,"force_update":false,"platform":"web","channel":"stable","latest_version":"1.1.0","min_supported_version":"1.0.0","update_type":"recommended","package_url":"","store_url":"","release_notes":"修复已知问题。","remind_after_seconds":86400}` |
 
 ## 2. 消息首页、全局导航与系统通知
 
@@ -1022,8 +1082,9 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 **状态：需改造。**
 
 - `GET /v1/im/system-notifications?cursor=` 返回 `id,event_type,title,summary,created_at,read_at,action`；实时刷新以 0.5.4.6 的 WS `{info what:"im|group"}` 业务事件为准，系统通知列表记录不等同于每一条实时事件。
+- `summary` 为服务端生成的可直接展示文案（如「对方已同意你的好友申请」「对方已婉拒你的好友申请」），前端直接渲染，无需再做状态码到文案的映射；`action` 读路径统一归一为 `{type,target_id,payload,...原始键}`。
 - 新设备登录事件内容为 `device_name,platform,ip_masked,login_at,security_action`；IP 只下发必要脱敏值。
-- 已读：`POST /v1/im/system-notifications/{id}/read`，带幂等键；跳转目标只接受服务端白名单 `action.type` 和内部参数。
+- 已读：`POST /v1/im/system-notifications/{id}/read`，带幂等键；重复已读返回首次持久化的 `read_at`，不回显本次提交值。跳转目标只接受服务端白名单 `action.type` 和内部参数。
 - 当前普通认证用户可向 `sys` Topic 发布的路径必须封禁。客户端不得渲染普通用户伪造的系统卡片为可信通知。
 
 ### 2.6 接口示例
@@ -1042,7 +1103,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | --- | --- | --- |
 | `GET /v1/im/bootstrap` | Query only | `{"features":{"create_group":true,"user_search":true,"scan_qr":true,"system_notifications":true,"message_recall":true,"message_edit":true,"audio_call":true,"video_call":true},"permissions":{"create_group":true,"user_search":true,"scan_qr":true,"audio_call":true,"video_call":true},"entries":{"new_friends":{"enabled":true,"route":"/contacts/new-friends","unread_count":0},"groups":{"enabled":true,"route":"/contacts/groups","unread_count":0},"file_assistant":{"enabled":true,"route":"/chat/file-assistant","topic":"slf","unread_count":0},"system_messages":{"enabled":true,"route":"/chat/system","topic":"sys","unread_count":0}},"entry_badges":{"new_friends_pending_count":0,"groups_unread_count":0,"file_assistant_unread_count":0,"system_unread_count":0,"workbench_total_unread":0},"system_topic":{"topic":"sys","type":"system"},"message_policy":{"recall_window_seconds":120,"edit_window_seconds":300,"supported_actions":["copy","quote","delete","recall","edit"]},"security":{"realname":{"status":"unverified","required":false,"allow_skip":true,"remind_after":"24h"}}}` |
 | `GET /v1/im/search/conversations?q=&cursor=` | Query only | `{"items":[{"topic":"grp...","public":{"name":"项目群"},"private":{"pinned":false,"mute_notifications":false},"seq":12,"read":10,"recv":12,"unread":2,"updated_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
-| `GET /v1/im/system-notifications?cursor=&limit=20` | Query only | `{"items":[{"id":"evt_1","event_type":"friend.request.created","title":"新的好友申请","summary":"张三请求添加你为好友","action":{"type":"friend_request","request_id":"frq_1"},"read_at":null,"created_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
+| `GET /v1/im/system-notifications?cursor=&limit=20` | Query only | `{"items":[{"id":"evt_1","event_type":"friend.request.created","title":"新的好友申请","summary":"张三请求添加你为好友","action":{"type":"friend_request","target_id":"usr...","payload":{"request_id":"frq_1"},"request_id":"frq_1"},"read_at":null,"created_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
 | `POST /v1/im/system-notifications/{id}/read` | `{"read_at":"2026-08-20T09:00:00Z"}` | `{"status":"ok","id":"evt_1","read_at":"2026-08-20T09:00:00Z"}` |
 
 ## 3. 单聊会话、会话建立与消息状态
@@ -1101,11 +1162,14 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 <img src="images/双方沟通状态.png" alt="双方沟通状态" width="360">
 
-**状态：上传基础已实现；媒体消息 Schema、ACL 和恢复需改造。**
+**状态：上传带 `topic` 与下载按会话授权已在服务端实现；客户端按本节接入。**
 
-- 选择媒体后本地生成 `client_mid` 和稳定占位；调用文件上传，得到 `file_id` 后再 `pub x-im-type=image|video|voice`。
+- 选择媒体后本地生成 `client_mid` 和稳定占位；调用文件上传（**必须带 `topic=<该会话 topic>`**，服务端校验成员资格并自动建立文件-会话引用），得到 `file_id` 后再 `pub x-im-type=image|video|voice`。
 - `content` 至少含 `file_id,name,size,mime,width,height,duration_ms,thumbnail_file_id` 中适用字段；上传进度是客户端任务状态，不写成聊天消息。
-- 服务端发布成功后关联文件与 Topic/消息；文件下载必须校验消息可见性。上传失败只重试上传，成功但 `pub` 失败时复用已上传 `file_id` 和 `client_mid`。
+- 服务端在上传阶段即建立文件与会话的引用（带 `topic`）；消息发布成功后按消息附件引用建立消息级 ACL；文件下载校验会话成员身份与消息可见性。
+- 媒体文件（缩略图、原图、视频、语音）一律走同一次上传流程并带同一个 `topic`；缩略图也必须挂到会话，否则对端只能看到占位图。
+- 上传失败（网络中断、超时、5xx）按**整文件重传**处理：重新调用 `POST /v0/file/u/` 上传完整文件，不做分片/断点续传；每次重传得到新 `file_id`，旧 `file_id` 直接放弃、由服务端 TTL 回收，客户端不得再引用。
+- 上传成功但 `pub` 失败时不重新上传，复用已上传 `file_id` 和原 `client_mid` 重发消息，服务端按 `client_mid` 幂等去重。
 
 ### 3.7 个人对话—拉黑状态／已读状态.png
 
@@ -1259,7 +1323,9 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 
 **状态：客户端任务管理新增；服务端上传需改造。**
 
-- 每个待发送项保存 `client_mid,local_uri,type,upload_id,progress,state`；同一文件可分片/断点续传时使用稳定 `upload_id`。
+- 每个待发送项保存 `client_mid,local_uri,type,upload_id,progress,state`；`upload_id` 仅在单次上传任务内有效（进度上报与本地去重用）。
+- 重试即新建上传任务：`progress` 归零、生成新 `upload_id`，**整文件重传** `POST /v0/file/u/`，不做分片/断点续传；重传成功后消息体 `file_id` 等字段全部取最新一次上传响应。
+- 自动重试采用指数退避且不超过 3 次，之后转人工点按重试；App 冷启动扫描本地 `failed` 任务队列重新上传。
 - 上传完成后再发布消息；多任务可并发但必须各自保持原排序号。离开页面不取消，退出账号必须暂停并隔离任务。
 - 服务端返回 `FILE_TOO_LARGE`、`FILE_TYPE_NOT_ALLOWED`、`STORAGE_QUOTA_EXCEEDED` 时不可自动无限重试。
 
@@ -1346,8 +1412,8 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 **状态：新增。**
 
 - `POST /v1/im/messages/forward`，Body `{"mode":"separate","sources":[{"topic":"p2p...","seq":12}],"target_topics":["grp..."],"comment":"..."}`。`seq` 兼容数字和字符串；P2P 源会话也可以传对方 `usr...` 用户 ID，服务端会归一化为 P2P topic。
-- 返回每个目标和源消息的 `client_mid/seq/status`；服务端保持源顺序，重新生成目标消息，不能复用原 `seq`。
-- 附件必须建立新的授权引用；原消息已撤回、过期或不可见时该项失败。留言作为每个目标的一条独立文本消息发送。
+- 返回每个目标和源消息的 `client_mid/seq/status`；`status` 取值为 `sent`、`pending`、`failed`。`pending` 表示服务端已分配 `seq/client_mid`，但 Kafka 投递结果暂不确定，客户端应按“发送中”展示，保留同一个 `Idempotency-Key` 重试或等待后续消息同步，不要立即生成第二条本地消息。服务端保持源顺序，重新生成目标消息，不能复用原 `seq`。
+- 附件必须建立新的授权引用；原消息已撤回、过期或不可见时该项失败。留言作为每个目标的一条独立文本消息发送，返回项可带 `comment_client_mid/comment_seq/comment_status/comment_reason`；转发消息本身仍保持原 `head/content`，不得把留言包装进图片、文件等原消息 `content`。
 
 ### 4.20 转发—合并转发—多选状态.png
 
@@ -1356,6 +1422,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 **状态：新增。**
 
 - 调用 4.19 接口，`mode:"bundle"`；服务端生成一条 `forward_bundle` 目标消息，内容含 `bundle_id,title,item_count,preview[],items[],source_refs[]`。首版 Bundle 明细以内联快照随消息下发，后续如消息量增大再扩展 `GET /v1/im/forward-bundles/{bundle_id}?cursor=` 分页详情。
+- `items[]` 和 `preview[]` 保留 `from` 原发送人 ID，并新增 `from_user` 用户摘要：`{"user_id":"usr...","display_name":"张三","avatar_file_id":"file_avatar"}`。头像为空时可缺省；若资料查询失败，服务端至少返回 `user_id/display_name` 兜底。
 - 快照保留显示名、时间和内容摘要，对撤回/敏感字段按策略脱敏；不得允许接收端利用 Bundle 获取原会话额外权限。
 - 多目标共享不可变 Bundle 内容但分别生成目标消息与授权记录。
 
@@ -1374,10 +1441,10 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 接口 | 输入示例 | 成功 `data` 示例 |
 | --- | --- | --- |
 | `GET /v1/im/conversations/{topic}/context` | Path `p2p...` 或 `grp...` | `{"topic":"p2p...","type":"p2p","relationship":"friend","can_send":true,"capabilities":{"text":true,"image":true,"file":true,"voice":true,"can_call":true},"peer":{"user_id":"usr...","display_name":"张三","avatar_file_id":""}}` |
-| `POST /v1/im/conversations/p2p` 待实现 | `{"peer_user_id":"usr..."}` | `{"topic":"p2p...","relationship":"friend","can_send":true}` |
-| `GET /v1/im/conversations/{topic}/settings` 待实现 | Path topic | `{"pinned":false,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":1,"permissions":{"can_update":true}}` |
-| `PATCH /v1/im/conversations/{topic}/settings` 待实现 | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"pinned":true,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":2}` |
-| `GET /v1/im/conversations/{topic}/messages` 待实现 | Query `?since=12&limit=20` | `{"topic":"p2p...","items":[{"seq":13,"from":"usr...","ts":"2026-08-20T09:00:00Z","head":{"x-im-type":"text"},"content":{"text":"你好"}}],"next_cursor":""}` |
+| `POST /v1/im/conversations/p2p` | `{"peer_user_id":"usr..."}` | `{"topic":"p2p...","relationship":"friend","can_send":true}` |
+| `GET /v1/im/conversations/{topic}/settings` | Path topic | `{"pinned":false,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":1,"permissions":{"can_update":true}}` |
+| `PATCH /v1/im/conversations/{topic}/settings` | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"pinned":true,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":2}` |
+| `GET /v1/im/conversations/{topic}/messages` | **服务端当前为空占位**：GET 恒返回空列表，勿用 `?since=&limit=` 调它；历史消息（首屏与向上翻页）一律走 WS `get data` 的 `since`/`before`/`limit`（向上翻页见 0.5.1 约定） | `{"topic":"p2p...","items":[],"next_cursor":"","has_more":false}` |
 | `PUT /v1/im/topics/{topic}/draft` 待实现 | `{"content":"未发送草稿","version":1}` | `{"topic":"grp...","content":"未发送草稿","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `POST /v1/im/topics/{topic}/messages/{seq}/recall` | 单条撤回；`topic` 可传 `p2p...` 或 `grp...`；Body `{}`，可选 `{"version":1,"reason":"mistake"}` | `{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `POST /v1/im/topics/{topic}/messages/recall` | 多选批量撤回；`{"items":[{"seq":12,"version":1},{"seq":13}],"reason":"mistake"}`；`items` 1～50 条，`version` 可选 | `{"topic":"grp...","items":[{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"},{"seq":13,"status":"failed","http":409,"code":30006,"reason":"VERSION_CONFLICT","message":"message version conflict"}]}` |
@@ -1551,7 +1618,32 @@ Body：
 
 #### 4.21.3 消息变更同步水位
 
-撤回、编辑属于 `seq` 不变的原地变更。在线且已订阅 Topic 时，客户端会收到 `message.recalled` / `message.edited` 实时事件；离线或未订阅时，需要靠会话级水位补偿。
+撤回、编辑属于 `seq` 不变的原地变更。在线且已订阅 Topic 时，客户端会收到 `message.recalled` / `message.edited` 实时事件；单聊中如果客户端在线但当前没有订阅该 P2P，服务端会额外向双方用户通道下发 `message.mutation` 脏标记事件；离线或错过实时事件时，需要靠会话级水位补偿。
+
+单聊未订阅脏标记示例：
+
+```json
+{
+  "info": {
+    "topic": "usr_target",
+    "from": "usr_actor",
+    "what": "im",
+    "event": "message.mutation",
+    "payload": {
+      "topic": "p2pJaOWxMvALjB4i1K_h_NZgQ",
+      "seq": 12,
+      "version": 2,
+      "event": "message.recalled"
+    }
+  }
+}
+```
+
+收到 `message.mutation` 后不要直接改本地消息内容，先把 `payload.topic` 标记为脏，再调用：
+
+```http
+GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}&limit=50
+```
 
 会话列表同步时，`me.meta.sub[].private` 会带：
 
@@ -1606,6 +1698,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - `mutation_version` 是会话级水位，不是单条消息的 `version`。
 - 本地只做 `服务端 mutation_version > 本地 mutation_version` 比较，不要假设连续递增。
+- 补偿接口返回的是最新 `limit` 条（默认 50、上限 100）变更的**状态快照**，非严格增量；变更条数超过 `limit` 时更早的变更不再返回。撤回窗口 120 秒、编辑窗口 300 秒，超窗变更无需客户端处理。
 - 拉到 `message.recalled` 后，将本地 `topic + seq` 标记为撤回，并只在 `version` 更高时覆盖。
 - 拉到 `message.edited` 后，按 `seq + version` 拉取或覆盖消息内容。
 - 实时事件和补偿接口可能重复到达，客户端必须按 `topic + seq + version` 幂等处理。
@@ -1618,7 +1711,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增产品通讯录接口。**
 
-- 好友列表：`GET /v1/im/friends?query=&initial=&cursor=`，返回 `user_id,display_name,remark,avatar_file_id,initial,online_visibility`；显示名优先级为备注名、昵称、账号。
+- 好友列表：`GET /v1/im/friends?query=&initial=&cursor=`，返回 `user_id,display_name,remark,avatar_file_id,avatar_url,initial,online,online_visibility`（`avatar_url` 统一回填规则见 0.5.5.1 第 4 条）；好友展示名统一读取 `display_name`，服务端按当前登录人计算，优先级为备注名、昵称、账号。`remark` 仅用于备注编辑页回显，`nickname` 表示对方自己设置的昵称，不应直接作为好友列表或单聊标题的最终展示名。
 - 分页：`next_cursor` 当前按最后一条好友的 `peer_id` 生成，客户端必须作为不透明字符串原样回传，不要自行解析、排序或拼接。
 - 组织成员：`GET /v1/im/organization/members?query=&department_id=&cursor=`；好友和组织成员是两种关系，前端不得混为一个可发消息权限。
 - 新朋友、群列表、文件助手和系统消息入口由 `GET /v1/im/bootstrap` 的 `entries` 控制显示，初始红点由 `entry_badges` 和各入口 `unread_count` 返回。新朋友待处理数使用业务统计；文件助手当前返回 `topic:"slf", unread_source:"topic"`；系统消息当前返回 `topic:"sys", unread_source:"business"`，未读来自系统通知业务表。列表缓存以租户和用户隔离。
@@ -1632,6 +1725,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - 列表：`GET /v1/im/friend-requests?direction=inbound&status=all&cursor=`，返回 `request_id,applicant,message,source,status,created_at,handled_at`。
 - 同意：`POST /v1/im/friend-requests/{request_id}/accept`；拒绝：`POST /v1/im/friend-requests/{request_id}/reject`，均带幂等键和可选 `version`。
 - 成功返回最终 `status` 和 P2P `topic`。重复审批返回原结果；并发冲突返回 `REQUEST_ALREADY_HANDLED` 并附当前状态，前端刷新该项。
+- 申请不存在时 `accept/reject` 统一返回 `404/20004 RESOURCE_NOT_FOUND`；通用语义见 0.4。
 - 主动下行：创建申请时被申请人收到 `info.what="im", event="friend.request.created"`；通过/拒绝后申请人与处理人本人都收到 `friend.request.accepted/rejected`。前端收到后刷新新朋友列表、好友列表、会话 context 和 `bootstrap.entry_badges`。当前系统通知列表只给被申请人/申请人写记录，处理人本人主要靠实时业务事件刷新。
 
 ### 5.3 添加好友.png
@@ -1680,7 +1774,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增。**
 
-- `GET /v1/im/users/{identifier}/profile` 返回按当前查看人裁剪后的 `display_name,remark,avatar_file_id,gender,region,public_account,signature,relationship,capabilities`；`identifier` 可传 `user_id`、`username` 或 `public_account`。
+- `GET /v1/im/users/{identifier}/profile` 返回按当前查看人裁剪后的 `username,display_name,remark,avatar_file_id,avatar_url,gender,region,public_account,signature,relationship,capabilities`（`avatar_url` 为可直接下载的头像地址，统一回填规则见 0.5.5.1 第 4 条）；`identifier` 可传 `user_id`、`username` 或 `public_account`。`username` 是登录账号，`nickname` 是原始昵称，`display_name` 是当前查看人应展示的名称（好友备注优先）；三者不得混用。
 - 查看该用户二维码调用 `POST /v1/im/users/{identifier}/qrcodes`，Body `{"purpose":"add_friend","expires_in_seconds":86400}`；前端在个人信息页只有用户名时直接把用户名作为 `identifier` 传入即可。服务端解析到真实用户后生成二维码，并按资料可见性与 `add_me_methods.qr` 做权限校验。
 - 发消息使用返回的 P2P `topic`；没有 Topic 时调用 `POST /v1/im/conversations/p2p`，Body `{"peer_user_id":"..."}` 并由服务端验证好友关系。
 - 音视频按钮只按 `capabilities.can_call` 展示，真正呼叫时再次鉴权。隐藏字段必须从响应中省略，不能只由前端遮挡。
@@ -1749,9 +1843,10 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 <img src="images/黑名单提示.png" alt="黑名单提示" width="360">
 
-**状态：图片文件名与画面语义不一致；按“清除聊天记录”实施，需改造。**
+**状态：图片文件名与画面语义不一致；按“清除聊天记录”实施。服务端已实现并实测（2026-10-09），剩余前端改造。**
 
 - 确认调用 MeetingIM `{del what:"msg",topic,delseq:[{"low":1,"hi":last_seq+1}],hard:false}`，仅删除当前用户视图；或封装 `DELETE /v1/im/conversations/{topic}/messages`。
+- 服务端现状（2026-10-09 测试环境实测通过）：REST 接口仅写 `im_dellog` 本人区间并递增 `deleted_id`，不改动消息行、对方视角不受影响，本人其他设备经 `deleted_id` 同步感知清空；WS `{del}` 语义相同，两条路径二选一即可。对非成员或不存在会话返回 403 FORBIDDEN。
 - 不解除好友、不影响对方历史、不删除收藏；附件仅在无任何有效引用且过保留期后回收。
 - 前端需在确认文案明确“仅清除自己的聊天记录”，成功后清本地 Topic 消息缓存并保留会话关系。
 
@@ -1777,7 +1872,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/friend-requests/{request_id}/reject` | `{"version":1}` | `{"request_id":"frq_1","status":"rejected","handled_at":"2026-08-20T09:00:00Z"}` |
 | `GET /v1/im/users/search?q=&type=account&cursor=` | Query only | `{"items":[{"user_id":"usr...","display_name":"张三","avatar_file_id":"","public_account":"zhangsan","relationship":"none","can_add":true}],"next_cursor":""}` |
 | `GET /v1/im/users/search?q=&type=exact_account` | Query only | `{"items":[{"user_id":"usr...","display_name":"张三","public_account":"zhangsan","relationship":"none","can_add":true}],"next_cursor":""}` |
-| `GET /v1/im/users/{identifier}/profile` | Path `user_id`/`username`/`public_account` | `{"user_id":"usr...","display_name":"张三","remark":"","avatar_file_id":"","gender":"","region":"","public_account":"zhangsan","signature":"","relationship":"friend","capabilities":{"can_send":true,"can_call":true,"can_add":false},"topic":"p2p..."}` |
+| `GET /v1/im/users/{identifier}/profile` | Path `user_id`/`username`/`public_account` | `{"user_id":"usr...","username":"zhangsan7","display_name":"张三","remark":"","avatar_file_id":"file_avatar","avatar_url":"/v0/file/s/file_avatar","gender":"","region":"","public_account":"zhangsan","signature":"","relationship":"friend","capabilities":{"can_send":true,"can_call":true,"can_add":false},"topic":"p2p..."}` |
 | `PATCH /v1/im/friends/{user_id}` | `{"remark":"老张"}` | `{"user_id":"usr...","remark":"老张","relationship":"friend","updated_at":"2026-08-20T09:00:00Z"}` |
 | `DELETE /v1/im/friends/{user_id}` | Path user ID | `{"user_id":"usr...","relationship":"none","deleted":true}` |
 | `GET /v1/im/blocks?cursor=` | Query only | `{"items":[{"user":{"user_id":"usr...","display_name":"张三","avatar_file_id":""},"blocked_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |
@@ -1815,7 +1910,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增邀请卡片和加入接口。**
 
-- 邀请卡展示以群邀请接口返回和系统通知记录为准；相关实时刷新使用 `info.what="group"` 群业务事件。
+- 邀请卡展示以群邀请接口返回和系统通知记录为准；系统通知 `event_type=group.invitation.created`，`action.type=group_invitation_accept`，`action.invitation_id` 用于点击加入，`action.topic` 为目标群。相关实时刷新使用 `info.what="group"` 群业务事件。
 - 点击加入：`POST /v1/im/group-invitations/{invitation_id}/accept`，带幂等键；返回 `status=joined|pending_approval` 和 `topic`。
 - 服务端校验邀请租户、有效期、群状态、成员资格和成员数上限；重复加入返回当前状态，过期返回 `INVITATION_EXPIRED`。
 
@@ -1835,7 +1930,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增。**
 
-- `GET /v1/im/groups/{topic}/join-requests?status=pending&cursor=` 返回申请人、邀请人、来源、时间、状态和 `version`。
+- `GET /v1/im/groups/{topic}/join-requests?status=pending&cursor=` 返回申请人、邀请人、来源、时间、状态和 `version`；申请人展示字段直接带 `display_name/avatar_file_id/user`，邀请人展示字段带 `inviter_display_name/inviter_avatar_file_id/inviter`。
 - 同意：`POST /v1/im/groups/{topic}/join-requests/{id}/accept`；拒绝：`POST /v1/im/groups/{topic}/join-requests/{id}/reject`，带幂等键与 `version`。
 - 仅群主/管理员可处理；同意时原子校验群成员上限。并发处理返回 `REQUEST_ALREADY_HANDLED` 和最终状态。
 
@@ -1886,6 +1981,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - `GET /v1/im/groups/{topic}/settings` 返回 `my_role,permissions,profile,announcement,member_count,pinned,mute_notifications` 和群治理开关。
 - 个人置顶/免打扰通过 `PATCH /v1/im/groups/{topic}/member-settings`；群级设置必须使用 6.17，不混在个人设置里。
 - 退出：`POST /v1/im/groups/{topic}/leave`；群主必须先转让或解散。清记录、举报分别见 5.14、11.3。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散返回 `410/30004 GROUP_DISSOLVED`；非群成员返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 
 ### 6.11 群资料.png
 
@@ -1915,7 +2011,9 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - `PUT /v1/im/groups/{topic}/members/me/profile`，Body `{"nickname":"...","version":n}`。
 - 服务端校验成员资格、长度和敏感词，返回 `nickname,version,updated_at` 并推送成员资料变化。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散返回 `410/30004 GROUP_DISSOLVED`；非群成员返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 - 该昵称仅作用当前群，不能修改全局用户昵称或其他群资料。
+- 群成员列表和群成员资料中的 `display_name` 仍由服务端按当前登录人计算，好友备注优先；群内昵称单独返回为 `group_nickname`，前端不要用 `nickname/group_nickname` 覆盖 `display_name`。
 
 ### 6.13.1 群成员列表拉取与缓存策略
 
@@ -1982,6 +2080,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 **状态：新增。**
 
 - `POST /v1/im/groups/{topic}/qrcodes`，Body `{"expires_in_seconds":86400}`，返回签名 `qr_token,qr_payload,expires_at,group,group_snapshot`；`group` 与 `group_snapshot` 内容一致，前端优先使用 `group`。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；群已解散返回 `410/30004 GROUP_DISSOLVED`；非群主/管理员返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 - 扫码调用 `POST /v1/im/qrcodes/resolve`，`purpose:"join_group"`；随后 `POST /v1/im/groups/{topic}/join-requests` 并携带 `qr_token`。
 - 群解散、二维码过期或管理员撤销后必须失效；二维码不得直接承载内部群权限。
 
@@ -1994,6 +2093,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - 查询/更新：`GET/PATCH /v1/im/groups/{topic}/governance`，字段为 `join_approval,mute_all,member_upload_files,member_private_chat,member_invite` 和 `version`。
 - 每个字段返回 `editable`；PATCH 仅群主或被授权管理员可用，记录操作者、旧值、新值和 Request ID。
 - 解散：`DELETE /v1/im/groups/{topic}`，需二次 `X-Action-Token` 和幂等键；成功后撤销 Topic、二维码、邀请和文件新增权限。
+- 群不存在返回 `404/30004 RESOURCE_NOT_FOUND`；已解散重复解散返回 `410/30004 GROUP_DISSOLVED`；非群主返回 `403/30005 PERMISSION_DENIED`。通用语义见 0.4。
 
 ### 6.18 设置群管理员.png
 
@@ -2098,9 +2198,9 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：需改造。**
 
-- 先用 `purpose=group_file,topic=...` 上传，再 `POST /v1/im/groups/{topic}/files`，Body `{"file_id":"..."}` 建立群文件记录。
-- 服务端校验 `member_upload_files`、单文件上限、租户总存储和群成员身份；成功返回完整群文件项。
-- 上传失败可复用 `upload_id`；登记失败不得在列表显示，孤立文件按 TTL 回收。
+- 先用 `purpose=group_file,topic=...` 上传，再 `POST /v1/im/groups/{topic}/files`，Body `{"file_id":"...","file_name":"方案.pdf","mime_type":"application/pdf","file_size":1024}` 建立群文件记录。
+- 服务端校验 `member_upload_files`、文件是否已上传完成、`file_name` 长度不超过 255、`mime_type` 长度不超过 128、`file_size` 非负且与上传记录一致、单文件上限、租户总存储和群成员身份；成功返回完整群文件项。
+- 上传失败按整文件重传重新上传并取得新 `file_id`；登记失败不得在列表显示，孤立文件按 TTL 回收。
 
 ### 6.29 接口示例
 
@@ -2121,18 +2221,20 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/groups` | `{"name":"项目群","description":"项目沟通","member_user_ids":["usr..."],"avatar_file_id":""}` | `{"topic":"grp...","name":"项目群","avatar_file_id":"","description":"项目沟通","owner":"usr_me","member_count":2,"version":1,"my_role":"owner","permissions":{"can_edit_profile":true,"can_invite_members":true,"can_manage_members":true,"can_manage_settings":true,"can_leave":false}}` |
 | `GET /v1/im/groups/{topic}` | Path topic | `{"topic":"grp...","name":"项目群","avatar_file_id":"","description":"项目沟通","owner":"usr_me","member_count":2,"version":1,"my_role":"owner","permissions":{"can_edit_profile":true}}` |
 | `PATCH /v1/im/groups/{topic}` | `{"name":"新群名","avatar_file_id":"file_avatar","description":"新简介","version":1}` | `{"topic":"grp...","name":"新群名","avatar_file_id":"file_avatar","description":"新简介","version":2,"permissions":{"can_edit_profile":true}}` |
-| `DELETE /v1/im/groups/{topic}` 待实现 | Header `X-Action-Token: action_token`；Body `{}` | `{"topic":"grp...","deleted":true}` |
+| `DELETE /v1/im/groups/{topic}` | Header `X-Action-Token: action_token`；Body `{}` | `{"topic":"grp...","deleted":true,"status":"dissolved","version":2}` |
 | `GET /v1/im/groups/{topic}/settings` | Path topic | `{"topic":"grp...","profile":{"name":"项目群","description":"项目沟通"},"pinned":false,"mute_notifications":false,"member_count":2,"permissions":{"can_manage_settings":true},"governance":{"join_approval":false,"mute_all":false,"member_invite":true}}` |
 | `PATCH /v1/im/groups/{topic}/member-settings` | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"topic":"grp...","pinned":true,"mute_notifications":false,"version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `PUT /v1/im/groups/{topic}/members/me/profile` | `{"nickname":"我在群里的昵称","version":1}` | `{"nickname":"我在群里的昵称","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `POST /v1/im/groups/{topic}/leave` | `{}` | `{"topic":"grp...","status":"left"}` |
-| `GET /v1/im/groups/{topic}/members?query=&cursor=&mentionable=true` | Query only | `{"topic":"grp...","items":[{"user_id":"usr...","display_name":"张三","avatar_file_id":"","role":"member","mentionable":true,"acs":{"want":"JRWP","given":"JRWP","mode":"JRWP"}}],"next_cursor":"","permissions":{"can_mention_all":true}}` |
-| `GET /v1/im/groups/{topic}/members/{user_id}/profile` | Path topic/user；`topic` 必须是 `grp...`，不能传 `usr...` | `{"topic":"grp...","user_id":"usr...","display_name":"张三","group_nickname":"小张","role":"member","relationship":"friend","capabilities":{"can_send":true,"can_call":true}}` |
+| `GET /v1/im/groups/{topic}/members?query=&cursor=&mentionable=true` | Query only | `{"topic":"grp...","items":[{"user_id":"usr...","display_name":"张三","group_nickname":"小张","avatar_file_id":"","role":"member","member_status":"active","version":1,"joined_at":"2026-08-20T09:00:00Z","updated_at":"2026-08-20T09:00:00Z","mentionable":true,"acs":{"want":"JRWP","given":"JRWP","mode":"JRWP"}}],"next_cursor":"","sync_mode":"full","permissions":{"can_mention_all":true}}` |
+| `GET /v1/im/groups/{topic}/members/{user_id}` | Path topic/user | `{"topic":"grp...","user_id":"usr...","display_name":"张三","group_nickname":"小张","role":"member","member_status":"active","version":1,"joined_at":"2026-08-20T09:00:00Z","updated_at":"2026-08-20T09:00:00Z","sync_mode":"single","acs":{"want":"JRWP","given":"JRWP","mode":"JRWP"}}` |
+| `DELETE /v1/im/groups/{topic}/members/{user_id}` | Path topic/user；管理员可移除普通成员，群主可移除管理员和普通成员；不能移除群主或自己 | `{"topic":"grp...","user_id":"usr...","status":"left"}` |
+| `GET /v1/im/groups/{topic}/members/{user_id}/profile` | Path topic/user；`topic` 必须是 `grp...`，不能传 `usr...`；`user_id` 可传本人，返回 `relationship:"self"`、`capabilities.can_send=true` | `{"topic":"grp...","user_id":"usr...","display_name":"张三","group_nickname":"小张","role":"member","relationship":"friend","capabilities":{"can_send":true,"can_call":true}}` |
 | `POST /v1/im/groups/{topic}/qrcodes` | `{"expires_in_seconds":86400}` | `{"qr_token":"token...","qr_payload":"im://qr?token=...&purpose=join_group","expires_at":"2026-08-21T09:00:00Z","group":{"topic":"grp...","name":"项目群","member_count":2},"group_snapshot":{"topic":"grp...","name":"项目群","member_count":2}}` |
 | `POST /v1/im/groups/{topic}/invitations` | `{"user_ids":["usr..."],"message":"进群一起讨论"}` | `{"topic":"grp...","items":[{"user_id":"usr...","status":"joined","invitation_id":"ginv_1"}]}` |
 | `POST /v1/im/group-invitations/{invitation_id}/accept` 待实现 | `{}` | `{"invitation_id":"ginv_1","status":"joined","topic":"grp..."}` |
 | `POST /v1/im/groups/{topic}/join-requests` | `{"message":"申请入群","source":"qr","qr_token":"token..."}` | `{"request_id":"gjr_1","topic":"grp...","status":"pending","created_at":"2026-08-20T09:00:00Z","version":1}` |
-| `GET /v1/im/groups/{topic}/join-requests?status=pending&cursor=` | Query only | `{"topic":"grp...","items":[{"request_id":"gjr_1","applicant":{"user_id":"usr...","display_name":"张三"},"status":"pending","source":"qr","created_at":"2026-08-20T09:00:00Z","version":1}],"next_cursor":""}` |
+| `GET /v1/im/groups/{topic}/join-requests?status=pending&cursor=` | Query only | `{"topic":"grp...","items":[{"request_id":"gjr_1","user_id":"usr...","display_name":"张三","avatar_file_id":"avatar.jpg","user":{"user_id":"usr...","display_name":"张三","avatar_file_id":"avatar.jpg"},"inviter_id":"usr_inviter","inviter_display_name":"李四","inviter_avatar_file_id":"inviter.jpg","inviter":{"user_id":"usr_inviter","display_name":"李四","avatar_file_id":"inviter.jpg"},"status":"pending","source":"invitation","created_at":"2026-08-20T09:00:00Z","version":1}],"next_cursor":""}` |
 | `POST /v1/im/groups/{topic}/join-requests/{id}/accept` | `{"version":1}` | `{"request_id":"gjr_1","topic":"grp...","status":"accepted","handled_at":"2026-08-20T09:00:00Z","version":2}` |
 | `POST /v1/im/groups/{topic}/join-requests/{id}/reject` | `{"version":1,"reason":"人数已满"}` | `{"request_id":"gjr_1","topic":"grp...","status":"rejected","handled_at":"2026-08-20T09:00:00Z","version":2}` |
 | `GET /v1/im/groups/{topic}/summary` | Path topic | `{"topic":"grp...","pending_join_request_count":0,"announcement":{"announcement_id":"ann_1","content":"公告"},"permissions":{"can_manage_members":true}}` |
@@ -2239,10 +2341,12 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 <img src="images/文件-下载.png" alt="文件-下载" width="360">
 
-**状态：底层下载已实现租户校验；资源 ACL 需改造。**
+**状态：下载授权已实现（按上传者/会话成员/消息引用/群成员/好友/收藏/头像放行）。**
 
-- 客户端使用 `GET /v0/file/s/{file_id}`，Header 传 API Key 与 `X-MeetingIM-Auth: token <base64_token>`；禁止 `?auth=&secret=`。
-- 服务端除 Token 租户外，还必须校验该用户通过消息、群文件或收藏拥有有效引用，并支持 `Range`、`ETag`、内容长度和安全文件名。
+- 客户端使用 `GET /v0/file/s/{file_id}`，Header 传 API Key 与 `X-MeetingIM-Auth: token <base64_token>`；禁止 `?auth=&secret=`。URL 可带扩展名，服务端自动剥离。
+- 服务端按文件 ACL 放行：上传者本人、文件所属 `p2p`/`grp` 会话成员、消息级引用可见者（未撤回未删除且未被执行删除）、群成员、好友关系、收藏引用、用户头像/资料文件（对任何登录用户放行，2026-10-14 更新）；非授权返回 `403 permission denied`（`FILE_FORBIDDEN`）。对象存储模式下鉴权通过返回 302 短期签名 URL。
+- 头像排障口径：群成员/资料接口返回的 `avatar_url` 可直接下载；若对端头像显示占位图且下载 `404`，说明该头像文件从未被引用或已被回收，让对方重新上传并设置头像即可；`403` 为非登录态（Token 失效），重新登录。
+- 前提：发送方上传附件时带了 `topic`（见 0.5.5.1）。若对端下载一直 404，说明该文件从未关联会话/消息且已被 1 小时回收任务删除，应让发送方重新上传并携带 `topic`。
 - 下载前客户端校验本地空间和网络策略；`FILE_FORBIDDEN` 不自动重试，`FILE_UNAVAILABLE` 显示失效。
 
 ### 7.10 文件-下载中.png
@@ -2331,10 +2435,10 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `GET /v1/im/favorites/{favorite_id}` | Path favorite ID | `{"favorite_id":"fav_1","type":"file","snapshot":{"file_id":"file_1","name":"a.pdf"},"source":{"topic":"grp...","seq":12},"availability":"available"}` |
 | `DELETE /v1/im/favorites/{favorite_id}` | Path favorite ID | `{"favorite_id":"fav_1","deleted":true}` |
 | `POST /v1/im/favorites/batch-delete` | `{"favorite_ids":["fav_1","fav_2"]}` | `{"items":[{"favorite_id":"fav_1","deleted":true},{"favorite_id":"fav_2","deleted":true}],"failed":[]}` |
-| `POST /v1/im/favorites/forward` | `{"favorite_ids":["fav_1"],"target_topics":["grp..."],"comment":"转给你"}` | `{"items":[{"favorite_id":"fav_1","target_topic":"grp...","status":"sent","seq":20}],"failed":[]}` |
+| `POST /v1/im/favorites/forward` | `{"favorite_ids":["fav_1"],"target_topics":["grp..."],"comment":"转给你"}` | `{"items":[{"favorite_id":"fav_1","target_topic":"grp...","status":"sent","seq":20,"comment_seq":19,"comment_status":"sent"}],"failed":[]}`；Kafka 投递结果不确定时返回 `status:"pending"`、`reason:"MESSAGE_PERSIST_PENDING"` |
 | `GET /v1/im/forward-targets?query=&cursor=` | Query only | `{"items":[{"topic":"grp...","type":"group","display_name":"项目群","avatar_file_id":"","can_receive_forward":true},{"topic":"slf","type":"file_assistant","display_name":"文件助手","can_receive_forward":true}],"next_cursor":"","has_more":false}` |
-| `POST /v1/im/messages/forward` 逐条转发 | `{"mode":"separate","sources":[{"topic":"grp...","seq":12}],"target_topics":["usr..."],"comment":""}` | `{"items":[{"source":{"topic":"grp...","seq":12},"target_topic":"p2p...","client_mid":"mid_1","seq":30,"status":"sent"}],"failed":[]}` |
-| `POST /v1/im/messages/forward` 合并转发 | `{"mode":"bundle","sources":[{"topic":"grp...","seq":12},{"topic":"grp...","seq":13}],"target_topics":["usr..."],"comment":""}` | `{"items":[{"sources":[{"topic":"grp...","seq":12},{"topic":"grp...","seq":13}],"target_topic":"p2p...","client_mid":"mid_1","seq":31,"status":"sent","mode":"bundle","bundle_id":"fbundle_1"}],"failed":[]}` |
+| `POST /v1/im/messages/forward` 逐条转发 | `{"mode":"separate","sources":[{"topic":"grp...","seq":12}],"target_topics":["usr..."],"comment":"转给你"}` | `{"items":[{"source":{"topic":"grp...","seq":12},"target_topic":"p2p...","client_mid":"mid_1","seq":30,"status":"sent","comment_seq":29,"comment_status":"sent"}],"failed":[]}`；Kafka 投递结果不确定时返回 `status:"pending"`、`reason:"MESSAGE_PERSIST_PENDING"` |
+| `POST /v1/im/messages/forward` 合并转发 | `{"mode":"bundle","sources":[{"topic":"grp...","seq":12},{"topic":"grp...","seq":13}],"target_topics":["usr..."],"comment":"转给你"}` | `{"items":[{"sources":[{"topic":"grp...","seq":12},{"topic":"grp...","seq":13}],"target_topic":"p2p...","client_mid":"mid_1","seq":31,"status":"sent","mode":"bundle","bundle_id":"fbundle_1","comment_seq":30,"comment_status":"sent"}],"failed":[]}`；Kafka 投递结果不确定时返回 `status:"pending"`、`reason:"MESSAGE_PERSIST_PENDING"` |
 | `GET /v1/im/forward-bundles/{bundle_id}?cursor=` 待实现 | Query only | `{"bundle_id":"fbundle_1","title":"聊天记录","item_count":2,"items":[{"from_display":"张三","ts":"2026-08-20T09:00:00Z","summary":"文本摘要"}],"next_cursor":""}` |
 | `POST /v1/im/security/urls/check` | `{"url":"https://example.com","source":"favorite"}` | `{"url":"https://example.com","decision":"allow","risk_level":"low","reason":"ok","source":"favorite"}` |
 
@@ -2354,11 +2458,12 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 <img src="images/对方状态.png" alt="对方状态" width="360">
 
-**状态：在线邀请已实现；Push 与产品鉴权需改造。**
+**状态：在线邀请、短有效期普通 Push 与产品鉴权已实现。**
 
 - 来电是 Topic 下行的初始 `{data}`：`head.webrtc="started"`、`head.x-im-type="call"`，`content` 至少含 `callId,callType,audio,video`。客户端保存该消息 `seq` 作为后续所有 call note 的关联 ID。
 - 来电端开始响铃后发送 `{note:{topic,what:"call",event:"ringing",seq,payload:{"callId":"..."}}}`；接听发送 `event:"accept"`；拒绝发送 `event:"hang-up"`。
-- 后台 Push 只携带 `callId,topic,seq,caller_display,callType,expires_at`，不含 SDP、ICE 或 Token；用户操作后必须回 WebSocket 鉴权。
+- 后台 Push 只携带 `callId,topic,seq,caller_id,caller_display,callType,expires_at`，不含 SDP、ICE 或 Token；iOS 来电 Push 使用普通 alert，`category=im_call`，`content-available=1`，短 TTL 约 30 秒，不使用 PushKit VoIP。
+- 被叫在未发送 `ringing/accept` 前也可以直接发送 `hang-up`，服务端按 `topic+seq+callId` 校验后立即结束主叫侧振铃，并把原通话消息替换为 `declined`；主叫主动取消则替换为 `missed`。
 
 ### 8.3 语音通话-对方待接受状态.png
 
@@ -2480,7 +2585,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增。**
 
-- `GET /v1/im/workbench` 返回 `modules[{code,name,icon_file_id,route,unread_count,enabled,permission}]`、布局版本和企业配置。
+- `GET /v1/im/workbench` 返回 `modules[{code,name,icon_file_id,route,sort_order,unread_count,enabled,permission}]`、布局版本和企业配置；服务端按 `sort_order ASC` 返回，默认顺序为打卡、月报、日报、部门框架、举报信箱、会议通知、会议笔记。`meetings` 模块的 `unread_count` 由服务端按未读系统通知实时补齐。
 - `GET /v1/im/bootstrap` 返回 `entry_badges.workbench_total_unread`，用于工作台一级入口总红点；当前只汇总“会议通知”模块的未读通知，会议笔记、日报、月报、打卡、部门框架和举报信箱均不产生工作台通知数。
 - 服务端按当前 Token 的租户、组织角色和功能开关裁剪；前端只接受白名单内部 `route`，禁止直接执行服务端任意 URL。
 - 工作台一级总未读以 `GET /v1/im/bootstrap` 和 `GET /v1/im/workbench` 返回为准；当前只有会议通知可接收移动端通知，其他工作台模块在进入页面时主动拉取数据刷新。若后续启用 `workbench.badge.updated`，应按 0.5.4.6 的 `info.what="im"` 业务事件下发。切租户必须重新加载，不复用另一企业工作台。
@@ -2528,6 +2633,16 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 - 返回我的最终响应和会议版本，并通过 `meeting.response.updated` 实时通知参会人；重复提交同状态幂等。
 - 会议过期返回 `MEETING_CLOSED` 并只读展示；客户端本地日历写入是可选系统动作，不替代服务端响应。
 
+### 9.4.1 会议笔记
+
+**状态：新增。**
+
+- 列表：`GET /v1/im/meeting-notes?query=&cursor=&limit=20` 返回可查看会议笔记的会议列表、`note_status/file_count/permissions`。
+- 详情：`GET /v1/im/meetings/{meeting_id}/notes` 返回会议信息和 `files[]`。
+- 上传并登记：调用通用文件上传 `POST /v0/file/u/`，multipart 包含 `file=@...`、`purpose=meeting_note`、`meeting_id=<meeting_id>`、`id=<本次上传幂等ID>`，请求头按文件上传鉴权携带 `X-MeetingIM-APIKey`、`X-MeetingIM-Auth`。服务端上传成功后会立即登记会议笔记文件，响应 `ctrl.params` 包含 `url,file_id,purpose,meeting_id,note_file_id,note_file_status,version`。
+- 兼容绑定：若客户端先完成普通文件上传，也可以调用 `POST /v1/im/meetings/{meeting_id}/notes/files`，Body `{"file_id":"..."}`，并携带 `Idempotency-Key` 完成登记。
+- 替换/删除：`PUT /v1/im/meetings/{meeting_id}/notes/files/{note_file_id}`、`DELETE /v1/im/meetings/{meeting_id}/notes/files/{note_file_id}?version=n`。只有记录人/发起人按权限可上传、替换和删除。
+
 ### 9.5 日报.png
 
 <img src="images/日报.png" alt="日报" width="360">
@@ -2604,7 +2719,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 **状态：新增。**
 
 - 页面配置：`GET /v1/im/executive-mailbox/config` 返回 `enabled,allow_anonymous,required_fields,max_length,attachment_policy,notice`。
-- 提交：`POST /v1/im/executive-mailbox/submissions`，Body `{"subject":"...","content":"...","anonymous":false,"attachment_file_ids":[]}`，带幂等键。
+- 提交：`POST /v1/im/executive-mailbox/submissions`，Body `{"subject":"...","content":"...","anonymous":false,"attachment_file_ids":[]}`，带幂等键。`subject` 最多 200 字符，`content` 最多 5000 字符；超限返回 `VALIDATION_FAILED`，不返回 500。
 - 成功仅返回 `submission_id,status:"received",submitted_at`；匿名模式下业务接收方不见身份，但安全审计是否保留内部追踪按企业政策执行并提前告知。
 
 ### 9.13 总经理信箱-文案提示.png
@@ -2693,7 +2808,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 **状态：基础文件读取已实现；会议笔记 ACL 和预览转换新增。**
 
 - 文件项返回 `preview.status=ready|processing|unsupported|failed`、`preview.mode=native|converted|download_only` 和可选 `preview_file_id`，客户端根据状态选择直接预览、轮询转换状态或提示暂不支持。
-- 原生可预览文件使用受认证的 `GET /v0/file/s/{file_id}`；转换预览使用 `GET /v0/file/s/{preview_file_id}`。两个接口都必须校验当前用户仍有会议笔记查看权限。
+- 原生可预览文件使用受认证的 `GET /v0/file/s/{file_id}`；转换预览使用 `GET /v0/file/s/{preview_file_id}`。对象存储模式下服务端鉴权通过后返回 302 到短期签名 URL，客户端跟随 `Location` 获取文件内容。
 - 服务端不得返回长期有效的公共下载 URL。客户端缓存键至少包含 `tenant_code + user_id + file_id + etag`，退出登录或切换企业时清理受控缓存。
 - `preview.status="processing"` 时客户端可在当前详情页低频刷新，建议 2 秒后开始、最长 30 秒；离开页面立即停止轮询。
 
@@ -2703,7 +2818,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：复用统一下载任务；会议笔记 ACL 新增。**
 
-- 下载使用 `GET /v0/file/s/{file_id}`，Header 传 API Key 与 `X-MeetingIM-Auth: token <base64_token>`，并支持 `Range` 和 `If-Range` 断点续传。
+- 下载使用 `GET /v0/file/s/{file_id}`，Header 传 API Key 与 `X-MeetingIM-Auth: token <base64_token>`，并支持 `Range` 和 `If-Range` 断点续传；对象存储模式下客户端跟随 302 `Location`。
 - 下载任务保存 `file_id,etag,total_bytes,downloaded_bytes,temp_path,state`。Token 更新后使用新 Token 续传，禁止把 Token 写入任务文件或日志。
 - 服务端在每次下载及续传时重新校验会议可见权限。返回 `FILE_FORBIDDEN` 时客户端停止重试；返回 `FILE_UNAVAILABLE` 时标记文件失效并刷新详情。
 - 下载进度属于客户端本地状态，不更新会议笔记业务状态、不产生工作台通知，也不写入未读数。
@@ -2736,7 +2851,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/meetings/{meeting_id}/notes/files` 新增 | Header `Idempotency-Key`；Body `{"file_id":"file_1"}` | `{"note_file_id":"mnote_1","meeting_id":"mtg_1","file_id":"file_1","name":"会议纪要.pdf","size":204800,"mime":"application/pdf","created_at":"2026-09-05T03:00:00Z","version":1,"preview":{"status":"processing","mode":"converted"}}` |
 | `PUT /v1/im/meetings/{meeting_id}/notes/files/{note_file_id}` 新增 | Header `Idempotency-Key`；Body `{"file_id":"file_2","version":1}` | `{"note_file_id":"mnote_1","meeting_id":"mtg_1","file_id":"file_2","name":"会议纪要-v2.pdf","version":2,"updated_at":"2026-09-05T03:10:00Z"}` |
 | `DELETE /v1/im/meetings/{meeting_id}/notes/files/{note_file_id}` 新增 | Header `Idempotency-Key`；Query `version=2` | `{"note_file_id":"mnote_1","deleted":true,"deleted_at":"2026-09-05T03:20:00Z"}` |
-| `GET /v0/file/s/{file_id}` | Header `X-MeetingIM-Auth`；可带 `Range: bytes=0-` | 返回文件字节流及 `Content-Type`、`Content-Length`、`ETag`、`Accept-Ranges`；失败返回 `FILE_FORBIDDEN` 或 `FILE_UNAVAILABLE` |
+| `GET /v0/file/s/{file_id}` | Header `X-MeetingIM-Auth`；可带 `Range: bytes=0-` | 对象存储模式下鉴权通过后返回 302 到短期签名 URL；客户端跟随 Location 获取文件内容 |
 
 ### 9.14.10 字段与状态约定
 
@@ -2815,6 +2930,10 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/meetings/{id}/cancel` | `{"version":2,"reason":"时间冲突"}` | `{"meeting_id":"mtg_1","state":"cancelled","version":3}` |
 | `POST /v1/im/meetings/{id}/reminders` | `{}` | `{"meeting_id":"mtg_1","items":[{"user_id":"usr...","status":"sent"}]}` |
 | `PUT /v1/im/meetings/{meeting_id}/my-response` | `{"response":"accepted","version":1}` | `{"meeting_id":"mtg_1","my_response":"accepted","version":2,"response_at":"2026-08-20T09:00:00Z"}` |
+| `GET /v1/im/meeting-notes?query=&cursor=` | Query only | `{"items":[{"meeting_id":"mtg_1","title":"周会","note_status":"available","file_count":1,"permissions":{"can_upload":true,"can_download":true}}],"next_cursor":"","has_more":false}` |
+| `GET /v1/im/meetings/{meeting_id}/notes` | Path meeting ID | `{"meeting_id":"mtg_1","note_status":"available","files":[{"note_file_id":"mnote_1","file_id":"file_1","file_name":"会议纪要.pdf","mime_type":"application/pdf","permissions":{"can_download":true}}]}` |
+| `POST /v0/file/u/` 会议笔记上传并登记 | Multipart `purpose=meeting_note&meeting_id=mtg_1&id=upload_1&file=@note.pdf` | `{"ctrl":{"code":200,"params":{"url":"/v0/file/s/file_1.pdf","file_id":"file_1","purpose":"meeting_note","meeting_id":"mtg_1","note_file_id":"mnote_1","note_file_status":"active","version":1}}}` |
+| `POST /v1/im/meetings/{meeting_id}/notes/files` | Header `Idempotency-Key`；Body `{"file_id":"file_1"}` | `{"note_file_id":"mnote_1","meeting_id":"mtg_1","file_id":"file_1","status":"active","version":1}` |
 | `GET /v1/im/reports/daily?scope=mine&from=&to=&status=&cursor=` | Query only | `{"items":[{"report_id":"dr_1","report_date":"2026-08-20","content_short":"今日完成联调和问题回归...","status":"draft","draft_updated_at":"2026-08-20T09:00:00Z","submitted_at":null,"read_state":"unread"}],"next_cursor":"","permissions":{"can_create":true,"makeup_allowed_days":7}}` |
 | `GET /v1/im/reports/daily?scope=managed&date=&status=submitted\|missing&department_id=&cursor=` | Query only | `{"items":[{"report_id":"dr_1","author":{"user_id":"usr...","display_name":"张三"},"report_date":"2026-08-20","content_short":"完成日报提交和项目同步...","status":"submitted","submitted_at":"2026-08-20T09:00:00Z","read_state":"unread"}],"next_cursor":"","permissions":{"can_remind_unsubmitted":true,"can_view_managed":true}}` |
 | `POST /v1/im/reports/daily` | `{"report_date":"2026-08-20"}` | `{"report_id":"dr_1","report_date":"2026-08-20","content":"","attachments":[],"status":"draft","version":1,"permissions":{"can_edit":true,"can_submit":true,"can_view":true}}` |
@@ -2852,8 +2971,9 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：MeetingIM `me` 资料更新已有基础；目标产品接口需改造。**
 
-- 查询 `GET /v1/im/me/profile` 返回 `avatar_file_id,nickname,birth_date,signature,gender,region,email,public_account,version,field_rules`；`email` 当前仅为资料字段，不用于登录或找回密码。
-- 更新统一使用 `PATCH /v1/im/me/profile`，仅提交变更字段并带 `version`；服务端更新后同步 MeetingIM `me.public` 并推送资料事件。
+- 查询 `GET /v1/im/me/profile` 返回 `username,avatar_file_id,avatar_url,nickname,birth_date,signature,gender,region,email,public_account,phone_mask,version,field_rules`（`avatar_url` 统一回填规则见 0.5.5.1 第 4 条）；`username` 为只读登录账号；`phone_mask` 为只读脱敏手机号（例如 `136****3333`），未绑定手机号时返回空字符串；`email` 当前仅为资料字段，不用于登录或找回密码。
+- 更新统一使用 `PATCH /v1/im/me/profile`，仅提交变更字段并带 `version`（乐观锁必填，`version` 取自最近一次 `GET /v1/im/me/profile` 的返回值）；缺失或 `<=0` 返回 `400/20000 MALFORMED_REQUEST`，与当前版本不一致返回 `409/20009 VERSION_CONFLICT`（重新 GET 取最新 `version` 后重试即可）；服务端更新后同步 MeetingIM `me.public` 并推送资料事件。
+- 头像、昵称、签名、性别、地区、公开账号等资料字段以 `im_user_profiles` 为业务真源；`im_users.public` 和 `im_subscriptions.public` 只作为服务端生成的展示投影/缓存，前端不得依赖它们作为可编辑源。
 - 头像先以 `purpose=user_avatar` 上传再 PATCH；任何字段的可见性由隐私策略裁剪。
 
 ### 10.3 设置昵称.png
@@ -2864,7 +2984,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 - `PATCH /v1/im/me/profile`，Body `{"nickname":"新昵称","version":n}`。
 - 服务端校验 Unicode 长度、全空白、控制字符和敏感内容；返回更新后的 `nickname,version,updated_at`。
-- 成功刷新全局资料和联系人快照，但不得覆盖各群昵称。版本冲突先拉最新资料再由用户确认。
+- 成功刷新全局资料和联系人快照，但不得覆盖各群昵称。版本冲突（`409/20009`）先拉最新资料再由用户确认。
 
 ### 10.4 出生日期.png
 
@@ -2900,7 +3020,7 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 **状态：菜单纯客户端；数据接口部分新增。**
 
 - 菜单来自 `bootstrap.settings_menu`，安全、通知、隐私、通用、关于按权限展示。系统通知权限状态由 iOS API 读取，不由服务端伪造。
-- 退出：`POST /v1/im/auth/logout` 撤销当前登录 Token 对应的设备会话，成功或 Token 已失效后关闭 WS、清安全存储和本租户用户缓存。
+- 退出：`POST /v1/im/auth/logout` 将当前登录 Token 的 SHA-256 摘要写入 Redis 撤销集合，TTL 与 Token 剩余有效期一致，不影响同账号其他设备。成功后关闭 WS、清安全存储和本租户用户缓存；请求须带 `Authorization: Bearer <token>` 和 `Idempotency-Key`。
 - 多设备退出使用 `DELETE /v1/im/security/sessions/{session_id}`，需二次验证。
 
 ### 10.8 设置（安卓）.png
@@ -2927,8 +3047,13 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 
 **状态：新增 App 配置接口。**
 
-- `GET /v1/im/app/releases/latest?platform=ios|android|web&current_version=1.0.0&channel=stable`，未登录可在企业解析后调用。
-- 返回 `latest_version,min_supported_version,update_type=none|optional|required,release_notes,store_url,package_url,checksum,published_at`。
+完整接口与 Android OSS APK 对接流程见：[IM-App版本更新前后端对接文档](./IM-App版本更新前后端对接文档.md)。
+
+- `GET /v1/im/app/releases/latest?platform=ios|android|web&current_version=1.0.0&channel=stable`，全局公共接口，不依赖租户解析。`current_version` 必传，使用数字点分版本号（如 `1.2.0`）。
+- 服务端返回 `has_update`、`force_update` 和 `update_type=none|recommended|force`；iOS 客户端使用 `store_url` 跳转 App Store。
+- Android 客户端使用 `package_url` 下载 OSS/CDN 上的 APK，并在安装前使用 `checksum` 完成 SHA-256 校验；强制更新时不得绕过进入主业务。
+- 版本策略由 Admin 在 `hotgo.im_app_releases` 统一管理，IM Server 通过 HMAC 内部配置接口读取，不从租户库查询。
+- 返回 `current_version,has_update,force_update,latest_version,min_supported_version,update_type=none|recommended|force,release_notes,store_url,package_url,checksum,published_at`。
 - 客户端按平台只打开受信任商店/签名下载地址；Android 包必须校验签名和 checksum，服务端 URL 使用允许域名。
 
 ### 10.11 发现新版本.png
@@ -3052,8 +3177,8 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | 接口 | 输入示例 | 成功 `data` 示例 |
 | --- | --- | --- |
 | `GET /v1/im/me` | Query only | `{"user_id":"usr...","profile":{"public_account":"usr...","nickname":"张三","avatar_file_id":"","signature":"","version":1},"profile_version":1,"realname":{"status":"unverified"},"youth_mode":{"enabled":false}}` |
-| `GET /v1/im/me/profile` | Query only | `{"avatar_file_id":"","nickname":"张三","birth_date":"1990-01-01","signature":"签名","gender":"male","region":"上海","email":"a@example.com","public_account":"usr...","version":1,"field_rules":{"nickname":{"min_length":1,"max_length":32},"signature":{"max_length":120}}}` |
-| `PATCH /v1/im/me/profile` | `{"nickname":"新昵称","signature":"新签名","version":1}` | `{"avatar_file_id":"","nickname":"新昵称","signature":"新签名","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
+| `GET /v1/im/me/profile` | Query only | `{"username":"zhangsan7","avatar_file_id":"file_avatar","avatar_url":"/v0/file/s/file_avatar","nickname":"张三","birth_date":"1990-01-01","signature":"签名","gender":"male","region":"上海","email":"a@example.com","public_account":"usr...","phone_mask":"136****3333","version":1,"field_rules":{"nickname":{"min_length":1,"max_length":32},"signature":{"max_length":120}}}` |
+| `PATCH /v1/im/me/profile` | `{"nickname":"新昵称","signature":"新签名","version":1}` | `{"avatar_file_id":"file_avatar","avatar_url":"/v0/file/s/file_avatar","nickname":"新昵称","signature":"新签名","version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `GET /v1/im/me/privacy` | Query only | `{"add_me_methods":{"account":true,"phone":true,"qr":true,"group":true},"profile_visibility":"friends","last_seen_visibility":"friends","read_receipts":true,"friend_request_verification":true,"group_invite_verification":false,"version":1,"editable":{"add_me_methods":true,"profile_visibility":true,"last_seen_visibility":true,"read_receipts":true,"friend_request_verification":true,"group_invite_verification":true}}` |
 | `PATCH /v1/im/me/privacy` | `{"add_me_methods":{"phone":false},"read_receipts":false,"friend_request_verification":false,"group_invite_verification":true,"version":1}` | `{"add_me_methods":{"account":true,"phone":false,"qr":true,"group":true},"read_receipts":false,"friend_request_verification":false,"group_invite_verification":true,"version":2,"updated_at":"2026-08-20T09:00:00Z"}` |
 | `GET /v1/im/settings/youth-mode` | Query only | `{"enabled":false,"policy_version":1,"restrictions":["night_quiet","content_filter","payment_guard"],"restriction_items":[{"code":"night_quiet","title":"深夜免打扰","description":"夜间减少消息提醒打扰，帮助用户保持健康作息。","enforced":true},{"code":"content_filter","title":"内容过滤","description":"对不适合青少年的内容进行识别和限制展示。","enforced":true},{"code":"payment_guard","title":"支付守护","description":"限制或确认支付、充值等敏感消费行为。","enforced":false}],"password_set":false,"can_enable":false,"updated_at":"2026-08-20T09:00:00Z"}` |
@@ -3068,9 +3193,29 @@ GET /v1/im/topics/{topic}/message-mutations?since_version={localMutationVersion}
 | `POST /v1/im/security/challenges/{id}/verify` 关闭青少年模式 | `{"code":"123456"}` | `{"action_token":"close_token","action":"close_youth_mode","expires_at":"2026-08-20T09:05:00Z"}` |
 | `GET /v1/im/security/realname` | Query only | `{"status":"unverified","can_submit":true}` |
 | `POST /v1/im/security/realname/submissions` | `{"name":"张三","id_type":"cn_id","id_number":"110101199001011234"}` | `{"submission_id":"rn_1","status":"pending","can_submit":false}` |
-| `POST /v1/im/security/realname/appeals` 待实现 | `{"reason":"证件变更","description":"需要更正实名信息","action_token":"action_token"}` | `{"appeal_id":"rna_1","status":"pending","submitted_at":"2026-08-20T09:00:00Z"}` |
+| `POST /v1/im/security/realname/appeals` | `{"reason":"证件变更需要更正实名信息","attachments":["file_1"]}` | `{"appeal_id":"rna_1","reason":"...","attachments":["file_1"],"status":"pending"}`；当前无需二次身份验证（如后续启用，将复用 1.7 的 action_token 机制并在此处更新） |
 | `PUT /v1/im/devices/{device_id}/push-token` | `{"provider":"jpush","token":"registration_id","platform":"android","app_version":"1.0.0","push_env":"test","sdk_version":"5.0.0","notification_permission":"granted"}` | `{"device_id":"device_1","provider":"jpush","platform":"android","app_version":"1.0.0","updated_at":"2026-08-20T09:00:00Z"}` |
 | `DELETE /v1/im/security/sessions/{session_id}` 待实现 | Header `X-Action-Token: action_token` | `{"session_id":"sess_1","revoked":true}` |
+| `POST /v1/im/me/password` | `{"old_password":"OldPass123","new_password":"NewPass123"}` | `{"status":"ok"}`；旧密码错误返回 HTTP `401`：`{"code":30001,"reason":"AUTH_REQUIRED","message":"invalid credentials"}`；新密码不满足策略返回 HTTP `400`：`{"code":30040,"reason":"PASSWORD_POLICY_VIOLATION"}` |
+| `POST /v1/im/security/challenges` 注销账号发码 | Header `Idempotency-Key`；Body `{"scene":"delete_account","channel":"sms"}` | `{"challenge_id":"sec_chg_9","phone_mask":"+861****000","expires_in_seconds":300,"resend_after_seconds":60}` |
+| `POST /v1/im/security/challenges/{id}/verify` 注销账号验证 | `{"code":"123456"}` | `{"action_token":"del_token","action":"delete_account","expires_at":"2026-08-20T09:05:00Z"}` |
+| `POST /v1/im/me/deletion` | Header `X-Action-Token: del_token`；Body `{}` | `{"status":"ok"}` |
+
+#### 10.22.2 账号安全：修改密码与注销账号
+
+**修改密码 `POST /v1/im/me/password`（已实现）：**
+
+- 已登录（Bearer）用户提交 `old_password`、`new_password`；两者必填，缺一返回 `400 MALFORMED_REQUEST`。
+- 服务端先用旧密码走 `basic` 认证校验，失败返回 HTTP `401`：`{"code":30001,"reason":"AUTH_REQUIRED","message":"invalid credentials"}`，不泄露账号状态。
+- 新密码不满足密码策略返回 HTTP `400`：`{"code":30040,"reason":"PASSWORD_POLICY_VIOLATION"}`。
+- 成功后服务端递增 `auth_version` 并撤销该用户全部在线 Session（广播 `password_changed`）；包括当前请求在内的所有旧 Token 全部失效，客户端收到成功响应后必须清理本租户凭证并跳转登录页。
+
+**注销账号 `POST /v1/im/me/deletion`（已实现）：**
+
+- 两步挑战复用 1.7 敏感操作基建：`POST /v1/im/security/challenges`（Body `{"scene":"delete_account","channel":"sms"}`，发码到账号绑定手机号）→ `POST /v1/im/security/challenges/{id}/verify`（返回一次性 `action_token`）→ `POST /v1/im/me/deletion`（Header `X-Action-Token` 携带）。
+- 服务端配置 `permanent_accounts=true` 时拒绝注销：HTTP `403` `{"code":30040,"reason":"FORBIDDEN","message":"account deletion is disabled"}`。
+- 执行成功为**软删除**：撤销全部认证记录（含登录密码）、踢出所有在线 Session（`reason=user_deleted`）、退出并停用其拥有的群与 P2P 会话、向关注该用户的好友下发 `gone` 在线状态；账号不再可登录。客户端收到成功响应后清理本地数据并返回企业入口。
+- 挑战阶段限流与错误码同 1.7（`VERIFICATION_RATE_LIMITED`、`CHALLENGE_EXPIRED`、`CODE_INVALID`、`TOO_MANY_ATTEMPTS`）；action token 缺失/无效返回 HTTP `403` `{"code":30042,"reason":"ACTION_TOKEN_INVALID"}`。
 
 ## 11. 反诈安全、举报与意见反馈
 

go.mod

@@ -24,6 +24,7 @@ require (
 	github.com/gorilla/websocket v1.5.3
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/jmoiron/sqlx v1.4.0
+	github.com/minio/minio-go/v7 v7.4.1
 	github.com/mozillazg/go-pinyin v0.20.0
 	github.com/nyaruka/phonenumbers v1.8.0
 	github.com/prometheus/client_golang v1.23.2
@@ -34,12 +35,13 @@ require (
 	github.com/tinode/jsonco v1.0.0
 	github.com/tinode/snowflake v1.0.0
 	go.mongodb.org/mongo-driver v1.17.9
-	golang.org/x/crypto v0.53.0
+	golang.org/x/crypto v0.57.0
 	golang.org/x/oauth2 v0.36.0
-	golang.org/x/text v0.38.0
+	golang.org/x/sync v0.23.0
+	golang.org/x/text v0.42.0
 	google.golang.org/api v0.287.0
 	google.golang.org/grpc v1.82.0
-	google.golang.org/protobuf v1.36.11
+	google.golang.org/protobuf v1.36.12
 	gopkg.in/rethinkdb/rethinkdb-go.v6 v6.2.2
 )
 
@@ -79,6 +81,7 @@ require (
 	github.com/clbanning/mxj/v2 v2.7.0 // indirect
 	github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/envoyproxy/go-control-plane/envoy v1.37.0 // indirect
 	github.com/envoyproxy/protoc-gen-validate v1.3.3 // indirect
 	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
@@ -87,15 +90,22 @@ require (
 	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.4.0 // indirect
+	github.com/klauspost/crc32 v1.3.0 // indirect
+	github.com/minio/crc64nvme v1.1.1 // indirect
+	github.com/minio/md5-simd v1.1.2 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/philhofer/fwd v1.2.0 // indirect
 	github.com/pierrec/lz4/v4 v4.1.15 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 // indirect
+	github.com/rs/xid v1.6.0 // indirect
 	github.com/spiffe/go-spiffe/v2 v2.8.1 // indirect
-	github.com/stretchr/objx v0.5.0 // indirect
+	github.com/tinylib/msgp v1.6.4 // indirect
 	github.com/tjfoc/gmsm v1.4.1 // indirect
+	github.com/zeebo/xxh3 v1.1.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/contrib/detectors/gcp v1.44.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0 // indirect
@@ -105,8 +115,9 @@ require (
 	go.opentelemetry.io/otel/sdk v1.44.0 // indirect
 	go.opentelemetry.io/otel/sdk/metric v1.44.0 // indirect
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
-	golang.org/x/net v0.56.0 // indirect
-	gopkg.in/ini.v1 v1.67.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/net v0.60.0 // indirect
+	gopkg.in/ini.v1 v1.67.3 // indirect
 )
 
 require (
@@ -128,19 +139,18 @@ require (
 	github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/klauspost/compress v1.19.0 // indirect
+	github.com/klauspost/compress v1.19.2 // indirect
 	github.com/montanaflynn/stats v0.9.0 // indirect
 	github.com/opentracing/opentracing-go v1.2.0 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/procfs v0.21.1 // indirect
-	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/sirupsen/logrus v1.10.2 // indirect
 	github.com/twilio/twilio-go v1.30.9
 	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
 	github.com/xdg-go/scram v1.2.0 // indirect
 	github.com/xdg-go/stringprep v1.0.4 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
-	golang.org/x/sync v0.21.0 // indirect
-	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/sys v0.48.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
 	google.golang.org/appengine v1.6.8 // indirect
 	google.golang.org/genproto v0.0.0-20260630182238-925bb5da69e7 // indirect

go.sum

@@ -176,6 +176,8 @@ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
 github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
 github.com/envoyproxy/go-control-plane v0.14.0 h1:hbG2kr4RuFj222B6+7T83thSPqLjwBIfQawTkC++2HA=
@@ -264,8 +266,13 @@ github.com/json-iterator/go v1.1.10/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
-github.com/klauspost/compress v1.19.0 h1:sXLILfc9jV2QYWkzFOPWStmcUVH2RHEB1JCdY2oVvCQ=
-github.com/klauspost/compress v1.19.0/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8=
+github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/cpuid/v2 v2.0.1/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
+github.com/klauspost/cpuid/v2 v2.4.0 h1:S6Hrbc7+ywsr0r+RLapfGBHfyefhCTwEh3A0tV913Dw=
+github.com/klauspost/cpuid/v2 v2.4.0/go.mod h1:19jmZ9mjzoF//ddRSUsv0zfBTJWh3QJh9FNxZTMrGxU=
+github.com/klauspost/crc32 v1.3.0 h1:sSmTt3gUt81RP655XGZPElI0PelVTZ6YwCRnPSupoFM=
+github.com/klauspost/crc32 v1.3.0/go.mod h1:D7kQaZhnkX/Y0tstFGf8VUzv2UofNGqCjnC3zdHB0Hw=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
@@ -281,6 +288,12 @@ github.com/localtunnel/go-localtunnel v0.0.0-20170326223115-8a804488f275 h1:IZyc
 github.com/localtunnel/go-localtunnel v0.0.0-20170326223115-8a804488f275/go.mod h1:zt6UU74K6Z6oMOYJbJzYpYucqdcQwSMPBEdSvGiaUMw=
 github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
 github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/minio/crc64nvme v1.1.1 h1:8dwx/Pz49suywbO+auHCBpCtlW1OfpcLN7wYgVR6wAI=
+github.com/minio/crc64nvme v1.1.1/go.mod h1:eVfm2fAzLlxMdUGc0EEBGSMmPwmXD5XiNRpnu9J3bvg=
+github.com/minio/md5-simd v1.1.2 h1:Gdi1DZK69+ZVMoNHRXJyNcxrMA4dSxoYHZSQbirFg34=
+github.com/minio/md5-simd v1.1.2/go.mod h1:MzdKDxYpY2BT9XQFocsiZf/NKVtR7nkE4RoEpN+20RM=
+github.com/minio/minio-go/v7 v7.4.1 h1:PtU/zIOfQRWZ+QydXAZysc+xZYHdG+BBR4Z6TUvy73w=
+github.com/minio/minio-go/v7 v7.4.1/go.mod h1:nQnQi7zTfXR4lREtYXZQWqo5aw0Rqv+ZqCGrTORygRk=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -304,6 +317,8 @@ github.com/onsi/gomega v1.9.0/go.mod h1:Ho0h+IUsWyvy1OpqCwxlQ/21gkhVunqlU8fDGcoT
 github.com/opentracing/opentracing-go v1.1.0/go.mod h1:UkNAQd3GIcIGf0SeVgPpRdFStlNbqXla1AfSYxPUl2o=
 github.com/opentracing/opentracing-go v1.2.0 h1:uEJPy/1a5RIPAJ0Ov+OIO8OxWu77jEv+1B0VhjKrZUs=
 github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc=
+github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
+github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
 github.com/pierrec/lz4/v4 v4.1.15 h1:MO0/ucJhngq7299dKLwIMtgTfbkoSPF6AoMYDd8Q4q0=
 github.com/pierrec/lz4/v4 v4.1.15/go.mod h1:gZWDp/Ze/IJXGXf23ltt2EXimqmTUXEy0GFuRQyBid4=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
@@ -311,8 +326,6 @@ github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINE
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
-github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
@@ -326,13 +339,15 @@ github.com/redis/go-redis/v9 v9.12.1 h1:k5iquqv27aBtnTm2tIkROUDp8JBXhXZIVu1InSgv
 github.com/redis/go-redis/v9 v9.12.1/go.mod h1:huWgSWd8mW6+m0VPhJjSSQ+d6Nh1VICQ6Q5lHuCH/Iw=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
-github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
-github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWbZV6S5g=
+github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
+github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
 github.com/segmentio/kafka-go v0.4.49 h1:GJiNX1d/g+kG6ljyJEoi9++PUMdXGAxb7JGPiDCuNmk=
 github.com/segmentio/kafka-go v0.4.49/go.mod h1:Y1gn60kzLEEaW28YshXyk2+VCUKbJ3Qr6DrnT3i4+9E=
 github.com/sirupsen/logrus v1.0.6/go.mod h1:pMByvHTf9Beacp5x1UXfOR9xyW/9antXMhjMPG0dEzc=
-github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
-github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/sirupsen/logrus v1.10.2 h1:G2SED73/qrAu6YwbdxOD6peLkCBI3z7L+ykJFTXJBBo=
+github.com/sirupsen/logrus v1.10.2/go.mod h1:SLEg8TqYulVKKfIGHldVp2K2aYz2DKSVBq4g/H5bR7Q=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
 github.com/smartystreets/assertions v1.1.0/go.mod h1:tcbTF8ujkAEcZ8TElKY+i30BzYlVhC/LOxJk7iOWnoo=
 github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
@@ -341,20 +356,26 @@ github.com/spiffe/go-spiffe/v2 v2.8.1/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnO
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.2.0/go.mod h1:qt09Ya8vawLte6SNmTgCsAVtYtaKzEcn8ATUoHMkEqE=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
+github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/tinode/jsonco v1.0.0 h1:zVcpjzDvjuA1G+HLrckI5EiiRyq9jgV3x37OQl6e5FE=
 github.com/tinode/jsonco v1.0.0/go.mod h1:Bnavu3302Qfn2pILMNwASkelodgeew3IvDrbdzU84u8=
 github.com/tinode/snowflake v1.0.0 h1:YciQ9ZKn1TrnvpS8yZErt044XJaxWVtR9aMO9rOZVOE=
 github.com/tinode/snowflake v1.0.0/go.mod h1:5JiaCe3o7QdDeyRcAeZBGVghwRS+ygt2CF/hxmAoptQ=
+github.com/tinylib/msgp v1.6.4 h1:mOwYbyYDLPj35mkA2BjjYejgJk9BuHxDdvRnb6v2ZcQ=
+github.com/tinylib/msgp v1.6.4/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
 github.com/tjfoc/gmsm v1.3.2/go.mod h1:HaUcFuY0auTiaHB9MHFGCPx5IaLhTUd2atbCFBQXn9w=
 github.com/tjfoc/gmsm v1.4.1 h1:aMe1GlZb+0bLjn+cKTPEvvn9oUEBlJitaZiiBwsbgho=
 github.com/tjfoc/gmsm v1.4.1/go.mod h1:j4INPkHWMrhJb38G+J6W4Tw0AbuN8Thu3PbdVYhVcTE=
@@ -372,6 +393,10 @@ github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9de
 github.com/yuin/goldmark v1.1.30/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
+github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
 go.mongodb.org/mongo-driver v1.17.9 h1:IexDdCuuNJ3BHrELgBlyaH9p60JXAvdzWR128q+U5tU=
 go.mongodb.org/mongo-driver v1.17.9/go.mod h1:LlOhpH5NUEfhxcAwG0UEkMqwYcc4JU18gtCdGudk/tQ=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
@@ -400,6 +425,8 @@ go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
 go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20191219195013-becbf705a915/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
@@ -415,8 +442,8 @@ golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDf
 golang.org/x/crypto v0.21.0/go.mod h1:0BP7YvVV9gBbVKyeTG0Gyn+gZm94bibOW5BjDEYAOMs=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.24.0/go.mod h1:Z1PMYSOR5nyMcyAVAIQSKCDwalqy85Aqn1x3Ws4L5DM=
-golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
-golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
+golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
 golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
@@ -451,8 +478,8 @@ golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.23.0/go.mod h1:JKghWKKOSdJwpW2GEx0Ja7fmaKnMsbu+MWVZTokSYmg=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
 golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=
-golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
-golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/net v0.60.0 h1:79p50tfZlm0J9YfoDsSi639qSXNGVwEzOPLCxM2FsYU=
+golang.org/x/net v0.60.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
@@ -467,8 +494,8 @@ golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
 golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
-golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
-golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
 golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
@@ -492,8 +519,8 @@ golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.21.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
-golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
 golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
@@ -517,8 +544,8 @@ golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.16.0/go.mod h1:GhwF1Be+LQoKShO3cGOHzqOgRrGaYc9AvblQOmPVHnI=
-golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
-golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
+golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
+golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
 golang.org/x/time v0.0.0-20200416051211-89c76fbcd5d1/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
@@ -569,8 +596,8 @@ google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzi
 google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
-google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
-google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
+google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/airbrake/gobrake.v2 v2.0.9/go.mod h1:/h5ZAUhDkGaJfjzjKLSjv6zCL6O0LLBxU4K+aSYdM/U=
 gopkg.in/cenkalti/backoff.v2 v2.2.1 h1:eJ9UAg01/HIHG987TwxvnzK2MgxXq97YY6rYDpY9aII=
 gopkg.in/cenkalti/backoff.v2 v2.2.1/go.mod h1:S0QdOvT2AlerfSBkp0O+dk+bbIMaNbEmVk876gPCthU=
@@ -581,8 +608,9 @@ gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EV
 gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
 gopkg.in/gemnasium/logrus-airbrake-hook.v2 v2.1.2/go.mod h1:Xk6kEKp8OKb+X14hQBKWaSkCsqBpgog8nAV2xsGOxlo=
 gopkg.in/ini.v1 v1.56.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
-gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
 gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
+gopkg.in/ini.v1 v1.67.3 h1:iM9Lhz5MRSGhHVGGwCuzG9KO8PoirCXj/m/qTmOJJQw=
+gopkg.in/ini.v1 v1.67.3/go.mod h1:x/cyOwCgZqOkJoDIJ3c1KNHMo10+nLGAhh+kn3Zizss=
 gopkg.in/rethinkdb/rethinkdb-go.v6 v6.2.2 h1:tczPZjdz6soV2thcuq1IFOuNLrBUGonFyUXBbIWXWis=
 gopkg.in/rethinkdb/rethinkdb-go.v6 v6.2.2/go.mod h1:c7Wo0IjB7JL9B9Avv0UZKorYJCUhiergpj3u1WtGT1E=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
@@ -590,7 +618,6 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

loadtest/im-pressure/.gitignore

@@ -1,5 +1,6 @@
 /im-pressure
 /config.json
+/config.single-machine.json
 /config.local*.json
 /.env.test
 /manifest*.json

loadtest/im-pressure/MACHINE-B.md

@@ -8,37 +8,39 @@
 
 ## 当前 allrich 测试批次
 
-以下参数适用于 2026-09-27 正在执行的第一轮单聊压测：
+以下参数适用于 2026-09-27 的 2000 人群聊压测：
 
 | 参数 | 值 |
 |---|---|
 | Git 分支 | `dev` |
-| 最低提交 | `6d17154` |
+| 最低提交 | `ea8732e` |
 | 企业码 | `allrich` |
 | HTTP | `https://api.118im.com` |
 | WebSocket | `wss://api.118im.com/v0/channels` |
 | 机器 A 内网地址 | `192.168.1.135` |
 | Coordinator | `http://192.168.1.135:8090` |
-| Run ID | `p2p-20260927-01` |
-| 场景 | `p2p` |
-| 机器 A 状态 | `1000/1000 READY`，等待机器 B |
+| Run ID | `group2k-r1-20260927-01` |
+| 场景 | `group` |
+| 机器 A 状态 | 等待启动 coordinator 和 agent A |
 
 机器 A 已生成安全运行包：
 
 ```text
-/tmp/allrich-machine-b-runtime-p2p-20260927-01.zip
-SHA-256: 479f119e7d01e1829c7262cace282c72a5f53ad8e7f5128abc2ade75d046db64
+/tmp/group2k-r1-20260927-01.zip
+SHA-256: 21e65b19476e64348b9214322021d880b231de1f9c9f685ea43d0082103e9cd1
 ```
 
+运行包文件名固定为 `/tmp/<RUN_ID>.zip`。它包含被 Git 忽略的密钥和 Token，因此 `git pull` 不会下载该文件，必须从机器 A 的 `/tmp` 目录单独复制。
+
 运行包内只有三个运行时文件：`.env.test`、`config.json`、`manifest.json`。其中包含 API Key、测试账号密码、固定测试验证码和账号 Token，不进入 Git，必须通过受控内网传输。测试环境验证码为 `123456`，正式环境禁止使用固定验证码。
 
 因此，机器 B 只执行 `git pull` 后看不到这三个文件是正常现象。机器 B 需要从机器 A 单独复制运行包：
 
 ```bash
-scp youshunlai@192.168.1.135:/tmp/allrich-machine-b-runtime-p2p-20260927-01.zip /tmp/
+scp youshunlai@192.168.1.135:/tmp/group2k-r1-20260927-01.zip /tmp/
 
-shasum -a 256 /tmp/allrich-machine-b-runtime-p2p-20260927-01.zip
-# 必须输出：479f119e7d01e1829c7262cace282c72a5f53ad8e7f5128abc2ade75d046db64
+shasum -a 256 /tmp/group2k-r1-20260927-01.zip
+# 必须输出：21e65b19476e64348b9214322021d880b231de1f9c9f685ea43d0082103e9cd1
 ```
 
 如果机器 B 无法主动连接 A，也可以由机器 A 执行 `scp` 推送；目标机器的用户名和地址由 B 机提供。禁止通过 Git、公开网盘或无访问控制的 HTTP 服务传输该运行包。
@@ -76,7 +78,7 @@ ulimit -n 100000
 在机器 B 的仓库根目录执行：
 
 ```bash
-unzip -o /tmp/allrich-machine-b-runtime-p2p-20260927-01.zip \
+unzip -o /tmp/group2k-r1-20260927-01.zip \
   -d loadtest/im-pressure
 chmod 600 \
   loadtest/im-pressure/.env.test \
@@ -108,7 +110,7 @@ source loadtest/im-pressure/.env.test
 set +a
 
 export MACHINE_A_IP='192.168.1.135'
-export RUN_ID='p2p-20260927-01'
+export RUN_ID='group2k-r1-20260927-01'
 
 ./loadtest/im-pressure/im-pressure verify \
   -config loadtest/im-pressure/config.json \
@@ -144,9 +146,10 @@ mkdir -p "loadtest/im-pressure/results/${RUN_ID}"
 1. 机器 B 建立 1000 条 WebSocket 连接并订阅对应 P2P Topic 和群 Topic。
 2. agent 向机器 A coordinator 报告 READY。
 3. 如果机器 A 尚未 READY，当前命令会等待，这是正常现象。
-4. coordinator 下发 `run_id`、场景和统一 UTC 开始时间。
-5. agent 完成发送、WS 到达统计、drain 和历史持久化回查。
-6. agent 写出 summary、上报 coordinator，然后正常退出。
+4. 等待期间连接断开会自动重连并重新订阅；在 A/B 都实时保持 1000 条连接并完成最终屏障前，agent 不会退出或开始发压。
+5. coordinator 下发 `run_id`、场景和统一 UTC 开始时间。
+6. agent 完成发送和 WS 到达统计后，先向协调器提交未 ACK 但已观测的消息台账；等待 `history_settle`（默认 5 分钟）后，以同 Topic 串行、不同 Topic 并行的限速分页方式执行历史持久化回查。等待期间不要停止进程。
+7. 两机历史回查完成后会通过 coordinator 汇总命中消息，B 也会据此计算 `realtime_lost_but_persisted`；随后 agent 在默认 10 秒窗口内渐进关闭连接、写出 summary 并正常退出。
 
 机器 B 不需要传场景参数。`p2p`、`group` 或 `mixed` 由机器 A coordinator 决定。
 

loadtest/im-pressure/README.md

@@ -2,6 +2,9 @@
 
 该工具按配置指定的企业租户运行：两台压测机各承载 1000 个 WebSocket 用户，共 2000 个用户、1000 对好友和一个 2000 人群。当前测试环境使用 `allrich`，本轮实时参数见 [MACHINE-B.md](./MACHINE-B.md) 和 [allrich 双机压测执行记录](../../docs/test/IM-allrich双机压测执行记录-20260927.md)。
 
+只使用一台物理压测机时，请使用 [单机 60% 容量压测方案](../../docs/test/IM-单机60%容量压力测试方案.md) 和 [config.single-machine.example.json](./config.single-machine.example.json)。单机依然运行 A/B 两个逻辑 agent，用于保留好友对、跨逻辑分片投递和合并报告的完整契约。
+首轮实测数据与瓶颈分析见 [单机 60% 容量压测结果](../../docs/test/IM-单机60%容量压力测试结果-20260929.md)。
+
 机器 B 上的 AI 或操作人请直接阅读 [MACHINE-B.md](./MACHINE-B.md)。该文件不重复讲方案，只给出机器 B 从核验到启动、观察和回传结果的完整命令。
 
 ## 两台机器的固定分工
@@ -40,17 +43,24 @@
 - 如果由机器 A 集中采集 agent 指标，机器 A 必须能访问 `http://机器B内网IP:9105/metrics`。
 - 两台机器都必须能访问配置中的 HTTP API 和各自的 WS 地址。
 - `8090` 是无鉴权的压测协调端口，只允许压测内网访问，不要暴露到公网。
-- 两台机器必须使用 NTP/chrony 同步时间；端到端延迟依赖两边时钟一致。
+- 两台机器必须使用 NTP/chrony 同步时间。报告会分别输出同机时钟延迟和跨机器单向延迟；跨机器出现负延迟样本时，后者仅用于诊断，不参与门禁。
+- agent 默认每 20 秒发送 WebSocket Ping，覆盖等待另一台机器、发压、drain 和历史核验阶段；`ws_ping_interval` 必须小于公网入口的空闲连接超时。
+- 正式开始前 agent 会持续检查实际存活连接；连接断开后自动重新登录并订阅 P2P、群 Topic。初次连接不齐或等待另一台机器期间掉线不会退出。
+- coordinator 使用三阶段屏障：两边实时连接数都达到配置值后进入验证倒计时；倒计时内任一方掉线就撤销屏障；提交最终开始时间后，两边必须在该时间前后 3 秒内再次到达起跑屏障，且双方都到达后才允许发送。任一方迟到会让两边共同终止本轮，避免生成错时压测结果。
+- 压测机如保持 OpenVPN 等全局 TUN，仅在另一套代理中设置 `DIRECT` 无法绕过它。起压前必须确认 `http_base` 和 WS 域名的每个当前 IP 都走物理网卡；需保留 VPN 访问内网时，可为这些 IP 配置经局域网关的 `/32` 主机路由。VPN 重连、DNS 变更或机器重启后需重新核验。
 
 ## 统计口径
 
 - 发送成功以 `{ctrl code=2xx, params.seq>0}` 为准，形成两台机器共享的 ACK 台账。
 - 实时到达只统计同时匹配本轮 `run_id` 和 `x-im-client-mid` 的 `{data}`。
 - 群消息设置 `noecho=false`，每条服务端接受的群消息期望 2000 个连接各收到一次。
-- 实时 drain 结束后通过 `{get what=data}` 按 ACK 的 Topic/Seq 回查历史，区分跨 Pod 实时漏投与数据库持久化缺失。
+- 实时 drain 结束后，两机先汇总 ACK 台账和“已实时观测但未收到 ACK”的消息台账；等待 `history_settle`（默认 5 分钟）让 Kafka 自然排空，再通过 `{get what=data}` 按 Topic/Seq 回查两类消息。
 - 每轮建立 WS 后、正式计时前，以 32 个 worker 对本机 1000 个账号做好友关系、P2P Topic 和发布权限预检；任一异常会终止本轮。
-- 历史回查默认使用 48 个 worker、总超时 3 分钟，并对缺失项再并发重试两轮。
-- publish 错误完整分类为 `403`、`502`、`503`、`ctrl_timeout`、`socket_error` 和 `other`，不受文本错误样本上限影响。
+- 历史回查默认每机最多使用 12 个 worker、每页 10 条、同一 Topic 两页之间至少间隔 500ms，并在每页请求后等待目标消息全部返回（最长 3 秒）再继续。同一 Topic 严格串行，不同 Topic 才并行；因此群聊只会有 1 个活跃回查 worker，单聊可并行核验不同 Topic。总超时默认 3 分钟，并在超时内持续重试缺失区间。该限速用于避免正确性核验本身制造 Topic/Proxy 洪峰；历史读取吞吐应使用独立场景测试。
+- agent 完成后默认在 10 秒内均匀关闭本机 WebSocket，避免 1000 个群订阅同时离线冲击 Topic 队列。两机退出时间可能相差数秒，协调器完成以两份 summary 都已提交为准。
+- publish 错误完整分类为 `403`、`502`、`503`、`ctrl_timeout`、`socket_error` 和 `other`。`publish_rejected` 只统计明确拒绝，超时和 socket 错误单独计入 `publish_outcome_unknown`。
+- `delivery_local_p95_ms` 使用发送方本机收到 echo 的同机时钟样本，是投递延迟门禁口径；兼容字段 `delivery_p95_ms` 与它保持一致。
+- `delivery_cross_machine_p95_ms` 是跨机器单向观测值，只有两机时钟同步达标时才有意义；`cross_machine_negative_latency_samples > 0` 明确表示存在时钟偏差。
 - `manifest.json` 含登录 token，文件权限为 `0600`，不得提交到 Git 或放入结果包。
 
 ## 两台机器初始化
@@ -187,8 +197,13 @@ mkdir -p "loadtest/im-pressure/results/${RUN_ID}"
 两个 agent 都建立 1000 条连接后，协调器下发统一的 UTC `start_at`。场景可替换为：
 
 - `p2p`：1000 对用户两侧同时发送，默认每人 10 条、间隔 1 秒。
-- `group`：每台机器 500 个发送者，每人 2 条；全局每 100ms 一条，共 2000 条。
-- `mixed`：300 对私聊用户每人 5 条，同时每台 250 个群发送者各发 2 条。
+- `group`：默认每个 agent 有 `group_senders_per_machine` 个发送者，每人 `group_rounds` 条；两机合并后按 `group_publish_interval` 控制全局发送间隔。双机默认 500+500 发送者、100ms 一条，共 2000 条；单机 60% 默认 300+300 发送者。
+- `mixed`：默认使用 `mixed_p2p_users_per_machine` 对私聊用户和 `mixed_group_senders_per_machine` 个群发送者。双机默认每机 300 个私聊用户、250 个群发送者；单机 60% 默认每机 180 个私聊用户、150 个群发送者。
+- `idle`：只建立并维持 WS 连接，不发送业务消息，持续 `idle_duration`。该场景用于先确认 2000 长连接在入口、Pod、DNS、心跳和自动重连下是否稳定。
+
+群聊容量阶梯建议只改 `group_publish_interval`，保持发送者和轮数不变：`125ms` 约等于 8 msg/s，`100ms` 约等于 10 msg/s，`83ms` 约等于 12 msg/s，`67ms` 约等于 15 msg/s，`56ms` 约等于 18 msg/s。先跑 `idle`，再从低速 `group` 逐级上探；某一级出现连接波动、ACK 长尾或 DB pool wait 明显上升时，重复该级确认后再进入下一档。
+
+自动重连由 `reconnect_workers`、`reconnect_min_wait`、`reconnect_max_wait` 控制。断线账号会按指数退避并附带确定性抖动后重连，避免两台压测机在入口抖动时同时打出登录洪峰。
 
 ## 机器 A：回收并合并报告
 
@@ -208,7 +223,7 @@ scp "${MACHINE_B_SSH}:${MACHINE_B_REPO}/loadtest/im-pressure/results/${RUN_ID}/a
   -output "loadtest/im-pressure/results/${RUN_ID}/report.json"
 ```
 
-`report.json` 给出 ACK、实时投递、重复、乱序、断连和历史持久化核验结果。当前正确性门禁要求上述错误计数全部为 0。
+`report.json` 给出 ACK、实时投递、重复、乱序、断连和历史持久化核验结果。断连会额外输出 `disconnect_reasons` 分类计数和最多 100 条 `disconnect_samples` 原始错误样本。当前正确性门禁要求上述错误计数全部为 0。
 
 每个 agent 在 `:9105/metrics` 暴露连接、发送、接收、重复、乱序、断连以及 Go/process 指标；端口冲突时可通过 `-metrics-listen` 修改，传空字符串可关闭。
 

loadtest/im-pressure/agent_history_test.go

@@ -1,11 +1,16 @@
 package main
 
-import "testing"
+import (
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+)
 
 func TestHistoryQueriesForMessagesGroupsRangesByTopic(t *testing.T) {
 	p2pClient := &WSClient{}
 	groupClient := &WSClient{}
-	run := &agentRun{clients: map[int]*WSClient{1: groupClient, 7: p2pClient}}
+	run := &agentRun{cfg: &Config{HistoryPageSize: 200}, clients: map[int]*WSClient{1: groupClient, 7: p2pClient}}
 	messages := make([]AcceptedMessage, 0, 207)
 	for seq := int64(205); seq >= 1; seq-- {
 		messages = append(messages, AcceptedMessage{Kind: "p2p", Topic: "p2p-a", PeerIndex: 7, Seq: seq})
@@ -25,7 +30,7 @@ func TestHistoryQueriesForMessagesGroupsRangesByTopic(t *testing.T) {
 		switch query.topic {
 		case "p2p-a":
 			p2pQueries++
-			if query.client != p2pClient || query.limit != 256 {
+			if query.client != p2pClient || query.limit != 200 || len(query.expected) == 0 {
 				t.Fatalf("unexpected p2p query: %#v", query)
 			}
 		case "grp-a":
@@ -39,3 +44,99 @@ func TestHistoryQueriesForMessagesGroupsRangesByTopic(t *testing.T) {
 		t.Fatalf("p2p queries=%d group queries=%d", p2pQueries, groupQueries)
 	}
 }
+
+func TestClassifyPublishErrorTreatsClosedConnectionAsUnknownSocketError(t *testing.T) {
+	run := &agentRun{}
+	run.classifyPublishError(errors.New("write tcp: use of closed network connection"))
+	if run.publishSocket.Load() != 1 || run.publishOther.Load() != 0 {
+		t.Fatalf("socket=%d other=%d", run.publishSocket.Load(), run.publishOther.Load())
+	}
+}
+
+func TestScenarioUsersScaleWithConfiguredCapacity(t *testing.T) {
+	tests := []struct {
+		users      int
+		group      int
+		mixedP2P   int
+		mixedGroup int
+	}{
+		{users: 1000, group: 500, mixedP2P: 300, mixedGroup: 250},
+		{users: 600, group: 300, mixedP2P: 180, mixedGroup: 150},
+	}
+	for _, tc := range tests {
+		if got := scaledUsers(tc.users, 1, 2); got != tc.group {
+			t.Fatalf("users=%d group=%d want=%d", tc.users, got, tc.group)
+		}
+		if got := scaledUsers(tc.users, 3, 10); got != tc.mixedP2P {
+			t.Fatalf("users=%d mixed p2p=%d want=%d", tc.users, got, tc.mixedP2P)
+		}
+		if got := scaledUsers(tc.users, 1, 4); got != tc.mixedGroup {
+			t.Fatalf("users=%d mixed group=%d want=%d", tc.users, got, tc.mixedGroup)
+		}
+	}
+}
+
+func TestReconnectBackoffCapsAndJitters(t *testing.T) {
+	minWait := 2 * time.Second
+	maxWait := 30 * time.Second
+	first := reconnectBackoff(minWait, maxWait, 1, 10)
+	if first < minWait || first >= minWait+minWait/4 {
+		t.Fatalf("first backoff=%s outside expected jitter range", first)
+	}
+	capped := reconnectBackoff(minWait, maxWait, 10, 10)
+	if capped < maxWait || capped >= maxWait+maxWait/4 {
+		t.Fatalf("capped backoff=%s outside expected jitter range", capped)
+	}
+	if reconnectBackoff(minWait, maxWait, 3, 10) == reconnectBackoff(minWait, maxWait, 3, 11) {
+		t.Fatal("different account indexes should receive different jitter")
+	}
+}
+
+func TestValidScenarioIncludesIdle(t *testing.T) {
+	for _, scenario := range []string{"p2p", "group", "mixed", "idle"} {
+		if !validScenario(scenario) {
+			t.Fatalf("scenario %s should be valid", scenario)
+		}
+	}
+	if validScenario("unknown") {
+		t.Fatal("unknown scenario should be rejected")
+	}
+}
+
+func TestNewHistoryQueryIncludesInterleavedSequenceRange(t *testing.T) {
+	messages := make([]AcceptedMessage, 10)
+	for i := range messages {
+		messages[i] = AcceptedMessage{ClientMid: fmt.Sprintf("mid-%d", i), Seq: int64(100 + i*2)}
+	}
+	query := newHistoryQuery(nil, "p2p-one", messages, 10)
+	if query.since != 100 || query.before != 119 || query.limit != 19 {
+		t.Fatalf("history query range=%d-%d limit=%d want=100-119/19", query.since, query.before, query.limit)
+	}
+}
+
+func TestMergeMessageLedgersPrefersPeerObservationAndAck(t *testing.T) {
+	senderEcho := AcceptedMessage{ClientMid: "mid-1", SenderMachine: "a", PeerMachine: "a", Seq: 10}
+	peerDelivery := AcceptedMessage{ClientMid: "mid-1", SenderMachine: "a", PeerMachine: "b", PeerIndex: 7, Seq: 10}
+	merged := mergeMessageLedgers(nil, []AcceptedMessage{senderEcho, peerDelivery})
+	if len(merged) != 1 || merged[0].PeerMachine != "b" || merged[0].PeerIndex != 7 {
+		t.Fatalf("peer observation was not preferred: %+v", merged)
+	}
+	ack := AcceptedMessage{ClientMid: "mid-1", SenderMachine: "a", PeerMachine: "b", PeerIndex: 7, Seq: 10,
+		Scenario: "p2p"}
+	merged = mergeMessageLedgers([]AcceptedMessage{ack}, []AcceptedMessage{peerDelivery})
+	if len(merged) != 1 || merged[0].Scenario != "p2p" {
+		t.Fatalf("ACK ledger was not authoritative: %+v", merged)
+	}
+}
+
+func TestCloseScheduleInterleavesLogicalAgents(t *testing.T) {
+	cfg := &Config{CloseRamp: "60s"}
+	intervalA, delayA := closeSchedule(cfg, "a", 601)
+	intervalB, delayB := closeSchedule(cfg, "b", 601)
+	if intervalA != 200*time.Millisecond || intervalB != intervalA {
+		t.Fatalf("intervals: a=%s b=%s, want 200ms", intervalA, intervalB)
+	}
+	if delayA != 0 || delayB != 100*time.Millisecond {
+		t.Fatalf("delays: a=%s b=%s, want 0/100ms", delayA, delayB)
+	}
+}

loadtest/im-pressure/agent_metrics.go

@@ -26,7 +26,7 @@ func startAgentMetrics(address string, run *agentRun) (func(), error) {
 		collectors.NewGoCollector(),
 		collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
 		prometheus.NewGaugeFunc(prometheus.GaugeOpts{Name: "im_load_agent_ready_connections", Help: "Current ready WebSocket connections.", ConstLabels: labels}, func() float64 {
-			return float64(run.ready.Load())
+			return float64(run.aliveConnections())
 		}),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_attempted_total", Help: "Publish commands attempted.", ConstLabels: labels}, func() float64 {
 			return float64(run.attempted.Load())
@@ -36,13 +36,20 @@ func startAgentMetrics(address string, run *agentRun) (func(), error) {
 			defer run.mu.Unlock()
 			return float64(len(run.accepted))
 		}),
-		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_rejected_total", Help: "Publish commands rejected or timed out.", ConstLabels: labels}, func() float64 {
-			return float64(run.rejected.Load())
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_rejected_total", Help: "Publish commands explicitly rejected by the server.", ConstLabels: labels}, func() float64 {
+			return float64(run.explicitRejected())
+		}),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_outcome_unknown_total", Help: "Publish commands with ACK timeout or socket failure and therefore unknown outcome.", ConstLabels: labels}, func() float64 {
+			return float64(run.outcomeUnknown())
 		}),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_403_total", Help: "Publish commands rejected with 403.", ConstLabels: labels}, func() float64 { return float64(run.publish403.Load()) }),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_502_total", Help: "Publish commands rejected with 502.", ConstLabels: labels}, func() float64 { return float64(run.publish502.Load()) }),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_503_total", Help: "Publish commands rejected with 503.", ConstLabels: labels}, func() float64 { return float64(run.publish503.Load()) }),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_ctrl_timeout_total", Help: "Publish commands with control-response timeout.", ConstLabels: labels}, func() float64 { return float64(run.publishTimeout.Load()) }),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_ctrl_observed_total", Help: "Publish control responses observed, including responses received after command timeout.", ConstLabels: labels}, func() float64 { return float64(run.publishCtrlObserved.Load()) }),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_ctrl_over_20s_total", Help: "Publish control responses taking longer than 20 seconds.", ConstLabels: labels}, func() float64 { return float64(run.publishCtrlOver20.Load()) }),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_ctrl_late_total", Help: "Publish control responses received after command timeout.", ConstLabels: labels}, func() float64 { return float64(run.publishLateCtrl.Load()) }),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{Name: "im_load_agent_publish_ctrl_unresolved", Help: "Publish control responses still unresolved after accounting for late responses.", ConstLabels: labels}, func() float64 { return float64(run.unresolvedCtrl()) }),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_publish_socket_error_total", Help: "Publish commands with socket errors.", ConstLabels: labels}, func() float64 { return float64(run.publishSocket.Load()) }),
 		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_received_total", Help: "Unique matching data deliveries received.", ConstLabels: labels}, func() float64 {
 			received, _, _, _ := run.recorder.metricCounts()
@@ -60,6 +67,27 @@ func startAgentMetrics(address string, run *agentRun) (func(), error) {
 			_, _, _, disconnects := run.recorder.metricCounts()
 			return float64(disconnects)
 		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{Name: "im_load_agent_callback_queue_current", Help: "Data callbacks currently waiting to start.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.current.Load())
+		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{Name: "im_load_agent_callback_queue_max", Help: "Peak data callbacks waiting to start.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.maximum.Load())
+		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{Name: "im_load_agent_callback_processing", Help: "Data callbacks currently processing.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.processing.Load())
+		}),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_callback_queue_enqueued_total", Help: "Data callbacks enqueued.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.enqueued.Load())
+		}),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_callback_queue_completed_total", Help: "Data callbacks which completed processing.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.completed.Load())
+		}),
+		prometheus.NewCounterFunc(prometheus.CounterOpts{Name: "im_load_agent_callback_queue_wait_seconds_total", Help: "Cumulative time spent waiting to start data callbacks.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.waitNanos.Load()) / float64(time.Second)
+		}),
+		prometheus.NewGaugeFunc(prometheus.GaugeOpts{Name: "im_load_agent_callback_queue_wait_seconds_max", Help: "Maximum time spent waiting to start a data callback.", ConstLabels: labels}, func() float64 {
+			return float64(run.callbackQueue.maxWait.Load()) / float64(time.Second)
+		}),
 	)
 	mux := http.NewServeMux()
 	mux.Handle("/metrics", promhttp.HandlerFor(registry, promhttp.HandlerOpts{}))

loadtest/im-pressure/agent_reconnect_test.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+func TestMaintainConnectionsRestoresClosedClient(t *testing.T) {
+	var connections atomic.Int64
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err != nil {
+			return
+		}
+		connections.Add(1)
+		defer conn.Close()
+		for {
+			var packet map[string]json.RawMessage
+			if err = conn.ReadJSON(&packet); err != nil {
+				return
+			}
+			for _, raw := range packet {
+				var body struct {
+					ID string `json:"id"`
+				}
+				if json.Unmarshal(raw, &body) != nil || body.ID == "" {
+					continue
+				}
+				response := map[string]any{"ctrl": map[string]any{
+					"id": body.ID, "code": 200, "text": "ok",
+					"params": map[string]any{"user": "usrReconnectTest"},
+				}}
+				if err = conn.WriteJSON(response); err != nil {
+					return
+				}
+			}
+		}
+	}))
+	defer server.Close()
+
+	account := AccountRecord{
+		Machine: "a", Index: 1, Username: "lta0001", Token: "token",
+		P2PTopic: "p2pReconnectTest", Endpoint: "ws" + strings.TrimPrefix(server.URL, "http"),
+	}
+	cfg := &Config{Tenant: "allrich", CommandTimeout: "1s", WSPingInterval: "1h"}
+	run := &agentRun{
+		cfg: cfg, machine: "a", clients: make(map[int]*WSClient),
+		recorder: newDeliveryRecorder("pending", "a", 1), ack: NewDurationHistogram(),
+	}
+	initial, err := run.connectAccountWithRetry(context.Background(), account, "grpReconnectTest", "api-key", "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	run.setClient(account.Index, initial)
+	initial.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	done := make(chan struct{})
+	go func() {
+		run.maintainConnections(ctx, []AccountRecord{account}, "grpReconnectTest", "api-key", "")
+		close(done)
+	}()
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if replacement := run.client(account.Index); replacement != initial && replacement.alive() {
+			cancel()
+			<-done
+			run.close()
+			if got := connections.Load(); got < 2 {
+				t.Fatalf("websocket connections = %d, want at least 2", got)
+			}
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	cancel()
+	<-done
+	run.close()
+	t.Fatal("closed client was not restored before deadline")
+}

loadtest/im-pressure/callback_queue.go

@@ -0,0 +1,70 @@
+package main
+
+import (
+	"sync/atomic"
+	"time"
+)
+
+type callbackQueueMetrics struct {
+	current    atomic.Int64
+	processing atomic.Int64
+	maximum    atomic.Int64
+	enqueued   atomic.Int64
+	completed  atomic.Int64
+	waitNanos  atomic.Int64
+	maxWait    atomic.Int64
+}
+
+func (m *callbackQueueMetrics) enqueue() {
+	if m == nil {
+		return
+	}
+	current := m.current.Add(1)
+	m.enqueued.Add(1)
+	updateAtomicMax(&m.maximum, current)
+}
+
+func (m *callbackQueueMetrics) startCallback(queuedAt time.Time) {
+	if m == nil {
+		return
+	}
+	wait := time.Since(queuedAt).Nanoseconds()
+	if wait < 0 {
+		wait = 0
+	}
+	m.current.Add(-1)
+	m.processing.Add(1)
+	m.waitNanos.Add(wait)
+	updateAtomicMax(&m.maxWait, wait)
+}
+
+func (m *callbackQueueMetrics) finishCallback() {
+	if m == nil {
+		return
+	}
+	m.processing.Add(-1)
+	m.completed.Add(1)
+}
+
+func (m *callbackQueueMetrics) snapshot() CallbackQueueSnapshot {
+	if m == nil {
+		return CallbackQueueSnapshot{}
+	}
+	return CallbackQueueSnapshot{
+		Current: m.current.Load(), Processing: m.processing.Load(), Maximum: m.maximum.Load(), Enqueued: m.enqueued.Load(),
+		Completed: m.completed.Load(), WaitSecondsTotal: float64(m.waitNanos.Load()) / float64(time.Second),
+		WaitSecondsMax: float64(m.maxWait.Load()) / float64(time.Second),
+	}
+}
+
+func (m *callbackQueueMetrics) isDrained() bool {
+	return m == nil || (m.current.Load() == 0 && m.processing.Load() == 0)
+}
+
+func updateAtomicMax(target *atomic.Int64, value int64) {
+	for current := target.Load(); value > current; current = target.Load() {
+		if target.CompareAndSwap(current, value) {
+			return
+		}
+	}
+}

loadtest/im-pressure/callback_queue_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestCallbackQueueMetricsTrackWaitingAndProcessing(t *testing.T) {
+	metrics := &callbackQueueMetrics{}
+	metrics.enqueue()
+	metrics.enqueue()
+	metrics.startCallback(time.Now().Add(-10 * time.Millisecond))
+
+	snapshot := metrics.snapshot()
+	if snapshot.Current != 1 || snapshot.Processing != 1 || snapshot.Maximum != 2 || snapshot.Enqueued != 2 {
+		t.Fatalf("unexpected active queue snapshot: %+v", snapshot)
+	}
+	if snapshot.WaitSecondsTotal <= 0 || snapshot.WaitSecondsMax <= 0 || metrics.isDrained() {
+		t.Fatalf("wait or drain state not tracked: %+v", snapshot)
+	}
+
+	metrics.finishCallback()
+	metrics.startCallback(time.Now())
+	metrics.finishCallback()
+	if snapshot = metrics.snapshot(); snapshot.Current != 0 || snapshot.Processing != 0 || snapshot.Completed != 2 || !metrics.isDrained() {
+		t.Fatalf("unexpected drained queue snapshot: %+v", snapshot)
+	}
+}
+
+func TestWaitForCallbackQueueWaitsForProcessingCallback(t *testing.T) {
+	metrics := &callbackQueueMetrics{}
+	metrics.enqueue()
+	metrics.startCallback(time.Now())
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		metrics.finishCallback()
+	}()
+
+	started := time.Now()
+	if err := waitForCallbackQueue(context.Background(), metrics, time.Second); err != nil {
+		t.Fatal(err)
+	}
+	if time.Since(started) < 15*time.Millisecond {
+		t.Fatal("wait returned before the callback finished")
+	}
+}
+
+func TestWaitForDeliveryQuiescenceResetsForLateDelivery(t *testing.T) {
+	recorder := newDeliveryRecorder("run", "a", 1)
+	queue := &callbackQueueMetrics{}
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		recorder.received.Add(1)
+	}()
+
+	started := time.Now()
+	if err := waitForDeliveryQuiescence(context.Background(), recorder, queue, 150*time.Millisecond, time.Second); err != nil {
+		t.Fatal(err)
+	}
+	if elapsed := time.Since(started); elapsed < 250*time.Millisecond {
+		t.Fatalf("quiet period was not reset after late delivery: elapsed=%s", elapsed)
+	}
+}

loadtest/im-pressure/config.example.json

@@ -13,13 +13,30 @@
   "insecure_tls": false,
   "prepare_workers": 20,
   "connect_ramp": "20s",
+  "reconnect_workers": 8,
+  "reconnect_min_wait": "2s",
+  "reconnect_max_wait": "30s",
   "command_timeout": "20s",
+  "ws_ping_interval": "20s",
   "preflight_workers": 32,
   "skip_p2p_preflight": false,
-  "history_workers": 48,
+  "history_workers": 12,
+  "history_page_size": 10,
+  "history_query_interval": "500ms",
+  "history_page_wait": "3s",
+  "history_settle": "5m",
   "history_timeout": "3m",
+  "close_ramp": "10s",
   "p2p_messages_per_user": 10,
   "p2p_interval": "1s",
+  "group_senders_per_machine": 500,
+  "group_rounds": 2,
+  "group_publish_interval": "100ms",
+  "mixed_p2p_users_per_machine": 300,
+  "mixed_group_senders_per_machine": 250,
+  "idle_duration": "15m",
   "drain_p2p": "30s",
-  "drain_group": "60s"
+  "drain_group": "60s",
+  "delivery_quiet_period": "10s",
+  "delivery_quiet_timeout": "3m"
 }

loadtest/im-pressure/config.single-machine.example.json

@@ -0,0 +1,46 @@
+{
+  "tenant": "006",
+  "http_base": "https://im-api.example.com",
+  "api_key_env": "IM_API_KEY",
+  "password_env": "IM_LOAD_PASSWORD",
+  "verification_code_env": "IM_VERIFICATION_CODE",
+  "registration_phone_prefix": "",
+  "users_per_machine": 600,
+  "endpoints": {
+    "a": ["wss://im-api.example.com/v0/channels"],
+    "b": ["wss://im-api.example.com/v0/channels"]
+  },
+  "dial_ips": {
+    "a": [],
+    "b": []
+  },
+  "insecure_tls": false,
+  "prepare_workers": 20,
+  "connect_ramp": "30s",
+  "reconnect_workers": 8,
+  "reconnect_min_wait": "2s",
+  "reconnect_max_wait": "30s",
+  "command_timeout": "90s",
+  "ws_ping_interval": "20s",
+  "preflight_workers": 32,
+  "skip_p2p_preflight": false,
+  "history_workers": 12,
+  "history_page_size": 10,
+  "history_query_interval": "500ms",
+  "history_page_wait": "3s",
+  "history_settle": "5m",
+  "history_timeout": "3m",
+  "close_ramp": "60s",
+  "p2p_messages_per_user": 10,
+  "p2p_interval": "1s",
+  "group_senders_per_machine": 300,
+  "group_rounds": 2,
+  "group_publish_interval": "100ms",
+  "mixed_p2p_users_per_machine": 180,
+  "mixed_group_senders_per_machine": 150,
+  "idle_duration": "15m",
+  "drain_p2p": "30s",
+  "drain_group": "60s",
+  "delivery_quiet_period": "10s",
+  "delivery_quiet_timeout": "3m"
+}

loadtest/im-pressure/coordinator.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"log"
@@ -16,23 +17,46 @@ import (
 )
 
 type StartInfo struct {
-	RunID    string    `json:"run_id"`
-	Scenario string    `json:"scenario"`
-	StartAt  time.Time `json:"start_at"`
+	RunID     string    `json:"run_id"`
+	Scenario  string    `json:"scenario"`
+	StartAt   time.Time `json:"start_at"`
+	Committed bool      `json:"committed"`
 }
 
 type AgentReady struct {
-	Machine          string `json:"machine"`
-	ReadyConnections int    `json:"ready_connections"`
+	Machine             string `json:"machine"`
+	ReadyConnections    int    `json:"ready_connections"`
+	ExpectedConnections int    `json:"expected_connections"`
+	Armed               bool   `json:"armed"`
 }
 
+type AgentStarted struct {
+	Machine     string    `json:"machine"`
+	ScheduledAt time.Time `json:"scheduled_at"`
+}
+
+type StartGate struct {
+	Proceed        bool   `json:"proceed"`
+	Error          string `json:"error,omitempty"`
+	ArrivedAgents  int    `json:"arrived_agents"`
+	ExpectedAgents int    `json:"expected_agents"`
+}
+
+const maxAgentStartSkew = 3 * time.Second
+
 type coordinatorState struct {
 	mu             sync.Mutex
 	start          StartInfo
 	startDelay     time.Duration
+	commitDelay    time.Duration
 	expectedAgents int
 	ready          map[string]AgentReady
+	armed          map[string]bool
+	started        map[string]time.Time
+	startError     string
 	ledgers        map[string][]AcceptedMessage
+	observed       map[string][]AcceptedMessage
+	history        map[string][]string
 	summaries      map[string]AgentSummary
 	complete       chan struct{}
 	completeOnce   sync.Once
@@ -49,14 +73,20 @@ func runCoordinator(ctx context.Context, listen, runID, scenario, output string,
 		expectedAgents = 2
 	}
 	state := &coordinatorState{
-		start: StartInfo{RunID: runID, Scenario: scenario}, startDelay: startDelay, expectedAgents: expectedAgents,
-		ready: make(map[string]AgentReady), ledgers: make(map[string][]AcceptedMessage),
+		start: StartInfo{RunID: runID, Scenario: scenario}, startDelay: startDelay, commitDelay: 5 * time.Second,
+		expectedAgents: expectedAgents,
+		ready:          make(map[string]AgentReady), ledgers: make(map[string][]AcceptedMessage),
+		observed: make(map[string][]AcceptedMessage), history: make(map[string][]string),
+		armed: make(map[string]bool), started: make(map[string]time.Time),
 		summaries: make(map[string]AgentSummary), complete: make(chan struct{}),
 	}
 	mux := http.NewServeMux()
 	mux.HandleFunc("/v1/ready", state.handleReady)
 	mux.HandleFunc("/v1/start", state.handleStart)
+	mux.HandleFunc("/v1/started", state.handleStarted)
 	mux.HandleFunc("/v1/ledger", state.handleLedger)
+	mux.HandleFunc("/v1/observed", state.handleObserved)
+	mux.HandleFunc("/v1/history", state.handleHistory)
 	mux.HandleFunc("/v1/summary", state.handleSummary)
 	mux.HandleFunc("/v1/status", state.handleStatus)
 	server := &http.Server{Addr: listen, Handler: mux, ReadHeaderTimeout: 5 * time.Second}
@@ -85,29 +115,185 @@ func runCoordinator(ctx context.Context, listen, runID, scenario, output string,
 	return nil
 }
 
+func (s *coordinatorState) handleHistory(w http.ResponseWriter, r *http.Request) {
+	machine := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("machine")))
+	switch r.Method {
+	case http.MethodPost:
+		if machine != "a" && machine != "b" {
+			http.Error(w, "invalid machine", http.StatusBadRequest)
+			return
+		}
+		var messageIDs []string
+		if !decodeLimitedJSON(w, r, &messageIDs) {
+			return
+		}
+		s.mu.Lock()
+		if s.history == nil {
+			s.history = make(map[string][]string)
+		}
+		s.history[machine] = messageIDs
+		count := len(s.history)
+		s.mu.Unlock()
+		writeJSON(w, http.StatusOK, map[string]int{"submitted_agents": count})
+	case http.MethodGet:
+		s.mu.Lock()
+		defer s.mu.Unlock()
+		if len(s.history) < s.expectedAgents {
+			writeJSON(w, http.StatusAccepted, map[string]int{"submitted_agents": len(s.history), "expected_agents": s.expectedAgents})
+			return
+		}
+		unique := make(map[string]bool)
+		for _, messageIDs := range s.history {
+			for _, mid := range messageIDs {
+				if mid != "" {
+					unique[mid] = true
+				}
+			}
+		}
+		merged := make([]string, 0, len(unique))
+		for mid := range unique {
+			merged = append(merged, mid)
+		}
+		sort.Strings(merged)
+		writeJSON(w, http.StatusOK, merged)
+	default:
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+	}
+}
+
+func (s *coordinatorState) handleObserved(w http.ResponseWriter, r *http.Request) {
+	machine := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("machine")))
+	switch r.Method {
+	case http.MethodPost:
+		if machine != "a" && machine != "b" {
+			http.Error(w, "invalid machine", http.StatusBadRequest)
+			return
+		}
+		var messages []AcceptedMessage
+		if !decodeLimitedJSON(w, r, &messages) {
+			return
+		}
+		s.mu.Lock()
+		if s.observed == nil {
+			s.observed = make(map[string][]AcceptedMessage)
+		}
+		s.observed[machine] = messages
+		count := len(s.observed)
+		s.mu.Unlock()
+		writeJSON(w, http.StatusOK, map[string]int{"submitted_agents": count})
+	case http.MethodGet:
+		s.mu.Lock()
+		defer s.mu.Unlock()
+		if len(s.observed) < s.expectedAgents {
+			writeJSON(w, http.StatusAccepted, map[string]int{"submitted_agents": len(s.observed), "expected_agents": s.expectedAgents})
+			return
+		}
+		var merged []AcceptedMessage
+		for _, messages := range s.observed {
+			merged = append(merged, messages...)
+		}
+		merged = mergeMessageLedgers(nil, merged)
+		writeJSON(w, http.StatusOK, merged)
+	default:
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+	}
+}
+
 func (s *coordinatorState) handleReady(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
 	var ready AgentReady
-	if !decodeLimitedJSON(w, r, &ready) || (ready.Machine != "a" && ready.Machine != "b") || ready.ReadyConnections <= 0 {
+	if !decodeLimitedJSON(w, r, &ready) || (ready.Machine != "a" && ready.Machine != "b") ||
+		ready.ExpectedConnections <= 0 || ready.ReadyConnections < 0 || ready.ReadyConnections > ready.ExpectedConnections {
 		if ready.Machine != "a" && ready.Machine != "b" {
 			http.Error(w, "invalid machine", http.StatusBadRequest)
+		} else {
+			http.Error(w, "invalid connection counts", http.StatusBadRequest)
 		}
 		return
 	}
 	s.mu.Lock()
 	s.ready[ready.Machine] = ready
-	if len(s.ready) == s.expectedAgents && s.start.StartAt.IsZero() {
-		s.start.StartAt = time.Now().UTC().Add(s.startDelay)
-		log.Printf("all agents ready; start_at=%s", s.start.StartAt.Format(time.RFC3339Nano))
+	now := time.Now().UTC()
+	allStable := len(s.ready) == s.expectedAgents
+	for _, agent := range s.ready {
+		if agent.ReadyConnections != agent.ExpectedConnections {
+			allStable = false
+			break
+		}
+	}
+	if !allStable && (!s.start.Committed || now.Before(s.start.StartAt)) {
+		log.Printf("agent readiness dropped before start; resetting start barrier")
+		s.start.StartAt = time.Time{}
+		s.start.Committed = false
+		clear(s.armed)
+		clear(s.started)
+		s.startError = ""
+	}
+	if allStable && s.start.StartAt.IsZero() {
+		s.start.StartAt = now.Add(s.startDelay)
+		s.start.Committed = false
+		clear(s.armed)
+		clear(s.started)
+		s.startError = ""
+		log.Printf("all agents ready; validation_at=%s", s.start.StartAt.Format(time.RFC3339Nano))
+	}
+	if allStable && !s.start.Committed && ready.Armed && !now.Before(s.start.StartAt) {
+		s.armed[ready.Machine] = true
+	}
+	if allStable && !s.start.Committed && len(s.armed) == s.expectedAgents {
+		delay := s.commitDelay
+		if delay <= 0 {
+			delay = 5 * time.Second
+		}
+		s.start.StartAt = now.Add(delay)
+		s.start.Committed = true
+		log.Printf("all agents validated; committed start_at=%s", s.start.StartAt.Format(time.RFC3339Nano))
 	}
 	start := s.start
 	s.mu.Unlock()
 	writeJSON(w, http.StatusOK, start)
 }
 
+func (s *coordinatorState) handleStarted(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	var arrival AgentStarted
+	if !decodeLimitedJSON(w, r, &arrival) || (arrival.Machine != "a" && arrival.Machine != "b") || arrival.ScheduledAt.IsZero() {
+		http.Error(w, "invalid start arrival", http.StatusBadRequest)
+		return
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if !s.start.Committed || !arrival.ScheduledAt.Equal(s.start.StartAt) {
+		writeJSON(w, http.StatusOK, StartGate{Error: "start schedule changed", ExpectedAgents: s.expectedAgents})
+		return
+	}
+	if s.started == nil {
+		s.started = make(map[string]time.Time)
+	}
+	if _, exists := s.started[arrival.Machine]; !exists {
+		now := time.Now().UTC()
+		s.started[arrival.Machine] = now
+		skew := now.Sub(s.start.StartAt)
+		if skew < -maxAgentStartSkew || skew > maxAgentStartSkew {
+			s.startError = fmt.Sprintf("agent %s reached start barrier %s from schedule (limit %s)",
+				arrival.Machine, skew.Round(time.Millisecond), maxAgentStartSkew)
+			log.Printf("start barrier rejected: %s", s.startError)
+		}
+	}
+	gate := StartGate{
+		Proceed: len(s.started) == s.expectedAgents && s.startError == "", Error: s.startError,
+		ArrivedAgents: len(s.started), ExpectedAgents: s.expectedAgents,
+	}
+	writeJSON(w, http.StatusOK, gate)
+}
+
 func (s *coordinatorState) handleStart(w http.ResponseWriter, r *http.Request) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -185,18 +371,29 @@ func (s *coordinatorState) handleStatus(w http.ResponseWriter, _ *http.Request)
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	writeJSON(w, http.StatusOK, map[string]any{
-		"start": s.start, "ready": s.ready, "ledger_agents": len(s.ledgers), "summary_agents": len(s.summaries),
+		"start": s.start, "ready": s.ready, "armed": s.armed, "started": s.started,
+		"start_error":   s.startError,
+		"ledger_agents": len(s.ledgers), "observed_agents": len(s.observed),
+		"history_agents": len(s.history), "summary_agents": len(s.summaries),
 	})
 }
 
 func (s *coordinatorState) writeOutput(path string) error {
 	s.mu.Lock()
 	data := struct {
-		Start     StartInfo                    `json:"start"`
-		Ready     map[string]AgentReady        `json:"ready"`
-		Ledgers   map[string][]AcceptedMessage `json:"ledgers"`
-		Summaries map[string]AgentSummary      `json:"summaries"`
-	}{s.start, s.ready, s.ledgers, s.summaries}
+		Start      StartInfo                    `json:"start"`
+		Ready      map[string]AgentReady        `json:"ready"`
+		Started    map[string]time.Time         `json:"started"`
+		StartError string                       `json:"start_error,omitempty"`
+		Ledgers    map[string][]AcceptedMessage `json:"ledgers"`
+		Observed   map[string][]AcceptedMessage `json:"observed"`
+		History    map[string][]string          `json:"history"`
+		Summaries  map[string]AgentSummary      `json:"summaries"`
+	}{
+		Start: s.start, Ready: s.ready, Started: s.started, StartError: s.startError,
+		Ledgers: s.ledgers, Observed: s.observed,
+		History: s.history, Summaries: s.summaries,
+	}
 	s.mu.Unlock()
 	raw, err := json.MarshalIndent(data, "", "  ")
 	if err != nil {
@@ -232,24 +429,37 @@ func newCoordinatorClient(base string) *coordinatorClient {
 	return &coordinatorClient{base: strings.TrimRight(base, "/"), client: &http.Client{Timeout: 35 * time.Second}}
 }
 
-func (c *coordinatorClient) ready(ctx context.Context, ready AgentReady) (StartInfo, error) {
+func (c *coordinatorClient) ready(ctx context.Context, current func() AgentReady) (StartInfo, error) {
 	var start StartInfo
-	if _, err := c.request(ctx, http.MethodPost, "/v1/ready", ready, &start); err != nil {
-		return start, err
-	}
-	for start.StartAt.IsZero() {
+	armed := false
+	for {
+		state := current()
+		state.Armed = armed
+		if _, err := c.request(ctx, http.MethodPost, "/v1/ready", state, &start); err != nil {
+			return start, err
+		}
+		if start.StartAt.IsZero() {
+			armed = false
+		} else {
+			remaining := time.Until(start.StartAt)
+			if start.Committed && remaining <= 0 {
+				return start, nil
+			}
+			if !start.Committed && remaining <= 0 {
+				armed = true
+				continue
+			}
+			if remaining < time.Second {
+				if err := waitContext(ctx, remaining); err != nil {
+					return start, err
+				}
+				continue
+			}
+		}
 		if err := waitContext(ctx, time.Second); err != nil {
 			return start, err
 		}
-		status, err := c.request(ctx, http.MethodGet, "/v1/start", nil, &start)
-		if err != nil {
-			return start, err
-		}
-		if status != http.StatusOK {
-			start = StartInfo{}
-		}
 	}
-	return start, nil
 }
 
 func (c *coordinatorClient) submitLedger(ctx context.Context, machine string, messages []AcceptedMessage) error {
@@ -257,6 +467,25 @@ func (c *coordinatorClient) submitLedger(ctx context.Context, machine string, me
 	return err
 }
 
+func (c *coordinatorClient) started(ctx context.Context, machine string, scheduledAt time.Time) error {
+	arrival := AgentStarted{Machine: machine, ScheduledAt: scheduledAt}
+	for {
+		var gate StartGate
+		if _, err := c.request(ctx, http.MethodPost, "/v1/started", arrival, &gate); err != nil {
+			return err
+		}
+		if gate.Error != "" {
+			return errors.New(gate.Error)
+		}
+		if gate.Proceed {
+			return nil
+		}
+		if err := waitContext(ctx, 100*time.Millisecond); err != nil {
+			return err
+		}
+	}
+}
+
 func (c *coordinatorClient) ledger(ctx context.Context) ([]AcceptedMessage, error) {
 	for {
 		var messages []AcceptedMessage
@@ -273,6 +502,48 @@ func (c *coordinatorClient) ledger(ctx context.Context) ([]AcceptedMessage, erro
 	}
 }
 
+func (c *coordinatorClient) submitObserved(ctx context.Context, machine string, messages []AcceptedMessage) error {
+	_, err := c.request(ctx, http.MethodPost, "/v1/observed?machine="+machine, messages, nil)
+	return err
+}
+
+func (c *coordinatorClient) observed(ctx context.Context) ([]AcceptedMessage, error) {
+	for {
+		var messages []AcceptedMessage
+		status, err := c.request(ctx, http.MethodGet, "/v1/observed", nil, &messages)
+		if err != nil {
+			return nil, err
+		}
+		if status == http.StatusOK {
+			return messages, nil
+		}
+		if err = waitContext(ctx, time.Second); err != nil {
+			return nil, err
+		}
+	}
+}
+
+func (c *coordinatorClient) submitHistory(ctx context.Context, machine string, messageIDs []string) error {
+	_, err := c.request(ctx, http.MethodPost, "/v1/history?machine="+machine, messageIDs, nil)
+	return err
+}
+
+func (c *coordinatorClient) history(ctx context.Context) ([]string, error) {
+	for {
+		var messageIDs []string
+		status, err := c.request(ctx, http.MethodGet, "/v1/history", nil, &messageIDs)
+		if err != nil {
+			return nil, err
+		}
+		if status == http.StatusOK {
+			return messageIDs, nil
+		}
+		if err = waitContext(ctx, time.Second); err != nil {
+			return nil, err
+		}
+	}
+}
+
 func (c *coordinatorClient) submitSummary(ctx context.Context, summary AgentSummary) error {
 	_, err := c.request(ctx, http.MethodPost, "/v1/summary", summary, nil)
 	return err

loadtest/im-pressure/coordinator_test.go

@@ -1,18 +1,59 @@
 package main
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"time"
 )
 
+func TestCoordinatorResetsBarrierWhenConnectionCountDrops(t *testing.T) {
+	state := &coordinatorState{
+		start: StartInfo{RunID: "run-reset", Scenario: "group"}, startDelay: time.Minute,
+		commitDelay: time.Second, expectedAgents: 2, ready: make(map[string]AgentReady),
+		armed: make(map[string]bool), ledgers: make(map[string][]AcceptedMessage),
+		started:   make(map[string]time.Time),
+		summaries: make(map[string]AgentSummary), complete: make(chan struct{}),
+	}
+	postReady := func(ready AgentReady) StartInfo {
+		raw, err := json.Marshal(ready)
+		if err != nil {
+			t.Fatal(err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/v1/ready", bytes.NewReader(raw))
+		w := httptest.NewRecorder()
+		state.handleReady(w, req)
+		if w.Code != http.StatusOK {
+			t.Fatalf("ready status=%d body=%s", w.Code, w.Body.String())
+		}
+		var start StartInfo
+		if err = json.Unmarshal(w.Body.Bytes(), &start); err != nil {
+			t.Fatal(err)
+		}
+		return start
+	}
+	fullA := AgentReady{Machine: "a", ReadyConnections: 1000, ExpectedConnections: 1000}
+	fullB := AgentReady{Machine: "b", ReadyConnections: 1000, ExpectedConnections: 1000}
+	postReady(fullA)
+	if start := postReady(fullB); start.StartAt.IsZero() {
+		t.Fatal("full agents must create a validation barrier")
+	}
+	fullA.ReadyConnections = 999
+	if start := postReady(fullA); !start.StartAt.IsZero() || start.Committed {
+		t.Fatalf("connection drop must reset barrier: %+v", start)
+	}
+}
+
 func TestCoordinatorClientWaitsForBothAgentsAndMergesLedger(t *testing.T) {
 	state := &coordinatorState{
-		start: StartInfo{RunID: "run1", Scenario: "p2p"}, startDelay: time.Second, expectedAgents: 2,
+		start: StartInfo{RunID: "run1", Scenario: "p2p"}, startDelay: 50 * time.Millisecond,
+		commitDelay: 50 * time.Millisecond, expectedAgents: 2,
 		ready: make(map[string]AgentReady), ledgers: make(map[string][]AcceptedMessage),
-		summaries: make(map[string]AgentSummary), complete: make(chan struct{}),
+		armed: make(map[string]bool), summaries: make(map[string]AgentSummary), complete: make(chan struct{}),
+		started: make(map[string]time.Time),
 	}
 	server := httptest.NewServer(testCoordinatorMux(state))
 	defer server.Close()
@@ -20,12 +61,16 @@ func TestCoordinatorClientWaitsForBothAgentsAndMergesLedger(t *testing.T) {
 
 	aDone := make(chan StartInfo, 1)
 	go func() {
-		start, _ := client.ready(context.Background(), AgentReady{Machine: "a", ReadyConnections: 1000})
+		start, _ := client.ready(context.Background(), func() AgentReady {
+			return AgentReady{Machine: "a", ReadyConnections: 1000, ExpectedConnections: 1000}
+		})
 		aDone <- start
 	}()
 	time.Sleep(50 * time.Millisecond)
-	startB, err := client.ready(context.Background(), AgentReady{Machine: "b", ReadyConnections: 1000})
-	if err != nil || startB.StartAt.IsZero() {
+	startB, err := client.ready(context.Background(), func() AgentReady {
+		return AgentReady{Machine: "b", ReadyConnections: 1000, ExpectedConnections: 1000}
+	})
+	if err != nil || startB.StartAt.IsZero() || !startB.Committed {
 		t.Fatalf("machine B ready: start=%+v err=%v", startB, err)
 	}
 	select {
@@ -47,14 +92,84 @@ func TestCoordinatorClientWaitsForBothAgentsAndMergesLedger(t *testing.T) {
 	if err != nil || len(ledger) != 2 || ledger[0].ClientMid != "a" || ledger[1].ClientMid != "b" {
 		t.Fatalf("ledger=%+v err=%v", ledger, err)
 	}
+	if err = client.submitObserved(context.Background(), "a", []AcceptedMessage{{ClientMid: "unknown", Seq: 10}}); err != nil {
+		t.Fatal(err)
+	}
+	if err = client.submitObserved(context.Background(), "b", []AcceptedMessage{{ClientMid: "unknown", Seq: 10}}); err != nil {
+		t.Fatal(err)
+	}
+	observed, err := client.observed(context.Background())
+	if err != nil || len(observed) != 1 || observed[0].ClientMid != "unknown" {
+		t.Fatalf("observed=%+v err=%v", observed, err)
+	}
+	if err = client.submitHistory(context.Background(), "a", []string{"mid-2", "mid-1"}); err != nil {
+		t.Fatal(err)
+	}
+	if err = client.submitHistory(context.Background(), "b", []string{"mid-2", "mid-3"}); err != nil {
+		t.Fatal(err)
+	}
+	history, err := client.history(context.Background())
+	if err != nil || len(history) != 3 || history[0] != "mid-1" || history[1] != "mid-2" || history[2] != "mid-3" {
+		t.Fatalf("history=%+v err=%v", history, err)
+	}
 }
 
 func testCoordinatorMux(state *coordinatorState) *http.ServeMux {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/v1/ready", state.handleReady)
 	mux.HandleFunc("/v1/start", state.handleStart)
+	mux.HandleFunc("/v1/started", state.handleStarted)
 	mux.HandleFunc("/v1/ledger", state.handleLedger)
+	mux.HandleFunc("/v1/observed", state.handleObserved)
+	mux.HandleFunc("/v1/history", state.handleHistory)
 	mux.HandleFunc("/v1/summary", state.handleSummary)
 	mux.HandleFunc("/v1/status", state.handleStatus)
 	return mux
 }
+
+func TestCoordinatorRejectsLateAgentForBothMachines(t *testing.T) {
+	startAt := time.Now().Add(-maxAgentStartSkew - time.Second).UTC()
+	state := &coordinatorState{
+		start:          StartInfo{RunID: "run-late", Scenario: "group", StartAt: startAt, Committed: true},
+		expectedAgents: 2, started: make(map[string]time.Time),
+	}
+	server := httptest.NewServer(testCoordinatorMux(state))
+	defer server.Close()
+	client := newCoordinatorClient(server.URL)
+	if err := client.started(context.Background(), "b", startAt); err == nil {
+		t.Fatal("late agent must be rejected")
+	}
+	if err := client.started(context.Background(), "a", startAt); err == nil {
+		t.Fatal("the other agent must observe the same rejected run")
+	}
+}
+
+func TestCoordinatorReleasesAgentsOnlyAfterBothReachStart(t *testing.T) {
+	startAt := time.Now().UTC()
+	state := &coordinatorState{
+		start:          StartInfo{RunID: "run-synced", Scenario: "group", StartAt: startAt, Committed: true},
+		expectedAgents: 2, started: make(map[string]time.Time),
+	}
+	server := httptest.NewServer(testCoordinatorMux(state))
+	defer server.Close()
+	client := newCoordinatorClient(server.URL)
+	aDone := make(chan error, 1)
+	go func() { aDone <- client.started(context.Background(), "a", startAt) }()
+	time.Sleep(50 * time.Millisecond)
+	select {
+	case err := <-aDone:
+		t.Fatalf("machine A passed before B arrived: %v", err)
+	default:
+	}
+	if err := client.started(context.Background(), "b", startAt); err != nil {
+		t.Fatalf("machine B start: %v", err)
+	}
+	select {
+	case err := <-aDone:
+		if err != nil {
+			t.Fatalf("machine A start: %v", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("machine A was not released")
+	}
+}

loadtest/im-pressure/dbverify.go

@@ -14,17 +14,18 @@ import (
 )
 
 type dbVerifyResult struct {
-	RunID         string   `json:"run_id"`
-	TenantCode    string   `json:"tenant_code"`
-	TenantID      int64    `json:"tenant_id"`
-	Expected      int      `json:"expected"`
-	FoundExact    int      `json:"found_exact"`
-	Missing       int      `json:"missing"`
-	Mismatch      int      `json:"mismatch"`
-	DuplicateRows int      `json:"duplicate_rows"`
-	Unexpected    int      `json:"unexpected_rows"`
-	Tables        []string `json:"tables"`
-	MissingMIDs   []string `json:"missing_client_mids,omitempty"`
+	RunID          string   `json:"run_id"`
+	TenantCode     string   `json:"tenant_code"`
+	TenantID       int64    `json:"tenant_id"`
+	Expected       int      `json:"expected"`
+	FoundExact     int      `json:"found_exact"`
+	Missing        int      `json:"missing"`
+	Mismatch       int      `json:"mismatch"`
+	DuplicateRows  int      `json:"duplicate_rows"`
+	Unexpected     int      `json:"unexpected_rows"`
+	Tables         []string `json:"tables"`
+	MissingMIDs    []string `json:"missing_client_mids,omitempty"`
+	UnexpectedMIDs []string `json:"unexpected_client_mids,omitempty"`
 }
 
 type persistedIdentity struct {
@@ -40,8 +41,9 @@ func runDBVerify(ctx context.Context, coordinatorPath, output, tenantCode, dsnEn
 		return err
 	}
 	var coordinator struct {
-		Start   StartInfo                    `json:"start"`
-		Ledgers map[string][]AcceptedMessage `json:"ledgers"`
+		Start    StartInfo                    `json:"start"`
+		Ledgers  map[string][]AcceptedMessage `json:"ledgers"`
+		Observed map[string][]AcceptedMessage `json:"observed"`
 	}
 	if err = json.Unmarshal(raw, &coordinator); err != nil {
 		return fmt.Errorf("decode coordinator: %w", err)
@@ -76,17 +78,11 @@ func runDBVerify(ctx context.Context, coordinatorPath, output, tenantCode, dsnEn
 		return err
 	}
 
-	expected := make(map[string]AcceptedMessage)
+	expected := expectedDBMessages(coordinator.Start.RunID, coordinator.Ledgers, coordinator.Observed)
 	months := make(map[string]struct{})
-	for _, ledger := range coordinator.Ledgers {
-		for _, message := range ledger {
-			if message.RunID != coordinator.Start.RunID {
-				continue
-			}
-			expected[message.ClientMid] = message
-			if message.Kind == "group" {
-				months[message.SentAt.UTC().Format("200601")] = struct{}{}
-			}
+	for _, message := range expected {
+		if message.Kind == "group" {
+			months[message.SentAt.UTC().Format("200601")] = struct{}{}
 		}
 	}
 	tables := []string{fmt.Sprintf("im_%03d_messages", tenantID)}
@@ -145,9 +141,11 @@ func runDBVerify(ctx context.Context, coordinatorPath, output, tenantCode, dsnEn
 	for mid := range actual {
 		if _, ok := expected[mid]; !ok {
 			result.Unexpected++
+			result.UnexpectedMIDs = append(result.UnexpectedMIDs, mid)
 		}
 	}
 	sort.Strings(result.MissingMIDs)
+	sort.Strings(result.UnexpectedMIDs)
 	resultRaw, _ := json.MarshalIndent(result, "", "  ")
 	if output == "" || output == "-" {
 		if _, err = fmt.Fprintln(os.Stdout, string(resultRaw)); err != nil {
@@ -164,3 +162,20 @@ func runDBVerify(ctx context.Context, coordinatorPath, output, tenantCode, dsnEn
 	}
 	return nil
 }
+
+func expectedDBMessages(runID string, ledgers, observed map[string][]AcceptedMessage) map[string]AcceptedMessage {
+	all := make([]AcceptedMessage, 0)
+	for _, messages := range observed {
+		all = append(all, messages...)
+	}
+	for _, messages := range ledgers {
+		all = append(all, messages...)
+	}
+	expected := make(map[string]AcceptedMessage, len(all))
+	for _, message := range mergeMessageLedgers(nil, all) {
+		if message.RunID == runID && message.ClientMid != "" {
+			expected[message.ClientMid] = message
+		}
+	}
+	return expected
+}

loadtest/im-pressure/dbverify_test.go

@@ -0,0 +1,24 @@
+package main
+
+import "testing"
+
+func TestExpectedDBMessagesIncludesObservedWithoutAck(t *testing.T) {
+	ledgers := map[string][]AcceptedMessage{
+		"a": {{RunID: "run-1", ClientMid: "acked", Topic: "grp-one", Seq: 1}},
+	}
+	observed := map[string][]AcceptedMessage{
+		"a": {
+			{RunID: "run-1", ClientMid: "unacked", Topic: "grp-one", Seq: 2},
+			{RunID: "other", ClientMid: "foreign", Topic: "grp-one", Seq: 3},
+		},
+		"b": {{RunID: "run-1", ClientMid: "unacked", Topic: "grp-one", Seq: 2}},
+	}
+
+	expected := expectedDBMessages("run-1", ledgers, observed)
+	if len(expected) != 2 {
+		t.Fatalf("expected messages=%d want=2: %+v", len(expected), expected)
+	}
+	if expected["acked"].Seq != 1 || expected["unacked"].Seq != 2 {
+		t.Fatalf("unexpected merged messages: %+v", expected)
+	}
+}

loadtest/im-pressure/histogram.go

@@ -2,7 +2,7 @@ package main
 
 import (
 	"sort"
-	"sync"
+	"sync/atomic"
 	"time"
 )
 
@@ -10,14 +10,14 @@ var latencyBounds = []time.Duration{
 	time.Millisecond, 3 * time.Millisecond, 5 * time.Millisecond, 10 * time.Millisecond,
 	25 * time.Millisecond, 50 * time.Millisecond, 100 * time.Millisecond, 200 * time.Millisecond,
 	500 * time.Millisecond, time.Second, 2 * time.Second, 5 * time.Second, 10 * time.Second,
+	20 * time.Second, 30 * time.Second, 45 * time.Second, 60 * time.Second, 90 * time.Second, 120 * time.Second,
 }
 
 type DurationHistogram struct {
-	mu     sync.Mutex
-	count  int64
-	sum    time.Duration
-	max    time.Duration
-	bucket []int64
+	count  atomic.Int64
+	sum    atomic.Int64
+	max    atomic.Int64
+	bucket []atomic.Int64
 }
 
 type HistogramSnapshot struct {
@@ -28,37 +28,36 @@ type HistogramSnapshot struct {
 }
 
 func NewDurationHistogram() *DurationHistogram {
-	return &DurationHistogram{bucket: make([]int64, len(latencyBounds)+1)}
+	return &DurationHistogram{bucket: make([]atomic.Int64, len(latencyBounds)+1)}
 }
 
 func (h *DurationHistogram) Observe(value time.Duration) {
 	if value < 0 {
 		return
 	}
-	h.mu.Lock()
-	defer h.mu.Unlock()
-	h.count++
-	h.sum += value
-	if value > h.max {
-		h.max = value
+	nanos := int64(value)
+	h.count.Add(1)
+	h.sum.Add(nanos)
+	for previous := h.max.Load(); nanos > previous; previous = h.max.Load() {
+		if h.max.CompareAndSwap(previous, nanos) {
+			break
+		}
 	}
 	idx := sort.Search(len(latencyBounds), func(i int) bool { return value <= latencyBounds[i] })
-	h.bucket[idx]++
+	h.bucket[idx].Add(1)
 }
 
 func (h *DurationHistogram) Snapshot() HistogramSnapshot {
-	h.mu.Lock()
-	defer h.mu.Unlock()
 	buckets := make(map[string]int64, len(h.bucket))
-	for i, count := range h.bucket {
+	for i := range h.bucket {
 		label := "+Inf"
 		if i < len(latencyBounds) {
 			label = latencyBounds[i].String()
 		}
-		buckets[label] = count
+		buckets[label] = h.bucket[i].Load()
 	}
 	return HistogramSnapshot{
-		Count: h.count, SumMS: float64(h.sum) / float64(time.Millisecond),
-		MaxMS: float64(h.max) / float64(time.Millisecond), Buckets: buckets,
+		Count: h.count.Load(), SumMS: float64(h.sum.Load()) / float64(time.Millisecond),
+		MaxMS: float64(h.max.Load()) / float64(time.Millisecond), Buckets: buckets,
 	}
 }

loadtest/im-pressure/httpapi.go

@@ -197,15 +197,17 @@ func (a *apiClient) findPendingFriendRequest(ctx context.Context, target Account
 func (a *apiClient) createFriendRequest(ctx context.Context, source, target AccountRecord) (*friendRequestResponse, error) {
 	var result friendRequestResponse
 	body := map[string]any{"target_user_id": target.UserID, "message": "loadtest", "source": "search", "source_topic": ""}
+	idempotencyKey := fmt.Sprintf("loadtest-friend-%d-%s-%04d", time.Now().UnixNano(), source.Machine, source.Index)
 	err := a.do(ctx, http.MethodPost, "/v1/im/friend-requests", source.Token,
-		fmt.Sprintf("loadtest-friend-%04d", source.Index), body, &result)
+		idempotencyKey, body, &result)
 	return &result, err
 }
 
 func (a *apiClient) acceptFriendRequest(ctx context.Context, target AccountRecord, requestID string) (*friendRequestResponse, error) {
 	var result friendRequestResponse
+	idempotencyKey := fmt.Sprintf("loadtest-friend-accept-%d", time.Now().UnixNano())
 	err := a.do(ctx, http.MethodPost, "/v1/im/friend-requests/"+url.PathEscape(requestID)+"/accept", target.Token,
-		"loadtest-friend-accept-"+requestID, map[string]any{}, &result)
+		idempotencyKey, map[string]any{}, &result)
 	return &result, err
 }
 
@@ -216,11 +218,12 @@ type p2pResponse struct {
 
 func (a *apiClient) ensureP2P(ctx context.Context, source, target AccountRecord) (*p2pResponse, error) {
 	var result p2pResponse
-	// EnsureP2P is itself idempotent and must execute on every preflight so it
-	// can repair subscriptions and refresh a loaded topic. A stable HTTP
-	// idempotency key would replay an old response and skip that repair.
+	// EnsureP2P must execute on every preflight so it can repair subscriptions
+	// and refresh a loaded topic. Use a fresh key instead of replaying an old
+	// successful response from a previous load-test run.
+	idempotencyKey := fmt.Sprintf("loadtest-p2p-%d-%s-%04d", time.Now().UnixNano(), source.Machine, source.Index)
 	err := a.do(ctx, http.MethodPost, "/v1/im/conversations/p2p", source.Token,
-		"",
+		idempotencyKey,
 		map[string]any{"peer_user_id": target.UserID}, &result)
 	return &result, err
 }
@@ -266,6 +269,11 @@ type groupMembersResponse struct {
 }
 
 func (a *apiClient) countGroupMembers(ctx context.Context, account AccountRecord, topic string) (int, error) {
+	members, err := a.groupMemberIDs(ctx, account, topic)
+	return len(members), err
+}
+
+func (a *apiClient) groupMemberIDs(ctx context.Context, account AccountRecord, topic string) (map[string]bool, error) {
 	cursor := ""
 	seen := make(map[string]bool)
 	for {
@@ -275,7 +283,7 @@ func (a *apiClient) countGroupMembers(ctx context.Context, account AccountRecord
 		}
 		var page groupMembersResponse
 		if err := a.do(ctx, http.MethodGet, path, account.Token, "", nil, &page); err != nil {
-			return 0, err
+			return nil, err
 		}
 		for _, item := range page.Items {
 			seen[item.UserID] = true
@@ -284,11 +292,11 @@ func (a *apiClient) countGroupMembers(ctx context.Context, account AccountRecord
 			break
 		}
 		if page.NextCursor == cursor {
-			return 0, fmt.Errorf("group member cursor did not advance: %s", cursor)
+			return nil, fmt.Errorf("group member cursor did not advance: %s", cursor)
 		}
 		cursor = page.NextCursor
 	}
-	return len(seen), nil
+	return seen, nil
 }
 
 func queryInt(value string, fallback int) int {

loadtest/im-pressure/main.go

@@ -101,7 +101,7 @@ func coordinatorCommand(ctx context.Context, args []string) error {
 	fs := flag.NewFlagSet("coordinator", flag.ContinueOnError)
 	listen := fs.String("listen", ":8090", "coordinator listen address")
 	runID := fs.String("run-id", "", "unique run ID, max 24 characters")
-	scenario := fs.String("scenario", "", "p2p, group, or mixed")
+	scenario := fs.String("scenario", "", "p2p, group, mixed, or idle")
 	output := fs.String("output", "loadtest/im-pressure/results/coordinator.json", "coordinator result path")
 	expected := fs.Int("expected-agents", 2, "number of agents")
 	delay := fs.Duration("start-delay", 30*time.Second, "delay after all agents are ready")

loadtest/im-pressure/merge.go

@@ -6,38 +6,58 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
+	"strings"
 	"time"
 )
 
 type CombinedReport struct {
-	RunID               string            `json:"run_id"`
-	Scenario            string            `json:"scenario"`
-	GeneratedAt         time.Time         `json:"generated_at"`
-	Agents              []AgentSummary    `json:"agents"`
-	ExpectedConnections int               `json:"expected_connections"`
-	ReadyConnections    int               `json:"ready_connections"`
-	PublishAttempted    int64             `json:"publish_attempted"`
-	PublishAccepted     int64             `json:"publish_accepted"`
-	PublishRejected     int64             `json:"publish_rejected"`
-	PublishErrors       map[string]int64  `json:"publish_errors,omitempty"`
-	PublishSuccessRate  float64           `json:"publish_success_rate"`
-	AckP95MS            float64           `json:"ack_p95_ms"`
-	DeliveryP95MS       float64           `json:"delivery_p95_ms"`
-	ExpectedDeliveries  int64             `json:"expected_deliveries"`
-	ReceivedDeliveries  int64             `json:"received_deliveries"`
-	RealtimeLost        int64             `json:"realtime_lost"`
-	RealtimeLostStored  int64             `json:"realtime_lost_but_persisted"`
-	ArrivalRate         float64           `json:"arrival_rate"`
-	LossRate            float64           `json:"loss_rate"`
-	Duplicates          int64             `json:"duplicates"`
-	OutOfOrder          int64             `json:"out_of_order"`
-	Disconnects         int64             `json:"disconnects"`
-	HistoryChecked      int64             `json:"history_checked"`
-	HistoryFound        int64             `json:"history_found"`
-	PersistenceLost     int64             `json:"persistence_lost"`
-	Missing             []MissingDelivery `json:"missing,omitempty"`
-	Passed              bool              `json:"passed"`
-	FailureReasons      []string          `json:"failure_reasons,omitempty"`
+	RunID                  string                  `json:"run_id"`
+	Scenario               string                  `json:"scenario"`
+	GeneratedAt            time.Time               `json:"generated_at"`
+	Agents                 []AgentSummary          `json:"agents"`
+	ExpectedConnections    int                     `json:"expected_connections"`
+	ReadyConnections       int                     `json:"ready_connections"`
+	PublishAttempted       int64                   `json:"publish_attempted"`
+	PublishAccepted        int64                   `json:"publish_accepted"`
+	PublishLateAccepted    int64                   `json:"publish_late_accepted"`
+	PublishFinalAccepted   int64                   `json:"publish_final_accepted"`
+	PublishRejected        int64                   `json:"publish_rejected"`
+	PublishExplicitReject  int64                   `json:"publish_explicitly_rejected"`
+	PublishOutcomeUnknown  int64                   `json:"publish_outcome_unknown"`
+	PublishErrors          map[string]int64        `json:"publish_errors,omitempty"`
+	PublishCtrlObserved    int64                   `json:"publish_ctrl_observed"`
+	PublishCtrlOver20      int64                   `json:"publish_ctrl_over_20s"`
+	PublishLateCtrl        int64                   `json:"publish_ctrl_late"`
+	PublishCtrlUnresolved  int64                   `json:"publish_ctrl_unresolved"`
+	PublishCtrlP95MS       float64                 `json:"publish_ctrl_p95_ms"`
+	CtrlObservationSamples []CtrlObservationSample `json:"ctrl_observation_samples,omitempty"`
+	PublishSuccessRate     float64                 `json:"publish_success_rate"`
+	AckP95MS               float64                 `json:"ack_p95_ms"`
+	DeliveryP95MS          float64                 `json:"delivery_p95_ms"`
+	DeliveryLocalP95MS     float64                 `json:"delivery_local_p95_ms"`
+	DeliveryCrossP95MS     float64                 `json:"delivery_cross_machine_p95_ms"`
+	CrossClockSkewSamples  int64                   `json:"cross_machine_negative_latency_samples"`
+	ExpectedDeliveries     int64                   `json:"expected_deliveries"`
+	ReceivedDeliveries     int64                   `json:"received_deliveries"`
+	RealtimeLost           int64                   `json:"realtime_lost"`
+	RealtimeLostStored     int64                   `json:"realtime_lost_but_persisted"`
+	ArrivalRate            float64                 `json:"arrival_rate"`
+	LossRate               float64                 `json:"loss_rate"`
+	Duplicates             int64                   `json:"duplicates"`
+	OutOfOrder             int64                   `json:"out_of_order"`
+	OrderingViolations     []OrderingViolation     `json:"ordering_violations,omitempty"`
+	Disconnects            int64                   `json:"disconnects"`
+	DisconnectReasons      map[string]int64        `json:"disconnect_reasons,omitempty"`
+	DisconnectSamples      []DisconnectSample      `json:"disconnect_samples,omitempty"`
+	UnexpectedMessages     int64                   `json:"unexpected_messages"`
+	HistoryChecked         int64                   `json:"history_checked"`
+	HistoryFound           int64                   `json:"history_found"`
+	HistoryUnackedChecked  int64                   `json:"history_unacked_observed_checked"`
+	HistoryUnackedFound    int64                   `json:"history_unacked_observed_found"`
+	PersistenceLost        int64                   `json:"persistence_lost"`
+	Missing                []MissingDelivery       `json:"missing,omitempty"`
+	Passed                 bool                    `json:"passed"`
+	FailureReasons         []string                `json:"failure_reasons,omitempty"`
 }
 
 func runMerge(aPath, bPath, output string) error {
@@ -53,7 +73,7 @@ func runMerge(aPath, bPath, output string) error {
 		return fmt.Errorf("agent summaries do not belong to the same run")
 	}
 	report := CombinedReport{RunID: a.RunID, Scenario: a.Scenario, GeneratedAt: time.Now().UTC(), Agents: []AgentSummary{a, b}, Passed: true,
-		PublishErrors: make(map[string]int64)}
+		PublishErrors: make(map[string]int64), DisconnectReasons: make(map[string]int64)}
 	for _, summary := range report.Agents {
 		expectedConnections := summary.ExpectedConnections
 		if expectedConnections == 0 {
@@ -63,30 +83,91 @@ func runMerge(aPath, bPath, output string) error {
 		report.ReadyConnections += summary.ReadyConnections
 		report.PublishAttempted += summary.PublishAttempted
 		report.PublishAccepted += summary.PublishAccepted
-		report.PublishRejected += summary.PublishRejected
+		lateAccepted := summary.PublishLateAccepted
+		// Backfill summaries generated before publish_ctrl_late_accepted was added.
+		if summary.CtrlTrackingEnabled && lateAccepted == 0 {
+			for _, sample := range summary.CtrlObservationSamples {
+				if sample.Late && sample.Code >= 200 && sample.Code < 300 {
+					lateAccepted++
+				}
+			}
+		}
+		report.PublishLateAccepted += lateAccepted
+		report.PublishFinalAccepted += summary.PublishAccepted + lateAccepted
 		for category, count := range summary.PublishErrors {
 			report.PublishErrors[category] += count
 		}
+		unknown := summary.PublishOutcomeUnknown
+		if summary.CtrlTrackingEnabled {
+			unknown = summary.PublishCtrlUnresolved + summary.PublishErrors["socket"]
+		} else if unknown == 0 {
+			unknown = summary.PublishErrors["ctrl_timeout"] + summary.PublishErrors["socket"]
+		}
+		explicit := summary.PublishErrors["403"] + summary.PublishErrors["502"] +
+			summary.PublishErrors["503"] + summary.PublishErrors["other"]
+		report.PublishOutcomeUnknown += unknown
+		report.PublishCtrlObserved += summary.PublishCtrlObserved
+		report.PublishCtrlOver20 += summary.PublishCtrlOver20
+		report.PublishLateCtrl += summary.PublishLateCtrl
+		report.PublishCtrlUnresolved += summary.PublishCtrlUnresolved
+		if remaining := 1000 - len(report.CtrlObservationSamples); remaining > 0 {
+			if remaining > len(summary.CtrlObservationSamples) {
+				remaining = len(summary.CtrlObservationSamples)
+			}
+			report.CtrlObservationSamples = append(report.CtrlObservationSamples, summary.CtrlObservationSamples[:remaining]...)
+		}
+		report.PublishExplicitReject += explicit
+		report.PublishRejected += explicit
 		report.ExpectedDeliveries += summary.ExpectedPeer + summary.ExpectedGroup
 		report.ReceivedDeliveries += summary.ReceivedPeer + summary.ReceivedGroup
 		report.RealtimeLost += summary.RealtimeLost
 		report.RealtimeLostStored += summary.RealtimeLostStored
 		report.Duplicates += summary.Duplicates
 		report.OutOfOrder += summary.OutOfOrder
+		report.OrderingViolations = append(report.OrderingViolations, summary.OrderingViolations...)
 		report.Disconnects += summary.Disconnects
+		for category, count := range summary.DisconnectReasons {
+			report.DisconnectReasons[category] += count
+		}
+		if remaining := 100 - len(report.DisconnectSamples); remaining > 0 {
+			if remaining > len(summary.DisconnectSamples) {
+				remaining = len(summary.DisconnectSamples)
+			}
+			report.DisconnectSamples = append(report.DisconnectSamples, summary.DisconnectSamples[:remaining]...)
+		}
+		report.UnexpectedMessages += summary.UnexpectedMessages
 		report.HistoryChecked += summary.HistoryChecked
 		report.HistoryFound += summary.HistoryFound
+		report.HistoryUnackedChecked += summary.HistoryUnackedChecked
+		report.HistoryUnackedFound += summary.HistoryUnackedFound
 		report.PersistenceLost += summary.PersistenceLost
+		report.CrossClockSkewSamples += summary.CrossClockSkewSamples
 		report.Missing = append(report.Missing, summary.Missing...)
-		if len(summary.Errors) > 0 {
-			report.FailureReasons = append(report.FailureReasons, fmt.Sprintf("agent %s errors=%d", summary.Machine, len(summary.Errors)))
+		actionableErrors := len(summary.Errors)
+		lateTimeouts := int(lateAccepted)
+		for _, message := range summary.Errors {
+			if lateTimeouts > 0 && strings.Contains(message, "ctrl timeout") {
+				actionableErrors--
+				lateTimeouts--
+			}
+		}
+		if actionableErrors > 0 {
+			report.FailureReasons = append(report.FailureReasons, fmt.Sprintf("agent %s unresolved errors=%d", summary.Machine, actionableErrors))
 		}
 	}
 	if report.PublishAttempted > 0 {
-		report.PublishSuccessRate = float64(report.PublishAccepted) / float64(report.PublishAttempted)
+		report.PublishSuccessRate = float64(report.PublishFinalAccepted) / float64(report.PublishAttempted)
+	}
+	report.AckP95MS = mergedAckP95(report.Agents)
+	report.PublishCtrlP95MS = mergedHistogramP95(report.Agents, func(summary AgentSummary) HistogramSnapshot { return summary.PublishCtrlLatency })
+	report.DeliveryLocalP95MS = mergedHistogramP95(report.Agents, func(summary AgentSummary) HistogramSnapshot { return summary.DeliveryLatencyLocal })
+	report.DeliveryCrossP95MS = mergedHistogramP95(report.Agents, func(summary AgentSummary) HistogramSnapshot { return summary.DeliveryLatencyCross })
+	// delivery_p95_ms remains the compatibility field, but now uses only same-clock
+	// samples. Cross-machine wall clocks cannot produce a valid one-way latency.
+	report.DeliveryP95MS = report.DeliveryLocalP95MS
+	if report.DeliveryP95MS == 0 {
+		report.DeliveryP95MS = mergedHistogramP95(report.Agents, func(summary AgentSummary) HistogramSnapshot { return summary.DeliveryLatency })
 	}
-	report.AckP95MS = mergedHistogramP95(report.Agents, func(summary AgentSummary) HistogramSnapshot { return summary.AckLatency })
-	report.DeliveryP95MS = mergedHistogramP95(report.Agents, func(summary AgentSummary) HistogramSnapshot { return summary.DeliveryLatency })
 	if report.ExpectedDeliveries > 0 {
 		report.ArrivalRate = float64(report.ReceivedDeliveries) / float64(report.ExpectedDeliveries)
 		report.LossRate = float64(report.RealtimeLost) / float64(report.ExpectedDeliveries)
@@ -99,14 +180,15 @@ func runMerge(aPath, bPath, output string) error {
 		report.FailureReasons = append(report.FailureReasons,
 			fmt.Sprintf("publish success rate=%.6f expected>=0.999900", report.PublishSuccessRate))
 	}
-	if report.AckP95MS > 500 {
-		report.FailureReasons = append(report.FailureReasons, fmt.Sprintf("ack p95=%.0fms expected<=500ms", report.AckP95MS))
-	}
-	if report.DeliveryP95MS > 1000 {
+	if report.PublishOutcomeUnknown > 0 {
 		report.FailureReasons = append(report.FailureReasons,
-			fmt.Sprintf("delivery p95=%.0fms expected<=1000ms", report.DeliveryP95MS))
+			fmt.Sprintf("publish outcome unknown=%d (ACK timeout or socket failure)", report.PublishOutcomeUnknown))
 	}
-	if report.PublishRejected > 0 || report.RealtimeLost > 0 || report.PersistenceLost > 0 || report.Duplicates > 0 || report.OutOfOrder > 0 || report.Disconnects > 0 {
+	if report.UnexpectedMessages > 0 {
+		report.FailureReasons = append(report.FailureReasons,
+			fmt.Sprintf("deliveries observed without ACK ledger=%d", report.UnexpectedMessages))
+	}
+	if report.PublishRejected > 0 || report.RealtimeLost > 0 || report.PersistenceLost > 0 || report.Duplicates > 0 || report.OutOfOrder > 0 || report.Disconnects > 0 || report.UnexpectedMessages > 0 {
 		report.FailureReasons = append(report.FailureReasons, "message correctness gate failed")
 	}
 	report.Passed = len(report.FailureReasons) == 0
@@ -119,6 +201,26 @@ func runMerge(aPath, bPath, output string) error {
 	return writeJSONFile(output, report)
 }
 
+func mergedAckP95(agents []AgentSummary) float64 {
+	var expected int64
+	latencies := make([]float64, 0)
+	for _, agent := range agents {
+		expected += agent.AckLatency.Count
+		for _, message := range agent.AcceptedLocal {
+			if message.SentAt.IsZero() || message.AckAt.Before(message.SentAt) {
+				continue
+			}
+			latencies = append(latencies, float64(message.AckAt.Sub(message.SentAt))/float64(time.Millisecond))
+		}
+	}
+	if expected == 0 || int64(len(latencies)) != expected {
+		return mergedHistogramP95(agents, func(summary AgentSummary) HistogramSnapshot { return summary.AckLatency })
+	}
+	sort.Float64s(latencies)
+	index := (len(latencies)*95 + 99) / 100
+	return latencies[index-1]
+}
+
 func mergedHistogramP95(agents []AgentSummary, selectHistogram func(AgentSummary) HistogramSnapshot) float64 {
 	var count int64
 	buckets := make([]int64, len(latencyBounds)+1)

loadtest/im-pressure/merge_test.go

@@ -5,18 +5,27 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+	"time"
 )
 
 func TestRunMergeComputesArrivalAndPersistenceGate(t *testing.T) {
 	dir := t.TempDir()
 	a := AgentSummary{RunID: "run1", Scenario: "p2p", Machine: "a", ReadyConnections: 1000,
 		ExpectedConnections: 1000,
-		PublishAttempted:    10, PublishAccepted: 10, ExpectedPeer: 10, ReceivedPeer: 9,
-		RealtimeLost: 1, HistoryChecked: 10, HistoryFound: 10}
+		PublishAttempted:    10, PublishAccepted: 10, ExpectedPeer: 10, ReceivedPeer: 9, UnexpectedMessages: 42,
+		CtrlTrackingEnabled: true, PublishCtrlObserved: 9, PublishCtrlOver20: 2, PublishLateCtrl: 2,
+		PublishCtrlUnresolved: 1,
+		PublishErrors:         map[string]int64{"ctrl_timeout": 3, "socket": 2, "503": 1},
+		RealtimeLost:          1, HistoryChecked: 10, HistoryFound: 10, Disconnects: 1,
+		DisconnectReasons: map[string]int64{"timeout": 1},
+		DisconnectSamples: []DisconnectSample{{ReceiverMachine: "a", ReceiverIndex: 3, Category: "timeout"}}}
 	b := AgentSummary{RunID: "run1", Scenario: "p2p", Machine: "b", ReadyConnections: 1000,
 		ExpectedConnections: 1000,
 		PublishAttempted:    10, PublishAccepted: 10, ExpectedPeer: 10, ReceivedPeer: 10,
-		HistoryChecked: 10, HistoryFound: 9, PersistenceLost: 1}
+		HistoryChecked: 10, HistoryFound: 9, PersistenceLost: 1, OutOfOrder: 1,
+		CtrlTrackingEnabled: true, PublishCtrlObserved: 10,
+		Disconnects: 2, DisconnectReasons: map[string]int64{"timeout": 1, "connection_reset": 1},
+		OrderingViolations: []OrderingViolation{{ReceiverMachine: "b", ReceiverIndex: 7, PreviousSeq: 12, CurrentSeq: 11}}}
 	aPath, bPath, reportPath := filepath.Join(dir, "a.json"), filepath.Join(dir, "b.json"), filepath.Join(dir, "report.json")
 	writeSummaryForTest(t, aPath, a)
 	writeSummaryForTest(t, bPath, b)
@@ -37,6 +46,22 @@ func TestRunMergeComputesArrivalAndPersistenceGate(t *testing.T) {
 	if report.Passed || report.PersistenceLost != 1 {
 		t.Fatalf("correctness gate did not fail: %+v", report)
 	}
+	if report.UnexpectedMessages != 42 || report.PublishOutcomeUnknown != 3 ||
+		report.PublishExplicitReject != 1 || report.PublishRejected != 1 {
+		t.Fatalf("ambiguous publish outcomes were not merged: %+v", report)
+	}
+	if report.PublishCtrlObserved != 19 || report.PublishCtrlOver20 != 2 || report.PublishLateCtrl != 2 ||
+		report.PublishCtrlUnresolved != 1 {
+		t.Fatalf("ctrl observations were not merged: %+v", report)
+	}
+	if len(report.OrderingViolations) != 1 || report.OrderingViolations[0].ReceiverIndex != 7 {
+		t.Fatalf("ordering violations were not merged: %+v", report.OrderingViolations)
+	}
+	if report.Disconnects != 3 || report.DisconnectReasons["timeout"] != 2 ||
+		report.DisconnectReasons["connection_reset"] != 1 || len(report.DisconnectSamples) != 1 {
+		t.Fatalf("disconnect diagnostics were not merged: count=%d reasons=%v samples=%+v",
+			report.Disconnects, report.DisconnectReasons, report.DisconnectSamples)
+	}
 }
 
 func TestMergedHistogramP95(t *testing.T) {
@@ -49,6 +74,117 @@ func TestMergedHistogramP95(t *testing.T) {
 	}
 }
 
+func TestMergedHistogramP95DoesNotUseMaximumForLongTail(t *testing.T) {
+	histogram := NewDurationHistogram()
+	for i := 0; i < 94; i++ {
+		histogram.Observe(5 * time.Second)
+	}
+	for i := 0; i < 5; i++ {
+		histogram.Observe(25 * time.Second)
+	}
+	histogram.Observe(70 * time.Second)
+	agents := []AgentSummary{{PublishCtrlLatency: histogram.Snapshot()}}
+	if got := mergedHistogramP95(agents, func(summary AgentSummary) HistogramSnapshot {
+		return summary.PublishCtrlLatency
+	}); got != 30000 {
+		t.Fatalf("p95=%v want=30000", got)
+	}
+}
+
+func TestMergedAckP95UsesExactAcceptedTimestamps(t *testing.T) {
+	base := time.Date(2026, 9, 27, 8, 0, 0, 0, time.UTC)
+	agents := []AgentSummary{{
+		AckLatency: HistogramSnapshot{Count: 4, MaxMS: 900, Buckets: map[string]int64{"1s": 4}},
+		AcceptedLocal: []AcceptedMessage{
+			{SentAt: base, AckAt: base.Add(100 * time.Millisecond)},
+			{SentAt: base, AckAt: base.Add(200 * time.Millisecond)},
+			{SentAt: base, AckAt: base.Add(300 * time.Millisecond)},
+			{SentAt: base, AckAt: base.Add(400 * time.Millisecond)},
+		},
+	}}
+	if got := mergedAckP95(agents); got != 400 {
+		t.Fatalf("exact p95=%v want=400", got)
+	}
+}
+
+func TestMergedAckP95FallsBackWhenRawSamplesAreIncomplete(t *testing.T) {
+	agents := []AgentSummary{{
+		AckLatency:    HistogramSnapshot{Count: 2, MaxMS: 900, Buckets: map[string]int64{"1s": 2}},
+		AcceptedLocal: []AcceptedMessage{{SentAt: time.Now(), AckAt: time.Now().Add(100 * time.Millisecond)}},
+	}}
+	if got := mergedAckP95(agents); got != 1000 {
+		t.Fatalf("fallback p95=%v want=1000", got)
+	}
+}
+
+func TestRunMergeReportsSameClockDeliveryLatency(t *testing.T) {
+	dir := t.TempDir()
+	local := HistogramSnapshot{Count: 10, MaxMS: 200, Buckets: map[string]int64{"200ms": 10}}
+	cross := HistogramSnapshot{Count: 10, MaxMS: 5000, Buckets: map[string]int64{"5s": 10}}
+	a := AgentSummary{RunID: "run1", Scenario: "p2p", Machine: "a", ExpectedConnections: 1,
+		ReadyConnections: 1, PublishAttempted: 1, PublishAccepted: 1, ExpectedPeer: 1, ReceivedPeer: 1,
+		DeliveryLatencyLocal: local, DeliveryLatencyCross: cross, CrossClockSkewSamples: 3}
+	b := a
+	b.Machine = "b"
+	aPath, bPath, reportPath := filepath.Join(dir, "a.json"), filepath.Join(dir, "b.json"), filepath.Join(dir, "report.json")
+	writeSummaryForTest(t, aPath, a)
+	writeSummaryForTest(t, bPath, b)
+	if err := runMerge(aPath, bPath, reportPath); err != nil {
+		t.Fatal(err)
+	}
+	var report CombinedReport
+	raw, err := os.ReadFile(reportPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = json.Unmarshal(raw, &report); err != nil {
+		t.Fatal(err)
+	}
+	if report.DeliveryP95MS != 200 || report.DeliveryLocalP95MS != 200 || report.DeliveryCrossP95MS != 5000 {
+		t.Fatalf("unexpected delivery percentiles: %+v", report)
+	}
+	if report.CrossClockSkewSamples != 6 || !report.Passed {
+		t.Fatalf("cross-machine clock skew must not fail correctness acceptance: %+v", report)
+	}
+}
+
+func TestRunMergeTreatsLateSuccessAsFinalAcceptance(t *testing.T) {
+	dir := t.TempDir()
+	late := AgentSummary{
+		RunID: "run1", Scenario: "group", Machine: "a", ExpectedConnections: 1, ReadyConnections: 1,
+		PublishAttempted: 1, PublishAccepted: 0, CtrlTrackingEnabled: true,
+		PublishCtrlObserved: 1, PublishLateCtrl: 1, PublishCtrlUnresolved: 0,
+		PublishErrors:          map[string]int64{"ctrl_timeout": 1},
+		CtrlObservationSamples: []CtrlObservationSample{{Code: 202, Late: true}},
+		Errors:                 []string{"publish message-1: ctrl timeout id=pub-a-1"},
+	}
+	timely := AgentSummary{
+		RunID: "run1", Scenario: "group", Machine: "b", ExpectedConnections: 1, ReadyConnections: 1,
+		PublishAttempted: 1, PublishAccepted: 1, CtrlTrackingEnabled: true,
+		PublishCtrlObserved: 1, PublishErrors: map[string]int64{},
+	}
+	aPath, bPath, reportPath := filepath.Join(dir, "a.json"), filepath.Join(dir, "b.json"), filepath.Join(dir, "report.json")
+	writeSummaryForTest(t, aPath, late)
+	writeSummaryForTest(t, bPath, timely)
+	if err := runMerge(aPath, bPath, reportPath); err != nil {
+		t.Fatal(err)
+	}
+	var report CombinedReport
+	raw, err := os.ReadFile(reportPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = json.Unmarshal(raw, &report); err != nil {
+		t.Fatal(err)
+	}
+	if report.PublishAccepted != 1 || report.PublishLateAccepted != 1 || report.PublishFinalAccepted != 2 || report.PublishSuccessRate != 1 {
+		t.Fatalf("late acceptance was not included in final publish outcome: %+v", report)
+	}
+	if !report.Passed || len(report.FailureReasons) != 0 {
+		t.Fatalf("resolved late ACK must not fail the report: %+v", report.FailureReasons)
+	}
+}
+
 func writeSummaryForTest(t *testing.T, path string, summary AgentSummary) {
 	t.Helper()
 	raw, err := json.Marshal(summary)

loadtest/im-pressure/model.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net"
 	"os"
 	"sort"
 	"strings"
@@ -15,26 +16,44 @@ import (
 const manifestVersion = 1
 
 type Config struct {
-	Tenant           string              `json:"tenant"`
-	HTTPBase         string              `json:"http_base"`
-	APIKeyEnv        string              `json:"api_key_env"`
-	PasswordEnv      string              `json:"password_env"`
-	UsersPerMachine  int                 `json:"users_per_machine"`
-	Endpoints        map[string][]string `json:"endpoints"`
-	InsecureTLS      bool                `json:"insecure_tls"`
-	PrepareWorkers   int                 `json:"prepare_workers"`
-	ConnectRamp      string              `json:"connect_ramp"`
-	CommandTimeout   string              `json:"command_timeout"`
-	P2PMessages      int                 `json:"p2p_messages_per_user"`
-	P2PInterval      string              `json:"p2p_interval"`
-	DrainP2P         string              `json:"drain_p2p"`
-	DrainGroup       string              `json:"drain_group"`
-	PhonePrefix      string              `json:"registration_phone_prefix"`
-	VerifyCodeEnv    string              `json:"verification_code_env"`
-	HistoryWorkers   int                 `json:"history_workers"`
-	HistoryTimeout   string              `json:"history_timeout"`
-	PreflightWorkers int                 `json:"preflight_workers"`
-	SkipP2PPreflight bool                `json:"skip_p2p_preflight"`
+	Tenant            string              `json:"tenant"`
+	HTTPBase          string              `json:"http_base"`
+	APIKeyEnv         string              `json:"api_key_env"`
+	PasswordEnv       string              `json:"password_env"`
+	UsersPerMachine   int                 `json:"users_per_machine"`
+	Endpoints         map[string][]string `json:"endpoints"`
+	DialIPs           map[string][]string `json:"dial_ips,omitempty"`
+	InsecureTLS       bool                `json:"insecure_tls"`
+	PrepareWorkers    int                 `json:"prepare_workers"`
+	ConnectRamp       string              `json:"connect_ramp"`
+	ReconnectWorkers  int                 `json:"reconnect_workers"`
+	ReconnectMinWait  string              `json:"reconnect_min_wait"`
+	ReconnectMaxWait  string              `json:"reconnect_max_wait"`
+	CommandTimeout    string              `json:"command_timeout"`
+	WSPingInterval    string              `json:"ws_ping_interval"`
+	P2PMessages       int                 `json:"p2p_messages_per_user"`
+	P2PInterval       string              `json:"p2p_interval"`
+	GroupSenders      int                 `json:"group_senders_per_machine"`
+	GroupRounds       int                 `json:"group_rounds"`
+	GroupInterval     string              `json:"group_publish_interval"`
+	MixedP2PUsers     int                 `json:"mixed_p2p_users_per_machine"`
+	MixedGroupSenders int                 `json:"mixed_group_senders_per_machine"`
+	IdleDuration      string              `json:"idle_duration"`
+	DrainP2P          string              `json:"drain_p2p"`
+	DrainGroup        string              `json:"drain_group"`
+	DeliveryQuiet     string              `json:"delivery_quiet_period"`
+	DeliveryTimeout   string              `json:"delivery_quiet_timeout"`
+	PhonePrefix       string              `json:"registration_phone_prefix"`
+	VerifyCodeEnv     string              `json:"verification_code_env"`
+	HistoryWorkers    int                 `json:"history_workers"`
+	HistoryPageSize   int                 `json:"history_page_size"`
+	HistoryInterval   string              `json:"history_query_interval"`
+	HistoryPageWait   string              `json:"history_page_wait"`
+	HistorySettle     string              `json:"history_settle"`
+	HistoryTimeout    string              `json:"history_timeout"`
+	CloseRamp         string              `json:"close_ramp"`
+	PreflightWorkers  int                 `json:"preflight_workers"`
+	SkipP2PPreflight  bool                `json:"skip_p2p_preflight"`
 }
 
 func loadConfig(path string) (*Config, error) {
@@ -58,33 +77,128 @@ func loadConfig(path string) (*Config, error) {
 	if cfg.ConnectRamp == "" {
 		cfg.ConnectRamp = "20s"
 	}
+	if cfg.ReconnectWorkers <= 0 {
+		cfg.ReconnectWorkers = 8
+	}
+	if cfg.ReconnectWorkers > 128 {
+		return nil, errors.New("reconnect_workers must not exceed 128")
+	}
+	if cfg.ReconnectMinWait == "" {
+		cfg.ReconnectMinWait = "2s"
+	}
+	if _, err = configDuration(cfg.ReconnectMinWait); err != nil {
+		return nil, fmt.Errorf("reconnect_min_wait: %w", err)
+	}
+	if cfg.ReconnectMaxWait == "" {
+		cfg.ReconnectMaxWait = "30s"
+	}
+	minReconnect, _ := configDuration(cfg.ReconnectMinWait)
+	maxReconnect, err := configDuration(cfg.ReconnectMaxWait)
+	if err != nil {
+		return nil, fmt.Errorf("reconnect_max_wait: %w", err)
+	}
+	if maxReconnect < minReconnect {
+		return nil, errors.New("reconnect_max_wait must be greater than or equal to reconnect_min_wait")
+	}
 	if cfg.CommandTimeout == "" {
 		cfg.CommandTimeout = "20s"
 	}
+	if cfg.WSPingInterval == "" {
+		cfg.WSPingInterval = "20s"
+	}
+	if _, err = configDuration(cfg.WSPingInterval); err != nil {
+		return nil, fmt.Errorf("ws_ping_interval: %w", err)
+	}
 	if cfg.P2PMessages <= 0 {
 		cfg.P2PMessages = 10
 	}
 	if cfg.P2PInterval == "" {
 		cfg.P2PInterval = "1s"
 	}
+	if cfg.GroupRounds <= 0 {
+		cfg.GroupRounds = 2
+	}
+	if cfg.GroupInterval == "" {
+		cfg.GroupInterval = "100ms"
+	}
+	if _, err = configDuration(cfg.GroupInterval); err != nil {
+		return nil, fmt.Errorf("group_publish_interval: %w", err)
+	}
+	if cfg.GroupSenders < 0 {
+		return nil, errors.New("group_senders_per_machine must not be negative")
+	}
+	if cfg.MixedP2PUsers < 0 {
+		return nil, errors.New("mixed_p2p_users_per_machine must not be negative")
+	}
+	if cfg.MixedGroupSenders < 0 {
+		return nil, errors.New("mixed_group_senders_per_machine must not be negative")
+	}
+	if cfg.IdleDuration == "" {
+		cfg.IdleDuration = "15m"
+	}
+	if _, err = configDuration(cfg.IdleDuration); err != nil {
+		return nil, fmt.Errorf("idle_duration: %w", err)
+	}
 	if cfg.DrainP2P == "" {
 		cfg.DrainP2P = "30s"
 	}
 	if cfg.DrainGroup == "" {
 		cfg.DrainGroup = "60s"
 	}
+	if cfg.DeliveryQuiet == "" {
+		cfg.DeliveryQuiet = "10s"
+	}
+	if _, err = configDuration(cfg.DeliveryQuiet); err != nil {
+		return nil, fmt.Errorf("delivery_quiet_period: %w", err)
+	}
+	if cfg.DeliveryTimeout == "" {
+		cfg.DeliveryTimeout = "3m"
+	}
+	if _, err = configDuration(cfg.DeliveryTimeout); err != nil {
+		return nil, fmt.Errorf("delivery_quiet_timeout: %w", err)
+	}
 	if cfg.HistoryWorkers <= 0 {
-		cfg.HistoryWorkers = 48
+		cfg.HistoryWorkers = 12
 	}
 	if cfg.HistoryWorkers > 128 {
 		return nil, errors.New("history_workers must not exceed 128")
 	}
+	if cfg.HistoryPageSize <= 0 {
+		cfg.HistoryPageSize = 10
+	}
+	if cfg.HistoryPageSize > 200 {
+		return nil, errors.New("history_page_size must not exceed 200")
+	}
+	if cfg.HistoryInterval == "" {
+		cfg.HistoryInterval = "500ms"
+	}
+	if _, err = configDuration(cfg.HistoryInterval); err != nil {
+		return nil, fmt.Errorf("history_query_interval: %w", err)
+	}
+	if cfg.HistoryPageWait == "" {
+		cfg.HistoryPageWait = "3s"
+	}
+	if _, err = configDuration(cfg.HistoryPageWait); err != nil {
+		return nil, fmt.Errorf("history_page_wait: %w", err)
+	}
 	if cfg.HistoryTimeout == "" {
 		cfg.HistoryTimeout = "3m"
 	}
+	if cfg.HistorySettle == "" {
+		cfg.HistorySettle = "5m"
+	}
+	if _, err = configDuration(cfg.HistorySettle); err != nil {
+		return nil, fmt.Errorf("history_settle: %w", err)
+	}
 	if _, err = configDuration(cfg.HistoryTimeout); err != nil {
 		return nil, fmt.Errorf("history_timeout: %w", err)
 	}
+	if cfg.CloseRamp == "" {
+		cfg.CloseRamp = "10s"
+	}
+	if _, err = configDuration(cfg.CloseRamp); err != nil {
+		return nil, fmt.Errorf("close_ramp: %w", err)
+	}
 	if cfg.PreflightWorkers <= 0 {
 		cfg.PreflightWorkers = 32
 	}
@@ -98,6 +212,11 @@ func loadConfig(path string) (*Config, error) {
 		if len(cfg.Endpoints[machine]) == 0 {
 			return nil, fmt.Errorf("at least one endpoint is required for machine %s", machine)
 		}
+		for _, ip := range cfg.DialIPs[machine] {
+			if net.ParseIP(strings.TrimSpace(ip)) == nil {
+				return nil, fmt.Errorf("invalid dial IP %q for machine %s", ip, machine)
+			}
+		}
 	}
 	if cfg.PhonePrefix != "" {
 		if len(cfg.PhonePrefix) != 7 || strings.Trim(cfg.PhonePrefix, "0123456789") != "" {
@@ -172,6 +291,7 @@ type AccountRecord struct {
 	TokenExpires time.Time `json:"token_expires,omitempty"`
 	P2PTopic     string    `json:"p2p_topic,omitempty"`
 	Endpoint     string    `json:"endpoint,omitempty"`
+	DialIP       string    `json:"-"`
 }
 
 func newManifest(cfg *Config) *Manifest {
@@ -343,39 +463,95 @@ type AcceptedMessage struct {
 }
 
 type AgentSummary struct {
-	RunID               string            `json:"run_id"`
-	Scenario            string            `json:"scenario"`
-	Machine             string            `json:"machine"`
-	StartedAt           time.Time         `json:"started_at"`
-	LoadEndedAt         time.Time         `json:"load_ended_at"`
-	FinishedAt          time.Time         `json:"finished_at"`
-	ExpectedConnections int               `json:"expected_connections"`
-	ReadyConnections    int               `json:"ready_connections"`
-	PublishAttempted    int64             `json:"publish_attempted"`
-	PublishAccepted     int64             `json:"publish_accepted"`
-	PublishRejected     int64             `json:"publish_rejected"`
-	PublishErrors       map[string]int64  `json:"publish_errors,omitempty"`
-	ExpectedPeer        int64             `json:"expected_peer"`
-	ReceivedPeer        int64             `json:"received_peer"`
-	ExpectedEcho        int64             `json:"expected_echo"`
-	ReceivedEcho        int64             `json:"received_echo"`
-	ExpectedGroup       int64             `json:"expected_group"`
-	ReceivedGroup       int64             `json:"received_group"`
-	RealtimeLost        int64             `json:"realtime_lost"`
-	RealtimeLostStored  int64             `json:"realtime_lost_but_persisted"`
-	Duplicates          int64             `json:"duplicates"`
-	OutOfOrder          int64             `json:"out_of_order"`
-	Disconnects         int64             `json:"disconnects"`
-	UnexpectedMessages  int64             `json:"unexpected_messages"`
-	HistoryChecked      int64             `json:"history_checked"`
-	HistoryFound        int64             `json:"history_found"`
-	PersistenceLost     int64             `json:"persistence_lost"`
-	AckLatency          HistogramSnapshot `json:"ack_latency"`
-	DeliveryLatency     HistogramSnapshot `json:"delivery_latency"`
-	Errors              []string          `json:"errors,omitempty"`
-	Missing             []MissingDelivery `json:"missing,omitempty"`
-	PersistenceMissing  []string          `json:"persistence_missing,omitempty"`
-	AcceptedLocal       []AcceptedMessage `json:"accepted_local,omitempty"`
+	RunID                  string                  `json:"run_id"`
+	Scenario               string                  `json:"scenario"`
+	Machine                string                  `json:"machine"`
+	StartedAt              time.Time               `json:"started_at"`
+	LoadEndedAt            time.Time               `json:"load_ended_at"`
+	FinishedAt             time.Time               `json:"finished_at"`
+	ExpectedConnections    int                     `json:"expected_connections"`
+	ReadyConnections       int                     `json:"ready_connections"`
+	PublishAttempted       int64                   `json:"publish_attempted"`
+	PublishAccepted        int64                   `json:"publish_accepted"`
+	PublishRejected        int64                   `json:"publish_rejected"`
+	PublishOutcomeUnknown  int64                   `json:"publish_outcome_unknown"`
+	PublishErrors          map[string]int64        `json:"publish_errors,omitempty"`
+	CtrlTrackingEnabled    bool                    `json:"ctrl_tracking_enabled"`
+	PublishCtrlObserved    int64                   `json:"publish_ctrl_observed"`
+	PublishCtrlOver20      int64                   `json:"publish_ctrl_over_20s"`
+	PublishLateCtrl        int64                   `json:"publish_ctrl_late"`
+	PublishLateAccepted    int64                   `json:"publish_ctrl_late_accepted"`
+	PublishCtrlUnresolved  int64                   `json:"publish_ctrl_unresolved"`
+	PublishCtrlLatency     HistogramSnapshot       `json:"publish_ctrl_latency"`
+	CtrlObservationSamples []CtrlObservationSample `json:"ctrl_observation_samples,omitempty"`
+	ExpectedPeer           int64                   `json:"expected_peer"`
+	ReceivedPeer           int64                   `json:"received_peer"`
+	ExpectedEcho           int64                   `json:"expected_echo"`
+	ReceivedEcho           int64                   `json:"received_echo"`
+	ExpectedGroup          int64                   `json:"expected_group"`
+	ReceivedGroup          int64                   `json:"received_group"`
+	RealtimeLost           int64                   `json:"realtime_lost"`
+	RealtimeLostStored     int64                   `json:"realtime_lost_but_persisted"`
+	Duplicates             int64                   `json:"duplicates"`
+	OutOfOrder             int64                   `json:"out_of_order"`
+	OrderingViolations     []OrderingViolation     `json:"ordering_violations,omitempty"`
+	Disconnects            int64                   `json:"disconnects"`
+	DisconnectReasons      map[string]int64        `json:"disconnect_reasons,omitempty"`
+	DisconnectSamples      []DisconnectSample      `json:"disconnect_samples,omitempty"`
+	UnexpectedMessages     int64                   `json:"unexpected_messages"`
+	HistoryChecked         int64                   `json:"history_checked"`
+	HistoryFound           int64                   `json:"history_found"`
+	HistoryUnackedChecked  int64                   `json:"history_unacked_observed_checked"`
+	HistoryUnackedFound    int64                   `json:"history_unacked_observed_found"`
+	PersistenceLost        int64                   `json:"persistence_lost"`
+	AckLatency             HistogramSnapshot       `json:"ack_latency"`
+	DeliveryLatency        HistogramSnapshot       `json:"delivery_latency"`
+	DeliveryLatencyLocal   HistogramSnapshot       `json:"delivery_latency_local"`
+	DeliveryLatencyCross   HistogramSnapshot       `json:"delivery_latency_cross_machine"`
+	CrossClockSkewSamples  int64                   `json:"cross_machine_negative_latency_samples"`
+	CallbackQueue          CallbackQueueSnapshot   `json:"callback_queue"`
+	Errors                 []string                `json:"errors,omitempty"`
+	Missing                []MissingDelivery       `json:"missing,omitempty"`
+	PersistenceMissing     []string                `json:"persistence_missing,omitempty"`
+	AcceptedLocal          []AcceptedMessage       `json:"accepted_local,omitempty"`
+}
+
+type CtrlObservationSample struct {
+	Machine    string    `json:"machine"`
+	Index      int       `json:"index"`
+	ID         string    `json:"id"`
+	Code       int       `json:"code"`
+	SentAt     time.Time `json:"sent_at"`
+	ReceivedAt time.Time `json:"received_at"`
+	LatencyMS  float64   `json:"latency_ms"`
+	Late       bool      `json:"late"`
+}
+
+type CallbackQueueSnapshot struct {
+	Current          int64   `json:"current"`
+	Processing       int64   `json:"processing"`
+	Maximum          int64   `json:"maximum"`
+	Enqueued         int64   `json:"enqueued"`
+	Completed        int64   `json:"completed"`
+	WaitSecondsTotal float64 `json:"wait_seconds_total"`
+	WaitSecondsMax   float64 `json:"wait_seconds_max"`
+}
+
+type DisconnectSample struct {
+	ReceiverMachine string    `json:"receiver_machine"`
+	ReceiverIndex   int       `json:"receiver_index"`
+	Category        string    `json:"category"`
+	Error           string    `json:"error"`
+	At              time.Time `json:"at"`
+}
+
+type OrderingViolation struct {
+	ReceiverMachine string `json:"receiver_machine"`
+	ReceiverIndex   int    `json:"receiver_index"`
+	TopicHash       string `json:"topic_hash"`
+	PreviousSeq     int64  `json:"previous_seq"`
+	CurrentSeq      int64  `json:"current_seq"`
+	ClientMid       string `json:"client_mid"`
 }
 
 type MissingDelivery struct {

loadtest/im-pressure/model_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"os"
 	"path/filepath"
+	"reflect"
 	"testing"
 )
 
@@ -16,11 +17,54 @@ func TestLoadConfigAppliesBoundedHistoryDefaults(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if cfg.HistoryWorkers != 48 || cfg.HistoryTimeout != "3m" || cfg.PreflightWorkers != 32 {
+	if cfg.HistoryWorkers != 12 || cfg.HistoryPageSize != 10 || cfg.HistoryInterval != "500ms" ||
+		cfg.HistoryPageWait != "3s" || cfg.CloseRamp != "10s" ||
+		cfg.HistorySettle != "5m" || cfg.HistoryTimeout != "3m" ||
+		cfg.PreflightWorkers != 32 || cfg.WSPingInterval != "20s" {
 		t.Fatalf("unexpected defaults: %+v", cfg)
 	}
 }
 
+func TestAssignAgentEndpointsDistributesDialIPsAcrossMachines(t *testing.T) {
+	cfg := &Config{
+		Endpoints: map[string][]string{"a": {"wss://api.example.test/ws"}, "b": {"wss://api.example.test/ws"}},
+		DialIPs:   map[string][]string{"a": {"192.0.2.1", "192.0.2.2", "192.0.2.3"}, "b": {"192.0.2.1", "192.0.2.2", "192.0.2.3"}},
+	}
+	a := []AccountRecord{{Index: 1}, {Index: 2}, {Index: 3}}
+	b := []AccountRecord{{Index: 1}, {Index: 2}, {Index: 3}}
+	assignAgentEndpoints(cfg, "a", a)
+	assignAgentEndpoints(cfg, "b", b)
+	got := []string{a[0].DialIP, b[0].DialIP, a[1].DialIP, b[1].DialIP, a[2].DialIP, b[2].DialIP}
+	want := []string{"192.0.2.1", "192.0.2.2", "192.0.2.3", "192.0.2.1", "192.0.2.2", "192.0.2.3"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected dial IP distribution: got=%v want=%v", got, want)
+	}
+}
+
+func TestLoadConfigRejectsInvalidDialIP(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	raw := []byte(`{"http_base":"https://example.test","endpoints":{"a":["wss://a"],"b":["wss://b"]},"dial_ips":{"a":["not-an-ip"]}}`)
+	if err := os.WriteFile(path, raw, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := loadConfig(path); err == nil {
+		t.Fatal("invalid dial IP was accepted")
+	}
+}
+
+func TestSingleMachineExampleUsesSixtyPercentCapacity(t *testing.T) {
+	cfg, err := loadConfig("config.single-machine.example.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.UsersPerMachine != 600 || cfg.CloseRamp != "60s" {
+		t.Fatalf("unexpected single-machine capacity: users=%d close_ramp=%s", cfg.UsersPerMachine, cfg.CloseRamp)
+	}
+	if len(cfg.Endpoints["a"]) != 1 || len(cfg.Endpoints["b"]) != 1 {
+		t.Fatalf("single-machine endpoints must define both logical agents: %+v", cfg.Endpoints)
+	}
+}
+
 func TestNewManifestDistributesUsersAndEndpoints(t *testing.T) {
 	cfg := &Config{Tenant: "006", UsersPerMachine: 3, Endpoints: map[string][]string{
 		"a": {"ws://a1", "ws://a2"}, "b": {"ws://b1"},

loadtest/im-pressure/prepare.go

@@ -49,7 +49,7 @@ func runPrepare(ctx context.Context, cfg *Config, manifestPath string) error {
 	if err = saveManifest(manifestPath, manifest); err != nil {
 		return err
 	}
-	if err = prepareGroup(ctx, cfg, manifest, api); err != nil {
+	if err = prepareGroup(ctx, cfg, manifest, api, manifestPath); err != nil {
 		return err
 	}
 	if err = saveManifest(manifestPath, manifest); err != nil {
@@ -127,12 +127,23 @@ func prepareFriendships(ctx context.Context, cfg *Config, manifest *Manifest, ap
 	err := parallelAccounts(ctx, pairs, cfg.PrepareWorkers, func(a AccountRecord) error {
 		return retryPrepareOperation(ctx, fmt.Sprintf("friend-pair-%04d", a.Index), func() error {
 			b := *accounts[accountKey("b", a.Index)]
-			if a.P2PTopic != "" && b.P2PTopic == a.P2PTopic {
-				return nil
-			}
 			if a.UserID == "" || b.UserID == "" {
 				return fmt.Errorf("pair %d has missing user ID", a.Index)
 			}
+			conversation, conversationErr := api.ensureP2P(ctx, a, b)
+			if conversationErr == nil && conversation.Relationship == "friend" && conversation.Topic != "" {
+				mu.Lock()
+				accounts[accountKey("a", a.Index)].P2PTopic = conversation.Topic
+				accounts[accountKey("b", a.Index)].P2PTopic = conversation.Topic
+				mu.Unlock()
+				return nil
+			}
+			if conversationErr != nil {
+				var apiErr *apiError
+				if !errors.As(conversationErr, &apiErr) || apiErr.Status != http.StatusForbidden {
+					return fmt.Errorf("check friend pair %d: %w", a.Index, conversationErr)
+				}
+			}
 			request, requestErr := api.createFriendRequest(ctx, a, b)
 			if requestErr == nil && request.Status == "pending" {
 				if _, requestErr = api.acceptFriendRequest(ctx, b, request.RequestID); requestErr != nil {
@@ -173,7 +184,7 @@ func prepareFriendships(ctx context.Context, cfg *Config, manifest *Manifest, ap
 	return err
 }
 
-func prepareGroup(ctx context.Context, cfg *Config, manifest *Manifest, api *apiClient) error {
+func prepareGroup(ctx context.Context, cfg *Config, manifest *Manifest, api *apiClient, manifestPath string) error {
 	if err := parallelAccounts(ctx, manifest.Accounts, cfg.PrepareWorkers, func(account AccountRecord) error {
 		return retryPrepareOperation(ctx, "privacy-"+account.Username, func() error {
 			return api.disableGroupInviteVerification(ctx, account)
@@ -189,6 +200,9 @@ func prepareGroup(ctx context.Context, cfg *Config, manifest *Manifest, api *api
 			return err
 		}
 		manifest.GroupTopic = group.Topic
+		if err = saveManifest(manifestPath, manifest); err != nil {
+			return fmt.Errorf("checkpoint created group: %w", err)
+		}
 		log.Printf("created load-test group topic_hash=%s", topicHash(group.Topic))
 	}
 	memberIDs := make([]string, 0, len(manifest.Accounts)-1)
@@ -203,20 +217,9 @@ func prepareGroup(ctx context.Context, cfg *Config, manifest *Manifest, api *api
 		if end > len(memberIDs) {
 			end = len(memberIDs)
 		}
-		var response *groupInvitationResponse
-		err := retryPrepareOperation(ctx, fmt.Sprintf("group-invite-%03d", batch), func() error {
-			var inviteErr error
-			response, inviteErr = api.inviteGroup(ctx, owner, manifest.GroupTopic, batch, memberIDs[offset:end])
-			return inviteErr
-		})
-		if err != nil {
+		if err := ensureGroupMembers(ctx, api, owner, manifest.GroupTopic, batch, memberIDs[offset:end]); err != nil {
 			return fmt.Errorf("invite group batch %d: %w", batch, err)
 		}
-		for _, item := range response.Items {
-			if item.Status != "joined" && item.Status != "already_member" {
-				return fmt.Errorf("invite user %s status=%s reason=%s", item.UserID, item.Status, item.Reason)
-			}
-		}
 	}
 	count, err := api.countGroupMembers(ctx, owner, manifest.GroupTopic)
 	if err != nil {
@@ -229,9 +232,60 @@ func prepareGroup(ctx context.Context, cfg *Config, manifest *Manifest, api *api
 	return nil
 }
 
-func retryPrepareOperation(ctx context.Context, label string, operation func() error) error {
+func ensureGroupMembers(ctx context.Context, api *apiClient, owner AccountRecord, topic string, batch int, desired []string) error {
 	var lastErr error
-	for attempt := 1; attempt <= 6; attempt++ {
+	for attempt := 1; attempt <= 12; attempt++ {
+		members, err := api.groupMemberIDs(ctx, owner, topic)
+		if err != nil {
+			lastErr = fmt.Errorf("list current members: %w", err)
+		} else {
+			missing := make([]string, 0, len(desired))
+			for _, userID := range desired {
+				if !members[userID] {
+					missing = append(missing, userID)
+				}
+			}
+			if len(missing) == 0 {
+				return nil
+			}
+			response, inviteErr := api.inviteGroup(ctx, owner, topic, batch, missing)
+			if inviteErr != nil {
+				lastErr = inviteErr
+			} else {
+				lastErr = nil
+				for _, item := range response.Items {
+					if item.Status != "joined" && item.Status != "already_member" {
+						lastErr = fmt.Errorf("invite user %s status=%s reason=%s", item.UserID, item.Status, item.Reason)
+						break
+					}
+				}
+				if lastErr == nil {
+					continue
+				}
+			}
+		}
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		if attempt == 12 {
+			break
+		}
+		delay := time.Duration(attempt*5) * time.Second
+		log.Printf("operation=group-invite-%03d attempt=%d failed; retry_in=%s: %v", batch, attempt, delay, lastErr)
+		if err := waitContext(ctx, delay); err != nil {
+			return err
+		}
+	}
+	return fmt.Errorf("missing members not recovered after retries: %w", lastErr)
+}
+
+func retryPrepareOperation(ctx context.Context, label string, operation func() error) error {
+	return retryOperation(ctx, label, 6, operation)
+}
+
+func retryOperation(ctx context.Context, label string, attempts int, operation func() error) error {
+	var lastErr error
+	for attempt := 1; attempt <= attempts; attempt++ {
 		if err := operation(); err == nil {
 			return nil
 		} else {
@@ -240,6 +294,9 @@ func retryPrepareOperation(ctx context.Context, label string, operation func() e
 		if ctx.Err() != nil {
 			return ctx.Err()
 		}
+		if attempt == attempts {
+			break
+		}
 		delay := time.Duration(attempt*5) * time.Second
 		log.Printf("operation=%s attempt=%d failed; retry_in=%s: %v", label, attempt, delay, lastErr)
 		if err := waitContext(ctx, delay); err != nil {

loadtest/im-pressure/recorder.go

@@ -2,46 +2,91 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"math/bits"
+	"net"
+	"sort"
 	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
 )
 
+const observationShardCount = 64
+
 type observation struct {
-	topic string
-	seq   int64
-	bits  []uint64
+	topic         string
+	seq           int64
+	senderMachine string
+	senderIndex   int
+	scenario      string
+	sentAt        int64
+	bits          []atomic.Uint64
+}
+
+type observationView struct {
+	topic         string
+	seq           int64
+	senderMachine string
+	senderIndex   int
+	scenario      string
+	sentAt        int64
+	bits          []uint64
+}
+
+type observationShard struct {
+	mu       sync.RWMutex
+	observed map[string]*observation
+	history  map[string]bool
+}
+
+type sequenceState struct {
+	mu   sync.Mutex
+	last map[string]int64
 }
 
 type deliveryRecorder struct {
-	machine     string
-	localUsers  int
-	latency     *DurationHistogram
-	disconnects atomic.Int64
-	received    atomic.Int64
-	runID       atomic.Value
-	historyMode atomic.Bool
+	machine      string
+	localUsers   int
+	latency      *DurationHistogram
+	localLatency *DurationHistogram
+	crossLatency *DurationHistogram
+	disconnects  atomic.Int64
+	received     atomic.Int64
+	runID        atomic.Value
+	historyMode  atomic.Bool
 
-	mu         sync.Mutex
-	observed   map[string]*observation
-	lastSeq    []map[string]int64
-	duplicates int64
-	outOfOrder int64
-	malformed  int64
-	history    map[string]bool
+	shards                []observationShard
+	sequences             []sequenceState
+	duplicates            atomic.Int64
+	outOfOrder            atomic.Int64
+	malformed             atomic.Int64
+	crossClockSkewSamples atomic.Int64
+
+	orderingMu sync.Mutex
+	ordering   []OrderingViolation
+
+	disconnectMu      sync.Mutex
+	disconnectReasons map[string]int64
+	disconnectSamples []DisconnectSample
 }
 
 func newDeliveryRecorder(runID, machine string, localUsers int) *deliveryRecorder {
-	lastSeq := make([]map[string]int64, localUsers)
-	for i := range lastSeq {
-		lastSeq[i] = make(map[string]int64)
+	shards := make([]observationShard, observationShardCount)
+	for i := range shards {
+		shards[i].observed = make(map[string]*observation)
+		shards[i].history = make(map[string]bool)
+	}
+	sequences := make([]sequenceState, localUsers)
+	for i := range sequences {
+		sequences[i].last = make(map[string]int64)
 	}
 	recorder := &deliveryRecorder{
 		machine: machine, localUsers: localUsers, latency: NewDurationHistogram(),
-		observed: make(map[string]*observation), lastSeq: lastSeq, history: make(map[string]bool),
+		localLatency: NewDurationHistogram(), crossLatency: NewDurationHistogram(),
+		shards: shards, sequences: sequences, disconnectReasons: make(map[string]int64),
 	}
 	recorder.runID.Store(runID)
 	return recorder
@@ -49,6 +94,14 @@ func newDeliveryRecorder(runID, machine string, localUsers int) *deliveryRecorde
 
 func (r *deliveryRecorder) setRunID(runID string) { r.runID.Store(runID) }
 
+func (r *deliveryRecorder) resetDisconnects() {
+	r.disconnectMu.Lock()
+	r.disconnects.Store(0)
+	r.disconnectReasons = make(map[string]int64)
+	r.disconnectSamples = nil
+	r.disconnectMu.Unlock()
+}
+
 func (r *deliveryRecorder) onData(account AccountRecord, data dataPacket) {
 	runID, _ := r.runID.Load().(string)
 	mid, _ := data.Head["x-im-client-mid"].(string)
@@ -56,91 +109,269 @@ func (r *deliveryRecorder) onData(account AccountRecord, data dataPacket) {
 		return
 	}
 	var content struct {
-		RunID  string `json:"run_id"`
-		SentAt int64  `json:"sent_at_unix_nano"`
+		RunID         string `json:"run_id"`
+		SenderMachine string `json:"sender_machine"`
+		SenderIndex   int    `json:"sender_index"`
+		Scenario      string `json:"scenario"`
+		SentAt        int64  `json:"sent_at_unix_nano"`
 	}
 	if json.Unmarshal(data.Content, &content) != nil || content.RunID != runID {
-		r.mu.Lock()
-		r.malformed++
-		r.mu.Unlock()
+		r.malformed.Add(1)
 		return
 	}
 	if r.historyMode.Load() {
-		r.mu.Lock()
-		r.history[mid] = true
-		r.mu.Unlock()
+		shard := r.shard(mid)
+		shard.mu.Lock()
+		shard.history[mid] = true
+		shard.mu.Unlock()
 		return
 	}
 	index := account.Index - 1
 	if index < 0 || index >= r.localUsers {
 		return
 	}
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	obs := r.observed[mid]
+	shard := r.shard(mid)
+	shard.mu.RLock()
+	obs := shard.observed[mid]
+	shard.mu.RUnlock()
 	if obs == nil {
-		obs = &observation{topic: data.Topic, seq: data.Seq, bits: make([]uint64, (r.localUsers+63)/64)}
-		r.observed[mid] = obs
+		shard.mu.Lock()
+		obs = shard.observed[mid]
+		if obs == nil {
+			obs = &observation{topic: data.Topic, seq: data.Seq, senderMachine: content.SenderMachine,
+				senderIndex: content.SenderIndex, scenario: content.Scenario, sentAt: content.SentAt,
+				bits: make([]atomic.Uint64, (r.localUsers+63)/64)}
+			shard.observed[mid] = obs
+		}
+		shard.mu.Unlock()
 	}
 	word, bit := index/64, uint(index%64)
 	mask := uint64(1) << bit
-	if obs.bits[word]&mask != 0 {
-		r.duplicates++
+	if !markObservationBit(obs.bits, word, mask) {
+		r.duplicates.Add(1)
 		return
 	}
-	obs.bits[word] |= mask
 	r.received.Add(1)
-	if previous := r.lastSeq[index][data.Topic]; previous > 0 && data.Seq < previous {
-		r.outOfOrder++
+	sequence := &r.sequences[index]
+	sequence.mu.Lock()
+	previous := sequence.last[data.Topic]
+	violation := previous > 0 && data.Seq < previous
+	if data.Seq > previous {
+		sequence.last[data.Topic] = data.Seq
 	}
-	if data.Seq > r.lastSeq[index][data.Topic] {
-		r.lastSeq[index][data.Topic] = data.Seq
+	sequence.mu.Unlock()
+	if violation {
+		r.outOfOrder.Add(1)
+		r.orderingMu.Lock()
+		if len(r.ordering) < 100 {
+			r.ordering = append(r.ordering, OrderingViolation{
+				ReceiverMachine: r.machine,
+				ReceiverIndex:   account.Index,
+				TopicHash:       topicHash(data.Topic),
+				PreviousSeq:     previous,
+				CurrentSeq:      data.Seq,
+				ClientMid:       mid,
+			})
+		}
+		r.orderingMu.Unlock()
 	}
 	if content.SentAt > 0 {
-		r.latency.Observe(time.Since(time.Unix(0, content.SentAt)))
+		delay := time.Since(time.Unix(0, content.SentAt))
+		r.latency.Observe(delay)
+		senderMachine := content.SenderMachine
+		if senderMachine == "" {
+			senderMachine = senderMachineFromClientMid(runID, mid)
+		}
+		if senderMachine == r.machine {
+			r.localLatency.Observe(delay)
+		} else if delay < 0 {
+			r.crossClockSkewSamples.Add(1)
+		} else {
+			r.crossLatency.Observe(delay)
+		}
 	}
 }
 
+func senderMachineFromClientMid(runID, mid string) string {
+	prefix := strings.TrimPrefix(mid, runID+"-")
+	parts := strings.SplitN(prefix, "-", 3)
+	if len(parts) < 2 {
+		return ""
+	}
+	return parts[1]
+}
+
 func (r *deliveryRecorder) metricCounts() (received, duplicates, outOfOrder, disconnects int64) {
-	r.mu.Lock()
-	duplicates = r.duplicates
-	outOfOrder = r.outOfOrder
-	r.mu.Unlock()
-	return r.received.Load(), duplicates, outOfOrder, r.disconnects.Load()
+	return r.received.Load(), r.duplicates.Load(), r.outOfOrder.Load(), r.disconnects.Load()
 }
 
 func (r *deliveryRecorder) beginHistory() { r.historyMode.Store(true) }
 
 func (r *deliveryRecorder) historyFound(mid string) bool {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	return r.history[mid]
+	shard := r.shard(mid)
+	shard.mu.RLock()
+	found := shard.history[mid]
+	shard.mu.RUnlock()
+	return found
 }
 
-func (r *deliveryRecorder) onDisconnect(_ AccountRecord, _ error) {
+func (r *deliveryRecorder) historyFoundAll(messageIDs []string) bool {
+	for _, mid := range messageIDs {
+		if !r.historyFound(mid) {
+			return false
+		}
+	}
+	return true
+}
+
+func (r *deliveryRecorder) unackedObservedMessages(ledger []AcceptedMessage, scenario string) []AcceptedMessage {
+	accepted := make(map[string]bool, len(ledger))
+	for _, message := range ledger {
+		accepted[message.ClientMid] = true
+	}
+	runID, _ := r.runID.Load().(string)
+	messages := make([]AcceptedMessage, 0)
+	for i := range r.shards {
+		shard := &r.shards[i]
+		shard.mu.RLock()
+		for mid, obs := range shard.observed {
+			if accepted[mid] || obs.seq <= 0 || obs.topic == "" {
+				continue
+			}
+			kind := "p2p"
+			if strings.HasPrefix(obs.topic, "grp") {
+				kind = "group"
+			}
+			observedScenario := obs.scenario
+			if observedScenario == "" {
+				observedScenario = scenario
+			}
+			message := AcceptedMessage{RunID: runID, Scenario: observedScenario, Kind: kind,
+				ClientMid: mid, Topic: obs.topic, Seq: obs.seq, SenderMachine: obs.senderMachine,
+				SenderIndex: obs.senderIndex, PeerMachine: r.machine, PeerIndex: firstObservedAtomicIndex(obs.bits)}
+			if obs.sentAt > 0 {
+				message.SentAt = time.Unix(0, obs.sentAt).UTC()
+			}
+			messages = append(messages, message)
+		}
+		shard.mu.RUnlock()
+	}
+	sort.Slice(messages, func(i, j int) bool { return messages[i].ClientMid < messages[j].ClientMid })
+	return messages
+}
+
+func firstObservedIndex(words []uint64) int {
+	for wordIndex, word := range words {
+		if word != 0 {
+			return wordIndex*64 + bits.TrailingZeros64(word) + 1
+		}
+	}
+	return 0
+}
+
+func firstObservedAtomicIndex(words []atomic.Uint64) int {
+	for wordIndex := range words {
+		if word := words[wordIndex].Load(); word != 0 {
+			return wordIndex*64 + bits.TrailingZeros64(word) + 1
+		}
+	}
+	return 0
+}
+
+func markObservationBit(words []atomic.Uint64, word int, mask uint64) bool {
+	for {
+		current := words[word].Load()
+		if current&mask != 0 {
+			return false
+		}
+		if words[word].CompareAndSwap(current, current|mask) {
+			return true
+		}
+	}
+}
+
+func (r *deliveryRecorder) onDisconnect(account AccountRecord, err error) {
+	category := disconnectCategory(err)
+	r.disconnectMu.Lock()
 	r.disconnects.Add(1)
+	r.disconnectReasons[category]++
+	if len(r.disconnectSamples) < 100 {
+		message := ""
+		if err != nil {
+			message = err.Error()
+			if len(message) > 300 {
+				message = message[:300]
+			}
+		}
+		r.disconnectSamples = append(r.disconnectSamples, DisconnectSample{
+			ReceiverMachine: r.machine, ReceiverIndex: account.Index, Category: category,
+			Error: message, At: time.Now().UTC(),
+		})
+	}
+	r.disconnectMu.Unlock()
+}
+
+func disconnectCategory(err error) string {
+	if err == nil {
+		return "unknown"
+	}
+	if errors.Is(err, io.EOF) {
+		return "eof"
+	}
+	if errors.Is(err, net.ErrClosed) {
+		return "closed_connection"
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) && netErr.Timeout() {
+		return "timeout"
+	}
+	message := strings.ToLower(err.Error())
+	switch {
+	case strings.Contains(message, "close 1006") || strings.Contains(message, "abnormal closure"):
+		return "abnormal_close"
+	case strings.Contains(message, "close 1000") || strings.Contains(message, "normal closure"):
+		return "normal_close"
+	case strings.Contains(message, "connection reset"):
+		return "connection_reset"
+	case strings.Contains(message, "broken pipe"):
+		return "broken_pipe"
+	case strings.Contains(message, "timeout") || strings.Contains(message, "deadline exceeded"):
+		return "timeout"
+	case strings.Contains(message, "use of closed network connection"):
+		return "closed_connection"
+	default:
+		return "other"
+	}
 }
 
 func (r *deliveryRecorder) summarize(base AgentSummary, ledger []AcceptedMessage) AgentSummary {
 	base.DeliveryLatency = r.latency.Snapshot()
+	base.DeliveryLatencyLocal = r.localLatency.Snapshot()
+	base.DeliveryLatencyCross = r.crossLatency.Snapshot()
+	r.disconnectMu.Lock()
 	base.Disconnects = r.disconnects.Load()
+	base.DisconnectReasons = cloneCountMap(r.disconnectReasons)
+	base.DisconnectSamples = append([]DisconnectSample(nil), r.disconnectSamples...)
+	r.disconnectMu.Unlock()
 	runID, _ := r.runID.Load().(string)
 	accepted := make(map[string]AcceptedMessage, len(ledger))
 	const missingLimit = 100000
 
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	base.Duplicates = r.duplicates
-	base.OutOfOrder = r.outOfOrder
-	if r.malformed > 0 {
-		base.Errors = append(base.Errors, fmt.Sprintf("malformed run messages=%d", r.malformed))
+	base.Duplicates = r.duplicates.Load()
+	base.OutOfOrder = r.outOfOrder.Load()
+	base.CrossClockSkewSamples = r.crossClockSkewSamples.Load()
+	r.orderingMu.Lock()
+	base.OrderingViolations = append([]OrderingViolation(nil), r.ordering...)
+	r.orderingMu.Unlock()
+	if malformed := r.malformed.Load(); malformed > 0 {
+		base.Errors = append(base.Errors, fmt.Sprintf("malformed run messages=%d", malformed))
 	}
 	for _, message := range ledger {
 		if message.RunID != runID {
 			continue
 		}
 		accepted[message.ClientMid] = message
-		obs := r.observed[message.ClientMid]
+		obs := r.observationSnapshot(message.ClientMid)
 		switch message.Kind {
 		case "group":
 			base.ExpectedGroup += int64(r.localUsers)
@@ -168,10 +399,15 @@ func (r *deliveryRecorder) summarize(base AgentSummary, ledger []AcceptedMessage
 			}
 		}
 	}
-	for mid, obs := range r.observed {
-		if _, ok := accepted[mid]; !ok {
-			base.UnexpectedMessages += bitsetCount(obs.bits)
+	for i := range r.shards {
+		shard := &r.shards[i]
+		shard.mu.RLock()
+		for mid, obs := range shard.observed {
+			if _, ok := accepted[mid]; !ok {
+				base.UnexpectedMessages += atomicBitsetCount(obs.bits)
+			}
 		}
+		shard.mu.RUnlock()
 	}
 	base.RealtimeLost = (base.ExpectedPeer - base.ReceivedPeer) + (base.ExpectedGroup - base.ReceivedGroup)
 	if len(base.Missing) == missingLimit {
@@ -180,16 +416,18 @@ func (r *deliveryRecorder) summarize(base AgentSummary, ledger []AcceptedMessage
 	return base
 }
 
-func (r *deliveryRecorder) countRealtimeLostStored(ledger []AcceptedMessage) int64 {
+func (r *deliveryRecorder) countRealtimeLostStored(ledger []AcceptedMessage, storedMessageIDs []string) int64 {
 	runID, _ := r.runID.Load().(string)
-	r.mu.Lock()
-	defer r.mu.Unlock()
+	stored := make(map[string]bool, len(storedMessageIDs))
+	for _, mid := range storedMessageIDs {
+		stored[mid] = true
+	}
 	var count int64
 	for _, message := range ledger {
-		if message.RunID != runID || !r.history[message.ClientMid] {
+		if message.RunID != runID || !stored[message.ClientMid] {
 			continue
 		}
-		obs := r.observed[message.ClientMid]
+		obs := r.observationSnapshot(message.ClientMid)
 		switch message.Kind {
 		case "group":
 			for index := 1; index <= r.localUsers; index++ {
@@ -206,7 +444,44 @@ func (r *deliveryRecorder) countRealtimeLostStored(ledger []AcceptedMessage) int
 	return count
 }
 
-func observationHas(obs *observation, receiverIndex int) bool {
+func (r *deliveryRecorder) shard(mid string) *observationShard {
+	var hash uint32 = 2166136261
+	for i := 0; i < len(mid); i++ {
+		hash ^= uint32(mid[i])
+		hash *= 16777619
+	}
+	return &r.shards[hash%uint32(len(r.shards))]
+}
+
+func (r *deliveryRecorder) observationSnapshot(mid string) *observationView {
+	shard := r.shard(mid)
+	shard.mu.RLock()
+	obs := shard.observed[mid]
+	shard.mu.RUnlock()
+	if obs == nil {
+		return nil
+	}
+	view := &observationView{topic: obs.topic, seq: obs.seq, senderMachine: obs.senderMachine,
+		senderIndex: obs.senderIndex, scenario: obs.scenario, sentAt: obs.sentAt,
+		bits: make([]uint64, len(obs.bits))}
+	for i := range obs.bits {
+		view.bits[i] = obs.bits[i].Load()
+	}
+	return view
+}
+
+func cloneCountMap(source map[string]int64) map[string]int64 {
+	if len(source) == 0 {
+		return nil
+	}
+	clone := make(map[string]int64, len(source))
+	for key, value := range source {
+		clone[key] = value
+	}
+	return clone
+}
+
+func observationHas(obs *observationView, receiverIndex int) bool {
 	if obs == nil || receiverIndex <= 0 {
 		return false
 	}
@@ -215,6 +490,14 @@ func observationHas(obs *observation, receiverIndex int) bool {
 	return word < len(obs.bits) && obs.bits[word]&(uint64(1)<<bit) != 0
 }
 
+func atomicBitsetCount(words []atomic.Uint64) int64 {
+	var count int64
+	for i := range words {
+		count += int64(bits.OnesCount64(words[i].Load()))
+	}
+	return count
+}
+
 func bitsetCount(words []uint64) int64 {
 	var count int64
 	for _, word := range words {

loadtest/im-pressure/recorder_test.go

@@ -2,6 +2,9 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
+	"fmt"
+	"sync"
 	"testing"
 	"time"
 )
@@ -43,13 +46,137 @@ func TestDeliveryRecorderSeparatesHistoryFromRealtime(t *testing.T) {
 	if !recorder.historyFound(message.ClientMid) {
 		t.Fatal("history message was not recorded")
 	}
-	if got := recorder.countRealtimeLostStored([]AcceptedMessage{message}); got != 1 {
+	if got := recorder.countRealtimeLostStored([]AcceptedMessage{message}, []string{message.ClientMid}); got != 1 {
 		t.Fatalf("realtime lost but persisted=%d", got)
 	}
 }
 
+func TestDeliveryRecorderUsesSharedHistoryForRealtimeLostStored(t *testing.T) {
+	recorder := newDeliveryRecorder("run1", "b", 1)
+	message := AcceptedMessage{RunID: "run1", Kind: "group", ClientMid: "run1-g-a-0001-01", Topic: "grp-one", Seq: 10}
+
+	if got := recorder.countRealtimeLostStored([]AcceptedMessage{message}, []string{message.ClientMid}); got != 1 {
+		t.Fatalf("shared history count=%d want=1", got)
+	}
+	if got := recorder.countRealtimeLostStored([]AcceptedMessage{message}, nil); got != 0 {
+		t.Fatalf("empty shared history count=%d want=0", got)
+	}
+}
+
+func TestDeliveryRecorderExportsObservedMessagesWithoutAck(t *testing.T) {
+	recorder := newDeliveryRecorder("run1", "b", 2)
+	acked := AcceptedMessage{RunID: "run1", Scenario: "group", Kind: "group", ClientMid: "run1-g-a-0001-01",
+		Topic: "grp-one", Seq: 10, SenderMachine: "a", SenderIndex: 1}
+	unacked := AcceptedMessage{RunID: "run1", Scenario: "group", Kind: "group", ClientMid: "run1-g-a-0002-01",
+		Topic: "grp-one", Seq: 11, SenderMachine: "a", SenderIndex: 2}
+	recorder.onData(AccountRecord{Index: 1}, testData(acked, time.Now()))
+	recorder.onData(AccountRecord{Index: 2}, testData(unacked, time.Now()))
+
+	messages := recorder.unackedObservedMessages([]AcceptedMessage{acked}, "group")
+	if len(messages) != 1 || messages[0].ClientMid != unacked.ClientMid || messages[0].Seq != 11 ||
+		messages[0].PeerMachine != "b" || messages[0].PeerIndex != 2 || messages[0].SenderIndex != 2 {
+		t.Fatalf("unexpected observed ledger: %+v", messages)
+	}
+}
+
+func TestDeliveryRecorderCapturesOrderingViolationDetails(t *testing.T) {
+	recorder := newDeliveryRecorder("run1", "b", 1)
+	newer := AcceptedMessage{RunID: "run1", ClientMid: "run1-p-a-0001-02", Topic: "p2p-one", Seq: 12}
+	older := AcceptedMessage{RunID: "run1", ClientMid: "run1-p-a-0001-01", Topic: "p2p-one", Seq: 11}
+	recorder.onData(AccountRecord{Index: 1}, testData(newer, time.Now()))
+	recorder.onData(AccountRecord{Index: 1}, testData(older, time.Now()))
+
+	summary := recorder.summarize(AgentSummary{}, nil)
+	if summary.OutOfOrder != 1 || len(summary.OrderingViolations) != 1 {
+		t.Fatalf("out_of_order=%d violations=%+v", summary.OutOfOrder, summary.OrderingViolations)
+	}
+	violation := summary.OrderingViolations[0]
+	if violation.ReceiverMachine != "b" || violation.ReceiverIndex != 1 ||
+		violation.PreviousSeq != 12 || violation.CurrentSeq != 11 || violation.ClientMid != older.ClientMid {
+		t.Fatalf("unexpected violation: %+v", violation)
+	}
+}
+
+func TestDeliveryRecorderSeparatesLocalAndCrossMachineLatency(t *testing.T) {
+	recorder := newDeliveryRecorder("run1", "a", 1)
+	local := AcceptedMessage{RunID: "run1", ClientMid: "run1-p-a-0001-01", Topic: "p2p-one", Seq: 1}
+	cross := AcceptedMessage{RunID: "run1", ClientMid: "run1-p-b-0001-01", Topic: "p2p-one", Seq: 2}
+	recorder.onData(AccountRecord{Index: 1}, testData(local, time.Now().Add(-10*time.Millisecond)))
+	recorder.onData(AccountRecord{Index: 1}, testData(cross, time.Now().Add(time.Second)))
+
+	summary := recorder.summarize(AgentSummary{}, nil)
+	if summary.DeliveryLatencyLocal.Count != 1 || summary.DeliveryLatencyCross.Count != 0 {
+		t.Fatalf("unexpected split latency counts: local=%d cross=%d",
+			summary.DeliveryLatencyLocal.Count, summary.DeliveryLatencyCross.Count)
+	}
+	if summary.CrossClockSkewSamples != 1 {
+		t.Fatalf("cross clock skew samples=%d", summary.CrossClockSkewSamples)
+	}
+}
+
+func TestDeliveryRecorderConcurrentGroupFanout(t *testing.T) {
+	const users = 32
+	const messages = 64
+	recorder := newDeliveryRecorder("run1", "a", users)
+	ledger := make([]AcceptedMessage, messages)
+	for messageIndex := range ledger {
+		ledger[messageIndex] = AcceptedMessage{
+			RunID: "run1", Kind: "group", Topic: "grp-one", Seq: 1,
+			ClientMid: fmt.Sprintf("run1-g-b-%04d-01", messageIndex+1), SenderMachine: "b",
+		}
+	}
+
+	var writers sync.WaitGroup
+	for receiver := 1; receiver <= users; receiver++ {
+		for _, message := range ledger {
+			writers.Add(1)
+			go func(receiver int, message AcceptedMessage) {
+				defer writers.Done()
+				recorder.onData(AccountRecord{Index: receiver}, testData(message, time.Now().Add(-time.Millisecond)))
+			}(receiver, message)
+		}
+	}
+	writers.Wait()
+
+	summary := recorder.summarize(AgentSummary{}, ledger)
+	want := int64(users * messages)
+	if summary.ExpectedGroup != want || summary.ReceivedGroup != want || summary.RealtimeLost != 0 {
+		t.Fatalf("group expected/received/lost = %d/%d/%d, want %d/%d/0",
+			summary.ExpectedGroup, summary.ReceivedGroup, summary.RealtimeLost, want, want)
+	}
+	if summary.Duplicates != 0 || summary.DeliveryLatency.Count != want {
+		t.Fatalf("duplicates=%d latency samples=%d want=0/%d", summary.Duplicates, summary.DeliveryLatency.Count, want)
+	}
+}
+
+func TestDeliveryRecorderDisconnectDiagnostics(t *testing.T) {
+	recorder := newDeliveryRecorder("run1", "a", 1)
+	recorder.onDisconnect(AccountRecord{Index: 1}, errors.New("websocket: close 1006 (abnormal closure): unexpected EOF"))
+	recorder.onDisconnect(AccountRecord{Index: 1}, errors.New("read tcp: connection reset by peer"))
+
+	summary := recorder.summarize(AgentSummary{}, nil)
+	if summary.Disconnects != 2 || summary.DisconnectReasons["abnormal_close"] != 1 ||
+		summary.DisconnectReasons["connection_reset"] != 1 || len(summary.DisconnectSamples) != 2 {
+		t.Fatalf("unexpected disconnect diagnostics: count=%d reasons=%v samples=%+v",
+			summary.Disconnects, summary.DisconnectReasons, summary.DisconnectSamples)
+	}
+	recorder.resetDisconnects()
+	summary = recorder.summarize(AgentSummary{}, nil)
+	if summary.Disconnects != 0 || len(summary.DisconnectReasons) != 0 || len(summary.DisconnectSamples) != 0 {
+		t.Fatalf("disconnect diagnostics were not reset: %+v", summary)
+	}
+}
+
+func TestBitsetCountCountsEachBitOnce(t *testing.T) {
+	if got := bitsetCount([]uint64{0b1011, 0b100000}); got != 4 {
+		t.Fatalf("bitset count=%d want=4", got)
+	}
+}
+
 func testData(message AcceptedMessage, sentAt time.Time) dataPacket {
-	content, _ := json.Marshal(map[string]any{"run_id": message.RunID, "sent_at_unix_nano": sentAt.UnixNano()})
+	content, _ := json.Marshal(map[string]any{"run_id": message.RunID, "scenario": message.Scenario,
+		"sender_machine": message.SenderMachine, "sender_index": message.SenderIndex,
+		"sent_at_unix_nano": sentAt.UnixNano()})
 	return dataPacket{Topic: message.Topic, Seq: message.Seq,
 		Head: map[string]any{"x-im-client-mid": message.ClientMid}, Content: content}
 }

loadtest/im-pressure/wsclient.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net"
 	"net/http"
 	"net/url"
 	"strconv"
@@ -35,11 +36,42 @@ type dataPacket struct {
 	Content   json.RawMessage `json:"content"`
 }
 
+type queuedDataPacket struct {
+	packet   dataPacket
+	queuedAt time.Time
+}
+
+type ctrlWait struct {
+	ch     chan ctrlPacket
+	kind   string
+	sentAt time.Time
+}
+
+type timedOutCtrl struct {
+	kind   string
+	sentAt time.Time
+}
+
+type ctrlObservation struct {
+	ID         string
+	Kind       string
+	Code       int
+	SentAt     time.Time
+	ReceivedAt time.Time
+	Latency    time.Duration
+	Late       bool
+}
+
 type ctrlError struct {
 	Code int
 	Text string
 }
 
+const (
+	dataCallbackQueueSize = 512
+	lateCtrlRetention     = 10 * time.Minute
+)
+
 func (e *ctrlError) Error() string {
 	return fmt.Sprintf("ctrl code=%d text=%s", e.Code, e.Text)
 }
@@ -50,17 +82,22 @@ type WSClient struct {
 	commandTimeout time.Duration
 	onData         func(AccountRecord, dataPacket)
 	onDisconnect   func(AccountRecord, error)
+	onCtrlObserved func(AccountRecord, ctrlObservation)
+	callbackQueue  *callbackQueueMetrics
 
-	sendMu sync.Mutex
-	mu     sync.Mutex
-	seq    uint64
-	waits  map[string]chan ctrlPacket
-	done   chan struct{}
-	closed atomic.Bool
+	sendMu        sync.Mutex
+	mu            sync.Mutex
+	seq           uint64
+	waits         map[string]ctrlWait
+	timedOutCtrls map[string]timedOutCtrl
+	done          chan struct{}
+	data          chan queuedDataPacket
+	closed        atomic.Bool
 }
 
 func connectWSClient(ctx context.Context, cfg *Config, account AccountRecord, apiKey, password string,
-	onData func(AccountRecord, dataPacket), onDisconnect func(AccountRecord, error)) (*WSClient, error) {
+	onData func(AccountRecord, dataPacket), onDisconnect func(AccountRecord, error),
+	onCtrlObserved func(AccountRecord, ctrlObservation), callbackQueue *callbackQueueMetrics) (*WSClient, error) {
 	timeout, err := configDuration(cfg.CommandTimeout)
 	if err != nil {
 		return nil, err
@@ -70,6 +107,17 @@ func connectWSClient(ctx context.Context, cfg *Config, account AccountRecord, ap
 		return nil, err
 	}
 	dialer := *websocket.DefaultDialer
+	if account.DialIP != "" {
+		targetHost := endpointHostname(endpoint)
+		var netDialer net.Dialer
+		dialer.NetDialContext = func(ctx context.Context, network, address string) (net.Conn, error) {
+			host, port, splitErr := net.SplitHostPort(address)
+			if splitErr == nil && strings.EqualFold(host, targetHost) {
+				address = net.JoinHostPort(account.DialIP, port)
+			}
+			return netDialer.DialContext(ctx, network, address)
+		}
+	}
 	if cfg.InsecureTLS {
 		dialer.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} // #nosec G402: explicit load-test option.
 	}
@@ -82,8 +130,11 @@ func connectWSClient(ctx context.Context, cfg *Config, account AccountRecord, ap
 	}
 	client := &WSClient{
 		account: account, conn: conn, commandTimeout: timeout, onData: onData, onDisconnect: onDisconnect,
-		waits: make(map[string]chan ctrlPacket), done: make(chan struct{}),
+		onCtrlObserved: onCtrlObserved,
+		callbackQueue:  callbackQueue,
+		waits:          make(map[string]ctrlWait), timedOutCtrls: make(map[string]timedOutCtrl), done: make(chan struct{}),
 	}
+	client.startDataProcessor()
 	go client.readLoop()
 	if _, err = client.command(ctx, "hi", map[string]any{"hi": map[string]any{
 		"id": client.nextID("hi"), "ver": "0.25", "ua": "im-pressure/1.0",
@@ -116,9 +167,23 @@ func connectWSClient(ctx context.Context, cfg *Config, account AccountRecord, ap
 		return nil, fmt.Errorf("login %s: %w", account.Username, err)
 	}
 	client.applyLogin(ctrl)
+	pingInterval, err := configDuration(cfg.WSPingInterval)
+	if err != nil {
+		client.Close()
+		return nil, err
+	}
+	client.startKeepalive(pingInterval)
 	return client, nil
 }
 
+func endpointHostname(raw string) string {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return ""
+	}
+	return u.Hostname()
+}
+
 func connectForPrepare(ctx context.Context, cfg *Config, account AccountRecord, api *apiClient, password, verificationCode string) (*WSClient, bool, error) {
 	timeout, err := configDuration(cfg.CommandTimeout)
 	if err != nil {
@@ -136,7 +201,8 @@ func connectForPrepare(ctx context.Context, cfg *Config, account AccountRecord,
 	if err != nil {
 		return nil, false, err
 	}
-	client := &WSClient{account: account, conn: conn, commandTimeout: timeout, waits: make(map[string]chan ctrlPacket), done: make(chan struct{})}
+	client := &WSClient{account: account, conn: conn, commandTimeout: timeout,
+		waits: make(map[string]ctrlWait), timedOutCtrls: make(map[string]timedOutCtrl), done: make(chan struct{})}
 	go client.readLoop()
 	if _, err = client.command(ctx, "hi", map[string]any{"hi": map[string]any{
 		"id": client.nextID("hi"), "ver": "0.25", "ua": "im-pressure-prepare/1.0", "tenant": cfg.Tenant,
@@ -245,7 +311,8 @@ func (c *WSClient) Publish(ctx context.Context, topic, clientMid, runID, scenari
 		"id": id, "topic": topic, "noecho": false,
 		"head": map[string]any{"mime": "application/json", "x-im-schema": 1, "x-im-type": "text", "x-im-client-mid": clientMid},
 		"content": map[string]any{"text": "loadtest", "run_id": runID, "scenario": scenario,
-			"sender_index": c.account.Index, "message_index": messageIndex, "sent_at_unix_nano": sentAt.UnixNano()},
+			"sender_machine": c.account.Machine, "sender_index": c.account.Index,
+			"message_index": messageIndex, "sent_at_unix_nano": sentAt.UnixNano()},
 	}})
 	if err != nil {
 		return AcceptedMessage{}, err
@@ -278,14 +345,15 @@ func ctrlInt64(raw json.RawMessage) (int64, error) {
 	return strconv.ParseInt(text, 10, 64)
 }
 
-func (c *WSClient) command(ctx context.Context, _ string, message map[string]any) (ctrlPacket, error) {
+func (c *WSClient) command(ctx context.Context, kind string, message map[string]any) (ctrlPacket, error) {
 	id := nestedMessageID(message)
 	if id == "" {
 		return ctrlPacket{}, errors.New("command id is required")
 	}
 	wait := make(chan ctrlPacket, 1)
+	sentAt := time.Now()
 	c.mu.Lock()
-	c.waits[id] = wait
+	c.waits[id] = ctrlWait{ch: wait, kind: kind, sentAt: sentAt}
 	c.mu.Unlock()
 	c.sendMu.Lock()
 	err := c.conn.WriteJSON(message)
@@ -303,7 +371,33 @@ func (c *WSClient) command(ctx context.Context, _ string, message map[string]any
 		}
 		return ctrl, nil
 	case <-timer.C:
-		c.removeWait(id)
+		c.mu.Lock()
+		entry, pending := c.waits[id]
+		if pending {
+			delete(c.waits, id)
+			if entry.kind == "pub" {
+				c.timedOutCtrls[id] = timedOutCtrl{kind: entry.kind, sentAt: entry.sentAt}
+			}
+		}
+		c.mu.Unlock()
+		if !pending {
+			// The read loop won the timer race and placed the response in the
+			// buffered channel before removing the waiter.
+			ctrl := <-wait
+			if ctrl.Code < 200 || ctrl.Code >= 300 {
+				return ctrl, &ctrlError{Code: ctrl.Code, Text: ctrl.Text}
+			}
+			return ctrl, nil
+		}
+		if entry.kind == "pub" {
+			time.AfterFunc(lateCtrlRetention, func() {
+				c.mu.Lock()
+				if current, ok := c.timedOutCtrls[id]; ok && current.sentAt.Equal(sentAt) {
+					delete(c.timedOutCtrls, id)
+				}
+				c.mu.Unlock()
+			})
+		}
 		return ctrlPacket{}, fmt.Errorf("ctrl timeout id=%s", id)
 	case <-ctx.Done():
 		c.removeWait(id)
@@ -337,7 +431,13 @@ func (c *WSClient) removeWait(id string) {
 }
 
 func (c *WSClient) readLoop() {
-	defer close(c.done)
+	defer func() {
+		_ = c.conn.Close()
+		if c.data != nil {
+			close(c.data)
+		}
+		close(c.done)
+	}()
 	for {
 		var envelope map[string]json.RawMessage
 		if err := c.conn.ReadJSON(&envelope); err != nil {
@@ -350,11 +450,23 @@ func (c *WSClient) readLoop() {
 			var ctrl ctrlPacket
 			if json.Unmarshal(raw, &ctrl) == nil && ctrl.ID != "" {
 				c.mu.Lock()
-				wait := c.waits[ctrl.ID]
-				delete(c.waits, ctrl.ID)
+				wait, pending := c.waits[ctrl.ID]
+				late, timedOut := c.timedOutCtrls[ctrl.ID]
+				receivedAt := time.Now()
+				if pending {
+					wait.ch <- ctrl
+					delete(c.waits, ctrl.ID)
+				} else if timedOut {
+					delete(c.timedOutCtrls, ctrl.ID)
+				}
 				c.mu.Unlock()
-				if wait != nil {
-					wait <- ctrl
+				if c.onCtrlObserved != nil && (pending && wait.kind == "pub" || timedOut && late.kind == "pub") {
+					kind, sentAt, isLate := wait.kind, wait.sentAt, false
+					if timedOut {
+						kind, sentAt, isLate = late.kind, late.sentAt, true
+					}
+					c.onCtrlObserved(c.account, ctrlObservation{ID: ctrl.ID, Kind: kind, Code: ctrl.Code,
+						SentAt: sentAt, ReceivedAt: receivedAt, Latency: receivedAt.Sub(sentAt), Late: isLate})
 				}
 			}
 			continue
@@ -362,12 +474,63 @@ func (c *WSClient) readLoop() {
 		if raw := envelope["data"]; len(raw) > 0 && c.onData != nil {
 			var data dataPacket
 			if json.Unmarshal(raw, &data) == nil {
-				c.onData(c.account, data)
+				if c.data == nil {
+					c.onData(c.account, data)
+				} else {
+					queued := queuedDataPacket{packet: data, queuedAt: time.Now()}
+					c.callbackQueue.enqueue()
+					c.data <- queued
+				}
 			}
 		}
 	}
 }
 
+func (c *WSClient) startDataProcessor() {
+	if c.onData == nil || c.data != nil {
+		return
+	}
+	c.data = make(chan queuedDataPacket, dataCallbackQueueSize)
+	go func() {
+		for data := range c.data {
+			c.callbackQueue.startCallback(data.queuedAt)
+			c.onData(c.account, data.packet)
+			c.callbackQueue.finishCallback()
+		}
+	}()
+}
+
+func (c *WSClient) startKeepalive(interval time.Duration) {
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				deadline := time.Now().Add(interval / 2)
+				if err := c.conn.WriteControl(websocket.PingMessage, nil, deadline); err != nil {
+					_ = c.conn.Close()
+					return
+				}
+			case <-c.done:
+				return
+			}
+		}
+	}()
+}
+
+func (c *WSClient) alive() bool {
+	if c == nil || c.closed.Load() {
+		return false
+	}
+	select {
+	case <-c.done:
+		return false
+	default:
+		return true
+	}
+}
+
 func (c *WSClient) Close() {
 	if c == nil || !c.closed.CompareAndSwap(false, true) {
 		return

loadtest/im-pressure/wsclient_test.go

@@ -0,0 +1,185 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+func TestWSClientObservesCtrlAfterCommandTimeout(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		var command map[string]any
+		if err = conn.ReadJSON(&command); err != nil {
+			return
+		}
+		time.Sleep(40 * time.Millisecond)
+		_ = conn.WriteJSON(map[string]any{"ctrl": map[string]any{"id": "pub-a-0001", "code": 202, "text": "accepted"}})
+	}))
+	defer server.Close()
+
+	conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http"), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	observed := make(chan ctrlObservation, 1)
+	client := &WSClient{
+		account: AccountRecord{Machine: "a", Index: 1}, conn: conn, commandTimeout: 10 * time.Millisecond,
+		waits: make(map[string]ctrlWait), timedOutCtrls: make(map[string]timedOutCtrl), done: make(chan struct{}),
+		onCtrlObserved: func(_ AccountRecord, observation ctrlObservation) { observed <- observation },
+	}
+	go client.readLoop()
+	defer client.Close()
+
+	_, err = client.command(context.Background(), "pub", map[string]any{"pub": map[string]any{"id": "pub-a-0001"}})
+	if err == nil || !strings.Contains(err.Error(), "ctrl timeout") {
+		t.Fatalf("command error=%v, want ctrl timeout", err)
+	}
+	select {
+	case observation := <-observed:
+		if !observation.Late || observation.Kind != "pub" || observation.Code != 202 || observation.Latency < 10*time.Millisecond {
+			t.Fatalf("unexpected observation: %+v", observation)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("late ctrl response was not observed")
+	}
+}
+
+func TestWSClientKeepaliveSendsPing(t *testing.T) {
+	ping := make(chan struct{}, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		conn.SetPingHandler(func(string) error {
+			select {
+			case ping <- struct{}{}:
+			default:
+			}
+			return conn.WriteControl(websocket.PongMessage, nil, time.Now().Add(time.Second))
+		})
+		for {
+			if _, _, err = conn.ReadMessage(); err != nil {
+				return
+			}
+		}
+	}))
+	defer server.Close()
+
+	conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http"), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	client := &WSClient{conn: conn, waits: make(map[string]ctrlWait), timedOutCtrls: make(map[string]timedOutCtrl), done: make(chan struct{})}
+	go client.readLoop()
+	client.startKeepalive(10 * time.Millisecond)
+	defer client.Close()
+
+	select {
+	case <-ping:
+	case <-time.After(time.Second):
+		t.Fatal("websocket keepalive ping was not received")
+	}
+}
+
+func TestWSClientReadLoopClosesConnectionAfterDecodeError(t *testing.T) {
+	serverSawClose := make(chan struct{}, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		if err = conn.WriteMessage(websocket.TextMessage, []byte("{")); err != nil {
+			return
+		}
+		if _, _, err = conn.ReadMessage(); err != nil {
+			serverSawClose <- struct{}{}
+		}
+	}))
+	defer server.Close()
+
+	conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http"), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	client := &WSClient{conn: conn, waits: make(map[string]ctrlWait), timedOutCtrls: make(map[string]timedOutCtrl), done: make(chan struct{})}
+	go client.readLoop()
+
+	select {
+	case <-client.done:
+	case <-time.After(time.Second):
+		t.Fatal("read loop did not exit after malformed frame")
+	}
+	select {
+	case <-serverSawClose:
+	case <-time.After(time.Second):
+		t.Fatal("read loop exited without closing the underlying connection")
+	}
+}
+
+func TestWSClientDataCallbackDoesNotBlockPong(t *testing.T) {
+	pong := make(chan struct{}, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := (&websocket.Upgrader{}).Upgrade(w, r, nil)
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		conn.SetPongHandler(func(string) error {
+			select {
+			case pong <- struct{}{}:
+			default:
+			}
+			return nil
+		})
+		if err = conn.WriteJSON(map[string]any{"data": map[string]any{
+			"topic": "grp-test", "seq": 1, "head": map[string]any{}, "content": map[string]any{},
+		}}); err != nil {
+			return
+		}
+		if err = conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(time.Second)); err != nil {
+			return
+		}
+		conn.SetReadDeadline(time.Now().Add(time.Second))
+		for {
+			if _, _, readErr := conn.ReadMessage(); readErr != nil {
+				return
+			}
+		}
+	}))
+	defer server.Close()
+
+	conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http"), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	blocked := make(chan struct{})
+	client := &WSClient{
+		conn: conn, waits: make(map[string]ctrlWait), timedOutCtrls: make(map[string]timedOutCtrl), done: make(chan struct{}),
+		onData: func(AccountRecord, dataPacket) { <-blocked },
+	}
+	client.startDataProcessor()
+	go client.readLoop()
+	defer func() {
+		close(blocked)
+		client.Close()
+	}()
+
+	select {
+	case <-pong:
+	case <-time.After(2 * time.Second):
+		t.Fatal("pong was blocked by the data callback")
+	}
+}

monitoring/im-server-alerts.yaml

@@ -49,6 +49,20 @@ spec:
             summary: "IM WebSocket connections are imbalanced across pods"
     - name: im-server-persistence
       rules:
+        - alert: IMDatabasePoolHigh
+          expr: im_db_pool_in_use_connections / clamp_min(im_db_pool_max_open_connections, 1) > 0.85
+          for: 1m
+          labels:
+            severity: warning
+          annotations:
+            summary: "IM database pool usage is above 85%"
+        - alert: IMDatabasePoolCritical
+          expr: im_db_pool_in_use_connections / clamp_min(im_db_pool_max_open_connections, 1) > 0.95
+          for: 30s
+          labels:
+            severity: critical
+          annotations:
+            summary: "IM database pool usage is above 95%"
         - alert: IMKafkaPersistDeadLetter
           expr: sum by (kind, reason) (increase(im_kafka_dead_letters_total[5m])) > 0
           labels:

scripts/IM-租户业务库初始化.sql

@@ -467,7 +467,7 @@ CREATE TABLE IF NOT EXISTS `im_filemsglinks` (
                                                  `id` int NOT NULL AUTO_INCREMENT,
                                                  `createdat` datetime(3) NOT NULL,
     `fileid` bigint NOT NULL,
-    `msgid` int DEFAULT NULL,
+    `msgid` bigint DEFAULT NULL,
     `topic` char(25) DEFAULT NULL,
     `userid` bigint DEFAULT NULL,
     PRIMARY KEY (`id`),

server/admin_internal_config.go

@@ -276,8 +276,9 @@ func (c *adminInternalClient) TenantLoginIPWhitelist(id types.TenantID) (*tenant
 	return &result, nil
 }
 
-func (c *adminInternalClient) LatestAppRelease(platform, channel string) (*types.AppRelease, error) {
+func (c *adminInternalClient) LatestAppRelease(appCode, platform, channel string) (*types.AppRelease, error) {
 	query := url.Values{}
+	query.Set("app_code", strings.ToLower(strings.TrimSpace(appCode)))
 	query.Set("platform", strings.ToLower(strings.TrimSpace(platform)))
 	query.Set("channel", strings.ToLower(strings.TrimSpace(channel)))
 	var dto struct {

server/admin_internal_config_test.go

@@ -38,7 +38,7 @@ func TestAdminInternalClientLatestAppRelease(t *testing.T) {
 		config: adminInternalAPIConfig{BaseURL: server.URL, ServiceName: "im-server", Secret: "test-secret"},
 		http:   server.Client(),
 	}
-	release, err := client.LatestAppRelease(" IOS ", "STABLE")
+	release, err := client.LatestAppRelease(" IM ", " IOS ", "STABLE")
 	if err != nil {
 		t.Fatal(err)
 	}

server/auth_audit_test.go

@@ -72,6 +72,19 @@ func TestMessageQuerySpecsExposeAdminFields(t *testing.T) {
 	}
 }
 
+func TestPrivateMessageQueryUsesTenantShardTables(t *testing.T) {
+	spec := privateMessagesInternalQuerySpecForTenant(types.TenantID(9))
+	query := strings.ToLower(spec.From)
+	for _, table := range []string{"im_009_messages", "im_009_subscriptions"} {
+		if !strings.Contains(query, table) {
+			t.Fatalf("private message query must use tenant shard table %q: %s", table, query)
+		}
+	}
+	if strings.Contains(query, "from im_messages ") || strings.Contains(query, "from im_subscriptions ") {
+		t.Fatalf("private message query must not use legacy shared tables: %s", query)
+	}
+}
+
 func TestGroupMessageQuerySupportsOperationalFilters(t *testing.T) {
 	req := httptest.NewRequest("GET", "/?seq_id=42&sender_username=alice&sender_nickname=%E5%B0%8F%E6%98%8E&group_name=%E6%B5%8B%E8%AF%95%E7%BE%A4", nil)
 	query, _, args, _, _, err := buildInternalAdminListQuery(req, groupMessagesInternalQuerySpec(), "", types.TenantID(1))

server/cluster.go

@@ -284,6 +284,9 @@ type ClusterResp struct {
 
 	// Original request type.
 	OrigReqType ProxyReqType
+
+	// Set after RPC decoding on the receiving node; not serialized by gob.
+	proxyQueuedAt time.Time
 }
 
 // ClusterPing is used to detect node restarts.
@@ -489,14 +492,16 @@ func clusterReqShard(msg *ClusterReq, count int) int {
 	return int(h.Sum32() % uint32(count))
 }
 
-// masterToProxyAsync forwards response from topic master to topic proxy
-// in a fire-and-forget manner.
-func (n *ClusterNode) masterToProxyAsync(msg *ClusterResp) error {
-	var unused bool
-	if c := n.callAsync("Cluster.TopicProxy", msg, &unused, nil); c.Error != nil {
-		return c.Error
+// masterToProxy forwards responses synchronously. A multiplexing session drains
+// one topic in order, so waiting for each RPC prevents the RPC server from
+// concurrently enqueueing later sequence IDs before earlier ones.
+func (n *ClusterNode) masterToProxy(msg *ClusterResp) error {
+	var rejected bool
+	err := n.call("Cluster.TopicProxy", msg, &rejected)
+	if err == nil && rejected {
+		return errClusterOverloaded
 	}
-	return nil
+	return err
 }
 
 // route routes server message within the cluster.
@@ -741,9 +746,12 @@ func (Cluster) TopicProxy(msg *ClusterResp, unused *bool) error {
 	// Find appropriate topic, send the message to it.
 	if t := globals.hub.topicGet(types.TopicKey{TenantID: msg.TenantID, Topic: msg.RcptTo}); t != nil {
 		msg.SrvMsg.uid = types.ParseUserId(msg.SrvMsg.AsUser)
+		msg.proxyQueuedAt = time.Now()
 		select {
 		case t.proxy <- msg:
+			immetrics.ObserveInternalQueueEnqueue("cluster_topic_proxy", len(t.proxy), cap(t.proxy), true)
 		default:
+			immetrics.ObserveInternalQueueEnqueue("cluster_topic_proxy", len(t.proxy), cap(t.proxy), false)
 			logs.Warn.Printf("cluster: proxy channel full, topic %s", msg.RcptTo)
 		}
 	} else {
@@ -1213,7 +1221,10 @@ func clusterInit(configString json.RawMessage, self *string) int {
 
 func registerClusterGobTypes() {
 	gob.Register([]any{})
+	gob.Register([]map[string]any{})
 	gob.Register(map[string]any{})
+	gob.Register(types.KVMap{})
+	gob.Register([]types.KVMap{})
 	gob.Register(map[string]int{})
 	gob.Register(map[string]string{})
 	gob.Register(MsgAccessMode{})
@@ -1391,6 +1402,13 @@ func (sess *Session) clusterWriteLoop(forTopic string) {
 	terminate := true
 	defer func() {
 		if terminate {
+			// The topic may retain this multiplexing session briefly while its
+			// unsubscribe request is processed. Reject writes to the stale session
+			// instead of filling a send queue which no longer has a drain owner.
+			sess.clusterQueueMu.Lock()
+			atomic.StoreInt32(&sess.terminating, 1)
+			sess.purgeChannels()
+			sess.clusterQueueMu.Unlock()
 			sess.closeRPC()
 			globals.sessionStore.Delete(sess)
 			sess.inflightReqs = nil
@@ -1406,6 +1424,8 @@ func (sess *Session) clusterWriteLoop(forTopic string) {
 				return
 			}
 			srvMsg := msg.(*ServerComMessage)
+			immetrics.ObserveClusterM2PDequeue(sess.clnode.name, srvMsg.clusterQueuedAt)
+			srvMsg.clusterQueuedAt = time.Time{}
 			response := &ClusterResp{TenantID: srvMsg.TenantID, SrvMsg: srvMsg}
 			if srvMsg.sess == nil {
 				response.OrigSid = "*"
@@ -1432,7 +1452,7 @@ func (sess *Session) clusterWriteLoop(forTopic string) {
 			srvMsg.RcptTo = forTopic
 			response.RcptTo = forTopic
 
-			if err := sess.clnode.masterToProxyAsync(response); err != nil {
+			if err := sess.clnode.masterToProxy(response); err != nil {
 				logs.Warn.Printf("cluster: response to proxy failed \"%s\": %s", sess.sid, err.Error())
 				return
 			}
@@ -1449,6 +1469,12 @@ func (sess *Session) clusterWriteLoop(forTopic string) {
 		case <-sess.detach:
 			return
 		default:
+			sess.clusterWriteScheduled.Store(false)
+			// An enqueue can race with releasing ownership. Either the enqueuer
+			// schedules the next drain or this check does; the CAS prevents both.
+			if len(sess.send) > 0 {
+				sess.scheduleClusterWriteLoop()
+			}
 			terminate = false
 			return
 		}

server/cluster_gob_test.go

@@ -28,6 +28,9 @@ func TestClusterGobRegistersSystemMessagePayloadTypes(t *testing.T) {
 				Content: map[string]any{
 					"text":     "成员加入了群聊",
 					"template": "group_member_joined",
+					"items":    []map[string]any{{"type": "member", "id": "usr123"}},
+					"action":   types.KVMap{"type": "group_profile", "target_id": "grpTest"},
+					"rows":     []types.KVMap{{"type": "member", "id": "usr123"}},
 					"actors": []imSystemMessageActor{{
 						UserID: "usr123",
 						Click:  map[string]any{"type": "user_profile", "target_id": "usr123"},

server/cluster_order_test.go

@@ -0,0 +1,165 @@
+package main
+
+import (
+	"net"
+	"net/rpc"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/tinode/chat/server/concurrency"
+	"github.com/tinode/chat/server/store/types"
+)
+
+type orderedTopicProxy struct {
+	mu       sync.Mutex
+	received []int64
+	done     chan struct{}
+}
+
+func (proxy *orderedTopicProxy) TopicProxy(msg *ClusterResp, rejected *bool) error {
+	if msg.SrvMsg.Data.SeqId == 1 {
+		time.Sleep(50 * time.Millisecond)
+	}
+	proxy.mu.Lock()
+	proxy.received = append(proxy.received, msg.SrvMsg.Data.SeqId)
+	if len(proxy.received) == 2 {
+		close(proxy.done)
+	}
+	proxy.mu.Unlock()
+	return nil
+}
+
+func TestClusterWriteLoopPreservesTopicOrder(t *testing.T) {
+	serverConn, clientConn := net.Pipe()
+	rpcServer := rpc.NewServer()
+	proxy := &orderedTopicProxy{done: make(chan struct{})}
+	if err := rpcServer.RegisterName("Cluster", proxy); err != nil {
+		t.Fatal(err)
+	}
+	go rpcServer.ServeConn(serverConn)
+
+	pool := concurrency.NewGoRoutinePool(4)
+	previousCluster := globals.cluster
+	globals.cluster = &Cluster{proxyEventQueue: pool}
+	t.Cleanup(func() {
+		globals.cluster = previousCluster
+		_ = clientConn.Close()
+		_ = serverConn.Close()
+		pool.Stop()
+	})
+
+	sess := &Session{
+		sid:          "multiplex-order-test",
+		proto:        MULTIPLEX,
+		proxiedTopic: "p2p-order-test",
+		send:         make(chan any, 2),
+		clnode:       &ClusterNode{endpoint: rpc.NewClient(clientConn), connected: true},
+	}
+	tenantID := types.TenantID(1)
+	sess.send <- &ServerComMessage{TenantID: tenantID, Data: &MsgServerData{SeqId: 1}}
+	sess.send <- &ServerComMessage{TenantID: tenantID, Data: &MsgServerData{SeqId: 2}}
+
+	// Scheduling twice used to start two concurrent drains for the same topic.
+	sess.scheduleClusterWriteLoop()
+	sess.scheduleClusterWriteLoop()
+
+	select {
+	case <-proxy.done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for cluster responses")
+	}
+	deadline := time.Now().Add(2 * time.Second)
+	for sess.clusterWriteScheduled.Load() && time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	if sess.clusterWriteScheduled.Load() {
+		t.Fatal("cluster write task did not release session ownership")
+	}
+
+	proxy.mu.Lock()
+	defer proxy.mu.Unlock()
+	if len(proxy.received) != 2 || proxy.received[0] != 1 || proxy.received[1] != 2 {
+		t.Fatalf("cluster responses arrived out of order: %v", proxy.received)
+	}
+}
+
+func TestClusterWriteLoopRejectsWritesAfterTermination(t *testing.T) {
+	previousSessionStore := globals.sessionStore
+	globals.sessionStore = NewSessionStore(time.Minute)
+	t.Cleanup(func() { globals.sessionStore = previousSessionStore })
+
+	sess := &Session{
+		sid:    "multiplex-termination-test",
+		proto:  MULTIPLEX,
+		send:   make(chan any, 1),
+		stop:   make(chan any, 1),
+		detach: make(chan string, 1),
+		subs:   make(map[string]*Subscription),
+	}
+	sess.stop <- nil
+
+	sess.clusterWriteLoop("grp-termination-test")
+
+	if atomic.LoadInt32(&sess.terminating) == 0 {
+		t.Fatal("terminated multiplexing session still accepts writes")
+	}
+	if !sess.queueOut(&ServerComMessage{TenantID: types.TenantID(1)}) {
+		t.Fatal("write to terminated multiplexing session should be discarded")
+	}
+	if len(sess.send) != 0 {
+		t.Fatalf("terminated multiplexing session retained %d outbound messages", len(sess.send))
+	}
+}
+
+func TestMultiplexEnqueueWaitsForDrain(t *testing.T) {
+	sess := &Session{proto: MULTIPLEX, send: make(chan any, 1)}
+	sess.send <- "existing"
+
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		<-sess.send
+	}()
+
+	payload := &ServerComMessage{TenantID: types.TenantID(1)}
+	if !sess.enqueueMultiplexOutbound(payload, 200*time.Millisecond) {
+		t.Fatal("multiplex enqueue failed while the drain was making progress")
+	}
+	if got := <-sess.send; got != payload {
+		t.Fatalf("unexpected queued payload: %#v", got)
+	}
+}
+
+func TestMultiplexEnqueueTimesOutWithoutDrain(t *testing.T) {
+	sess := &Session{proto: MULTIPLEX, send: make(chan any, 1)}
+	sess.send <- "existing"
+
+	started := time.Now()
+	if sess.enqueueMultiplexOutbound("next", 20*time.Millisecond) {
+		t.Fatal("multiplex enqueue succeeded without queue capacity")
+	}
+	if elapsed := time.Since(started); elapsed < 15*time.Millisecond || elapsed > 200*time.Millisecond {
+		t.Fatalf("multiplex enqueue timeout outside expected bounds: %s", elapsed)
+	}
+}
+
+func TestMultiplexEnqueueStopsWhenSessionTerminates(t *testing.T) {
+	sess := &Session{proto: MULTIPLEX, send: make(chan any, 1)}
+	sess.send <- "existing"
+
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		sess.clusterQueueMu.Lock()
+		atomic.StoreInt32(&sess.terminating, 1)
+		<-sess.send
+		sess.clusterQueueMu.Unlock()
+	}()
+
+	if !sess.enqueueMultiplexOutbound("next", 200*time.Millisecond) {
+		t.Fatal("terminating multiplex session should discard the pending write")
+	}
+	if len(sess.send) != 0 {
+		t.Fatalf("terminating multiplex session retained %d outbound messages", len(sess.send))
+	}
+}

server/datamodel.go

@@ -382,6 +382,8 @@ type ClientComMessage struct {
 	MetaWhat int `json:"-"`
 	// Timestamp when this message was received by the server.
 	Timestamp time.Time `json:"-"`
+	// Timestamp when this message entered the current topic client queue.
+	queuedAt time.Time
 	// Tenant context inherited from the originating session.
 	TenantID types.TenantID `json:"-"`
 
@@ -879,6 +881,8 @@ type ServerComMessage struct {
 	PreserveTopicName bool `json:"-"`
 	// User id affected by this message.
 	uid types.Uid
+	// Timestamp when this message entered a master-to-proxy multiplex queue.
+	clusterQueuedAt time.Time
 }
 
 // Deep-shallow copy of ServerComMessage. Deep copy of service fields,
@@ -897,6 +901,7 @@ func (src *ServerComMessage) copy() *ServerComMessage {
 		SkipSid:           src.SkipSid,
 		PreserveTopicName: src.PreserveTopicName,
 		uid:               src.uid,
+		clusterQueuedAt:   src.clusterQueuedAt,
 	}
 
 	dst.Ctrl = src.Ctrl.copy()

server/db/adapter.go

@@ -260,6 +260,12 @@ type TenantRoutedAdapter interface {
 	TenantAdapterFor(t.TenantID) (TenantBusinessAdapter, TenantAuthAdapter, error)
 }
 
+// TenantRouteCacheInvalidator clears cached tenant routing metadata. A zero
+// tenant ID clears every cached route.
+type TenantRouteCacheInvalidator interface {
+	InvalidateTenantRoute(t.TenantID)
+}
+
 type TenantMessageBatchAdapter interface {
 	TenantMessageSaveBatch(t.TenantID, []*t.Message) error
 	TenantGroupMessageSaveBatch(t.TenantID, []*t.Message) error
@@ -399,7 +405,9 @@ type TenantBusinessAdapter interface {
 	TenantGroupMemberUpsert(t.TenantID, *t.GroupMember) (*t.GroupMember, error)
 	TenantGroupMemberGet(t.TenantID, string, t.Uid) (*t.GroupMember, error)
 	TenantGroupMemberList(t.TenantID, string, t.GroupMemberListOptions) ([]t.GroupMember, string, error)
+	TenantGroupMembersCount(t.TenantID, []string) (map[string]int64, error)
 	TenantGroupMemberUpdate(t.TenantID, string, t.Uid, t.GroupMemberPatch) (*t.GroupMember, error)
+	TenantUsersShareOpenPrivateGroup(t.TenantID, t.Uid, t.Uid) (bool, error)
 	TenantGroupInvitationCreate(t.TenantID, *t.GroupInvitation) (*t.GroupInvitation, error)
 	TenantGroupInvitationAccept(t.TenantID, string, t.Uid, any, time.Time) (*t.GroupInvitation, error)
 	TenantGroupJoinRequestCreate(t.TenantID, *t.GroupJoinRequest) (*t.GroupJoinRequest, error)

server/db/mysql/adapter.go

@@ -21,8 +21,10 @@ import (
 	"github.com/tinode/chat/server/auth"
 	dbadapter "github.com/tinode/chat/server/db"
 	"github.com/tinode/chat/server/db/common"
+	immetrics "github.com/tinode/chat/server/metrics"
 	"github.com/tinode/chat/server/store"
 	t "github.com/tinode/chat/server/store/types"
+	"golang.org/x/sync/singleflight"
 )
 
 // adapter holds MySQL connection data.
@@ -42,14 +44,17 @@ type adapter struct {
 	// DB transaction timeout.
 	txTimeout time.Duration
 
-	baseConfig       *configType
-	tenantDBRouting  bool
-	tenantScopedDB   bool
-	tenantID         t.TenantID
-	tenantRegistryDB string
-	tenantAdapters   map[t.TenantID]*adapter
-	tenantMu         sync.Mutex
-	groupShardWindow string
+	baseConfig         *configType
+	tenantDBRouting    bool
+	tenantScopedDB     bool
+	tenantID           t.TenantID
+	tenantRegistryDB   string
+	tenantAdapters     map[t.TenantID]*adapter
+	tenantRouteExpiry  map[t.TenantID]time.Time
+	tenantRouteGen     uint64
+	tenantRouteRefresh singleflight.Group
+	tenantMu           sync.Mutex
+	groupShardWindow   string
 }
 
 const (
@@ -62,6 +67,7 @@ const (
 	defaultMaxResults = 1024
 	// This is capped by the Session's send queue limit (128).
 	defaultMaxMessageResults = 100
+	tenantRouteCacheTTL      = time.Minute
 
 	// If DB request timeout is specified,
 	// we allocate txTimeoutMultiplier times more time for transactions.
@@ -109,6 +115,9 @@ type configType struct {
 	MaxOpenConns int `json:"max_open_conns,omitempty"`
 	// Maximum number of connections in the idle connection pool.
 	MaxIdleConns int `json:"max_idle_conns,omitempty"`
+	// Registry database has a separate, much smaller workload and pool budget.
+	RegistryMaxOpenConns int `json:"registry_max_open_conns,omitempty"`
+	RegistryMaxIdleConns int `json:"registry_max_idle_conns,omitempty"`
 	// Maximum amount of time a connection may be reused (in seconds).
 	ConnMaxLifetime int `json:"conn_max_lifetime,omitempty"`
 
@@ -185,6 +194,7 @@ func openMySQLDB(config configType, dsn, dbName string) (*sqlx.DB, string, error
 	if config.ConnMaxLifetime > 0 {
 		db.SetConnMaxLifetime(time.Duration(config.ConnMaxLifetime) * time.Second)
 	}
+	immetrics.RegisterDBPool(dbName, db.DB)
 	return db, dbName, nil
 }
 
@@ -257,6 +267,7 @@ func (a *adapter) Open(jsonconfig json.RawMessage) error {
 	a.tenantID = defaultTenantID
 	a.tenantRegistryDB = strings.TrimSpace(config.TenantRegistryDB)
 	a.tenantAdapters = make(map[t.TenantID]*adapter)
+	a.tenantRouteExpiry = make(map[t.TenantID]time.Time)
 
 	if a.maxResults <= 0 {
 		a.maxResults = defaultMaxResults
@@ -281,7 +292,14 @@ func (a *adapter) Open(jsonconfig json.RawMessage) error {
 			a.txTimeout = time.Duration(float64(config.SqlTimeout)*txTimeoutMultiplier) * time.Second
 		}
 		if a.tenantRegistryDB != "" && a.tenantRegistryDB != a.dbName {
-			a.registryDB, _, err = openMySQLDB(config, a.dsn, a.tenantRegistryDB)
+			registryConfig := config
+			if config.RegistryMaxOpenConns > 0 {
+				registryConfig.MaxOpenConns = config.RegistryMaxOpenConns
+			}
+			if config.RegistryMaxIdleConns > 0 {
+				registryConfig.MaxIdleConns = config.RegistryMaxIdleConns
+			}
+			a.registryDB, _, err = openMySQLDB(registryConfig, a.dsn, a.tenantRegistryDB)
 			if err == nil {
 				err = a.registryDB.Ping()
 			}
@@ -308,6 +326,8 @@ func (a *adapter) Close() error {
 		}
 		delete(a.tenantAdapters, tenantID)
 	}
+	a.tenantRouteExpiry = make(map[t.TenantID]time.Time)
+	a.tenantRouteGen++
 	a.tenantMu.Unlock()
 	if a.registryDB != nil {
 		if closeErr := a.registryDB.Close(); err == nil {
@@ -463,35 +483,62 @@ func (a *adapter) TenantListActive(limit int) ([]t.Tenant, error) {
 }
 
 func (a *adapter) TenantAdapterFor(tenantID t.TenantID) (dbadapter.TenantBusinessAdapter, dbadapter.TenantAuthAdapter, error) {
-	if !a.tenantDBRouting {
-		if a.tenantID != defaultTenantID && a.tenantID != tenantID {
-			return nil, nil, t.ErrMalformed
-		}
-		if a.registryDB != nil {
-			tenant, err := a.tenantByID(tenantID)
-			if err != nil {
-				return nil, nil, err
-			}
-			if tenant.State != t.TenantStateActive {
-				return nil, nil, t.ErrPermissionDenied
-			}
-		}
-		return a, a, nil
+	if !tenantID.IsValid() || (!a.tenantDBRouting && a.tenantID != defaultTenantID && a.tenantID != tenantID) {
+		return nil, nil, t.ErrMalformed
 	}
-	tenant, err := a.tenantByID(tenantID)
+	if tenantAdp, ok := a.cachedTenantAdapter(tenantID, time.Now()); ok {
+		return tenantAdp, tenantAdp, nil
+	}
+
+	resolved, err, _ := a.tenantRouteRefresh.Do(strconv.FormatInt(int64(tenantID), 10), func() (any, error) {
+		if tenantAdp, ok := a.cachedTenantAdapter(tenantID, time.Now()); ok {
+			return tenantAdp, nil
+		}
+		generation := a.tenantRouteGeneration()
+		if a.registryDB != nil {
+			if _, err := a.tenantByID(tenantID); err != nil {
+				return nil, err
+			}
+		}
+		tenantAdp := a.tenantAdapter(tenantID)
+		a.cacheTenantAdapter(tenantID, tenantAdp, generation, time.Now().Add(tenantRouteCacheTTL))
+		return tenantAdp, nil
+	})
 	if err != nil {
 		return nil, nil, err
 	}
-	if tenant.State != t.TenantStateActive {
-		return nil, nil, t.ErrPermissionDenied
+	tenantAdp := resolved.(*adapter)
+	return tenantAdp, tenantAdp, nil
+}
+
+func (a *adapter) cachedTenantAdapter(tenantID t.TenantID, now time.Time) (*adapter, bool) {
+	a.tenantMu.Lock()
+	defer a.tenantMu.Unlock()
+	if expiresAt, ok := a.tenantRouteExpiry[tenantID]; !ok || !now.Before(expiresAt) {
+		return nil, false
+	}
+	if !a.tenantDBRouting {
+		return a, true
+	}
+	tenantAdp := a.tenantAdapters[tenantID]
+	return tenantAdp, tenantAdp != nil
+}
+
+func (a *adapter) tenantRouteGeneration() uint64 {
+	a.tenantMu.Lock()
+	defer a.tenantMu.Unlock()
+	return a.tenantRouteGen
+}
+
+func (a *adapter) tenantAdapter(tenantID t.TenantID) *adapter {
+	if !a.tenantDBRouting {
+		return a
 	}
 	a.tenantMu.Lock()
-	if tenantAdp := a.tenantAdapters[tenantID]; tenantAdp != nil {
-		a.tenantMu.Unlock()
-		return tenantAdp, tenantAdp, nil
+	defer a.tenantMu.Unlock()
+	if existing := a.tenantAdapters[tenantID]; existing != nil {
+		return existing
 	}
-	a.tenantMu.Unlock()
-
 	registryDB := a.registryDB
 	if registryDB == nil {
 		registryDB = a.db
@@ -513,14 +560,32 @@ func (a *adapter) TenantAdapterFor(tenantID t.TenantID) (dbadapter.TenantBusines
 		// explicit tenant_id writes enabled for logical isolation.
 		tenantScopedDB: false,
 	}
-	a.tenantMu.Lock()
-	if existing := a.tenantAdapters[tenantID]; existing != nil {
-		a.tenantMu.Unlock()
-		return existing, existing, nil
-	}
 	a.tenantAdapters[tenantID] = tenantAdp
-	a.tenantMu.Unlock()
-	return tenantAdp, tenantAdp, nil
+	return tenantAdp
+}
+
+func (a *adapter) cacheTenantAdapter(tenantID t.TenantID, tenantAdp *adapter, generation uint64, expiresAt time.Time) {
+	a.tenantMu.Lock()
+	defer a.tenantMu.Unlock()
+	if generation != a.tenantRouteGen || tenantAdp == nil {
+		return
+	}
+	if a.tenantRouteExpiry == nil {
+		a.tenantRouteExpiry = make(map[t.TenantID]time.Time)
+	}
+	a.tenantRouteExpiry[tenantID] = expiresAt
+}
+
+// InvalidateTenantRoute forces the next operation to revalidate tenant state.
+func (a *adapter) InvalidateTenantRoute(tenantID t.TenantID) {
+	a.tenantMu.Lock()
+	defer a.tenantMu.Unlock()
+	a.tenantRouteGen++
+	if tenantID.IsValid() {
+		delete(a.tenantRouteExpiry, tenantID)
+		return
+	}
+	a.tenantRouteExpiry = make(map[t.TenantID]time.Time)
 }
 
 func (a *adapter) tenantByID(tenantID t.TenantID) (*t.Tenant, error) {
@@ -4342,10 +4407,10 @@ func (a *adapter) FileStartUpload(fd *t.FileDef) error {
 		user = 0
 	}
 	_, err := a.db.ExecContext(ctx,
-		"INSERT INTO im_fileuploads(id,createdat,updatedat,userid,status,mimetype,size,etag,location) "+
-			"VALUES(?,?,?,?,?,?,?,?,?)",
+		"INSERT INTO im_fileuploads(id,createdat,updatedat,userid,status,mimetype,size,etag,location,original_name) "+
+			"VALUES(?,?,?,?,?,?,?,?,?,?)",
 		store.DecodeUid(fd.Uid()), fd.CreatedAt, fd.UpdatedAt, user,
-		fd.Status, fd.MimeType, fd.Size, fd.ETag, fd.Location)
+		fd.Status, fd.MimeType, fd.Size, fd.ETag, fd.Location, strings.TrimSpace(fd.OriginalName))
 	return err
 }
 
@@ -4367,8 +4432,8 @@ func (a *adapter) FileFinishUpload(fd *t.FileDef, success bool, size int64) (*t.
 
 	now := t.TimeNow()
 	if success {
-		_, err = tx.ExecContext(ctx, "UPDATE im_fileuploads SET updatedat=?,status=?,size=?,etag=?,location=? WHERE id=?",
-			now, t.UploadCompleted, size, fd.ETag, fd.Location, store.DecodeUid(fd.Uid()))
+		_, err = tx.ExecContext(ctx, "UPDATE im_fileuploads SET updatedat=?,status=?,size=?,etag=?,location=?,original_name=? WHERE id=?",
+			now, t.UploadCompleted, size, fd.ETag, fd.Location, strings.TrimSpace(fd.OriginalName), store.DecodeUid(fd.Uid()))
 		if err != nil {
 			return nil, err
 		}
@@ -4406,11 +4471,11 @@ func (a *adapter) FileGet(fid string) (*t.FileDef, error) {
 		defer cancel()
 	}
 	var fd t.FileDef
-	err := a.db.GetContext(ctx, &fd, "SELECT id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location "+
+	err := a.db.GetContext(ctx, &fd, "SELECT id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location,IFNULL(original_name,'') AS original_name "+
 		"FROM im_fileuploads WHERE id=?", store.DecodeUid(id))
 	if err == sql.ErrNoRows {
 		storageName := id.String32()
-		err = a.db.GetContext(ctx, &fd, "SELECT id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location "+
+		err = a.db.GetContext(ctx, &fd, "SELECT id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location,IFNULL(original_name,'') AS original_name "+
 			"FROM im_fileuploads WHERE location=? OR location LIKE ? ORDER BY createdat DESC LIMIT 1", storageName, "%/"+storageName)
 	}
 	if err == sql.ErrNoRows {
@@ -4664,6 +4729,17 @@ func (a *adapter) FileUserHasAccess(fid string, uid t.Uid) (bool, error) {
 			WHERE (gf.file_id=? OR gf.file_id LIKE CONCAT(?,'.%')) AND gf.status='active'
 					AND s.deletedat IS NULL AND INSTR(s.modewant,'R')>0 AND INSTR(s.modegiven,'R')>0
 			)
+			OR EXISTS (
+				-- 用户头像/资料文件：设置头像时写入的链接行有两种形态——
+				-- userid 形态（topic/msgid 为 NULL，userid=头像主人，旧版写入）与
+				-- 纯数字 uid topic 形态（现行写入；合法业务 topic 均带字母前缀，不会误伤）。
+				-- 头像属于公开资料，对任何登录用户放行。
+				SELECT 1 FROM im_filemsglinks AS fml
+				WHERE fml.fileid=fu.id AND fml.msgid IS NULL AND (
+					(fml.topic IS NULL AND fml.userid IS NOT NULL)
+					OR fml.topic REGEXP '^[0-9]+$'
+				)
+			)
 		) LIMIT 1`, args
 	}
 	run := func() error {
@@ -4671,7 +4747,7 @@ func (a *adapter) FileUserHasAccess(fid string, uid t.Uid) (bool, error) {
 		return a.db.GetContext(ctx, &allowed, query, args...)
 	}
 	err := run()
-	for attempt := 0; isRetryableMySQLReadErr(err) && attempt < 2; attempt++ {
+	for attempt := 0; isRetryableMySQLError(err) && attempt < 2; attempt++ {
 		time.Sleep(time.Duration(attempt+1) * 25 * time.Millisecond)
 		err = run()
 	}
@@ -4771,6 +4847,27 @@ func isDupe(err error) bool {
 	return ok && myerr.Number == 1062
 }
 
+func isInvalidConnection(err error) bool {
+	return errors.Is(err, ms.ErrInvalidConn)
+}
+
+// retryInvalidConnection retries only operations which are independently
+// idempotent. Callers must not use it for unconstrained writes.
+func retryInvalidConnection(operation string, fn func() error) error {
+	err := fn()
+	if !isInvalidConnection(err) {
+		return err
+	}
+	immetrics.IncDBInvalidConnectionRetry(operation, "attempt")
+	err = fn()
+	if err == nil || isDupe(err) {
+		immetrics.IncDBInvalidConnectionRetry(operation, "recovered")
+	} else {
+		immetrics.IncDBInvalidConnectionRetry(operation, "failed")
+	}
+	return err
+}
+
 func isMissingTable(err error) bool {
 	if err == nil {
 		return false
@@ -4813,7 +4910,7 @@ func isIDOutOfRange(err error) bool {
 	return ok && myerr.Number == 1264 && strings.Contains(strings.ToLower(myerr.Message), "id")
 }
 
-func isRetryableMySQLReadErr(err error) bool {
+func isRetryableMySQLError(err error) bool {
 	if err == nil {
 		return false
 	}

server/db/mysql/adapter_tenant_route_cache_test.go

@@ -0,0 +1,66 @@
+//go:build mysql
+
+package mysql
+
+import (
+	"testing"
+	"time"
+
+	"github.com/tinode/chat/server/store/types"
+)
+
+func TestTenantRouteCacheExpiresAndInvalidates(t *testing.T) {
+	now := time.Now()
+	tenantID := types.TenantID(8)
+	tenantAdp := &adapter{tenantID: tenantID}
+	root := &adapter{
+		tenantDBRouting:   true,
+		tenantAdapters:    map[types.TenantID]*adapter{tenantID: tenantAdp},
+		tenantRouteExpiry: make(map[types.TenantID]time.Time),
+	}
+
+	root.cacheTenantAdapter(tenantID, tenantAdp, root.tenantRouteGeneration(), now.Add(time.Minute))
+	if got, ok := root.cachedTenantAdapter(tenantID, now); !ok || got != tenantAdp {
+		t.Fatalf("cached route = %p, %v; want %p, true", got, ok, tenantAdp)
+	}
+	if got, _, err := root.TenantAdapterFor(tenantID); err != nil || got != tenantAdp {
+		t.Fatalf("TenantAdapterFor cached route = %p, %v; want %p, nil", got, err, tenantAdp)
+	}
+
+	staleGeneration := root.tenantRouteGeneration()
+	root.InvalidateTenantRoute(tenantID)
+	if _, ok := root.cachedTenantAdapter(tenantID, now); ok {
+		t.Fatal("invalidated tenant route remained cached")
+	}
+	root.cacheTenantAdapter(tenantID, tenantAdp, staleGeneration, now.Add(time.Minute))
+	if _, ok := root.cachedTenantAdapter(tenantID, now); ok {
+		t.Fatal("an in-flight stale refresh repopulated the route cache")
+	}
+
+	root.cacheTenantAdapter(tenantID, tenantAdp, root.tenantRouteGeneration(), now.Add(-time.Second))
+	if _, ok := root.cachedTenantAdapter(tenantID, now); ok {
+		t.Fatal("expired tenant route remained cached")
+	}
+}
+
+func TestInvalidateAllTenantRoutes(t *testing.T) {
+	now := time.Now()
+	root := &adapter{
+		tenantDBRouting: true,
+		tenantAdapters: map[types.TenantID]*adapter{
+			8: {tenantID: 8},
+			9: {tenantID: 9},
+		},
+		tenantRouteExpiry: map[types.TenantID]time.Time{
+			8: now.Add(time.Minute),
+			9: now.Add(time.Minute),
+		},
+	}
+
+	root.InvalidateTenantRoute(0)
+	for _, tenantID := range []types.TenantID{8, 9} {
+		if _, ok := root.cachedTenantAdapter(tenantID, now); ok {
+			t.Fatalf("tenant %d route remained cached after global invalidation", tenantID)
+		}
+	}
+}

server/db/mysql/admin_governance_schema.go

@@ -17,6 +17,7 @@ func ensureIMAdminGovernanceTables(exec sqlExecutor) error {
 			request_id VARCHAR(64) NOT NULL DEFAULT '', login_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 			logout_at DATETIME(3), metadata JSON, created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 			PRIMARY KEY(id), INDEX idx_im_user_login_tenant_time(tenant_id, login_at DESC, id DESC),
+			INDEX idx_im_user_login_session_close(tenant_id, session_id, logout_at),
 			INDEX idx_im_user_login_user_time(user_id, login_at DESC, id DESC),
 			INDEX idx_im_user_login_ip_time(ip, login_at DESC, id DESC),
 			INDEX idx_im_user_login_device_time(device_id(64), login_at DESC),
@@ -53,5 +54,9 @@ func ensureIMAdminGovernanceTables(exec sqlExecutor) error {
 			return err
 		}
 	}
+	if err := execIgnoreMySQLError(exec,
+		`ALTER TABLE im_user_login_logs ADD INDEX idx_im_user_login_session_close(tenant_id,session_id,logout_at)`, 1061); err != nil {
+		return err
+	}
 	return nil
 }

server/db/mysql/admin_governance_schema_test.go

@@ -13,8 +13,8 @@ func TestEnsureIMAdminGovernanceTablesDefinesLoginAuditTenantScope(t *testing.T)
 	if err := ensureIMAdminGovernanceTables(exec); err != nil {
 		t.Fatal(err)
 	}
-	if len(exec.statements) != 3 {
-		t.Fatalf("created %d admin governance tables, want 3", len(exec.statements))
+	if len(exec.statements) != 4 {
+		t.Fatalf("executed %d admin governance schema statements, want 4", len(exec.statements))
 	}
 	joined := strings.ToLower(strings.Join(exec.statements, "\n"))
 	for _, table := range []string{"im_user_login_logs", "im_message_admin_actions", "im_user_ip_whitelists"} {
@@ -38,4 +38,8 @@ func TestEnsureIMAdminGovernanceTablesDefinesLoginAuditTenantScope(t *testing.T)
 	if end < 0 || !strings.Contains(joined[start:start+end], "tenant_id bigint not null") {
 		t.Fatal("im_user_login_logs must declare tenant_id")
 	}
+	if !strings.Contains(joined, "idx_im_user_login_session_close(tenant_id, session_id, logout_at)") &&
+		!strings.Contains(joined, "idx_im_user_login_session_close(tenant_id,session_id,logout_at)") {
+		t.Fatal("im_user_login_logs must index tenant-scoped session close updates")
+	}
 }

server/db/mysql/file_review_tasks.go

@@ -6,6 +6,7 @@ package mysql
 import (
 	"context"
 	"database/sql"
+	"strings"
 
 	"github.com/tinode/chat/server/store"
 	t "github.com/tinode/chat/server/store/types"
@@ -16,6 +17,10 @@ type fileReviewExecContext interface {
 }
 
 func insertFileReviewTasks(ctx context.Context, exec fileReviewExecContext, fd *t.FileDef) error {
+	storageProvider := ""
+	if strings.HasPrefix(fd.Location, "minio://") {
+		storageProvider = "minio"
+	}
 	fileID := decodeUID(fd.Uid())
 	userID := int64(0)
 	if fd.User != "" {
@@ -37,7 +42,7 @@ func insertFileReviewTasks(ctx context.Context, exec fileReviewExecContext, fd *
 		_, err = exec.ExecContext(ctx, `INSERT IGNORE INTO im_file_review_tasks
 			(id,task_id,file_id,user_id,task_type,provider,storage_provider,object_name,mime_type,file_size,status,created_at,updated_at)
 			VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
-			id, taskID, fileID, userID, task.taskType, task.provider, "", fd.Location, fd.MimeType, fd.Size,
+			id, taskID, fileID, userID, task.taskType, task.provider, storageProvider, fd.Location, fd.MimeType, fd.Size,
 			t.FileReviewStatusPending, fd.UpdatedAt, fd.UpdatedAt)
 		if err != nil {
 			return err

server/db/mysql/group_schema_test.go

@@ -4,6 +4,7 @@ package mysql
 
 import (
 	"database/sql"
+	"os"
 	"strings"
 	"testing"
 
@@ -150,3 +151,44 @@ func TestTenantShardSQL(t *testing.T) {
 		t.Fatalf("tenant shard query rewrote index name: %s", query)
 	}
 }
+
+func TestSharedDBGroupFileLinkIncludesTenantID(t *testing.T) {
+	source, err := os.ReadFile("tenant_groups.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := sourceBetween(t, string(source), "func (a *adapter) TenantGroupFileCreate", "\nfunc (a *adapter) enrichGroupFileFromUpload")
+	for _, required := range []string{
+		"INSERT INTO im_filemsglinks(tenant_id,createdat,fileid,topic)",
+		"SELECT ?,?,?,? WHERE NOT EXISTS",
+		"SELECT 1 FROM im_filemsglinks WHERE tenant_id=? AND fileid=? AND topic=?)",
+	} {
+		if !strings.Contains(body, required) {
+			t.Fatalf("TenantGroupFileCreate shared-db file link must include tenant_id; missing %q", required)
+		}
+	}
+	if strings.Contains(body, "INSERT INTO im_filemsglinks(createdat,fileid,topic)") {
+		t.Fatal("TenantGroupFileCreate must not rely on im_filemsglinks.tenant_id default")
+	}
+}
+
+func TestTenantUsersShareOpenPrivateGroupChecksBothMembersAndSetting(t *testing.T) {
+	source, err := os.ReadFile("tenant_groups.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := sourceBetween(t, string(source), "func (a *adapter) TenantUsersShareOpenPrivateGroup", "\nfunc (a *adapter) TenantGroupMemberUpdate")
+	for _, required := range []string{
+		"INNER JOIN im_group_members AS gm2",
+		"gm2.topic=gm1.topic",
+		"INNER JOIN im_group_settings AS gs",
+		"gs.member_private_chat=1",
+		"gm1.member_status=?",
+		"gm2.member_status=?",
+		"gs.group_status=?",
+	} {
+		if !strings.Contains(body, required) {
+			t.Fatalf("TenantUsersShareOpenPrivateGroup must check active shared group and setting; missing %q", required)
+		}
+	}
+}

server/db/mysql/invalid_connection_test.go

@@ -0,0 +1,55 @@
+//go:build mysql
+
+package mysql
+
+import (
+	"context"
+	"database/sql/driver"
+	"errors"
+	"testing"
+
+	ms "github.com/go-sql-driver/mysql"
+)
+
+func TestRetryInvalidConnectionRetriesOnce(t *testing.T) {
+	attempts := 0
+	err := retryInvalidConnection("test", func() error {
+		attempts++
+		if attempts == 1 {
+			return ms.ErrInvalidConn
+		}
+		return nil
+	})
+	if err != nil || attempts != 2 {
+		t.Fatalf("err=%v attempts=%d", err, attempts)
+	}
+}
+
+func TestRetryInvalidConnectionDoesNotRetryOtherErrors(t *testing.T) {
+	want := errors.New("write failed")
+	attempts := 0
+	err := retryInvalidConnection("test", func() error {
+		attempts++
+		return want
+	})
+	if !errors.Is(err, want) || attempts != 1 {
+		t.Fatalf("err=%v attempts=%d", err, attempts)
+	}
+}
+
+func TestInstrumentedQueryDiscardsInvalidConnection(t *testing.T) {
+	conn := instrumentedConn{conn: invalidQueryConn{}}
+	_, err := conn.QueryContext(context.Background(), "SELECT 1", nil)
+	if !errors.Is(err, driver.ErrBadConn) {
+		t.Fatalf("err=%v want=%v", err, driver.ErrBadConn)
+	}
+}
+
+type invalidQueryConn struct{}
+
+func (invalidQueryConn) Prepare(string) (driver.Stmt, error) { return nil, driver.ErrSkip }
+func (invalidQueryConn) Close() error                        { return nil }
+func (invalidQueryConn) Begin() (driver.Tx, error)           { return nil, driver.ErrSkip }
+func (invalidQueryConn) QueryContext(context.Context, string, []driver.NamedValue) (driver.Rows, error) {
+	return nil, ms.ErrInvalidConn
+}

server/db/mysql/metrics_driver.go

@@ -113,6 +113,12 @@ func (c instrumentedConn) QueryContext(ctx context.Context, query string, args [
 	started := time.Now()
 	rows, err := queryer.QueryContext(ctx, query, args)
 	immetrics.ObserveDB("mysql", "query", started, err)
+	if isInvalidConnection(err) {
+		// Queries are idempotent. Returning ErrBadConn makes database/sql discard
+		// this connection and transparently retry on a fresh one.
+		immetrics.IncDBInvalidConnectionRetry("query", "discard")
+		return nil, driver.ErrBadConn
+	}
 	return rows, err
 }
 
@@ -211,6 +217,10 @@ func (s instrumentedStmt) QueryContext(ctx context.Context, args []driver.NamedV
 	started := time.Now()
 	rows, err := queryer.QueryContext(ctx, args)
 	immetrics.ObserveDB("mysql", "query", started, err)
+	if isInvalidConnection(err) {
+		immetrics.IncDBInvalidConnectionRetry("prepared_query", "discard")
+		return nil, driver.ErrBadConn
+	}
 	return rows, err
 }
 

server/db/mysql/tenant_adapter.go

@@ -2233,75 +2233,146 @@ func (a *adapter) TenantMessageSave(id t.TenantID, msg *t.Message) error {
 	if a.tenantScopedDB {
 		return a.MessageSave(msg)
 	}
-	ctx, cancel := a.getContext()
-	if cancel != nil {
-		defer cancel()
+	save := func() error {
+		ctx, cancel := a.getContext()
+		if cancel != nil {
+			defer cancel()
+		}
+		clientMsgID := sql.NullString{String: msg.ClientMsgID, Valid: msg.ClientMsgID != ""}
+		res, saveErr := a.db.ExecContext(ctx,
+			fmt.Sprintf("INSERT INTO %s(tenant_id,createdat,updatedat,seqid,topic,`from`,client_msg_id,version,head,content,content_nonce,key_version) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)", tenantMessagesTable(id)),
+			id, msg.CreatedAt, msg.UpdatedAt, msg.SeqId, msg.Topic, decodeUID(t.ParseUid(msg.From)), clientMsgID, messageVersion(msg.Version), msg.Head, common.ToJSON(msg.Content), msg.ContentNonce, msg.KeyVersion)
+		if saveErr == nil {
+			lastID, _ := res.LastInsertId()
+			msg.SetUid(t.Uid(lastID))
+		}
+		return saveErr
+	}
+	if msg.ClientMsgID == "" {
+		err = save()
+	} else {
+		err = retryInvalidConnection("tenant_message_save", save)
 	}
-	clientMsgID := sql.NullString{String: msg.ClientMsgID, Valid: msg.ClientMsgID != ""}
-	res, err := a.db.ExecContext(ctx,
-		fmt.Sprintf("INSERT INTO %s(tenant_id,createdat,updatedat,seqid,topic,`from`,client_msg_id,version,head,content,content_nonce,key_version) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)", tenantMessagesTable(id)),
-		id, msg.CreatedAt, msg.UpdatedAt, msg.SeqId, msg.Topic, decodeUID(t.ParseUid(msg.From)), clientMsgID, messageVersion(msg.Version), msg.Head, common.ToJSON(msg.Content), msg.ContentNonce, msg.KeyVersion)
 	if isDupe(err) {
 		return t.ErrDuplicate
 	}
-	if err == nil {
-		lastID, _ := res.LastInsertId()
-		msg.SetUid(t.Uid(lastID))
-	}
 	return err
 }
 
+// schemaColumnContract describes the required shape of one column.
+type schemaColumnContract struct {
+	dataType string
+	notNull  bool
+	autoInc  bool
+}
+
+func (c schemaColumnContract) describe() string {
+	out := strings.ToUpper(c.dataType)
+	if c.notNull {
+		out += " NOT NULL"
+	}
+	if c.autoInc {
+		out += " AUTO_INCREMENT"
+	}
+	return out
+}
+
+// TenantMessageSchemaValidate verifies the storage contracts asynchronous
+// persistence depends on: message ids and topic sequence counters are written
+// as explicit snowflake int64 values, and file-message links reference them.
+// A column that is still INT overflows on the first snowflake write and, under
+// Kafka persistence, stalls the consumer partition instead of failing fast.
 func (a *adapter) TenantMessageSchemaValidate(tenantIDs []t.TenantID) error {
 	if len(tenantIDs) == 0 {
 		return errors.New("mysql: no active tenants available for message schema validation")
 	}
+	// Message ids are explicit snowflake values stored in the auto-increment
+	// id column; sequence counters and file ids are snowflake-derived too.
+	var (
+		bigintPK  = schemaColumnContract{dataType: "bigint", notNull: true, autoInc: true}
+		bigintReq = schemaColumnContract{dataType: "bigint", notNull: true}
+		bigintOpt = schemaColumnContract{dataType: "bigint"}
+	)
+	type scopedCheck struct {
+		table  string
+		column string
+		want   schemaColumnContract
+	}
+	perTenant := func(tenantID t.TenantID, scopedDB bool) []scopedCheck {
+		msgTable, topicsTable, subsTable := tenantMessagesTable(tenantID), tenantTopicsTable(tenantID), tenantSubscriptionsTable(tenantID)
+		if scopedDB {
+			msgTable, topicsTable, subsTable = "im_messages", "im_topics", "im_subscriptions"
+		}
+		return []scopedCheck{
+			{msgTable, "id", bigintPK},
+			{topicsTable, "seqid", bigintReq},
+			{subsTable, "recvseqid", bigintOpt},
+			{subsTable, "readseqid", bigintOpt},
+			// Global file tables exist once per database and are shared by all tenants.
+			{"im_filemsglinks", "fileid", bigintReq},
+			{"im_filemsglinks", "msgid", bigintOpt},
+			{"im_fileuploads", "id", bigintReq},
+		}
+	}
 	validated := make(map[*adapter]map[string]struct{})
+	run := func(tenantAdp *adapter, chk scopedCheck) error {
+		key := chk.table + "." + chk.column
+		if _, ok := validated[tenantAdp][key]; ok {
+			return nil
+		}
+		if err := tenantAdp.validateColumnContract(chk.table, chk.column, chk.want); err != nil {
+			return err
+		}
+		if validated[tenantAdp] == nil {
+			validated[tenantAdp] = make(map[string]struct{})
+		}
+		validated[tenantAdp][key] = struct{}{}
+		return nil
+	}
 	for _, tenantID := range tenantIDs {
 		tenantAdp, err := a.routedTenantAdapter(tenantID)
 		if err != nil {
 			return fmt.Errorf("mysql: resolve tenant %d for message schema validation: %w", tenantID, err)
 		}
-		table := tenantMessagesTable(tenantID)
-		if tenantAdp.tenantScopedDB {
-			table = "im_messages"
+		for _, chk := range perTenant(tenantID, tenantAdp.tenantScopedDB) {
+			if err = run(tenantAdp, chk); err != nil {
+				return err
+			}
 		}
-		if validated[tenantAdp] == nil {
-			validated[tenantAdp] = make(map[string]struct{})
-		}
-		if _, ok := validated[tenantAdp][table]; ok {
-			continue
-		}
-		if err = tenantAdp.validateMessageIDColumn(table); err != nil {
-			return err
-		}
-		validated[tenantAdp][table] = struct{}{}
 	}
 	if !a.tenantScopedDB {
-		if err := a.validateMessageIDColumn("im_messages"); err != nil {
-			return err
+		for _, chk := range perTenant(0, true) {
+			if err := run(a, chk); err != nil {
+				return err
+			}
 		}
 	}
 	return nil
 }
 
-func (a *adapter) validateMessageIDColumn(table string) error {
-	if !regexp.MustCompile(`^im_(?:[0-9]+_)?messages$`).MatchString(table) {
-		return fmt.Errorf("mysql: unsafe message table name %q", table)
+// validateColumnContract fails when the live column shape does not match the
+// contract. The caller turns the error into a fatal startup failure so a
+// drifted schema is caught before the first write instead of as a stuck
+// persistence partition.
+func (a *adapter) validateColumnContract(table, column string, want schemaColumnContract) error {
+	if !regexp.MustCompile(`^im_(?:[0-9]{3}_)?[a-z_]+$`).MatchString(table) {
+		return fmt.Errorf("mysql: unsafe table name %q for schema validation", table)
 	}
 	var dataType, nullable, extra string
 	err := a.db.QueryRow(`SELECT DATA_TYPE,IS_NULLABLE,EXTRA FROM information_schema.COLUMNS
-		WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME=? AND COLUMN_NAME='id'`, table).
+		WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME=? AND COLUMN_NAME=?`, table, column).
 		Scan(&dataType, &nullable, &extra)
 	if err == sql.ErrNoRows {
-		return fmt.Errorf("mysql: required message table %s is missing", table)
+		return fmt.Errorf("mysql: required table %s is missing", table)
 	}
 	if err != nil {
-		return fmt.Errorf("mysql: inspect %s.id: %w", table, err)
+		return fmt.Errorf("mysql: inspect %s.%s: %w", table, column, err)
 	}
-	if !strings.EqualFold(dataType, "bigint") || !strings.EqualFold(nullable, "NO") ||
-		!strings.Contains(strings.ToLower(extra), "auto_increment") {
-		return fmt.Errorf("mysql: incompatible %s.id schema: type=%s nullable=%s extra=%s; want BIGINT NOT NULL AUTO_INCREMENT",
-			table, dataType, nullable, extra)
+	if !strings.EqualFold(dataType, want.dataType) || want.notNull != strings.EqualFold(nullable, "NO") ||
+		(want.autoInc && !strings.Contains(strings.ToLower(extra), "auto_increment")) {
+		return fmt.Errorf("mysql: incompatible %s.%s schema: type=%s nullable=%s extra=%s; want %s "+
+			"(apply scripts/IM-租户业务库初始化.sql equivalents or the matching BIGINT migration before starting)",
+			table, column, dataType, nullable, extra, want.describe())
 	}
 	return nil
 }
@@ -2349,7 +2420,17 @@ func (a *adapter) TenantGroupMessageSave(id t.TenantID, msg *t.Message) error {
 	if tenantAdp != a {
 		return tenantAdp.TenantGroupMessageSave(id, msg)
 	}
-	if err = a.ensureCurrentGroupMessageShardWindow(); err != nil {
+	err = retryInvalidConnection("tenant_group_message_save", func() error {
+		return a.tenantGroupMessageSaveOnce(id, msg)
+	})
+	if isDupe(err) {
+		return t.ErrDuplicate
+	}
+	return err
+}
+
+func (a *adapter) tenantGroupMessageSaveOnce(id t.TenantID, msg *t.Message) error {
+	if err := a.ensureCurrentGroupMessageShardWindow(); err != nil {
 		return err
 	}
 	ctx, cancel := a.getContext()
@@ -2398,9 +2479,6 @@ func (a *adapter) TenantGroupMessageSave(id t.TenantID, msg *t.Message) error {
 		id, messageID, msg.Topic, groupID, msg.SeqId, decodeUID(t.ParseUid(msg.From)), clientMsgID, messageHeadType(msg.Head), "normal",
 		contentJSON, msg.Head, messageHeadJSON(msg.Head, "mentioned_user_ids"), messageHeadBool(msg.Head, "mention_all"),
 		0, len(contentJSON), messageVersion(msg.Version), msg.CreatedAt, msg.UpdatedAt, msg.ContentNonce, msg.KeyVersion)
-	if isDupe(err) {
-		return t.ErrDuplicate
-	}
 	if err != nil {
 		return err
 	}
@@ -3305,7 +3383,7 @@ func (a *adapter) tenantP2PMessageMutations(ctx context.Context, id t.TenantID,
 			fmt.Sprintf("FROM %s AS m ", tenantMessagesTable(id))+
 			"LEFT JOIN im_dellog AS d ON d.tenant_id=m.tenant_id AND d.topic=m.topic AND m.seqid BETWEEN d.low AND d.hi-1 AND d.deletedfor=? "+
 			"LEFT JOIN im_message_revisions AS rev ON rev.tenant_id=m.tenant_id AND rev.topic=m.topic AND rev.seqid=m.seqid AND rev.version=m.version-1 "+
-			"WHERE m.tenant_id=? AND m.topic=? AND d.deletedfor IS NULL AND (m.version>1 OR m.recalled_at IS NOT NULL OR m.deletedat IS NOT NULL) "+
+			"WHERE m.tenant_id=? AND m.topic=? AND d.deletedfor IS NULL AND (m.version>1 OR m.recalled_at IS NOT NULL) "+
 			"ORDER BY m.updatedat DESC,m.seqid DESC LIMIT ?",
 		decodeUID(uid), id, topic, limit+1)
 	if err != nil {
@@ -3327,7 +3405,7 @@ func (a *adapter) tenantGroupMessageMutations(ctx context.Context, id t.TenantID
 			fmt.Sprintf("FROM %s AS m ", table)+
 			"LEFT JOIN im_dellog AS d ON d.tenant_id=m.tenant_id AND d.topic COLLATE utf8mb4_unicode_ci=m.topic AND m.seqid BETWEEN d.low AND d.hi-1 AND d.deletedfor=? "+
 			"LEFT JOIN im_message_revisions AS rev ON rev.tenant_id=m.tenant_id AND rev.topic=m.topic AND rev.seqid=m.seqid AND rev.version=m.version-1 "+
-			"WHERE m.tenant_id=? AND m.topic=? AND d.deletedfor IS NULL AND (m.version>1 OR m.recalled_at IS NOT NULL OR m.deleted_at IS NOT NULL OR m.status='recalled')")
+			"WHERE m.tenant_id=? AND m.topic=? AND d.deletedfor IS NULL AND (m.version>1 OR m.recalled_at IS NOT NULL OR m.status='recalled')")
 		args = append(args, decodeUID(uid), id, topic)
 	}
 	args = append(args, limit+1)
@@ -5200,8 +5278,8 @@ func (a *adapter) TenantFileStartUpload(id t.TenantID, fd *t.FileDef) error {
 		defer cancel()
 	}
 	_, err = a.db.ExecContext(ctx,
-		"INSERT INTO im_fileuploads(tenant_id,id,createdat,updatedat,userid,status,mimetype,size,etag,location) VALUES(?,?,?,?,?,?,?,?,?,?)",
-		id, decodeUID(fd.Uid()), fd.CreatedAt, fd.UpdatedAt, user, fd.Status, fd.MimeType, fd.Size, fd.ETag, fd.Location)
+		"INSERT INTO im_fileuploads(tenant_id,id,createdat,updatedat,userid,status,mimetype,size,etag,location,original_name) VALUES(?,?,?,?,?,?,?,?,?,?,?)",
+		id, decodeUID(fd.Uid()), fd.CreatedAt, fd.UpdatedAt, user, fd.Status, fd.MimeType, fd.Size, fd.ETag, fd.Location, strings.TrimSpace(fd.OriginalName))
 	return err
 }
 
@@ -5232,8 +5310,8 @@ func (a *adapter) TenantFileFinishUpload(id t.TenantID, fd *t.FileDef, success b
 	}()
 	now := t.TimeNow()
 	if success {
-		_, err = tx.Exec("UPDATE im_fileuploads SET updatedat=?,status=?,size=?,etag=?,location=? WHERE tenant_id=? AND id=?",
-			now, t.UploadCompleted, size, fd.ETag, fd.Location, id, decodeUID(fd.Uid()))
+		_, err = tx.Exec("UPDATE im_fileuploads SET updatedat=?,status=?,size=?,etag=?,location=?,original_name=? WHERE tenant_id=? AND id=?",
+			now, t.UploadCompleted, size, fd.ETag, fd.Location, strings.TrimSpace(fd.OriginalName), id, decodeUID(fd.Uid()))
 		if err == nil {
 			fd.UpdatedAt = now
 			fd.Size = size
@@ -5274,12 +5352,12 @@ func (a *adapter) TenantFileGet(id t.TenantID, fid string) (*t.FileDef, error) {
 	}
 	var fd t.FileDef
 	err = a.db.GetContext(ctx, &fd,
-		"SELECT tenant_id,id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location "+
+		"SELECT tenant_id,id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location,IFNULL(original_name,'') AS original_name "+
 			"FROM im_fileuploads WHERE tenant_id=? AND id=?", id, decodeUID(fileID))
 	if err == sql.ErrNoRows {
 		storageName := fileID.String32()
 		err = a.db.GetContext(ctx, &fd,
-			"SELECT tenant_id,id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location "+
+			"SELECT tenant_id,id,createdat,updatedat,userid AS user,status,mimetype,size,IFNULL(etag,'') AS etag,location,IFNULL(original_name,'') AS original_name "+
 				"FROM im_fileuploads WHERE tenant_id=? AND (location=? OR location LIKE ?) ORDER BY createdat DESC LIMIT 1",
 			id, storageName, "%/"+storageName)
 	}
@@ -5507,6 +5585,17 @@ func (a *adapter) TenantFileUserHasAccess(id t.TenantID, fid string, uid t.Uid)
 				WHERE gf.tenant_id=fu.tenant_id AND (gf.file_id=? OR gf.file_id LIKE CONCAT(?,'.%%')) AND gf.status='active'
 					AND s.deletedat IS NULL AND INSTR(s.modewant,'R')>0 AND INSTR(s.modegiven,'R')>0
 			)
+			OR EXISTS (
+				-- 用户头像/资料文件：设置头像时写入的链接行有两种形态——
+				-- userid 形态（topic/msgid 为 NULL，userid=头像主人）与
+				-- 纯数字 uid topic 形态（store 层已把 usr 前缀 topic 归一为 userid 形态）。
+				-- 头像属于公开资料，对任何登录用户放行；与 FileUserHasAccess 的第 9 条保持一致。
+				SELECT 1 FROM im_filemsglinks AS fml
+				WHERE fml.tenant_id=fu.tenant_id AND fml.fileid=fu.id AND fml.msgid IS NULL AND (
+					(fml.topic IS NULL AND fml.userid IS NOT NULL)
+					OR fml.topic REGEXP '^[0-9]+$'
+				)
+			)
 		) LIMIT 1`, tenantFriendshipsTable(id), tenantMessagesTable(id))),
 		id, decodeUID(fileID), fileID.String32(), "%/"+fileID.String32(), t.UploadCompleted, decodeUID(uid), decodeUID(uid), decodeUID(uid), t.RelationshipFriend,
 		decodeUID(uid), decodeUID(uid), t.GroupMemberStatusActive, decodeUID(uid), decodeUID(uid),
@@ -6872,7 +6961,7 @@ func (a *adapter) TenantFriendRequestAccept(id t.TenantID, requestID string, act
 	eventType := "friend.request." + t.FriendRequestAccepted
 	applicantEventID := t.StableEventID("relation", row.RequestID+":"+t.FriendRequestAccepted, eventType, applicant.UserId())
 	if err = insertSystemNotificationTx(tx, id, applicant, t.StableEventID(applicantEventID, "notification"), eventType,
-		"好友申请已处理", t.FriendRequestAccepted, map[string]any{"type": "friend_request", "request_id": row.RequestID, "user_id": actor.UserId(), "topic": topic}); err != nil {
+		"好友申请已处理", "对方已同意你的好友申请", map[string]any{"type": "friend_request", "request_id": row.RequestID, "user_id": actor.UserId(), "topic": topic}); err != nil {
 		return nil, err
 	}
 	if err = tx.Commit(); err != nil {
@@ -6899,8 +6988,12 @@ func (a *adapter) TenantFriendRequestResolve(id t.TenantID, requestID string, ac
 		defer cancel()
 	}
 	req, err := a.friendRequestByRequestID(ctx, id, requestID)
-	if err != nil || req == nil {
-		return req, err
+	if err != nil {
+		return nil, err
+	}
+	if req == nil {
+		// 好友申请不存在必须返回 ErrNotFound，否则上层拿到 (nil,nil) 会解引用 panic（网关 502）。
+		return nil, t.ErrNotFound
 	}
 	if req.TargetID != actor {
 		return nil, t.ErrPermissionDenied
@@ -6920,8 +7013,12 @@ func (a *adapter) TenantFriendRequestResolve(id t.TenantID, requestID string, ac
 	}
 	eventType := "friend.request." + status
 	eventID := t.StableEventID("relation", req.RequestID+":"+status, eventType, req.ApplicantID.UserId())
+	summary := "对方已婉拒你的好友申请"
+	if status == t.FriendRequestAccepted {
+		summary = "对方已同意你的好友申请"
+	}
 	if err = insertSystemNotificationTx(tx, id, req.ApplicantID, t.StableEventID(eventID, "notification"), eventType,
-		"好友申请已处理", status, map[string]any{"type": "friend_request", "request_id": req.RequestID, "user_id": actor.UserId()}); err != nil {
+		"好友申请已处理", summary, map[string]any{"type": "friend_request", "request_id": req.RequestID, "user_id": actor.UserId()}); err != nil {
 		return nil, err
 	}
 	if err = tx.Commit(); err != nil {

server/db/mysql/tenant_groups.go

@@ -394,6 +394,83 @@ func (a *adapter) TenantGroupMemberList(id t.TenantID, topic string, opts t.Grou
 	return items, next, rows.Err()
 }
 
+// TenantGroupMembersCount counts active members for the given topics using the
+// same visibility rules as TenantGroupMemberList: membership active, subscription
+// not deleted, user not deleted. Returns counts keyed by topic; topics with no
+// active members are absent from the map.
+func (a *adapter) TenantGroupMembersCount(id t.TenantID, topics []string) (map[string]int64, error) {
+	if tenantAdp, err := a.routeGroupTenant(id); err != nil {
+		return nil, err
+	} else if tenantAdp != a {
+		return tenantAdp.TenantGroupMembersCount(id, topics)
+	}
+	if len(topics) == 0 {
+		return map[string]int64{}, nil
+	}
+	placeholders := strings.TrimSuffix(strings.Repeat("?,", len(topics)), ",")
+	args := make([]any, 0, len(topics)+3)
+	args = append(args, t.StateDeleted, id, t.GroupMemberStatusActive)
+	for _, topic := range topics {
+		args = append(args, topic)
+	}
+	ctx, cancel := a.getContext()
+	if cancel != nil {
+		defer cancel()
+	}
+	rows, err := a.db.QueryContext(ctx, tenantShardSQL(id, `SELECT gm.topic, COUNT(DISTINCT gm.user_id) FROM im_group_members AS gm
+		JOIN im_subscriptions AS s ON s.tenant_id=gm.tenant_id AND s.topic=gm.topic AND s.userid=gm.user_id AND s.deletedat IS NULL
+		JOIN im_users AS u ON u.tenant_id=gm.tenant_id AND u.id=gm.user_id AND u.state!=?
+		WHERE gm.tenant_id=? AND gm.member_status=? AND gm.topic IN (`+placeholders+`)
+		GROUP BY gm.topic`), args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	counts := make(map[string]int64, len(topics))
+	for rows.Next() {
+		var topic string
+		var count int64
+		if err = rows.Scan(&topic, &count); err != nil {
+			return nil, err
+		}
+		counts[topic] = count
+	}
+	return counts, rows.Err()
+}
+
+func (a *adapter) TenantUsersShareOpenPrivateGroup(id t.TenantID, userID, peerID t.Uid) (bool, error) {
+	if tenantAdp, err := a.routeGroupTenant(id); err != nil {
+		return false, err
+	} else if tenantAdp != a {
+		return tenantAdp.TenantUsersShareOpenPrivateGroup(id, userID, peerID)
+	}
+	if userID.IsZero() || peerID.IsZero() || userID == peerID {
+		return false, t.ErrMalformed
+	}
+	ctx, cancel := a.getContext()
+	if cancel != nil {
+		defer cancel()
+	}
+	var exists int
+	err := a.db.GetContext(ctx, &exists, tenantShardSQL(id, `
+		SELECT 1
+		FROM im_group_members AS gm1
+		INNER JOIN im_group_members AS gm2
+			ON gm2.tenant_id=gm1.tenant_id AND gm2.topic=gm1.topic
+		INNER JOIN im_group_settings AS gs
+			ON gs.tenant_id=gm1.tenant_id AND gs.topic=gm1.topic
+		WHERE gm1.tenant_id=? AND gm1.user_id=? AND gm1.member_status=?
+			AND gm2.user_id=? AND gm2.member_status=?
+			AND gs.group_status=? AND gs.member_private_chat=1
+		LIMIT 1`),
+		id, decodeUID(userID), t.GroupMemberStatusActive,
+		decodeUID(peerID), t.GroupMemberStatusActive, t.GroupStatusActive)
+	if err == sql.ErrNoRows {
+		return false, nil
+	}
+	return exists == 1, err
+}
+
 func (a *adapter) TenantGroupMemberUpdate(id t.TenantID, topic string, uid t.Uid, patch t.GroupMemberPatch) (*t.GroupMember, error) {
 	if tenantAdp, err := a.routeGroupTenant(id); err != nil {
 		return nil, err
@@ -1132,10 +1209,10 @@ func (a *adapter) TenantGroupFileCreate(id t.TenantID, file *t.GroupFile) (*t.Gr
 					SELECT 1 FROM im_filemsglinks WHERE tenant_id=? AND fileid=? AND topic=?)`,
 				id, now, decodeUID(fid), file.Topic, id, decodeUID(fid), file.Topic)
 		} else {
-			_, err = tx.ExecContext(ctx, `INSERT INTO im_filemsglinks(createdat,fileid,topic)
-				SELECT ?,?,? WHERE NOT EXISTS (
-					SELECT 1 FROM im_filemsglinks WHERE fileid=? AND topic=?)`,
-				now, decodeUID(fid), file.Topic, decodeUID(fid), file.Topic)
+			_, err = tx.ExecContext(ctx, `INSERT INTO im_filemsglinks(tenant_id,createdat,fileid,topic)
+				SELECT ?,?,?,? WHERE NOT EXISTS (
+					SELECT 1 FROM im_filemsglinks WHERE tenant_id=? AND fileid=? AND topic=?)`,
+				id, now, decodeUID(fid), file.Topic, id, decodeUID(fid), file.Topic)
 		}
 		if err != nil {
 			return nil, err
@@ -1478,27 +1555,33 @@ func (a *adapter) TenantGroupOwnerTransfer(id t.TenantID, topic string, previous
 	return tx.Commit()
 }
 
-func (a *adapter) TenantGroupCanPost(id t.TenantID, topic string, uid t.Uid, admin bool, now time.Time) (bool, error) {
+func (a *adapter) TenantGroupCanPost(id t.TenantID, topic string, uid t.Uid, _ bool, now time.Time) (bool, error) {
 	if tenantAdp, err := a.routeGroupTenant(id); err != nil {
 		return false, err
 	} else if tenantAdp != a {
-		return tenantAdp.TenantGroupCanPost(id, topic, uid, admin, now)
-	}
-	if admin {
-		return true, nil
+		return tenantAdp.TenantGroupCanPost(id, topic, uid, false, now)
 	}
 	ctx, cancel := a.getContext()
 	if cancel != nil {
 		defer cancel()
 	}
+	var role string
 	var muteAll, memberMuted bool
-	err := a.db.QueryRowContext(ctx, `SELECT
+	err := a.db.QueryRowContext(ctx, tenantShardSQL(id, `SELECT
+		COALESCE((SELECT role FROM im_group_members WHERE tenant_id=? AND topic=? AND user_id=? AND member_status=? LIMIT 1),''),
 		COALESCE((SELECT mute_all FROM im_group_settings WHERE tenant_id=? AND topic=? AND group_status=? LIMIT 1),0),
-		EXISTS(SELECT 1 FROM im_group_mutes WHERE tenant_id=? AND topic=? AND user_id=? AND status=? AND (expires_at IS NULL OR expires_at>?))`,
-		id, topic, t.GroupStatusActive, id, topic, decodeUID(uid), t.GroupMuteStatusActive, now).Scan(&muteAll, &memberMuted)
+		EXISTS(SELECT 1 FROM im_group_mutes WHERE tenant_id=? AND topic=? AND user_id=? AND status=? AND (expires_at IS NULL OR expires_at>?))`),
+		id, topic, decodeUID(uid), t.GroupMemberStatusActive,
+		id, topic, t.GroupStatusActive, id, topic, decodeUID(uid), t.GroupMuteStatusActive, now).Scan(&role, &muteAll, &memberMuted)
 	if err != nil {
 		return false, err
 	}
+	if role == t.GroupMemberRoleOwner || role == t.GroupMemberRoleAdmin {
+		return true, nil
+	}
+	if role != t.GroupMemberRoleMember {
+		return false, nil
+	}
 	return !muteAll && !memberMuted, nil
 }
 

server/db/mysql/tenant_security_audit.go

@@ -93,7 +93,18 @@ func (a *adapter) TenantLoginAuditClose(id t.TenantID, sessionID string, at time
 	if tenantAdp != a {
 		return tenantAdp.TenantLoginAuditClose(id, sessionID, at)
 	}
-	_, err = a.db.Exec("UPDATE im_user_login_logs SET logout_at=? WHERE tenant_id=? AND session_id=? AND logout_at IS NULL", at, int64(id), sessionID)
+	return retryMySQLDeadlock(func() error {
+		_, execErr := a.db.Exec("UPDATE im_user_login_logs SET logout_at=? WHERE tenant_id=? AND session_id=? AND logout_at IS NULL", at, int64(id), sessionID)
+		return execErr
+	}, time.Sleep)
+}
+
+func retryMySQLDeadlock(operation func() error, sleep func(time.Duration)) error {
+	err := operation()
+	for attempt := 1; isRetryableMySQLError(err) && attempt < 4; attempt++ {
+		sleep(time.Duration(attempt) * 25 * time.Millisecond)
+		err = operation()
+	}
 	return err
 }
 

server/db/mysql/tenant_security_audit_test.go

@@ -3,9 +3,13 @@
 package mysql
 
 import (
+	"errors"
 	"os"
 	"strings"
 	"testing"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
 )
 
 func TestLoginAuditQueriesAreTenantScoped(t *testing.T) {
@@ -24,3 +28,48 @@ func TestLoginAuditQueriesAreTenantScoped(t *testing.T) {
 		}
 	}
 }
+
+func TestRetryMySQLDeadlockEventuallySucceeds(t *testing.T) {
+	calls := 0
+	var delays []time.Duration
+	err := retryMySQLDeadlock(func() error {
+		calls++
+		if calls < 3 {
+			return &mysqldriver.MySQLError{Number: 1213, SQLState: [5]byte{'4', '0', '0', '0', '1'}}
+		}
+		return nil
+	}, func(delay time.Duration) { delays = append(delays, delay) })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 3 {
+		t.Fatalf("operation calls=%d want=3", calls)
+	}
+	want := []time.Duration{25 * time.Millisecond, 50 * time.Millisecond}
+	if len(delays) != len(want) || delays[0] != want[0] || delays[1] != want[1] {
+		t.Fatalf("retry delays=%v want=%v", delays, want)
+	}
+}
+
+func TestRetryMySQLDeadlockStopsOnNonRetryableError(t *testing.T) {
+	want := errors.New("invalid update")
+	calls := 0
+	err := retryMySQLDeadlock(func() error {
+		calls++
+		return want
+	}, func(time.Duration) { t.Fatal("non-retryable error must not sleep") })
+	if !errors.Is(err, want) || calls != 1 {
+		t.Fatalf("err=%v calls=%d want=%v/1", err, calls, want)
+	}
+}
+
+func TestRetryMySQLDeadlockStopsAfterFourAttempts(t *testing.T) {
+	calls := 0
+	err := retryMySQLDeadlock(func() error {
+		calls++
+		return &mysqldriver.MySQLError{Number: 1205}
+	}, func(time.Duration) {})
+	if err == nil || calls != 4 {
+		t.Fatalf("err=%v calls=%d want non-nil/4", err, calls)
+	}
+}

server/default_avatar.go

@@ -36,6 +36,12 @@ func applyAvatarURL(data map[string]any) {
 	avatar := strings.TrimSpace(stringFromAny(data["avatar_file_id"]))
 	if isAvatarURLValue(avatar) {
 		data["avatar_url"] = avatar
+		return
+	}
+	// 裸文件 ID：统一补一个可直接下载的 avatar_url。
+	// 下载走 /v0/file/s/{file_id}，自定义头像的 ACL 对登录用户放行（见 adapter.FileUserHasAccess）。
+	if avatar != "" && !types.ParseUid(avatar).IsZero() {
+		data["avatar_url"] = "/v0/file/s/" + avatar
 	}
 }
 

server/docker_config_template_test.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestDockerConfigUsesKafkaBrokersFromEnvironment(t *testing.T) {
+	content, err := os.ReadFile("../docker/tinode/config.template")
+	if err != nil {
+		t.Fatalf("read Docker config template: %v", err)
+	}
+
+	template := string(content)
+	if !strings.Contains(template, `"brokers": $KAFKA_BROKERS_JSON`) {
+		t.Fatal("Docker config template must render Kafka brokers from KAFKA_BROKERS_JSON")
+	}
+	if strings.Contains(template, "kafka.118im.com:30835") {
+		t.Fatal("Docker config template must not hard-code the public Kafka NodePort")
+	}
+}

server/hdl_files.go

@@ -203,7 +203,7 @@ func largeFileReceiveHTTP(wrt http.ResponseWriter, req *http.Request) {
 
 	// Preflight request: process before any security checks.
 	if req.Method == http.MethodOptions {
-		headers, statusCode, err := mh.Headers(types.ZeroTenantID, req.Method, req.URL, req.Header, true)
+		headers, statusCode, err := mh.Headers(types.ZeroTenantID, req.Method, req.URL, req.Header, false)
 		if err != nil {
 			writeHttpResponse(decodeStoreError(err, "", now, nil), err)
 			return
@@ -239,6 +239,9 @@ func largeFileReceiveHTTP(wrt http.ResponseWriter, req *http.Request) {
 	}
 
 	msgID := req.FormValue("id")
+	// When the uploader passes a conversation topic, the file is linked to it so other
+	// members of that conversation can download it (see TenantFileUserHasAccess).
+	uploadTopic := strings.TrimSpace(req.FormValue("topic"))
 	// Check authorization: either auth information or SID must be present
 	authMethod, secret := getHttpAuth(req)
 	principal, challenge, err := authFileRequest(authMethod, secret, req.FormValue("sid"), getRemoteAddr(req))
@@ -250,11 +253,17 @@ func largeFileReceiveHTTP(wrt http.ResponseWriter, req *http.Request) {
 		writeHttpResponse(InfoChallenge(msgID, now, challenge), nil)
 		return
 	}
-	if principal.UID.IsZero() && req.FormValue("topic") != "newacc" {
+	if principal.UID.IsZero() && uploadTopic != "newacc" {
 		// Not authenticated and not signup.
 		writeHttpResponse(ErrAuthRequired(msgID, "", now, now), nil)
 		return
 	}
+	if !principal.UID.IsZero() && uploadTopic != "" {
+		if err = authorizeUploadTopicLink(principal.TenantID, principal.UID, uploadTopic); err != nil {
+			writeHttpResponse(decodeStoreError(err, msgID, now, nil), err)
+			return
+		}
+	}
 	// Check if uploads are handled elsewhere.
 	headers, statusCode, err := mh.Headers(principal.TenantID, req.Method, req.URL, req.Header, true)
 	if err != nil {
@@ -361,6 +370,13 @@ func largeFileReceiveHTTP(wrt http.ResponseWriter, req *http.Request) {
 		logs.Warn.Printf("media upload: failed to enqueue file lifecycle event file=%s: %v", fdef.Id, err)
 	}
 
+	if uploadTopic != "" {
+		if err = store.Files.LinkAttachments(principal.TenantID, uploadTopic, types.ZeroUid, []string{fdef.Uid().String()}); err != nil {
+			// The file itself is valid; linking is best-effort so do not fail the upload.
+			logs.Warn.Printf("media upload: failed to link file %s to topic %s: %v", fdef.Id, uploadTopic, err)
+		}
+	}
+
 	params := map[string]any{"url": url, "file_id": fdef.Uid().String()}
 	if globals.mediaGcPeriod > 0 {
 		// How long this file is guaranteed to exist without being attached to a message or a topic.
@@ -484,6 +500,40 @@ func authorizeLargeFileRequestURL(tenantID types.TenantID, uid types.Uid, rawURL
 	return authorizeLargeFileDownload(tenantID, uid, rawURL, fd)
 }
 
+// authorizeUploadTopicLink verifies the uploader is a reading member of the conversation
+// topic, so the uploaded file may be linked to it and downloaded by other members.
+func authorizeUploadTopicLink(tenantID types.TenantID, uid types.Uid, topic string) error {
+	switch types.GetTopicCat(topic) {
+	case types.TopicCatP2P, types.TopicCatGrp:
+	default:
+		return types.ErrPermissionDenied
+	}
+	if store.Store == nil || !store.Store.IsOpen() {
+		return types.ErrUnsupported
+	}
+	sub, err := store.Subs.Get(tenantID, topic, uid, false)
+	if err != nil || sub == nil || sub.DeletedAt != nil {
+		return types.ErrPermissionDenied
+	}
+	if !sub.ModeWant.IsReader() || !sub.ModeGiven.IsReader() {
+		return types.ErrPermissionDenied
+	}
+	if types.GetTopicCat(topic) == types.TopicCatGrp {
+		settings, err := store.GroupBusiness.GetSettings(tenantID, topic)
+		if err != nil {
+			return err
+		}
+		if settings != nil && !canUploadGroupFile(settings, sub.ModeGiven) {
+			return types.ErrPermissionDenied
+		}
+	}
+	return nil
+}
+
+func canUploadGroupFile(settings *types.GroupSettings, mode types.AccessMode) bool {
+	return settings == nil || settings.MemberUploadFiles || mode.IsAdmin()
+}
+
 func authorizeLargeFileDownload(tenantID types.TenantID, uid types.Uid, rawURL string, fd *types.FileDef) error {
 	if fd == nil {
 		return types.ErrNotFound

server/hdl_files_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"strings"
 	"testing"
 	"time"
 
@@ -23,11 +24,16 @@ type testLargeFileMediaHandler struct {
 	data          string
 	fid           types.Uid
 	headersCalled bool
+	corsOrigins   []media.AllowedOrigin
 }
 
 func (h *testLargeFileMediaHandler) Init(string) error { return nil }
-func (h *testLargeFileMediaHandler) Headers(types.TenantID, string, *url.URL, http.Header, bool) (http.Header, int, error) {
+func (h *testLargeFileMediaHandler) Headers(_ types.TenantID, method string, _ *url.URL, headers http.Header, serve bool) (http.Header, int, error) {
 	h.headersCalled = true
+	if h.corsOrigins != nil {
+		response, status := media.CORSHandler(method, headers, h.corsOrigins, serve)
+		return response, status, nil
+	}
 	return nil, 0, nil
 }
 func (h *testLargeFileMediaHandler) Upload(def *types.FileDef, file io.Reader) (string, int64, error) {
@@ -46,6 +52,59 @@ func (h *testLargeFileMediaHandler) GetIdFromUrl(string) types.Uid {
 	return h.fid
 }
 
+func TestCanUploadGroupFileHonorsGovernance(t *testing.T) {
+	settings := &types.GroupSettings{MemberUploadFiles: false}
+	if canUploadGroupFile(settings, types.ModeRead|types.ModeWrite) {
+		t.Fatal("ordinary member must not upload when group files are admin-only")
+	}
+	if !canUploadGroupFile(settings, types.ModeRead|types.ModeApprove) {
+		t.Fatal("group admin must be allowed to upload when group files are admin-only")
+	}
+	settings.MemberUploadFiles = true
+	if !canUploadGroupFile(settings, types.ModeRead|types.ModeWrite) {
+		t.Fatal("ordinary member must be allowed when group files are open to all")
+	}
+	if !canUploadGroupFile(nil, types.ModeRead|types.ModeWrite) {
+		t.Fatal("groups without business settings must retain the default allow behavior")
+	}
+}
+
+func TestLargeFileUploadPreflightAllowsPost(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+	oldStore := store.Store
+	defer func() { store.Store = oldStore }()
+
+	origins, err := media.ParseCORSAllow([]string{"https://web1.118im.com"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	handler := &testLargeFileMediaHandler{corsOrigins: origins}
+	mockStore := mock_store.NewMockPersistentStorageInterface(ctrl)
+	mockStore.EXPECT().GetMediaHandler().Return(handler)
+	store.Store = mockStore
+
+	req := httptest.NewRequest(http.MethodOptions, "/v0/file/u/", nil)
+	req.Header.Set("Origin", "https://web1.118im.com")
+	req.Header.Set("Access-Control-Request-Method", http.MethodPost)
+	req.Header.Set("Access-Control-Request-Headers", "authorization,x-meetingim-apikey")
+	wrt := httptest.NewRecorder()
+	largeFileReceiveHTTP(wrt, req)
+
+	if wrt.Code != http.StatusNoContent || !handler.headersCalled {
+		t.Fatalf("preflight response: status=%d headers_called=%t", wrt.Code, handler.headersCalled)
+	}
+	if got := wrt.Header().Get("Access-Control-Allow-Origin"); got != "https://web1.118im.com" {
+		t.Fatalf("allowed origin = %q", got)
+	}
+	if got := wrt.Header().Get("Access-Control-Allow-Methods"); !strings.Contains(got, http.MethodPost) {
+		t.Fatalf("POST missing from allowed methods: %q", got)
+	}
+	if got := wrt.Header().Get("Access-Control-Allow-Headers"); got != "authorization,x-meetingim-apikey" {
+		t.Fatalf("requested headers not allowed explicitly: %q", got)
+	}
+}
+
 func TestAuthFileRequestFromSessionRequiresTenant(t *testing.T) {
 	oldSessionStore := globals.sessionStore
 	globals.sessionStore = NewSessionStore(time.Minute)

server/hdl_websock.go

@@ -11,26 +11,52 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
+	"io"
+	"net"
 	"net/http"
 	"sync/atomic"
+	"syscall"
 	"time"
 
 	"github.com/gorilla/websocket"
 	"github.com/tinode/chat/server/logs"
+	immetrics "github.com/tinode/chat/server/metrics"
 	"github.com/tinode/chat/server/store/types"
 )
 
 const (
 	// Time allowed to write a message to the peer.
 	writeWait = 10 * time.Second
-
-	// Time allowed to read the next pong message from the peer.
-	pongWait = idleSessionTimeout
-
-	// Send pings to peer with this period. Must be less than pongWait.
-	pingPeriod = 15 * time.Second
+	// Heartbeat defaults tolerate transient mobile and public-network stalls while
+	// still detecting dead connections in a bounded amount of time.
+	defaultWSPongWait   = 90 * time.Second
+	defaultWSPingPeriod = 15 * time.Second
 )
 
+var (
+	pongWait   = defaultWSPongWait
+	pingPeriod = defaultWSPingPeriod
+)
+
+func configureWSHeartbeat(pingSeconds, pongSeconds int) error {
+	ping := defaultWSPingPeriod
+	pong := defaultWSPongWait
+	if pingSeconds > 0 {
+		ping = time.Duration(pingSeconds) * time.Second
+	}
+	if pongSeconds > 0 {
+		pong = time.Duration(pongSeconds) * time.Second
+	}
+	if ping >= pong {
+		return errors.New("websocket ping period must be shorter than pong wait")
+	}
+	pingPeriod = ping
+	pongWait = pong
+	immetrics.SetWSHeartbeatConfig(ping, pong)
+	return nil
+}
+
 func (sess *Session) closeWS() {
 	if sess.proto == WEBSOCK {
 		sess.ws.Close()
@@ -44,41 +70,57 @@ func (sess *Session) readLoop() {
 	}()
 
 	sess.ws.SetReadLimit(globals.maxMessageSize)
-	sess.ws.SetReadDeadline(time.Now().Add(pongWait))
-	sess.ws.SetPongHandler(func(string) error {
+	refreshReadDeadline := func(event, presenceSource string) {
 		atomic.StoreInt64(&sess.lastAction, types.TimeNow().UnixNano())
-		sess.refreshPresence("ws.pong")
-		sess.ws.SetReadDeadline(time.Now().Add(pongWait))
+		immetrics.IncWSHeartbeat(event)
+		if presenceSource != "" {
+			sess.refreshPresence(presenceSource)
+		}
+		_ = sess.ws.SetReadDeadline(time.Now().Add(pongWait))
+	}
+	_ = sess.ws.SetReadDeadline(time.Now().Add(pongWait))
+	sess.ws.SetPongHandler(func(string) error {
+		refreshReadDeadline("pong_received", "ws.pong")
 		return nil
 	})
+	sess.ws.SetPingHandler(func(appData string) error {
+		refreshReadDeadline("ping_received", "")
+		return sess.ws.WriteControl(websocket.PongMessage, []byte(appData), time.Now().Add(writeWait))
+	})
 
 	for {
 		// Read a ClientComMessage
 		_, raw, err := sess.ws.ReadMessage()
 		if err != nil {
-			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure,
-				websocket.CloseNormalClosure) {
-				logs.Err.Println("ws: readLoop", sess.sid, err)
+			reason := classifyWSError(err)
+			immetrics.IncWSDisconnect(reason)
+			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+				logs.Err.Printf("ws: readLoop sid=%s uid=%s reason=%s err=%v", sess.sid, sess.uid.UserId(), reason, err)
 			}
 			return
 		}
+		// Any successfully read client frame proves that the connection is alive.
+		// This prevents a busy client from timing out merely because its Pong was
+		// delayed behind application traffic.
+		atomic.StoreInt64(&sess.lastAction, types.TimeNow().UnixNano())
+		_ = sess.ws.SetReadDeadline(time.Now().Add(pongWait))
 		statsInc("IncomingMessagesWebsockTotal", 1)
+		dispatchStarted := time.Now()
 		sess.dispatchRaw(raw)
+		immetrics.ObserveWSReadDispatch(dispatchStarted)
 	}
 }
 
 func (sess *Session) sendMessage(msg any) bool {
-	if len(sess.send) > sendQueueLimit {
-		logs.Err.Println("ws: outbound queue limit exceeded", sess.sid)
+	if depth := len(sess.send); depth > sendQueueLimit {
+		immetrics.ObserveWSWrite("text", "rejected", "queue_limit", time.Now(), 0)
+		logs.Err.Printf("ws: outbound queue limit exceeded sid=%s uid=%s depth=%d capacity=%d",
+			sess.sid, sess.uid.UserId(), depth, cap(sess.send))
 		return false
 	}
 
 	statsInc("OutgoingMessagesWebsockTotal", 1)
-	if err := wsWrite(sess.ws, websocket.TextMessage, msg); err != nil {
-		if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure,
-			websocket.CloseNormalClosure) {
-			logs.Err.Println("ws: writeLoop", sess.sid, err)
-		}
+	if err := sess.writeWSFrame(websocket.TextMessage, msg); err != nil {
 		return false
 	}
 	return true
@@ -100,6 +142,7 @@ func (sess *Session) writeLoop() {
 				// Channel closed.
 				return
 			}
+			sess.observeOutboundDequeue(false)
 			switch v := msg.(type) {
 			case []*ServerComMessage: // batch of unserialized messages
 				for _, msg := range v {
@@ -107,12 +150,23 @@ func (sess *Session) writeLoop() {
 					if !sess.sendMessage(w) {
 						return
 					}
+					if isAcceptedCtrl(msg) {
+						immetrics.ObserveCtrlACKDelivery("write", msg.Timestamp)
+					}
 				}
 			case *ServerComMessage: // single unserialized message
 				w := sess.serializeAndUpdateStats(v)
 				if !sess.sendMessage(w) {
 					return
 				}
+				if isAcceptedCtrl(v) {
+					immetrics.ObserveCtrlACKDelivery("write", v.Timestamp)
+				}
+			case sharedServerMessage:
+				statsAddHistSample("OutgoingMessageSize", float64(len(v)))
+				if !sess.sendMessage([]byte(v)) {
+					return
+				}
 			default: // serialized message
 				if !sess.sendMessage(v) {
 					return
@@ -128,7 +182,7 @@ func (sess *Session) writeLoop() {
 		case msg := <-sess.stop:
 			// Shutdown requested, don't care if the message is delivered
 			if msg != nil {
-				wsWrite(sess.ws, websocket.TextMessage, msg)
+				sess.writeWSFrame(websocket.TextMessage, msg)
 			}
 			return
 
@@ -136,17 +190,81 @@ func (sess *Session) writeLoop() {
 			sess.delSub(topic)
 
 		case <-ticker.C:
-			if err := wsWrite(sess.ws, websocket.PingMessage, nil); err != nil {
-				if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure,
-					websocket.CloseNormalClosure) {
-					logs.Err.Println("ws: writeLoop ping", sess.sid, err)
-				}
+			if err := sess.writeWSFrame(websocket.PingMessage, nil); err != nil {
 				return
 			}
 		}
 	}
 }
 
+func (sess *Session) writeWSFrame(mt int, msg any) error {
+	frame := "text"
+	if mt == websocket.PingMessage {
+		frame = "ping"
+	}
+	payloadBytes := 0
+	if bits, ok := msg.([]byte); ok {
+		payloadBytes = len(bits)
+	}
+	started := time.Now()
+	err := wsWrite(sess.ws, mt, msg)
+	if err == nil {
+		immetrics.ObserveWSWrite(frame, "ok", "none", started, payloadBytes)
+		return nil
+	}
+	reason := classifyWSError(err)
+	immetrics.ObserveWSWrite(frame, "error", reason, started, payloadBytes)
+	if shouldLogWSWriteError(reason) {
+		logs.Err.Printf("ws: writeLoop sid=%s uid=%s frame=%s queue=%d capacity=%d reason=%s err=%v",
+			sess.sid, sess.uid.UserId(), frame, len(sess.send), cap(sess.send), reason, err)
+	}
+	return err
+}
+
+func shouldLogWSWriteError(reason string) bool {
+	switch reason {
+	case "close_normal", "close_going_away", "closed", "eof", "broken_pipe", "connection_reset":
+		return false
+	default:
+		return true
+	}
+}
+
+func classifyWSError(err error) string {
+	if err == nil {
+		return "none"
+	}
+	var closeErr *websocket.CloseError
+	if errors.As(err, &closeErr) {
+		switch closeErr.Code {
+		case websocket.CloseNormalClosure:
+			return "close_normal"
+		case websocket.CloseGoingAway:
+			return "close_going_away"
+		case websocket.CloseAbnormalClosure:
+			return "close_abnormal"
+		default:
+			return "close_other"
+		}
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) && netErr.Timeout() {
+		return "timeout"
+	}
+	switch {
+	case errors.Is(err, syscall.ECONNRESET):
+		return "connection_reset"
+	case errors.Is(err, syscall.EPIPE):
+		return "broken_pipe"
+	case errors.Is(err, net.ErrClosed):
+		return "closed"
+	case errors.Is(err, io.EOF):
+		return "eof"
+	default:
+		return "other"
+	}
+}
+
 // Writes a message with the given message type (mt) and payload.
 func wsWrite(ws *websocket.Conn, mt int, msg any) error {
 	var bits []byte

server/hdl_websock_config_test.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"testing"
+	"time"
+)
+
+func TestConfigureWSHeartbeat(t *testing.T) {
+	originalPing, originalPong := pingPeriod, pongWait
+	t.Cleanup(func() {
+		pingPeriod, pongWait = originalPing, originalPong
+	})
+
+	if err := configureWSHeartbeat(20, 120); err != nil {
+		t.Fatal(err)
+	}
+	if pingPeriod != 20*time.Second || pongWait != 120*time.Second {
+		t.Fatalf("heartbeat ping=%s pong=%s", pingPeriod, pongWait)
+	}
+	if err := configureWSHeartbeat(90, 90); err == nil {
+		t.Fatal("expected invalid heartbeat configuration to fail")
+	}
+	if err := configureWSHeartbeat(0, 0); err != nil {
+		t.Fatal(err)
+	}
+	if pingPeriod != defaultWSPingPeriod || pongWait != defaultWSPongWait {
+		t.Fatalf("default heartbeat ping=%s pong=%s", pingPeriod, pongWait)
+	}
+}

server/hdl_websock_test.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"syscall"
+	"testing"
+
+	"github.com/gorilla/websocket"
+)
+
+func TestClassifyWSError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want string
+	}{
+		{name: "none", want: "none"},
+		{name: "normal close", err: &websocket.CloseError{Code: websocket.CloseNormalClosure}, want: "close_normal"},
+		{name: "abnormal close", err: &websocket.CloseError{Code: websocket.CloseAbnormalClosure}, want: "close_abnormal"},
+		{name: "timeout", err: &net.OpError{Op: "write", Err: os.ErrDeadlineExceeded}, want: "timeout"},
+		{name: "reset", err: fmt.Errorf("write failed: %w", syscall.ECONNRESET), want: "connection_reset"},
+		{name: "broken pipe", err: fmt.Errorf("write failed: %w", syscall.EPIPE), want: "broken_pipe"},
+		{name: "closed", err: net.ErrClosed, want: "closed"},
+		{name: "eof", err: io.EOF, want: "eof"},
+		{name: "other", err: fmt.Errorf("unknown"), want: "other"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := classifyWSError(tc.err); got != tc.want {
+				t.Fatalf("classifyWSError()=%q want=%q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestShouldLogWSWriteError(t *testing.T) {
+	tests := []struct {
+		reason string
+		want   bool
+	}{
+		{reason: "close_normal", want: false},
+		{reason: "close_going_away", want: false},
+		{reason: "closed", want: false},
+		{reason: "eof", want: false},
+		{reason: "broken_pipe", want: false},
+		{reason: "connection_reset", want: false},
+		{reason: "timeout", want: true},
+		{reason: "close_abnormal", want: true},
+		{reason: "other", want: true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.reason, func(t *testing.T) {
+			if got := shouldLogWSWriteError(tc.reason); got != tc.want {
+				t.Fatalf("shouldLogWSWriteError(%q)=%v want %v", tc.reason, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestWebSocketOutboundQueueTiming(t *testing.T) {
+	sess := &Session{proto: WEBSOCK, send: make(chan any, 2)}
+	payload := []byte("message")
+	if !sess.queueOutBytes(payload) {
+		t.Fatal("queueOutBytes rejected payload")
+	}
+
+	queued := <-sess.send
+	sess.observeOutboundDequeue(false)
+	if string(queued.([]byte)) != string(payload) {
+		t.Fatalf("payload=%q want=%q", queued, payload)
+	}
+}

server/hub.go

@@ -10,12 +10,15 @@
 package main
 
 import (
+	"os"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/tinode/chat/server/auth"
 	"github.com/tinode/chat/server/logs"
+	immetrics "github.com/tinode/chat/server/metrics"
 	"github.com/tinode/chat/server/store"
 	"github.com/tinode/chat/server/store/types"
 )
@@ -29,6 +32,44 @@ var requestLatencyDistribution = []float64{1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20,
 var outgoingMessageSizeDistribution = []float64{1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 16384,
 	65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296}
 
+const (
+	defaultTopicClientQueue    = 4096
+	defaultTopicServerQueue    = 512
+	defaultTopicPublishWait    = 200 * time.Millisecond
+	topicClientQueueEnv        = "TOPIC_CLIENT_QUEUE_BUFFER"
+	topicServerQueueEnv        = "TOPIC_SERVER_QUEUE_BUFFER"
+	topicPublishEnqueueWaitEnv = "TOPIC_PUBLISH_ENQUEUE_WAIT_MS"
+)
+
+var topicQueueConfig = loadTopicQueueConfig()
+
+type topicQueueRuntimeConfig struct {
+	clientBuffer       int
+	serverBuffer       int
+	publishEnqueueWait time.Duration
+}
+
+func loadTopicQueueConfig() topicQueueRuntimeConfig {
+	return topicQueueRuntimeConfig{
+		clientBuffer:       intEnvOrDefault(topicClientQueueEnv, defaultTopicClientQueue),
+		serverBuffer:       intEnvOrDefault(topicServerQueueEnv, defaultTopicServerQueue),
+		publishEnqueueWait: time.Duration(intEnvOrDefault(topicPublishEnqueueWaitEnv, int(defaultTopicPublishWait/time.Millisecond))) * time.Millisecond,
+	}
+}
+
+func intEnvOrDefault(name string, fallback int) int {
+	raw := strings.TrimSpace(os.Getenv(name))
+	if raw == "" {
+		return fallback
+	}
+	parsed, err := strconv.Atoi(raw)
+	if err != nil || parsed <= 0 {
+		logs.Warn.Printf("invalid %s=%q, using %d", name, raw, fallback)
+		return fallback
+	}
+	return parsed
+}
+
 // Request to hub to remove the topic
 type topicUnreg struct {
 	// Tenant which owns the topic.
@@ -56,6 +97,12 @@ type userStatusReq struct {
 	state types.ObjState
 }
 
+type deferredPresenceKey struct {
+	tenantID types.TenantID
+	topic    string
+	source   string
+}
+
 // Hub is the core structure which holds topics.
 type Hub struct {
 
@@ -73,6 +120,9 @@ type Hub struct {
 
 	// Channel for routing server-generated messages, buffered at 4096
 	routeSrv chan *ServerComMessage
+	// Presence updates which could not immediately enter a topic queue.
+	deferredPresence     chan *ServerComMessage
+	deferredPresenceStop chan struct{}
 
 	// subscribe session to topic, possibly creating a new topic, buffered at 256
 	join chan *ClientComMessage
@@ -120,14 +170,16 @@ func newHub() *Hub {
 	h := &Hub{
 		topics: &sync.Map{},
 		// TODO: verify if these channels have to be buffered.
-		routeCli:   make(chan *ClientComMessage, 4096),
-		routeSrv:   make(chan *ServerComMessage, 4096),
-		join:       make(chan *ClientComMessage, 256),
-		unreg:      make(chan *topicUnreg, 256),
-		rehash:     make(chan bool),
-		meta:       make(chan *ClientComMessage, 128),
-		userStatus: make(chan *userStatusReq, 128),
-		shutdown:   make(chan chan<- bool),
+		routeCli:             make(chan *ClientComMessage, 4096),
+		routeSrv:             make(chan *ServerComMessage, 4096),
+		deferredPresence:     make(chan *ServerComMessage, 8192),
+		deferredPresenceStop: make(chan struct{}),
+		join:                 make(chan *ClientComMessage, 256),
+		unreg:                make(chan *topicUnreg, 256),
+		rehash:               make(chan bool),
+		meta:                 make(chan *ClientComMessage, 128),
+		userStatus:           make(chan *userStatusReq, 128),
+		shutdown:             make(chan chan<- bool),
 	}
 
 	statsRegisterInt("LiveTopics")
@@ -153,11 +205,70 @@ func newHub() *Hub {
 	statsRegisterHistogram("RequestLatency", requestLatencyDistribution)
 	statsRegisterHistogram("OutgoingMessageSize", outgoingMessageSizeDistribution)
 
+	go h.runDeferredPresence()
 	go h.run()
 
 	return h
 }
 
+func (h *Hub) deferPresence(msg *ServerComMessage) bool {
+	select {
+	case h.deferredPresence <- msg:
+		immetrics.ObserveInternalQueueEnqueue("topic_presence_deferred", len(h.deferredPresence), cap(h.deferredPresence), true)
+		return true
+	default:
+		immetrics.ObserveInternalQueueEnqueue("topic_presence_deferred", len(h.deferredPresence), cap(h.deferredPresence), false)
+		return false
+	}
+}
+
+func (h *Hub) runDeferredPresence() {
+	const maxPending = 16384
+	ticker := time.NewTicker(5 * time.Millisecond)
+	defer ticker.Stop()
+	pending := make(map[deferredPresenceKey]*ServerComMessage)
+
+	for {
+		select {
+		case msg := <-h.deferredPresence:
+			if msg == nil || msg.Pres == nil {
+				continue
+			}
+			key := deferredPresenceKey{tenantID: msg.TenantID, topic: msg.RcptTo, source: msg.Pres.Src}
+			if _, exists := pending[key]; exists || len(pending) < maxPending {
+				pending[key] = msg
+			} else {
+				immetrics.ObserveInternalQueueEnqueue("topic_presence_pending", len(pending), maxPending, false)
+				logs.Err.Printf("hub: deferred presence queue full topic=%s tenant=%d source=%s",
+					msg.RcptTo, msg.TenantID, msg.Pres.Src)
+			}
+			immetrics.SetInternalQueueCurrent("topic_presence_pending", len(pending))
+		case <-ticker.C:
+			budget := 64
+			for key, msg := range pending {
+				dst := h.topicGet(types.TopicKey{TenantID: key.tenantID, Topic: key.topic})
+				if dst == nil || dst.serverMsg == nil {
+					delete(pending, key)
+					continue
+				}
+				select {
+				case dst.serverMsg <- msg:
+					immetrics.ObserveInternalQueueEnqueue("topic_server", len(dst.serverMsg), cap(dst.serverMsg), true)
+					delete(pending, key)
+					budget--
+				default:
+				}
+				if budget == 0 {
+					break
+				}
+			}
+			immetrics.SetInternalQueueCurrent("topic_presence_pending", len(pending))
+		case <-h.deferredPresenceStop:
+			return
+		}
+	}
+}
+
 func (h *Hub) run() {
 	for {
 		select {
@@ -190,8 +301,8 @@ func (h *Hub) run() {
 					// Indicates a proxy topic.
 					isProxy:   globals.cluster.isRemoteTopic(key),
 					sessions:  make(map[*Session]perSessionData),
-					clientMsg: make(chan *ClientComMessage, 192),
-					serverMsg: make(chan *ServerComMessage, 64),
+					clientMsg: make(chan *ClientComMessage, topicQueueConfig.clientBuffer),
+					serverMsg: make(chan *ServerComMessage, topicQueueConfig.serverBuffer),
 					reg:       make(chan *ClientComMessage, 256),
 					unreg:     make(chan *ClientComMessage, 256),
 					meta:      make(chan *ClientComMessage, 64),
@@ -245,10 +356,17 @@ func (h *Hub) run() {
 			if dst := h.topicGet(key); dst != nil {
 				// Everything is OK, sending packet to known topic
 				if dst.clientMsg != nil {
+					msg.queuedAt = time.Now()
 					select {
 					case dst.clientMsg <- msg:
+						immetrics.ObserveInternalQueueEnqueue("topic_client", len(dst.clientMsg), cap(dst.clientMsg), true)
 					default:
-						logs.Err.Println("hub: topic's broadcast queue is full", dst.name)
+						immetrics.ObserveInternalQueueEnqueue("topic_client", len(dst.clientMsg), cap(dst.clientMsg), false)
+						if msg.sess != nil {
+							msg.sess.queueOut(ErrServiceUnavailableReply(msg, types.TimeNow()))
+						}
+						logs.Err.Printf("hub: topic's broadcast queue is full topic=%s tenant=%d len=%d cap=%d",
+							dst.name, dst.tenantID, len(dst.clientMsg), cap(dst.clientMsg))
 					}
 				} else {
 					logs.Warn.Println("hub: invalid topic category for broadcast", dst.name)
@@ -275,8 +393,12 @@ func (h *Hub) run() {
 				// Everything is OK, sending packet to known topic
 				select {
 				case dst.serverMsg <- msg:
+					immetrics.ObserveInternalQueueEnqueue("topic_server", len(dst.serverMsg), cap(dst.serverMsg), true)
 				default:
-					logs.Err.Println("hub: topic's broadcast queue is full", dst.name)
+					if msg.Pres == nil || !h.deferPresence(msg) {
+						immetrics.ObserveInternalQueueEnqueue("topic_server", len(dst.serverMsg), cap(dst.serverMsg), false)
+						logs.Err.Println("hub: topic's broadcast queue is full", dst.name)
+					}
 				}
 			} else if (strings.HasPrefix(msg.RcptTo, "usr") || strings.HasPrefix(msg.RcptTo, "grp")) &&
 				globals.cluster.isRemoteTopic(key) {
@@ -348,6 +470,9 @@ func (h *Hub) run() {
 			}
 
 			logs.Info.Printf("Hub shutdown completed with %d topics", topicCount)
+			if h.deferredPresenceStop != nil {
+				close(h.deferredPresenceStop)
+			}
 
 			// let the main goroutine know we are done with the cleanup
 			hubdone <- true

server/hub_tenant_test.go

@@ -102,3 +102,48 @@ func TestHubRejectsUnroutedClientMessageInsteadOfAcceptingWithoutSeq(t *testing.
 		t.Fatal("timeout waiting for unrouted message response")
 	}
 }
+
+func TestHubReturnsServiceUnavailableWhenTopicClientQueueIsFull(t *testing.T) {
+	h := &Hub{
+		topics:     &sync.Map{},
+		routeCli:   make(chan *ClientComMessage, 1),
+		shutdown:   make(chan chan<- bool),
+		routeSrv:   make(chan *ServerComMessage),
+		join:       make(chan *ClientComMessage),
+		meta:       make(chan *ClientComMessage),
+		unreg:      make(chan *topicUnreg),
+		userStatus: make(chan *userStatusReq),
+		rehash:     make(chan bool),
+	}
+	topic := &Topic{
+		tenantID: 7, name: "grpBusy", clientMsg: make(chan *ClientComMessage, 1),
+		exit: make(chan *shutDown, 1),
+	}
+	topic.clientMsg <- &ClientComMessage{Id: "occupy"}
+	h.topicPut(types.TopicKey{TenantID: 7, Topic: topic.name}, topic)
+
+	go h.run()
+	done := make(chan bool)
+	defer func() {
+		h.topicDel(types.TopicKey{TenantID: 7, Topic: topic.name})
+		h.shutdown <- done
+		<-done
+	}()
+
+	sess := &Session{tenantID: 7, send: make(chan any, 1)}
+	now := time.Now().UTC()
+	h.routeCli <- &ClientComMessage{
+		Id: "pub-overload", TenantID: 7, RcptTo: topic.name, Original: topic.name,
+		Timestamp: now, sess: sess,
+	}
+
+	select {
+	case raw := <-sess.send:
+		msg, ok := raw.(*ServerComMessage)
+		if !ok || msg.Ctrl == nil || msg.Ctrl.Code != http.StatusServiceUnavailable {
+			t.Fatalf("unexpected response: %#v", raw)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("timeout waiting for overload response")
+	}
+}

server/im_group_events.go

@@ -162,7 +162,7 @@ func enrichIMGroupMemberEventPayload(eventType string, payload any) any {
 	switch eventType {
 	case "group.member.left":
 		copyPayload["member_sync"] = "remove"
-	case "group.member.joined", "group.member.updated", "group.role.updated", "group.mute.updated":
+	case "group.member.joined", "group.member.updated", "group.member.profile.updated", "group.role.updated", "group.mute.updated":
 		if _, ok := copyPayload["user_id"]; ok {
 			copyPayload["member_sync"] = "single"
 		} else {
@@ -171,7 +171,7 @@ func enrichIMGroupMemberEventPayload(eventType string, payload any) any {
 	}
 	if isAdminOnlyIMGroupEvent(eventType) {
 		copyPayload["visibility"] = "admins_and_affected"
-	} else if eventType == "group.member.joined" {
+	} else if eventType == "group.member.joined" || eventType == "group.member.profile.updated" {
 		copyPayload["visibility"] = "all_members"
 	}
 	return copyPayload

server/im_group_events_test.go

@@ -11,6 +11,17 @@ import (
 	"github.com/tinode/chat/server/store/types"
 )
 
+func TestGroupMemberProfileEventIsVisibleToAllMembers(t *testing.T) {
+	const event = "group.member.profile.updated"
+	if isAdminOnlyIMGroupEvent(event) {
+		t.Fatal("group nickname update must reach ordinary members")
+	}
+	payload := enrichIMGroupMemberEventPayload(event, map[string]any{"user_id": "usrMember"}).(map[string]any)
+	if payload["member_sync"] != "single" || payload["visibility"] != "all_members" {
+		t.Fatalf("unexpected group profile event payload: %#v", payload)
+	}
+}
+
 func TestPublishIMGroupRealtimeEventRestrictsMemberRemoval(t *testing.T) {
 	oldGroupBusiness := store.GroupBusiness
 	oldSessions := globals.sessionStore

server/im_http.go

@@ -1494,8 +1494,12 @@ func serveIMRiskChallengeConfirm(wrt http.ResponseWriter, req *http.Request) {
 	if imReliableHTTPEventsEnabled(req) {
 		eventType := "security.risk." + decision
 		eventID := stableIMEventID("risk", challengeID, decision, challenge.State)
+		summary := "你已取消本次操作"
+		if decision == "continue" {
+			summary = "你已确认继续执行该操作"
+		}
 		if err = createIMSystemNotification(principal.TenantID, principal.Uid,
-			stableIMEventID(eventID, "notification"), eventType, "安全操作确认", decision,
+			stableIMEventID(eventID, "notification"), eventType, "安全操作确认", summary,
 			types.KVMap{"risk_challenge_id": challengeID}); err != nil {
 			writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
 			return
@@ -1704,6 +1708,155 @@ func serveIMFeedback(wrt http.ResponseWriter, req *http.Request) {
 	writeIMSuccess(wrt, req, feedbackSubmissionPayload(feedback))
 }
 
+type imMePasswordChangeRequest struct {
+	OldPassword string `json:"old_password"`
+	NewPassword string `json:"new_password"`
+}
+
+// serveIMMePasswordChange lets an authenticated user change own password by
+// presenting the current one. All sessions are evicted afterwards.
+func serveIMMePasswordChange(wrt http.ResponseWriter, req *http.Request) {
+	if req.Method != http.MethodPost {
+		writeIMError(wrt, req, http.StatusMethodNotAllowed, 30002, imReasonMethodNotAllowed, "method not allowed", nil)
+		return
+	}
+	principal, ok := authenticateIMHTTPBearer(wrt, req)
+	if !ok {
+		return
+	}
+	var body imMePasswordChangeRequest
+	if !decodeIMJSONBody(wrt, req, &body) {
+		return
+	}
+	if strings.TrimSpace(body.OldPassword) == "" || strings.TrimSpace(body.NewPassword) == "" {
+		writeIMError(wrt, req, http.StatusBadRequest, 30000, imReasonMalformedRequest, "malformed request", nil)
+		return
+	}
+	basicAuth := store.Store.GetLogicalAuthHandler("basic")
+	if basicAuth == nil || !basicAuth.IsInitialized() {
+		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+		return
+	}
+	login, authLevel, _, _, err := store.Users.GetAuthRecord(principal.TenantID, principal.Uid)
+	if err != nil || login == "" {
+		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+		return
+	}
+	authCtx := auth.AuthContext{TenantID: principal.TenantID, RemoteAddr: req.RemoteAddr}
+	if _, _, err = basicAuth.Authenticate(authCtx, []byte(login+":"+body.OldPassword)); err != nil {
+		writeIMError(wrt, req, http.StatusUnauthorized, 30001, imReasonAuthRequired, "invalid credentials", nil)
+		return
+	}
+	if _, err = basicAuth.UpdateRecord(authCtx, &auth.Rec{
+		TenantID:  principal.TenantID,
+		Uid:       principal.Uid,
+		AuthLevel: authLevel,
+	}, []byte(":"+body.NewPassword)); err != nil {
+		if err == types.ErrPolicy {
+			writeIMError(wrt, req, http.StatusBadRequest, 30040, imReasonPasswordPolicy, "password policy violation", nil)
+			return
+		}
+		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+		return
+	}
+	now := time.Now().UTC().Round(time.Millisecond)
+	if store.Security != nil {
+		if _, err = store.Security.BumpAuthVersion(principal.TenantID, principal.Uid, now); err != nil {
+			logs.Warn.Println("im me password change: bump auth version failed", err)
+			writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+			return
+		}
+	}
+	if globals.sessionStore != nil {
+		globals.sessionStore.EvictUser(principal.Uid, "")
+	}
+	publishRealtimeEvictUser(principal.TenantID, principal.Uid, "password_changed", "")
+	writeIMSuccess(wrt, req, map[string]any{"status": "ok"})
+}
+
+// serveIMMeDeletion deletes the authenticated user's account. Requires a
+// confirmed "delete_account" sensitive-action token obtained through
+// POST /v1/im/security/challenges + POST /v1/im/security/challenges/{id}.
+func serveIMMeDeletion(wrt http.ResponseWriter, req *http.Request) {
+	if req.Method != http.MethodPost {
+		writeIMError(wrt, req, http.StatusMethodNotAllowed, 30002, imReasonMethodNotAllowed, "method not allowed", nil)
+		return
+	}
+	principal, ok := authenticateIMHTTPBearer(wrt, req)
+	if !ok {
+		return
+	}
+	if globals.permanentAccounts {
+		writeIMError(wrt, req, http.StatusForbidden, 30040, imReasonForbidden, "account deletion is disabled", nil)
+		return
+	}
+	if !consumeIMActionTokenHeader(wrt, req, principal, "delete_account") {
+		return
+	}
+	tenantID, uid := principal.TenantID, principal.Uid
+	if state, err := userGetState(tenantID, uid); err != nil || state == types.StateDeleted {
+		logs.Warn.Println("im me deletion: user is missing or already deleted", err)
+		writeIMError(wrt, req, http.StatusNotFound, 20004, imReasonResourceNotFound, "user not found", nil)
+		return
+	}
+
+	// Disable all authenticators.
+	for _, name := range store.Store.GetAuthNames() {
+		hdl := store.Store.GetLogicalAuthHandler(name)
+		if !hdl.IsInitialized() {
+			continue
+		}
+		if err := hdl.DelRecords(tenantID, uid); err != nil {
+			// This could be completely benign, i.e. authenticator exists but not used.
+			logs.Warn.Println("im me deletion: failed to delete auth record", uid.UserId(), name, err)
+			if storeErr, ok := err.(types.StoreError); ok && storeErr == types.ErrUnsupported {
+				writeIMError(wrt, req, http.StatusForbidden, 30040, imReasonForbidden, "account cannot be deleted", nil)
+				return
+			}
+		}
+	}
+
+	// Terminate all sessions.
+	if globals.sessionStore != nil {
+		globals.sessionStore.EvictUser(uid, "", "user_deleted")
+	}
+	publishRealtimeEvictUser(tenantID, uid, "user_deleted", "")
+	// Remove user from cache and announce to cluster that the user is deleted.
+	usersRemoveUser(tenantID, uid)
+
+	// Stop topics where the user is the owner and p2p topics.
+	done := make(chan bool)
+	globals.hub.unreg <- &topicUnreg{tenantID: tenantID, forUser: uid, del: false, done: done}
+	<-done
+
+	// Notify users of interest that the user is gone.
+	if uoi, err := store.Users.GetSubs(tenantID, uid); err == nil {
+		presUsersOfInterestOffline(tenantID, uid, uoi, "gone")
+	} else {
+		logs.Warn.Println("im me deletion: failed to send notifications to users", err)
+	}
+	// Notify subscribers of the group topics where the user was the owner.
+	if ownTopics, err := store.Users.GetOwnTopics(tenantID, uid); err == nil {
+		for _, topicName := range ownTopics {
+			if subs, err := store.Topics.GetSubs(tenantID, topicName, nil); err == nil {
+				presSubsOfflineOffline(tenantID, topicName, types.TopicCatGrp, subs, "gone", &presParams{}, "")
+			} else {
+				logs.Warn.Println("im me deletion: failed to notify topic subscribers", err, topicName)
+			}
+		}
+	} else {
+		logs.Warn.Println("im me deletion: failed to send notifications to owned topics", err)
+	}
+
+	// Delete user's records from the database (soft delete).
+	if err := store.Users.Delete(tenantID, uid, false); err != nil {
+		logs.Warn.Println("im me deletion: failed to delete user", err)
+		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+		return
+	}
+	writeIMSuccess(wrt, req, map[string]any{"status": "ok"})
+}
+
 func serveIMSecurityChallenges(wrt http.ResponseWriter, req *http.Request) {
 	if req.Method != http.MethodPost {
 		writeIMError(wrt, req, http.StatusMethodNotAllowed, 30002, imReasonMethodNotAllowed, "method not allowed", nil)
@@ -2134,10 +2287,18 @@ func serveIMAppReleaseLatest(wrt http.ResponseWriter, req *http.Request) {
 	}
 	platform := strings.ToLower(strings.TrimSpace(req.URL.Query().Get("platform")))
 	channel := strings.ToLower(strings.TrimSpace(req.URL.Query().Get("channel")))
+	appCode := strings.ToLower(strings.TrimSpace(req.URL.Query().Get("app_code")))
 	currentVersion := strings.TrimSpace(req.URL.Query().Get("current_version"))
 	if channel == "" {
 		channel = "stable"
 	}
+	if appCode == "" {
+		appCode = "im"
+	}
+	if !isValidAppCode(appCode) {
+		writeIMError(wrt, req, http.StatusBadRequest, 30000, imReasonMalformedRequest, "malformed request", map[string]any{"field": "app_code"})
+		return
+	}
 	if platform != "ios" && platform != "android" && platform != "web" {
 		writeIMError(wrt, req, http.StatusBadRequest, 30000, imReasonMalformedRequest, "malformed request", map[string]any{"field": "platform"})
 		return
@@ -2147,7 +2308,7 @@ func serveIMAppReleaseLatest(wrt http.ResponseWriter, req *http.Request) {
 		writeIMError(wrt, req, http.StatusBadRequest, 30000, imReasonMalformedRequest, "malformed request", map[string]any{"field": "current_version"})
 		return
 	}
-	release, err := store.AppReleases.Latest(platform, channel)
+	release, err := store.AppReleases.Latest(appCode, platform, channel)
 	if err != nil {
 		if platform == "web" {
 			logs.Warn.Println("im app release latest: using web fallback", err)
@@ -2488,6 +2649,10 @@ func serveIMSystemNotificationRead(wrt http.ResponseWriter, req *http.Request) {
 			return
 		}
 		readAt = parsed.UTC().Round(time.Millisecond)
+		if readAt.After(time.Now().UTC().Round(time.Millisecond)) {
+			writeIMError(wrt, req, http.StatusBadRequest, 30000, imReasonMalformedRequest, "malformed request", map[string]any{"field": "read_at", "reason": "future_read_at"})
+			return
+		}
 	}
 	notification, err := store.Security.MarkSystemNotificationRead(principal.TenantID, principal.Uid, eventID, readAt)
 	if err != nil {
@@ -3133,6 +3298,25 @@ func serveIMTopicCalls(wrt http.ResponseWriter, req *http.Request) {
 	writeIMSuccess(wrt, req, map[string]any{"topic": topic, "items": callRecordPayloads(items, principal.Uid), "next_cursor": nextCursor})
 }
 
+// serveIMCallsByTopic serves GET /v1/im/calls/{topic} — 对接文档契约路径，按会话查通话记录。
+func serveIMCallsByTopic(wrt http.ResponseWriter, req *http.Request) {
+	if req.Method != http.MethodGet {
+		writeIMError(wrt, req, http.StatusMethodNotAllowed, 30002, imReasonMethodNotAllowed, "method not allowed", nil)
+		return
+	}
+	principal, topic, ok := authenticateTopicReader(wrt, req, topicFromCallsByTopicPath(req.URL.Path))
+	if !ok {
+		return
+	}
+	limit := parseIMLimit(req.URL.Query().Get("limit"), 50, 100)
+	items, nextCursor, err := store.Calls.List(principal.TenantID, principal.Uid, topic, strings.TrimSpace(req.URL.Query().Get("cursor")), limit)
+	if err != nil {
+		writeIMRelationError(wrt, req, err)
+		return
+	}
+	writeIMSuccess(wrt, req, map[string]any{"topic": topic, "items": callRecordPayloads(items, principal.Uid), "next_cursor": nextCursor})
+}
+
 func serveIMMessageSearch(wrt http.ResponseWriter, req *http.Request) {
 	if req.Method != http.MethodGet {
 		writeIMError(wrt, req, http.StatusMethodNotAllowed, 30002, imReasonMethodNotAllowed, "method not allowed", nil)
@@ -3854,15 +4038,6 @@ func serveIMFriendRequestCreate(wrt http.ResponseWriter, req *http.Request) {
 			writeIMError(wrt, req, http.StatusForbidden, 30005, imReasonPermissionDenied, "group membership required", nil)
 			return
 		}
-		settings, settingsErr := store.GroupBusiness.GetSettings(principal.TenantID, sourceTopic)
-		if settingsErr != nil {
-			writeIMRelationError(wrt, req, settingsErr)
-			return
-		}
-		if settings == nil || !settings.MemberPrivateChat {
-			writeIMError(wrt, req, http.StatusForbidden, 30005, imReasonPermissionDenied, "member private chat is disabled", nil)
-			return
-		}
 	default:
 		writeIMError(wrt, req, http.StatusBadRequest, 30000, imReasonMalformedRequest, "invalid friend request source", nil)
 		return
@@ -3911,6 +4086,12 @@ func serveIMFriendRequestCreate(wrt http.ResponseWriter, req *http.Request) {
 			writeIMRelationError(wrt, req, acceptErr)
 			return
 		}
+		if accepted == nil {
+			logs.Err.Printf("friend request auto-accept returned an empty result: tenant=%d request=%s actor=%s",
+				principal.TenantID, created.RequestID, target.String())
+			writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+			return
+		}
 		created = accepted
 	}
 	if imReliableHTTPEventsEnabled(req) {
@@ -4036,6 +4217,25 @@ func serveIMGroupList(wrt http.ResponseWriter, req *http.Request) {
 		items = append(items, item)
 		seen++
 	}
+	if len(items) > 0 {
+		listTopics := make([]string, 0, len(items))
+		for _, item := range items {
+			if topic, ok := item["topic"].(string); ok && topic != "" {
+				listTopics = append(listTopics, topic)
+			}
+		}
+		if counts, err := store.GroupBusiness.MembersCount(principal.TenantID, listTopics); err == nil {
+			for _, item := range items {
+				if topic, ok := item["topic"].(string); ok {
+					if count, ok := counts[topic]; ok {
+						item["member_count"] = count
+					}
+				}
+			}
+		} else {
+			logs.Warn.Printf("serveIMGroupList: failed to count members for %d topics: %v", len(listTopics), err)
+		}
+	}
 	writeIMSuccess(wrt, req, map[string]any{"items": items, "next_cursor": nextCursor, "has_more": nextCursor != ""})
 }
 
@@ -4129,7 +4329,7 @@ func serveIMGroupCreate(wrt http.ResponseWriter, req *http.Request) {
 		writeIMRelationError(wrt, req, err)
 		return
 	}
-	writeIMSuccess(wrt, req, groupDetailPayload(created, selfSub))
+	writeIMSuccess(wrt, req, groupDetailPayload(created, selfSub, groupMemberCountFor(principal.TenantID, topicName)))
 }
 
 func serveIMGroupResource(wrt http.ResponseWriter, req *http.Request) {
@@ -4408,6 +4608,10 @@ func serveIMGroupDetail(wrt http.ResponseWriter, req *http.Request, topic string
 		return
 	}
 	if selfSub == nil || !(selfSub.ModeGiven & selfSub.ModeWant).IsJoiner() || !(selfSub.ModeGiven & selfSub.ModeWant).IsReader() {
+		// 群不存在（404）或已解散（410）要与"存在但无权限"（403）区分开。
+		if selfSub == nil && writeIMGroupMissingIfGone(wrt, req, principal.TenantID, topic) {
+			return
+		}
 		writeIMError(wrt, req, http.StatusForbidden, 30005, imReasonPermissionDenied, "topic permission required", nil)
 		return
 	}
@@ -4422,7 +4626,7 @@ func serveIMGroupDetail(wrt http.ResponseWriter, req *http.Request, topic string
 			writeIMError(wrt, req, http.StatusNotFound, 30004, imReasonMalformedRequest, "group not found", nil)
 			return
 		}
-		payload := groupDetailPayload(group, selfSub)
+		payload := groupDetailPayload(group, selfSub, groupMemberCountFor(principal.TenantID, topic))
 		if settings, err := store.GroupBusiness.GetSettings(principal.TenantID, topic); err == nil {
 			if settings != nil && settings.GroupStatus == types.GroupStatusDissolved {
 				writeIMError(wrt, req, http.StatusGone, 30004, imReasonGroupDissolved, "group dissolved", map[string]any{"topic": topic})
@@ -4518,7 +4722,7 @@ func serveIMGroupDetail(wrt http.ResponseWriter, req *http.Request, topic string
 			writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
 			return
 		}
-		payload := groupDetailPayload(updated, selfSub)
+		payload := groupDetailPayload(updated, selfSub, groupMemberCountFor(principal.TenantID, topic))
 		if settingsUpdated {
 			if settings, err := store.GroupBusiness.GetSettings(principal.TenantID, topic); err == nil {
 				payload = mergeGroupSettingsPayload(payload, settings)
@@ -4584,7 +4788,7 @@ func serveIMGroupSettings(wrt http.ResponseWriter, req *http.Request, topic stri
 		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
 		return
 	}
-	payload := groupSettingsPayload(group, selfSub)
+	payload := groupSettingsPayload(group, selfSub, groupMemberCountFor(principal.TenantID, topic))
 	if settings, err := store.GroupBusiness.GetSettings(principal.TenantID, topic); err == nil {
 		payload = mergeGroupSettingsPayload(payload, settings)
 		payload["governance"] = groupGovernancePayloadFromSettings(settings, selfSub)
@@ -4688,7 +4892,7 @@ func serveIMGroupMyProfile(wrt http.ResponseWriter, req *http.Request, topic str
 	if _, err := store.GroupBusiness.UpdateMember(principal.TenantID, topic, principal.Uid, types.GroupMemberPatch{Nickname: &nickname}); err != nil {
 		if errors.Is(err, types.ErrNotFound) {
 			logs.Warn.Printf("group[%s]: member profile saved to subscription only; business member row missing for user %s", topic, principal.Uid.UserId())
-			publishIMGroupRealtimeEvent(principal.TenantID, topic, principal.Uid, "group.member.updated",
+			publishIMGroupRealtimeEvent(principal.TenantID, topic, principal.Uid, "group.member.profile.updated",
 				map[string]any{"user_id": principal.Uid.UserId()})
 			writeIMSuccess(wrt, req, map[string]any{"nickname": nickname, "version": currentVersion + 1, "updated_at": updatedAt.Format(time.RFC3339Nano)})
 			return
@@ -4699,7 +4903,7 @@ func serveIMGroupMyProfile(wrt http.ResponseWriter, req *http.Request, topic str
 		writeIMRelationError(wrt, req, err)
 		return
 	}
-	publishIMGroupRealtimeEvent(principal.TenantID, topic, principal.Uid, "group.member.updated",
+	publishIMGroupRealtimeEvent(principal.TenantID, topic, principal.Uid, "group.member.profile.updated",
 		map[string]any{"user_id": principal.Uid.UserId()})
 	writeIMSuccess(wrt, req, map[string]any{"nickname": nickname, "version": currentVersion + 1, "updated_at": updatedAt.Format(time.RFC3339Nano)})
 }
@@ -4761,7 +4965,7 @@ func serveIMGroupQRCodes(wrt http.ResponseWriter, req *http.Request, topic strin
 		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
 		return
 	}
-	groupPayload := groupDetailPayload(group, selfSub)
+	groupPayload := groupDetailPayload(group, selfSub, groupMemberCountFor(principal.TenantID, topic))
 	writeIMSuccess(wrt, req, map[string]any{
 		"qr_token":       token,
 		"qr_payload":     "im://qr?token=" + url.QueryEscape(token) + "&purpose=join_group",
@@ -5794,10 +5998,16 @@ func serveIMGroupMemberProfile(wrt http.ResponseWriter, req *http.Request, topic
 		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
 		return
 	}
-	ctx, err := store.Relations.GetRelationshipContext(principal.TenantID, principal.Uid, memberID, principal.Uid.P2PName(memberID))
-	if err != nil {
-		writeIMRelationError(wrt, req, err)
-		return
+	// 查询本人时 GetRelationshipContext 不接受 userID==peerID（会报 ErrMalformed），
+	// 直接构造 self 上下文，群内本人资料返回 200。
+	ctx := &types.RelationshipContext{Relationship: types.RelationshipSelf, CanSend: true}
+	if memberID != principal.Uid {
+		var err error
+		ctx, err = store.Relations.GetRelationshipContext(principal.TenantID, principal.Uid, memberID, principal.Uid.P2PName(memberID))
+		if err != nil {
+			writeIMRelationError(wrt, req, err)
+			return
+		}
 	}
 	writeIMSuccess(wrt, req, groupMemberProfilePayload(topic, memberSub, user, ctx))
 }
@@ -5897,7 +6107,7 @@ func serveIMQRCodesResolve(wrt http.ResponseWriter, req *http.Request) {
 		if selfSub != nil && (selfSub.ModeGiven & selfSub.ModeWant).IsJoiner() {
 			status = "joined"
 		}
-		groupPayload := groupDetailPayload(group, selfSub)
+		groupPayload := groupDetailPayload(group, selfSub, groupMemberCountFor(principal.TenantID, claims.Topic))
 		writeIMSuccess(wrt, req, map[string]any{
 			"purpose":        claims.Purpose,
 			"expires_at":     time.Unix(claims.Expires, 0).UTC().Format(time.RFC3339Nano),
@@ -6213,6 +6423,12 @@ func serveIMFriendRequestAction(wrt http.ResponseWriter, req *http.Request) {
 		writeIMRelationError(wrt, req, err)
 		return
 	}
+	if updated == nil {
+		logs.Err.Printf("friend request resolution returned an empty result: tenant=%d request=%s actor=%s status=%s",
+			principal.TenantID, requestID, principal.Uid.String(), status)
+		writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
+		return
+	}
 	if status == types.FriendRequestAccepted && imReliableHTTPEventsEnabled(req) {
 		topic := updated.ApplicantID.P2PName(updated.TargetID)
 		publishIMConversationSystemNotice(principal.TenantID, topic,
@@ -6225,11 +6441,13 @@ func serveIMFriendRequestAction(wrt http.ResponseWriter, req *http.Request) {
 	if imReliableHTTPEventsEnabled(req) {
 		eventType := "friend.request." + status
 		action := types.KVMap{}
+		summary := "对方已婉拒你的好友申请"
 		if status == types.FriendRequestAccepted {
 			action["topic"] = updated.ApplicantID.P2PName(updated.TargetID)
+			summary = "对方已同意你的好友申请"
 		}
 		if err = publishIMRelationEventWithAction(principal.TenantID, principal.Uid, updated.ApplicantID,
-			updated.RequestID+":"+status, eventType, "好友申请已处理", status, action); err != nil {
+			updated.RequestID+":"+status, eventType, "好友申请已处理", summary, action); err != nil {
 			writeIMError(wrt, req, http.StatusInternalServerError, 90000, imReasonInternal, "internal error", nil)
 			return
 		}
@@ -6813,6 +7031,8 @@ func defaultIMActionTarget(action, fallback string) string {
 		return "youth_mode"
 	case "group_owner_transfer", "group_dissolve":
 		return action
+	case "delete_account":
+		return "account"
 	default:
 		return fallback
 	}
@@ -7219,13 +7439,15 @@ func forwardTargetPayload(sub types.Subscription) map[string]any {
 	default:
 		return nil
 	}
-	return map[string]any{
+	target := map[string]any{
 		"topic":               sub.Topic,
 		"type":                topicType,
 		"display_name":        imDisplayNameFromPublic(sub.GetPublic(), sub.Topic),
 		"avatar_file_id":      imAvatarFileIDFromPublic(sub.GetPublic()),
 		"can_receive_forward": true,
 	}
+	applyAvatarURL(target)
+	return target
 }
 
 func forwardTargetMatches(topic, displayName, query string) bool {
@@ -7304,15 +7526,27 @@ func mergeGroupListSettingsPayload(payload map[string]any, settings *types.Group
 	return payload
 }
 
-func groupDetailPayload(group *types.Topic, selfSub *types.Subscription) map[string]any {
+// groupMemberCountFor returns the live member count for a single group topic,
+// mirroring the visibility rules of the group members list endpoint.
+func groupMemberCountFor(tenantID types.TenantID, topic string) int64 {
+	if topic == "" {
+		return 0
+	}
+	counts, err := store.GroupBusiness.MembersCount(tenantID, []string{topic})
+	if err != nil {
+		logs.Warn.Printf("group[%s]: failed to count members: %v", topic, err)
+		return 0
+	}
+	return counts[topic]
+}
+
+func groupDetailPayload(group *types.Topic, selfSub *types.Subscription, memberCount int64) map[string]any {
 	public := map[string]any{}
 	topic := ""
-	memberCount := 0
 	ownerID := ""
 	if group != nil {
 		public = groupPublicMap(group.Public)
 		topic = group.Id
-		memberCount = group.SubCnt
 		if owner := types.ParseUid(group.Owner); !owner.IsZero() {
 			ownerID = owner.UserId()
 		}
@@ -7341,8 +7575,8 @@ func groupDetailPayload(group *types.Topic, selfSub *types.Subscription) map[str
 	}
 }
 
-func groupSettingsPayload(group *types.Topic, selfSub *types.Subscription) map[string]any {
-	data := groupDetailPayload(group, selfSub)
+func groupSettingsPayload(group *types.Topic, selfSub *types.Subscription, memberCount int64) map[string]any {
+	data := groupDetailPayload(group, selfSub, memberCount)
 	private := map[string]any{}
 	if selfSub != nil {
 		private = groupPrivateMap(selfSub.Private)
@@ -7411,7 +7645,7 @@ func groupBusinessMemberPayload(member types.GroupMember, remark string) map[str
 }
 
 func maskIMGroupMemberProfileEntrypoint(data map[string]any) {
-	for _, key := range []string{"avatar_file_id", "public_account", "signature", "gender", "region"} {
+	for _, key := range []string{"avatar_file_id", "avatar_url", "public_account", "signature", "gender", "region"} {
 		delete(data, key)
 	}
 	data["can_add"] = false
@@ -8487,7 +8721,7 @@ func currentUserAccountPayload(tenantID types.TenantID, uid types.Uid) (map[stri
 func validIMSecurityChallengeScene(scene string) bool {
 	switch strings.TrimSpace(scene) {
 	case "set_independent_password", "enable_youth_mode", "close_youth_mode", "reset_independent_password",
-		"group_owner_transfer", "group_dissolve":
+		"group_owner_transfer", "group_dissolve", "delete_account":
 		return true
 	default:
 		return false
@@ -8589,6 +8823,19 @@ func appReleasePayload(release *types.AppRelease, currentVersion string, hasUpda
 	}
 }
 
+func isValidAppCode(raw string) bool {
+	if raw == "" || len(raw) > 32 {
+		return false
+	}
+	for _, r := range raw {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' || r == '_' {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
 func parseNumericAppVersion(raw string) ([]uint64, error) {
 	raw = strings.TrimPrefix(strings.ToLower(strings.TrimSpace(raw)), "v")
 	parts := strings.Split(raw, ".")
@@ -9219,12 +9466,33 @@ func requireIMGroupMember(wrt http.ResponseWriter, req *http.Request, topic stri
 		access = sub.ModeGiven & sub.ModeWant
 	}
 	if sub == nil || !access.IsJoiner() || (needRead && !access.IsReader()) {
+		// 群不存在（404）或已解散（410）要与"存在但无权限"（403）区分开。
+		if sub == nil && writeIMGroupMissingIfGone(wrt, req, principal.TenantID, topic) {
+			return nil, nil, false
+		}
 		writeIMError(wrt, req, http.StatusForbidden, 30005, imReasonPermissionDenied, "topic permission required", nil)
 		return nil, nil, false
 	}
 	return principal, sub, true
 }
 
+// writeIMGroupMissingIfGone 在群不存在或已删除时写出 404/410 并返回 true；查询失败时返回 false 保持原错误路径。
+func writeIMGroupMissingIfGone(wrt http.ResponseWriter, req *http.Request, tenantID types.TenantID, topic string) bool {
+	group, err := store.Topics.Get(tenantID, topic)
+	if err != nil {
+		return false
+	}
+	if group == nil {
+		writeIMError(wrt, req, http.StatusNotFound, 30004, imReasonResourceNotFound, "group not found", nil)
+		return true
+	}
+	if group.State == types.StateDeleted {
+		writeIMError(wrt, req, http.StatusGone, 30004, imReasonGroupDissolved, "group dissolved", map[string]any{"topic": topic})
+		return true
+	}
+	return false
+}
+
 func authenticateTopicReader(wrt http.ResponseWriter, req *http.Request, topic string) (*imPrincipal, string, bool) {
 	principal, ok := authenticateIMHTTPBearer(wrt, req)
 	if !ok {
@@ -10549,6 +10817,7 @@ func cleanStringList(values []string, limit int) []string {
 func isAllowedPublicUploadPurpose(purpose string) bool {
 	switch strings.TrimSpace(purpose) {
 	case types.PublicUploadPurposeEnterpriseLicense, types.PublicUploadPurposeTenantFeedback,
+		types.PublicUploadPurposeFeedback,
 		types.PublicUploadPurposeUserAvatar,
 		types.PublicUploadPurposeGroupAvatar:
 		return true
@@ -10565,7 +10834,7 @@ func isAllowedPublicUploadMime(purpose, mimeType string) bool {
 			strings.HasPrefix(mimeType, "image/png") ||
 			strings.HasPrefix(mimeType, "image/webp") ||
 			mimeType == "application/pdf"
-	case types.PublicUploadPurposeTenantFeedback:
+	case types.PublicUploadPurposeTenantFeedback, types.PublicUploadPurposeFeedback:
 		return strings.HasPrefix(mimeType, "image/jpeg") ||
 			strings.HasPrefix(mimeType, "image/png") ||
 			strings.HasPrefix(mimeType, "image/webp")
@@ -11006,6 +11275,15 @@ func topicFromCallsPath(path string) string {
 	return topicFromPathWithSuffix(path, prefix, suffix)
 }
 
+func topicFromCallsByTopicPath(path string) string {
+	const prefix = "/v1/im/calls/"
+	idx := strings.Index(path, prefix)
+	if idx < 0 {
+		return ""
+	}
+	return strings.Trim(strings.TrimSpace(path[idx+len(prefix):]), "/")
+}
+
 func topicFromDraftPath(path string) string {
 	const prefix = "/v1/im/topics/"
 	const suffix = "/draft"

server/im_http_test.go

@@ -41,7 +41,8 @@ type testVerificationStore struct {
 }
 
 type testHTTPInfrastructureStore struct {
-	deadLetters []types.KafkaDeadLetter
+	deadLetters      []types.KafkaDeadLetter
+	markSucceededErr error
 }
 
 type testTenantEntryStore struct {
@@ -110,6 +111,9 @@ func (s *testHTTPInfrastructureStore) BeginKafkaConsume(_ types.TenantID, record
 }
 
 func (s *testHTTPInfrastructureStore) MarkKafkaConsumeSucceeded(_ types.TenantID, _, _ string, _ time.Time) error {
+	if s.markSucceededErr != nil {
+		return s.markSucceededErr
+	}
 	return nil
 }
 
@@ -143,6 +147,7 @@ func (s *testHTTPInfrastructureStore) MarkKafkaDeadLetterReplay(_ types.TenantID
 type testRelationsStore struct {
 	context        *types.RelationshipContext
 	err            error
+	directAdded    bool
 	created        *types.FriendRequest
 	blocked        *types.UserBlock
 	deleted        bool
@@ -158,6 +163,7 @@ type testRelationsStore struct {
 	deleteTenant   types.TenantID
 	deleteUser     types.Uid
 	deletePeer     types.Uid
+	resolveNil     bool
 }
 
 type testFavoritesStore struct {
@@ -268,6 +274,7 @@ type testGroupBusinessStore struct {
 	listMembers       []types.GroupMember
 	listMembersOpts   types.GroupMemberListOptions
 	listMembersNext   string
+	membersCounts     map[string]int64
 	updatedSettings   types.GroupSettingsPatch
 	updatedMembers    []types.GroupMemberPatch
 	updatedRoleMode   types.AccessMode
@@ -349,6 +356,13 @@ func (s *testGroupBusinessStore) ListMembers(_ types.TenantID, _ string, opts ty
 	return s.listMembers, s.listMembersNext, nil
 }
 
+func (s *testGroupBusinessStore) MembersCount(_ types.TenantID, _ []string) (map[string]int64, error) {
+	if s.membersCounts == nil {
+		return map[string]int64{}, nil
+	}
+	return s.membersCounts, nil
+}
+
 func (s *testGroupBusinessStore) UpdateMember(_ types.TenantID, topic string, uid types.Uid, patch types.GroupMemberPatch) (*types.GroupMember, error) {
 	if s.updateMemberErr != nil {
 		return nil, s.updateMemberErr
@@ -725,7 +739,7 @@ func (s *testProfilesStore) UpdatePrivacy(_ types.TenantID, uid types.Uid, patch
 	return privacy, nil
 }
 
-func (s *testAppReleaseStore) Latest(platform, channel string) (*types.AppRelease, error) {
+func (s *testAppReleaseStore) Latest(_, platform, channel string) (*types.AppRelease, error) {
 	if s.err != nil {
 		return nil, s.err
 	}
@@ -951,6 +965,11 @@ func (s *testRelationsStore) CreateFriendRequest(_ types.TenantID, req *types.Fr
 	return req, nil
 }
 
+func (s *testRelationsStore) AddFriendDirect(_ types.TenantID, _, _ types.Uid, _ time.Time) error {
+	s.directAdded = true
+	return s.err
+}
+
 func (s *testRelationsStore) ListFriendRequests(_ types.TenantID, _ types.Uid, _, _, _ string, _ int) ([]types.FriendRequestListItem, string, error) {
 	return s.friendRequests, "", nil
 }
@@ -962,6 +981,9 @@ func (s *testRelationsStore) CountPendingFriendRequests(tenantID types.TenantID,
 }
 
 func (s *testRelationsStore) ResolveFriendRequest(_ types.TenantID, requestID string, actor types.Uid, status string, handledAt time.Time) (*types.FriendRequest, error) {
+	if s.resolveNil {
+		return nil, nil
+	}
 	return &types.FriendRequest{
 		TenantID:    7,
 		RequestID:   requestID,
@@ -975,6 +997,28 @@ func (s *testRelationsStore) ResolveFriendRequest(_ types.TenantID, requestID st
 	}, nil
 }
 
+func TestServeIMFriendRequestActionRejectsEmptyStoreResult(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+	expectIMBearer(t, ctrl, "token-1", 7, 42)
+
+	oldRelations := store.Relations
+	store.Relations = &testRelationsStore{resolveNil: true}
+	t.Cleanup(func() { store.Relations = oldRelations })
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/im/friend-requests/frq-1/accept", nil)
+	req.Header.Set("Authorization", "Bearer token-1")
+	rec := httptest.NewRecorder()
+	serveIMFriendRequestAction(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status: got %d, want %d; body=%s", rec.Code, http.StatusInternalServerError, rec.Body.String())
+	}
+	if response := decodeIMHTTPResponse(t, rec); response.Reason != imReasonInternal {
+		t.Fatalf("reason: got %q, want %q", response.Reason, imReasonInternal)
+	}
+}
+
 func (s *testRelationsStore) ListFriends(_ types.TenantID, _ types.Uid, _, _, _ string, _ int) ([]types.FriendListItem, string, error) {
 	return s.friends, "", nil
 }
@@ -3140,6 +3184,18 @@ func TestServeIMSystemNotificationsListAndRead(t *testing.T) {
 	if readAgainData["id"] != "evt-2" || readAgainData["read_at"] != readAt.UTC().Format(time.RFC3339Nano) {
 		t.Fatalf("read again response should keep persisted read_at: %#v", readAgainData)
 	}
+
+	expectIMBearer(t, ctrl, "token-read-future", 7, 42)
+	req = httptest.NewRequest(http.MethodPost, "/v1/im/system-notifications/evt-1/read", bytes.NewBufferString(`{"read_at":"2099-01-01T00:00:00Z"}`))
+	req.Header.Set("Authorization", "Bearer token-read-future")
+	req.Header.Set("Idempotency-Key", "read-future")
+	rec = httptest.NewRecorder()
+
+	serveIMSystemNotificationRead(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("future read_at status: got %d, want %d; body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
 }
 
 func TestServeIMMessageReceipts(t *testing.T) {
@@ -7814,26 +7870,23 @@ func mustP2PNameForUser(t *testing.T, uid types.Uid, topic string) string {
 	return name
 }
 
-func TestServeIMFriendRequestCreateHonorsGroupPrivateChatSetting(t *testing.T) {
+func TestServeIMFriendRequestCreateAllowsGroupSourceWhenPrivateChatDisabled(t *testing.T) {
 	ctrl := gomock.NewController(t)
 	defer ctrl.Finish()
-	expectIMBearer(t, ctrl, "token-1", 7, 1)
+	mockStore := expectIMBearer(t, ctrl, "token-1", 7, 1)
+	mockStore.EXPECT().GetUidString().Return("group-request-1")
 	oldRelations := store.Relations
 	oldProfiles := store.Profiles
 	oldSubs := store.Subs
-	oldGroups := store.GroupBusiness
-	store.Relations = &testRelationsStore{context: &types.RelationshipContext{Relationship: types.RelationshipNone}}
+	relations := &testRelationsStore{context: &types.RelationshipContext{Relationship: types.RelationshipNone}}
+	store.Relations = relations
 	store.Profiles = &testProfilesStore{}
 	subs := mock_store.NewMockSubsPersistenceInterface(ctrl)
 	store.Subs = subs
-	store.GroupBusiness = &testGroupBusinessStore{settings: &types.GroupSettings{
-		Topic: "grpAlpha", MemberPrivateChat: false, GroupStatus: types.GroupStatusActive,
-	}}
 	defer func() {
 		store.Relations = oldRelations
 		store.Profiles = oldProfiles
 		store.Subs = oldSubs
-		store.GroupBusiness = oldGroups
 	}()
 	memberMode := types.ModeCPublic
 	for _, uid := range []types.Uid{1, 2} {
@@ -7848,8 +7901,11 @@ func TestServeIMFriendRequestCreateHonorsGroupPrivateChatSetting(t *testing.T) {
 	req.Header.Set("Idempotency-Key", "fr-group-1")
 	rec := httptest.NewRecorder()
 	serveIMFriendRequests(rec, req)
-	if rec.Code != http.StatusForbidden {
-		t.Fatalf("status: got %d, want %d; body=%s", rec.Code, http.StatusForbidden, rec.Body.String())
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status: got %d, want %d; body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+	if relations.created == nil || relations.created.Source != "group" || relations.created.SourceTopic != "grpAlpha" {
+		t.Fatalf("unexpected group friend request: %#v", relations.created)
 	}
 }
 

server/im_security_policy_runtime.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/tinode/chat/server/logs"
@@ -20,6 +21,9 @@ const (
 
 	imYouthActionMessage = "message"
 	imYouthActionCall    = "call"
+
+	imSecurityPolicyCacheTTL      = 5 * time.Second
+	imSecurityPolicyErrorCacheTTL = 2 * time.Second
 )
 
 type imPolicyDecision struct {
@@ -29,6 +33,17 @@ type imPolicyDecision struct {
 	Details map[string]any
 }
 
+type imSecurityPolicyCacheEntry struct {
+	policy  *types.SecurityPolicy
+	err     error
+	expires time.Time
+}
+
+var imSecurityPolicyCache = struct {
+	sync.Mutex
+	entries map[string]imSecurityPolicyCacheEntry
+}{entries: make(map[string]imSecurityPolicyCacheEntry)}
+
 func imAllowDecision() imPolicyDecision {
 	return imPolicyDecision{Allowed: true}
 }
@@ -47,6 +62,12 @@ func imYouthModePolicyDecision(tenantID types.TenantID, actor types.Uid, action
 	if store.Security == nil || actor.IsZero() {
 		return imAllowDecision()
 	}
+	// Message content filtering is enforced by moderation below the policy
+	// check. Youth mode currently has no message-level deny rule, so avoid a
+	// database lookup on every ordinary publish.
+	if strings.TrimSpace(action) == imYouthActionMessage {
+		return imAllowDecision()
+	}
 	settings, err := store.Security.GetYouthMode(tenantID, actor)
 	if err != nil {
 		if !errors.Is(err, types.ErrNotFound) && !errors.Is(err, types.ErrUnsupported) {
@@ -65,10 +86,6 @@ func imYouthModePolicyDecision(tenantID types.TenantID, actor types.Uid, action
 				"policy_version": settings.PolicyVersion,
 			})
 		}
-	case imYouthActionMessage:
-		// content_filter is enforced by routing messages through content moderation
-		// before persistence; the decision remains allow unless moderation rejects it.
-		return imAllowDecision()
 	}
 	return imAllowDecision()
 }
@@ -117,7 +134,28 @@ func imSecurityPolicy(tenantID types.TenantID, tenantCode string) (*types.Securi
 	if tenantCode == "" {
 		return nil, types.ErrNotFound
 	}
+	key := fmt.Sprintf("%d:%s", tenantID, tenantCode)
+	now := time.Now()
+	imSecurityPolicyCache.Lock()
+	if cached, ok := imSecurityPolicyCache.entries[key]; ok && now.Before(cached.expires) {
+		imSecurityPolicyCache.Unlock()
+		return cached.policy, cached.err
+	}
+	if store.ModerationConfig == nil {
+		imSecurityPolicyCache.Unlock()
+		return nil, types.ErrUnsupported
+	}
 	policy, err := store.ModerationConfig.SecurityPolicy(tenantCode)
+	ttl := imSecurityPolicyCacheTTL
+	if err != nil {
+		ttl = imSecurityPolicyErrorCacheTTL
+	}
+	imSecurityPolicyCache.entries[key] = imSecurityPolicyCacheEntry{
+		policy:  policy,
+		err:     err,
+		expires: now.Add(ttl),
+	}
+	imSecurityPolicyCache.Unlock()
 	if err != nil {
 		return nil, err
 	}