# Banban 统一数据与接口设计文档（Mini Program + talkingq-url，V3）

## 1. 目标与边界

本设计用于统一 `mini-program` 与 `talkingq-url` 的数据库模型与接口语义，目标是：

1. 两个服务使用同一套设备身份（`device_id`）。
2. 保留 `talkingq-url/mysql/init/01-init.sql` 现有表结构不变。
3. 在不改动基础表的前提下，补齐家长/小孩/绑定/聊天/定位能力。

硬性边界：

1. `01-init.sql` 中现有表不改表名、不改字段、不改约束。
2. 所有新增表仅做增量扩展。
3. 新增表字段命名风格对齐现有风格：`snake_case`、`*_id`、`is_active`、`status`、`created_at`、`updated_at`。

## 2. 现有冻结表（来自 01-init.sql）

以下表为设备能力基础层，保持不变：

1. `device_auth`：设备身份白名单（`device_id + serial_number`）。
2. `device_configs`：设备角色与基础配置（含 `volume`）。
3. `conversation_histories`：设备与角色会话头。
4. `conversation_messages`：设备与角色会话消息。
5. `roles` / `role_languages`：角色与多语言配置。
6. `device_firmware_update`：设备固件升级状态。
7. `system_config`：系统配置项。

职责说明：

1. `conversation_histories/conversation_messages` 继续只服务“设备 <-> AI 角色”的对话，不承担家长-小孩 IM。
2. 设备鉴权统一走 `device_auth`，`device_id` 为全局设备业务标识。

## 3. 新增主体模型

### 3.1 家长主体表 `parents`

建议字段：

1. `user_id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `openid` VARCHAR(64) UNIQUE NOT NULL
3. `unionid` VARCHAR(64) NULL
4. `nickname` VARCHAR(64) NULL
5. `avatar_url` VARCHAR(255) NULL
6. `phone` VARCHAR(20) NULL
7. `status` TINYINT NOT NULL DEFAULT 1
8. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
9. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

索引建议：

1. `uk_openid(openid)`
2. `idx_unionid(unionid)`
3. `idx_phone(phone)`

### 3.2 小孩主体表 `children`

建议字段：

1. `child_id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `child_name` VARCHAR(32) NOT NULL
3. `child_gender` TINYINT NOT NULL DEFAULT 2
4. `child_birthday` DATE NULL
5. `status` TINYINT NOT NULL DEFAULT 1
6. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
7. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

说明：

1. 不在库内存储 `child_age` 计算列，年龄由查询层按时间实时计算，避免跨年缓存误差。

### 3.3 家长-小孩关系表 `parent_child_relations`

建议字段：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `user_id` BIGINT UNSIGNED NOT NULL
3. `child_id` BIGINT UNSIGNED NOT NULL
4. `relation_type` TINYINT NOT NULL DEFAULT 9
5. `is_primary` TINYINT(1) NOT NULL DEFAULT 0
6. `status` TINYINT NOT NULL DEFAULT 1
7. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
8. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

约束建议：

1. `UNIQUE(user_id, child_id)`
2. `FOREIGN KEY (user_id) REFERENCES parents(user_id)`
3. `FOREIGN KEY (child_id) REFERENCES children(child_id)`

### 3.4 设备归属表 `device_bindings`

用途：表达“当前哪块设备绑定到哪个小孩”，并与 `device_auth` 对齐。

建议字段：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `device_id` VARCHAR(64) NOT NULL
3. `child_id` BIGINT UNSIGNED NOT NULL
4. `status` TINYINT NOT NULL DEFAULT 1
5. `bound_at` DATETIME NOT NULL
6. `unbound_at` DATETIME NULL
7. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
8. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

约束建议：

1. `UNIQUE(device_id)`
2. `UNIQUE(child_id)`
3. `FOREIGN KEY (device_id) REFERENCES device_auth(device_id)`
4. `FOREIGN KEY (child_id) REFERENCES children(child_id)`

### 3.5 绑定会话表 `device_bind_sessions`

