banban/mini-program/design.md

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

1. 目标与边界

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

1. 两个服务使用同一套设备身份（device_id）。
2. 保留 talkingq-url/mysql/init/01-init.sql 现有表结构不变。
3. 在不改动基础表的前提下，补齐家长/小孩/绑定/聊天/定位能力。
4. 家长账号体系统一采用微信小程序登录，服务端基于 code2Session 换取真实 openid/unionid。

硬性边界：

1. 01-init.sql 中现有表不改表名、不改字段、不改约束。
2. 所有新增表仅做增量扩展。
3. 新增表字段命名风格对齐现有风格：snake_case、*_id、is_active、status、created_at、updated_at。
4. 微信 AppSecret 只能保存在服务端配置中，小程序端只持有一次性 code。

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. avatar_file_key VARCHAR(255) NULL
7. phone VARCHAR(20) NULL
8. status TINYINT NOT NULL DEFAULT 1
9. created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
10. updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

说明：

1. avatar_file_key 作为头像主存储值，保存 COS 对象 key。
2. avatar_url 作为兼容或展示字段使用，不作为唯一主依据。
3. openid 必须存储微信服务端 code2Session 返回的真实 OpenID；禁止将前端 code、测试用户名或设备标识写入该字段。
4. unionid 仅在微信返回时写入；历史记录为空时，后续登录可补写，不作为首次登录成功前置条件。
5. nickname/avatar_url 为展示资料，可由小程序端在登录时上传并在后续更新，但不参与身份认证。
6. phone 为业务补充字段，与微信登录态解耦；如后续接入手机号授权，应基于服务端掌握的 session_key 解密后再写入。

索引建议：

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. owner_user_id BIGINT UNSIGNED NOT NULL
4. child_id BIGINT UNSIGNED NULL
5. status TINYINT NOT NULL DEFAULT 1
6. bound_at DATETIME NOT NULL
7. unbound_at DATETIME NULL
8. created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
9. updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

说明：

1. 设备可以先归属到家长，再在后续流程中补充关联 child_id。
2. child_id 为空表示当前设备已归属，但尚未绑定到具体小孩。

约束建议：

1. UNIQUE(device_id)
2. UNIQUE(child_id)
3. INDEX idx_owner_user_id(owner_user_id)
4. FOREIGN KEY (device_id) REFERENCES device_auth(device_id)
5. FOREIGN KEY (owner_user_id) REFERENCES parents(user_id)
6. 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. 小程序调用 wx.login / Taro.login 获取一次性 code。
2. 小程序调用后端 POST /auth/login，上传 code，并可附带 nickname/avatar_url 作为资料字段。
3. 后端使用服务端配置的 wechat_app_id + wechat_app_secret 调用微信 code2Session。
4. 后端从微信响应中获取真实 openid、可选 unionid，以及仅供服务端使用的 session_key。
5. 后端以 openid 为唯一身份键 upsert parents；若本次拿到 unionid 且库中为空，则补写 unionid。
6. 后端签发本地 access_token(JWT) 返回给小程序，后续业务接口仍统一使用本地 Bearer Token。
7. 若微信换码失败、openid 缺失、code 失效或被重复使用，登录直接失败，不创建本地用户。
8. session_key 仅用于后续需要的微信敏感数据解密能力（如手机号）；当前阶段不作为登录态主键，也不写入 parents 主表。

5.2 设备注册与鉴权

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

5.3 绑定流程（扫码 + 确认码）

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.4 聊天流程

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

5.5 位置流程

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 直接入库。
9. 小程序端只上送一次性 code，不得自行调用微信换取 openid，更不得持有 AppSecret。
10. code 只用于调用微信 code2Session，不得入库为 openid、unionid 或任何长期身份字段。
11. session_key 不返回前端，不写入 parents 主表；如需支持手机号等敏感数据解密，应服务端短期缓存并设置明确过期时间。
12. nickname/avatar_url 仅作资料字段，不能作为登录态、账号归并或权限判断依据。

7. 分阶段落地

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

8. 验收标准

1. 家长可通过真实微信登录完成换码，并获取本地 Bearer Token。
2. parents.openid 存储值来自微信返回的真实 OpenID，而不是前端 code 或测试标识。
3. 不修改 01-init.sql 任一现有表，服务可正常启动。
4. 设备鉴权、角色配置、OTA能力保持可用。
5. 家长可完成扫码绑定、解绑、重绑，且历史保留。
6. 家长可查看自己小孩与其他小孩完整双向消息。
7. 小程序可查看小孩最新位置与历史轨迹。

9. 共享库落地规范

9.1 唯一数据库与唯一 Schema

1. mini-program 与 talkingq-url 必须共用同一个 MySQL 数据库：talkingq。
2. database/talkingq_shared_schema.sql 是唯一 schema 真相源。
3. mini-program/database/init.sql 仅保留给历史上的“单服务独立开发”场景，不再作为共享部署的建库依据。

9.2 表归属（Table Ownership）

talkingq-url 拥有以下表的写入责任：

1. device_auth
2. device_configs
3. conversation_histories
4. conversation_messages
5. roles
6. role_languages
7. device_firmware_update
8. system_config

mini-program 拥有以下表的写入责任：

1. parents
2. children
3. parent_child_relations
4. device_bindings
5. device_bind_sessions
6. device_bind_history
7. device_settings
8. cards
9. im_conversations
10. im_messages
11. child_location_current
12. child_location_history

约束：

1. 两个服务允许跨服务读取共享依赖表，但不允许跨服务写对方负责的主表。
2. mini-program 只读 device_auth，不直接承担设备注册主流程。
3. talkingq-url 不写 parents/children/device_bindings/im_* /child_location_*。

9.3 共享字段与真相源

1. 设备主身份统一以 device_auth.device_id 为准。
2. 设备与 AI 的历史消息统一以 conversation_histories + conversation_messages 为准。
3. 家长/儿童 IM 统一以 im_conversations + im_messages 为准。
4. 设备音量如需双端共享，以 device_configs.volume 为真相源；device_settings.volume 仅作小程序展示和兼容字段。

9.4 迁移原则

1. 目标库固定为 talkingq。
2. 迁移时以 talkingq-url 当前使用的 talkingq 数据为准。
3. 历史 mini_program 库中的业务数据不并入 talkingq，也不作为冲突解决依据。
4. 迁移动作只做两件事：
   1. 在 talkingq 上补齐 mini-program 所需扩展表。
   2. 将 mini-program 服务配置切换到 talkingq。
5. mini_program 库可在切换验证完成后归档或删除，但不再作为运行时数据库。

9.5 启动与建表策略

1. 共享部署下，服务启动默认只检查数据库连通性，不自动执行 ORM create_all。
2. 只有显式开启开发开关时，mini-program 才允许自动建表。
3. 生产、联调、共享测试环境统一通过 database/talkingq_shared_schema.sql 或正式 migration 执行建表与变更。