语音导览一期工程存档（数据层→TTS→C 端伴随页）
存档人：小冈（R1）· 2026-09-24
决策链：刘总 09-24 提出「位置感知语音导览」命题 → 小冈可行性研究（C/A/B 三档）→ 刘总令 gpt6 出完整方案 → 刘总「开做」→ 刘总拍板「先用微信 WechatSI」→ 本轮收官存档。
状态：一期工程链路全部落地并部署生产，剩余三步人工动作（人审/生成/质检）后即可上线。
一、方案要点（gpt6 完整方案，已按其纠偏落地）
- 位置回调频率不可承诺 → 自动播「尽力而为」+ 手动点播兜底
- 围栏三件套：进入/离开滞回（trigger 进、leave=1.33× 出）、连续 2 次命中确认、同点位 6h 冷却
- 播放中不打断：新触发进队列，播完续放
- 讲解稿三版制：short 20-40s / standard 60-90s / long 120-180s
- 文案修改不自动上线：draft → 人审 → TTS 生成 → 质检试听 → 发布（双人审节点）
- 隐私纪律：播放记录只存匿名事件，不存轨迹，不关联 openid/手机号
- 分档：C 档手动附近查询 / A 档前台伴随（已实现）/ B 档灭屏后台（一期不做）
二、数据层（迁移 094 + 种子 094b，生产与 staging 均已执行）
pois 扩展：latitude/longitude（coordinate_system 统一口径）、trigger_radius_m、leave_radius_m、content_status、coord_verified（实地核实标记，未核实不作核心卖点）、is_test- 7 张新表：guide_routes / guide_route_pois / guide_scripts（三档+审核+brand_creation_flag）/ guide_audios（版本化+sha256+质检状态，mp3 走 CDN 只存元数据）/ guide_packages+items（离线包）/ guide_play_records（匿名事件）
- 种子：12 POI（塔尔钦周边 6+转山沿线 4+芝达布日 2，坐标=公开资料近似值 wgs84、coord_verified=false）；2 线路（转山全线 52km 六点位按序 / 塔尔钦周边自驾半日七点位）；13 条编排
三、后端 API（已部署生产+staging，rev 见 git log）
C 端 miniapp_voice_guide（/api/miniapp/voice-guide）：
- GET /routes — 已发布线路列表（include_test 演示开关）
- GET /routes/{id} — 线路详情：点位按序+双半径+已审文案+已质检音频 URL（游客端一次下载即可本地围栏，弱网不依赖服务端）
- GET /nearby — C 档兜底（服务端 Haversine 精算，实测正确）
- POST /play-records — 匿名播放上报（北极星指标「人均有效收听点位数」数据源）
A 端 admin_voice_guide（/api/admin/voice-guide，require_admin）：
- POI/线路/编排 CRUD；讲解稿三档管理
- POST /scripts/{id}/review — 人审节点（approve 后进 TTS 队列，不自动可见）
- POST /audios — 音频登记；POST /audios/{id}/review — 质检节点（approve 才游客可见）
- GET /queue — 审校队列总览（草稿/待审/待生成/待质检/未核实坐标计数）
四、TTS 管线（刘总拍板 WechatSI）
- WechatSI 是小程序插件、无服务端 API、返回临时链接有时效 → 生成必须在端侧真机跑并立即转存自有 CDN
- 生成台 = v2 管理员工具页
pages/tts-generator（85 页时引入）：队列自动拉 approved 文案 → WechatSI textToSpeech（女声 1001/男声 1002 可选）→ 下载 mp3 → 上传 img.kailashi.cn（upload.py 白名单加 mp3/m4a+voice-guide 目录）→ 登记 guide_audios(pending) → 篇间 1s 防频控+运行日志+试听 - 管理员判定走服务端兜底（require_admin 真值），非管理员见锁定提示
- app.json 已声明插件（0.3.6 / wx069ba97219f66d99）；使用前需在 mp 后台「插件管理」添加该插件授权（刘总一次点击）
五、C 端两页（本轮收官，app.json 共 87 页）
pages/voice-guide 线路选择页：已发布线路卡+类型标签+点位数；长按标题切「测试内容」演示开关（与阿里文库同 key）；空/错/骨架态齐全pages/guide-companion 导览伴随页：围栏状态机完整实现（连续 2 次命中确认/滞回/6h 冷却/队列续播/播放中不打断）；吸底播放条+最近点位距离；点位展开读文字稿；无已质检音频不播不写冷却、显示「制作中」；品牌创作稿显式标注「神山秘境品牌创作·非宗教传统表述」；onHide 停定位（前台策略省电合规）；匿名播放上报（本地随机 ID）- 入口：首页工具卡「语音导览」（编号文案 x95-x97）+ 我的页游客/管理员双入口
- app.json：requiredPrivateInfos 补
onLocationChange；定位权限描述补导览用途 - 质量门：tsc 新文件 0 error；生产 API 实测（routes/nearby/play-records/401 闸）全过
六、内容第一批（11 篇 short 口语稿，两库各 12 篇含 3 样张）
- 覆盖：塔尔钦/色雄/曲古寺/止热寺/卓玛拉垭口/祖楚寺/观景台/拉昂措/纳木那尼/门士乡/芝达布日/玛旁雍措
- 从冈子 docs/content 原料口语化改写（非复制书面文）；【核实】数字模糊化（「大约」）；色雄稿明示「转山起点有多种说法」合规口径；芝达布日篇 brand_creation_flag=true
- 全部 review_status=draft 待人审；脚本
scripts/voice_guide_scripts_seed.py 幂等可重跑 - 游客口径验证：detail 接口对 draft 文案返回 0 篇——闸门正确工作（游客可见=审核通过）
七、上线前剩余三步（全人工，工程已就绪）
| # | 动作 | 入口 | 备注 |
|---|
| 1 | 12 篇 draft 讲解稿人审 approve | A 端 API /scripts/{id}/review | 可批量 |
| 2 | 生成音频 | v2 我的→音频生成台→「开始生成全部」 | 需管理员登录+mp 后台插件授权 |
| 3 | 质检试听 approve → 线路翻 published+is_test=false | A 端 /audios/{id}/review | 游客端立即可听 |
八、遗留与已知边界（如实）
- 真机未验：两新页过 tsc 类型层；onLocationChange 实机回调、WechatSI 音色需开发者工具+真机各跑一遍
- 音频时长为估算值（4.5 字/秒），质检环节以试听为准
- B 档（灭屏后台触发）一期不做，页面文案已明示「锁屏会暂停」
- 离线包表已建、下载器未做（二期：转山线整包预下载）
- staging 三个既有同名点位（塔尔钦/止热寺/祖楚寺）已补坐标对齐生产
九、文件清单
- backend/sql/094_voice_guide.sql · 094b_voice_guide_seed.sql
- backend/app/routers/miniapp_voice_guide.py · admin_voice_guide.py · upload.py（白名单扩展）
- miniprogram-v2/pages/voice-guide/* · guide-companion/* · tts-generator/*
- miniprogram-v2/app.json（87 页+插件+权限声明）· pages/home · pages/profile · utils/texts.ts（x95-x97）
- scripts/voice_guide_scripts_seed.py
- 关联文档：docs/reports/2026-09-24-gpt6完整方案-位置语音导览.md · 2026-09-24-位置感知语音导览可行性研究-v1.html