建议字段：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `bind_token` CHAR(36) UNIQUE NOT NULL
3. `device_id` VARCHAR(64) NOT NULL
4. `initiator_user_id` BIGINT UNSIGNED NOT NULL
5. `target_child_id` BIGINT UNSIGNED NULL
6. `challenge_code_hash` CHAR(64) NULL
7. `challenge_set_at` DATETIME NULL
8. `expires_at` DATETIME NOT NULL
9. `max_attempt_count` TINYINT UNSIGNED NOT NULL DEFAULT 5
10. `attempt_count` TINYINT UNSIGNED NOT NULL DEFAULT 0
11. `status` TINYINT NOT NULL DEFAULT 1
12. `confirmed_at` DATETIME NULL
13. `consumed_at` DATETIME NULL
14. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
15. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

约束建议：

1. `FOREIGN KEY (device_id) REFERENCES device_auth(device_id)`
2. `FOREIGN KEY (initiator_user_id) REFERENCES parents(user_id)`
3. `FOREIGN KEY (target_child_id) REFERENCES children(child_id)`

### 3.6 绑定历史表 `device_bind_history`

建议字段：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `device_id` VARCHAR(64) NOT NULL
3. `child_id` BIGINT UNSIGNED NOT NULL
4. `bound_by_user_id` BIGINT UNSIGNED NOT NULL
5. `unbound_by_user_id` BIGINT UNSIGNED NULL
6. `bind_source` TINYINT NOT NULL DEFAULT 1
7. `bound_at` DATETIME NOT NULL
8. `unbound_at` DATETIME NULL
9. `unbind_reason` VARCHAR(191) NULL
10. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP

约束建议：

1. `FOREIGN KEY (device_id) REFERENCES device_auth(device_id)`
2. `FOREIGN KEY (child_id) REFERENCES children(child_id)`
3. `FOREIGN KEY (bound_by_user_id) REFERENCES parents(user_id)`
4. `FOREIGN KEY (unbound_by_user_id) REFERENCES parents(user_id)`

### 3.7 卡片表 `cards`

建议字段：

1. `card_id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `card_uuid` VARCHAR(64) UNIQUE NOT NULL
3. `device_id` VARCHAR(64) UNIQUE NULL
4. `card_name` VARCHAR(64) NULL
5. `status` TINYINT NOT NULL DEFAULT 0
6. `total_swaps` INT NOT NULL DEFAULT 0
7. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
8. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

约束建议：

1. `FOREIGN KEY (device_id) REFERENCES device_auth(device_id)`

### 3.8 设备设置表 `device_settings`

建议字段：

1. `setting_id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `device_id` VARCHAR(64) NOT NULL UNIQUE
3. `sleep_mode` TINYINT NOT NULL DEFAULT 0
4. `disable_time_start` TIME NULL
5. `disable_time_end` TIME NULL
6. `timezone` VARCHAR(32) NOT NULL DEFAULT 'Asia/Shanghai'
7. `volume` TINYINT UNSIGNED NULL
8. `brightness` TINYINT UNSIGNED NULL
9. `disable_weekdays` VARCHAR(32) NULL
10. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
11. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

兼容规则：

1. `volume` 同步写入 `device_configs.volume`，防止两服务读到不同值。
2. 若只允许单一音量来源，则以 `device_configs.volume` 为准，`device_settings.volume` 可后续下线。
3. `disable_time_start/disable_time_end` 与历史命名 `sleep_start/sleep_end` 一一映射。
4. 禁用时段按 `timezone` 解释；跨天时段（如 22:00-07:00）按“跨日窗口”处理。

## 4. 聊天与定位模型（新增，不改 01 现有会话表）

### 4.1 IM 会话表 `im_conversations`

用途：仅服务家长-小孩、小孩-小孩 1v1，不与 `conversation_histories` 混用。

建议字段：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `conversation_type` TINYINT UNSIGNED NOT NULL
3. `participant_a_type` TINYINT UNSIGNED NOT NULL
4. `participant_a_id` VARCHAR(64) NOT NULL
5. `participant_b_type` TINYINT UNSIGNED NOT NULL
6. `participant_b_id` VARCHAR(64) NOT NULL
7. `pair_key` VARCHAR(191) NOT NULL
8. `status` TINYINT NOT NULL DEFAULT 1
9. `last_seq` BIGINT UNSIGNED NOT NULL DEFAULT 0
10. `message_count` BIGINT UNSIGNED NOT NULL DEFAULT 0
11. `last_message_preview` VARCHAR(255) NULL
12. `last_message_at` DATETIME NULL
13. `ext_json` JSON NULL
14. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
15. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

说明：

1. 会话核心字段保持通用，不使用 `child_low_id/child_high_id` 这类场景耦合命名。
2. `conversation_type` 使用类型码，可扩展；新增会话类型优先通过“类型码 + 业务校验 + `ext_json`”扩展，无需改核心表。
3. 当前建议启用类型：`1-child_peer`、`2-parent_child`。

约束建议：

1. `UNIQUE(conversation_type, pair_key)`
2. `INDEX idx_participant_a (participant_a_type, participant_a_id)`
3. `INDEX idx_participant_b (participant_b_type, participant_b_id)`
4. `INDEX idx_last_message_at (last_message_at)`

### 4.2 IM 消息表 `im_messages`

建议字段：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `conversation_id` BIGINT UNSIGNED NOT NULL
3. `seq` BIGINT UNSIGNED NOT NULL
4. `sender_type` TINYINT UNSIGNED NOT NULL
5. `sender_id` VARCHAR(64) NOT NULL
6. `receiver_type` TINYINT UNSIGNED NOT NULL
7. `receiver_id` VARCHAR(64) NOT NULL
8. `content_type` TINYINT UNSIGNED NOT NULL
9. `content_text` MEDIUMTEXT NULL
10. `content_json` JSON NULL
11. `media_file_key` VARCHAR(255) NULL
12. `media_duration_ms` INT UNSIGNED NULL
13. `media_mime_type` VARCHAR(64) NULL
14. `media_size_bytes` BIGINT UNSIGNED NULL
15. `media_transcript_text` TEXT NULL
16. `client_msg_id` VARCHAR(64) NULL
17. `sender_name_snapshot` VARCHAR(64) NULL
18. `sender_avatar_snapshot` VARCHAR(255) NULL
19. `receiver_name_snapshot` VARCHAR(64) NULL
20. `receiver_avatar_snapshot` VARCHAR(255) NULL
21. `ext_json` JSON NULL
22. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
23. `deleted_at` DATETIME NULL

约束建议：

1. `UNIQUE(conversation_id, seq)`
2. `UNIQUE(conversation_id, client_msg_id)`
3. `FOREIGN KEY (conversation_id) REFERENCES im_conversations(id) ON DELETE CASCADE`
4. `INDEX idx_sender (sender_type, sender_id, created_at)`
5. `INDEX idx_receiver (receiver_type, receiver_id, created_at)`

#### 4.2.1 文本与语音消息规则

1. `content_type=1(text)`：`content_text` 必填。
2. `content_type=2(audio)`：`media_file_key` 必填，建议同时写入 `media_duration_ms`、`media_mime_type`、`media_size_bytes`。
3. `content_type=3(image)`：`media_file_key` 必填。
4. `content_type=4(json)`：`content_json` 必填。
5. 语音转写内容可写入 `media_transcript_text`，用于检索与展示。
6. 展示层优先使用 `sender_name_snapshot/sender_avatar_snapshot` 与 `receiver_*_snapshot`，减少联表查询。

### 4.3 位置表

`child_location_current`：

1. `child_id` BIGINT UNSIGNED PK
2. `device_id` VARCHAR(64) NOT NULL
3. `coord_type` VARCHAR(16) NOT NULL DEFAULT 'gcj02'
4. `lat` DECIMAL(10,7) NOT NULL
5. `lng` DECIMAL(10,7) NOT NULL
6. `accuracy_m` INT UNSIGNED NULL
7. `altitude_m` DECIMAL(8,2) NULL
8. `speed_mps` DECIMAL(8,2) NULL
9. `heading_deg` SMALLINT UNSIGNED NULL
10. `source` TINYINT UNSIGNED NOT NULL
11. `battery_pct` TINYINT UNSIGNED NULL
12. `device_time` DATETIME NOT NULL
13. `server_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
14. `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

`child_location_history`：

1. `id` BIGINT UNSIGNED PK AUTO_INCREMENT
2. `child_id` BIGINT UNSIGNED NOT NULL
3. `device_id` VARCHAR(64) NOT NULL
4. `coord_type` VARCHAR(16) NOT NULL DEFAULT 'gcj02'
5. 其余定位字段与 `child_location_current` 对齐
6. `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP

#### 4.3.1 位置上报协议（统一格式）

1. 上报字段：`device_id`、`child_id`、`coord_type`、`lat`、`lng`、`accuracy_m`、`source`、`device_time`、`battery_pct`。
2. 坐标系标准：统一使用 `gcj02`。
3. 坐标格式：统一按 `lat,lng`（纬度在前，经度在后）传输和存储。
4. 若设备侧提供 `wgs84`，服务端需先转换到 `gcj02` 后再入库；原始坐标可选写入 `ext_json` 备查。
5. 写入规则：同事务写 `child_location_history` 并覆盖 `child_location_current`。

## 5. 核心业务流程

### 5.1 设备注册与鉴权

1. 生产或后台调用 `talkingq-url` 现有注册接口，写入 `device_auth`。
2. 手表请求携带 `X-Device-ID` 与 `X-Device-Serial`。
3. 后端基于 `device_auth` 鉴权通过后继续处理聊天/定位/绑定。

### 5.2 绑定流程（扫码 + 确认码）

1. 家长登录后发起 `bind/start`，创建 `device_bind_sessions`。
2. 手表上报确认码，更新会话挑战信息。
3. 家长提交确认码。
4. 后端校验通过后开启事务。
5. upsert `parent_child_relations`。
6. upsert `device_bindings`（保证一设备一行、一小孩一行）。
7. 追加 `device_bind_history`。
8. 更新会话状态为 `confirmed/consumed` 并提交事务。

### 5.3 聊天流程

1. 设备 AI 对话仍走 `conversation_histories + conversation_messages`。
2. 家长-小孩、小孩-小孩消息走 `im_conversations + im_messages`。
3. IM 消息统一使用 `sender_type/sender_id + receiver_type/receiver_id`，不按场景拆专用发送者字段。
4. 发送接口必须使用 `client_msg_id` 幂等。
5. 查询前必须校验 `parent_child_relations` 权限。
6. 列表展示优先读取消息快照字段，降低跨表查询成本。

### 5.4 位置流程

1. 手表上报定位写入 `child_location_history`。
2. 同事务更新 `child_location_current`。
3. 小程序查询当前定位读 `child_location_current`，轨迹读 `child_location_history`。
4. 地址解析使用腾讯位置服务；若解析失败，前端降级展示经纬度。

## 6. 统一约束与实现规则

1. 所有设备引用字段统一使用 `device_id VARCHAR(64)`，不再新增 `watch_device_id BIGINT`。
2. 设备主身份只认 `device_auth.device_id`。
3. 跨主体通用 ID 字段统一采用字符串（如 `participant_*_id`、`sender_id`、`receiver_id`）。
4. 所有业务表统一包含 `created_at/updated_at`（历史流水类可无 `updated_at`）。
5. `status` 用于业务态，`is_active` 用于启停态；两者不混用。
6. 关键写路径（绑定确认、发消息、位置写入）必须事务化。
7. 腾讯位置服务启用前提：必须配置合法 `key`，并完成域名/来源白名单与配额设置。
8. 地图相关接口统一使用 `gcj02` 和 `lat,lng`；禁止混用 `wgs84/bd09` 直接入库。

## 7. 分阶段落地

1. 第一阶段：落地 `parents/children/parent_child_relations/device_bind_*`，打通绑定链路。
2. 第二阶段：落地 `im_conversations/im_messages`，打通家长与小孩 IM。
3. 第三阶段：落地 `child_location_current/history`，打通定位链路。
4. 第四阶段：补充审计、告警、实时推送和运营能力。

## 8. 验收标准

1. 不修改 `01-init.sql` 任一现有表，服务可正常启动。
2. 设备鉴权、角色配置、OTA能力保持可用。
3. 家长可完成扫码绑定、解绑、重绑，且历史保留。
4. 家长可查看自己小孩与其他小孩完整双向消息。
5. 小程序可查看小孩最新位置与历史轨迹。