交付出件箱

← 返回出件箱

门店手机端「视光档案」实施方案 v0.1

• 立项日期：2026-09-15
• 分支：feature/store-mobile-refractive-archive（基线 origin/test @ 63972df0）
• 性质：新增门店手机端一套，平板端 /h5/tablet 保留不动（长官 D1 拍板）
• 状态：调研与 verify 已完成；方案待长官拍板后进需求变更流程

〇、一句话结论

这活是纯前端。后端 18 个端点、鉴权体系、机构开关、数据字典四层全部可以白拿，零改动；
真实工作量集中在把平板端 27 个文件 8548 行里的横屏布局假设按手机端绿系令牌重做，
外加一个必须先拆掉的物理障碍（seat-auth-recovery.ts 硬编码 /h5/tablet 跳转）。

🔴 9-15 更正（记账见 §八 #16）：以上"后端零改动"结论只在 D1-D8 范围内成立。长官 9-15 新增
「门店结论已读回执」需求（D9）后不再成立——本期新增新字段 store_conclusion_read_at、一条 alembic
迁移、一个新 POST 端点、门店端+家长端两处 DTO 出参改动。后端改动范围详见 §九。

一、长官已拍板决策（D1-D9 · 不再重议）

二、物理 verify 证据表（13 维 · 每条带命令与原始输出 · 0 命中带对照组）

铁律：下任何结论前必须物理 grep，并带对照组证明查法有效。
下表中 4 条是证伪/纠偏 —— 说明这些结论如果凭印象写，方案就会派单出错。

V1 手机端功能入口结构 —— ❌ 证伪（方向性错误）

原假设：手机端有个类似平板 TABLET_FEATURES 的菜单常量数组。

$ grep -n "isParentSeat" web/app/h5/chat/page.tsx
565:  const [isParentSeat, setIsParentSeat] = useState<boolean>(false);
...
2929:              {isParentSeat ? (
2998:              ) : (
3129:              )}
3130:            </div>
$ sed -n '2928p' web/app/h5/chat/page.tsx
            <div className="px-4 pt-1.5 pb-0 flex items-center justify-start gap-2 overflow-x-auto scrollbar-hide" id="v4ConsultEntry">

真相：chat/components/menu-sidebar.tsx 是会话历史侧抽屉（新建会话/历史/设置/退出），没有功能项数组。
手机端真正的功能入口是 chat/page.tsx:2928-3130 里一排内联 chip 按钮，按 isParentSeat 劈成两套：

• 家长坐席分支（2929-2997）：历史解读 / 个人档案 / 近视的世界 / 关于赵阳智脑
• 非家长（门店）坐席分支（2998-3129）：报告秒读 / 历史解读 / 抗近领航 / 谣言粉碎机 / 近视的世界 / 量身定案 / 关于赵阳智脑

门店坐席走哪套？getSeatType() 在 localStorage 无 seat_type 键时默认返回 "store"
（web/app/h5/chat/lib/auth.ts:619-626）→ isParentSeat=false → 走 2998-3129 这套。

→ 对方案的影响：加入口不是"数组加一行"，要在 2998-3129 分支里插一个新的
{featureFlags.enable_refractive_record && (<button …>视光档案</button>)} 块。

V2 家长端手机表单能不能直接拿来用 —— ✅ 证实（不能）

$ grep -n -B3 -A8 "getSeatType" "web/app/h5/family/[id]/exam/new/page.tsx"
664-  useEffect(() => {
665:    if (!getSeatToken() || getSeatType() !== "parent") {
666-      router.replace("/h5/chat");
667-      return;
668-    }

同款 gate 在 family/page.tsx:76、family/new/page.tsx:105、family/[id]/page.tsx:562 一致出现。

结论：家长端 4 个页面统一把「门店坐席」和「无 token 访客」都踢回 /h5/chat。
门店手机端必须另建路由，不能复用 family 那套页面本体（但样式与组件可以照抄，见 V13）。

V3 横屏布局硬伤精确计数 —— ✅ 证实

$ grep -rl '1fr 108px 108px' web/app/h5/tablet/pane/panes/refractive-record/ | while read f; do echo "$f: $(grep -c '1fr 108px 108px' "$f")"; done
web/app/h5/tablet/pane/panes/refractive-record/frame5-record-entry.tsx: 11
web/app/h5/tablet/pane/panes/refractive-record/record-canvas.tsx: 5

合计 16 处；frame5 的 11 处中 1 处是注释提及，代码 10 处：
L123, L452, L485, L495, L567, L580, L598, L607, L616, L657。
record-canvas.tsx 的 5 处全部落在 dead code 上（见 V4）。

→ 当前真实渲染路径需要改的是 10 处，不是 16 处。

V4 dead code 判定 —— ✅ 证实（省掉 776 行）

$ grep -rn "<PatientRail\|<RecordCanvas" web/app/
web/app/h5/tablet/pane/panes/refractive-record/patient-rail.tsx:70:  // ⚠️ 本文件当前未被 refractive-record-pane.tsx 渲染(仅 import 未 <PatientRail> 实例化)，
（1 命中——命中的是 patient-rail.tsx:70 自己注释里字面写的 "<PatientRail>"，不是真实 JSX 渲染）

# 排除注释后，才是真正证明"0 处真实 JSX 渲染"的查法：
$ grep -rn "<PatientRail\|<RecordCanvas" web/app/ --include="*.tsx" | grep -v "//"
（0 命中）

# 对照组（证明 grep 查法能抓到真实 JSX 渲染）：
$ grep -n "<Frame5RecordEntry" web/app/h5/tablet/pane/panes/refractive-record/refractive-record-pane.tsx
839:        <Frame5RecordEntry
857:        <Frame5RecordEntry
875:        <Frame5RecordEntry

🔴 记账：v0.1 此处曾贴出未经实跑的『0 命中』，9-15 自检发现并更正——真实是 1 命中（命中自己的注释），排除注释行后才是 0。

代码自证：patient-rail.tsx:70 注释原文「本文件当前未被 refractive-record-pane.tsx 渲染(仅 import 未 实例化)」。

结论不变：patient-rail.tsx(361行) + record-canvas.tsx(415行) = 776 行不用搬（V4 结论本身没错，错的是原证据命令贴的输出）。

V5 手机端宽度约定 —— ⚠️ 部分纠偏（"360 设计基准"查无实据）

$ grep -rln "max-w-\[420px\]" web/app/h5/ | wc -l
11        # 任意元素口径（不限 md: 前缀）：SeatStoreCard.tsx、rumor-buster/layout.tsx、
          # eye-nav/layout.tsx、ChatDemoReact.tsx、find-similar/page.tsx、family/layout.tsx、
          # field-sheet.tsx、family/[id]/page.tsx、chat/page.tsx、upload-sheet.tsx、
          # seat-wx-auth-landing.tsx（共 16 处命中，含 family/[id]/page.tsx ×2、chat/page.tsx ×2）
$ grep -rln "md:max-w-\[420px\]" web/app/h5/ | wc -l
5         # 页面容器口径（限定 md: 前缀）：eye-nav/layout.tsx、family/layout.tsx、
          # rumor-buster/layout.tsx、find-similar/page.tsx、chat/page.tsx
          # （共 7 处 grep 命中，其中 eye-nav:8 与 family/layout:3 是注释提及，真代码 5 处一一对应上述 5 个文件）
$ grep -rn "430px" web/app/h5/
（0 命中）

"360" 的全部命中都是 SVG viewBox 坐标系 / 弹层 maxWidth: 360，不是页面容器设计基准。

结论：唯一有代码实证的宽度规范是容器 md:max-w-[420px]（5 个文件真代码）。方案与效果图一律按 420px 写，
不得在文档里写"设计基准 360"（无出处）。

V6 后端可否零改动 —— ⚠️ 结论成立但措辞纠偏

$ grep -c "require_store_seat" app/api/refractive_records.py   → 21
$ grep -c "@router\."          app/api/refractive_records.py   → 18

18 个 @router. 端点，每个函数签名都带 seat: dict = Depends(require_store_seat)，
18 对 18、一一对应、无端点漏挂鉴权；多出的 3 次是 docstring / import / 注释。

$ grep -rn "device\|platform\|Source\b" app/api/refractive_records.py app/services/refractive_record_service.py app/schemas/refractive_record.py
（0 命中）
# 对照组：
$ grep -n "device_id" app/auth/middleware.py | head -1
256:            # 镜像 require_org_seat...不同 device_id 并存放行
$ grep -rln "platform\b" app/api | head -3
app/api/store_subseat.py / app/api/admin_parent_seats.py / app/api/voice.py

纠偏：不是"0 处 tablet/平板字样"——app/api/refractive_records.py:1 docstring 写着
「Phase 63 · 平板端视力与屈光检查记录 API」，refractive_record_service.py:1076 有一处注释引用了
mockup 文件名含 tablet。两处都是注释不是逻辑分支，
所以「后端逻辑零改动可直接给手机端复用」成立，但不能说"0 处 tablet 字样"。

端区分靠鉴权层：app/auth/middleware.py:398-409 require_store_seat 显式拒 seat_type=="parent"。

V7 手机端可复用组件真实签名 —— ✅ 证实（并补全）

// web/app/h5/family/components/field-sheet.tsx —— 导出 4 个（不是 2 个）
export function FieldButton({ value, placeholder = "请选择", onClick, ariaLabel })
export function SheetShell({ title, onClose, children })
export function OptionSheet({ title, options, value, onPick, onClose })
export function MultiOptionSheet({ title, options, value, onConfirm, onClose })

// web/app/h5/family/components/date-wheel.tsx —— 还导出 TimeWheel 与主题类型
export interface DateWheelAccent { border: string; bg: string; }
export function DateWheel({ value, onChange, minYear, maxDate, ariaPrefix = "出生", accent = DEFAULT_ACCENT })
export function TimeWheel({ value, onChange })

// web/app/h5/chat/components/upload-sheet.tsx
export type UploadKind = "refraction" | "axial" | "oct" | "fundus";
export function UploadSheet({ open, onOpenChange, kind, onConfirm })

⚠️ date-wheel.tsx:23 注释写着「平板门店端「视光档案」是蓝色主题(#2563eb)」→ 手机端复用时
必须传自己的 accent（绿系），否则会把平板蓝带进手机端。
⚠️ UploadKind 目前只有 4 种，若手机端要传视光档案的其他影像类型需先扩这个 union。

V8 机构开关在手机端是否已下发 —— ❌ 证伪（不是新增工作量）

$ grep -n "fetchSeatOrgFeatures\|applySeatOrgFeatures" web/app/h5/chat/page.tsx
852:      if (getSeatToken() && !urlTempToken) {
853:        const seatState = await fetchSeatOrgFeatures();
3281:              applySeatOrgFeatures(orgFeatures);
3282:              setFeatureFlags(applyParentFeatureGate(getOrgFeatureFlags()));
$ grep -n "enable_refractive_record" web/app/h5/chat/lib/auth.ts
276:  enable_refractive_record?: boolean | null;

结论：手机端 bootstrap 阶段早就在拉机构开关，而且 auth.ts:276 的类型里
Phase 63 当时就把 enable_refractive_record 字段准备好了。
入口门禁直接 getOrgFeatureFlags().enable_refractive_record 即可，零新增。

V9 用户可见文案盘点 —— ✅ 证实 + V11 纠正范围

$ sed -n '456,458p' "web/app/(dashboard)/admin/orgs/page.tsx"
                  <div className="font-semibold text-slate-800 text-sm">视光档案</div>
                  <p className="text-xs text-slate-500 mt-1 leading-relaxed">
                    开启后，本机构席位可在平板端使用视光档案功能；默认关闭

全仓把"视光档案"与"平板端"绑定、且属于用户可见 UI 文案（非注释）的，只有这 1 处。

V11 settlement 两处开关文案 —— ⚠️ 纠正一次范围性假 0

子代理只查了 web/app 就判"文件不存在"。扩范围复查：

$ find web/app -path "*orgs/new*" -o -iname "*switches*" | wc -l
0                                    # ← 代理据此误判"不存在"
$ find settlement/web -path "*orgs/new*" -name "*.tsx" -o -path "*switches*" -name "*.tsx"
settlement/web/app/platform/minicup/orgs/new/page.tsx
settlement/web/app/platform/minicup/orgs/[orgId]/switches/page.tsx
$ grep -rn "enable_refractive_record" settlement/web/app/platform/minicup/orgs/new/page.tsx settlement/web/app/platform/minicup/orgs/\[orgId\]/switches/page.tsx
new/page.tsx:41:      { key: "enable_refractive_record", label: "视光档案", defaultOn: false },
switches/page.tsx:68:      { key: "enable_refractive_record", label: "视光档案", desc: "开放视光档案模块" },
# 对照组（证明查法有效）：
$ grep -rn "enable_myopia_world" settlement/web/app/platform/minicup/orgs/new/page.tsx | head -2
29:  | "enable_myopia_world"
62:      { key: "enable_myopia_world", label: "近视的世界", defaultOn: true },

结论：两个文件真实存在，但它们的文案是 label: "视光档案" / desc: "开放视光档案模块"，
都没提"平板端" → 全仓只有 1 处文案要改，不是 3 处。

V12 真实物理障碍 —— 🔴 新发现（必须先拆）

平板端 lib/api.ts 本体是纯 REST 客户端无 UI，但依赖链里带了平板专属跳转：

$ sed -n '8,9p' web/app/h5/tablet/pane/panes/refractive-record/lib/api.ts
import { authHeaders } from "../../../../../chat/lib/auth";
import { recoverOrRefreshSeatAuth } from "../../../../lib/seat-auth-recovery";
$ grep -n "/h5/tablet" web/app/h5/tablet/lib/seat-auth-recovery.ts
27:    window.location.href = "/h5/tablet?login=seat";
49:    window.location.href = "/h5/tablet?login=seat";
51:    // 门店密码平板(非微信):标记被踢 + 跳纯 /h5/tablet · 门户读 flag 显「已在其他设备登录」+席位登录窗。
59:    window.location.href = "/h5/tablet";

（真跑是 4 行，第 51 行是注释提及不是真实跳转逻辑——跟 V3/V4/V5 排除注释行的处理方式对齐，
真正的条件跳转只有 27/49/59 三处。9-15 第二轮自检核实：v0.1 原贴的这段 grep 输出漏了第 51 行。）

后果：手机端若直接复用 api.ts，401 续期失败时会把手机端用户踢到平板登录页。
这是本次唯一必须动到平板侧代码的地方 —— 需把跳转目标参数化（或给手机端另建一份 recovery）。
⚠️ 参数化会动到平板端在用的文件，属于 D1「平板端不动」的唯一例外，需长官知悉。

V13 双眼排布定案依据 —— ✅ 家长端已有上线解法（⚠️ 9-15 第二轮自检：算式漏了一层容器 padding，已重算，结论有变）

$ sed -n '283,290p' "web/app/h5/family/[id]/exam/new/page.tsx"
    <div className="grid grid-cols-[76px_1fr_1fr] gap-2 items-center mt-2.5">
      <div />
      <div className="text-[11px] font-extrabold text-[#94a3b8] text-center">右眼 OD</div>
      <div className="text-[11px] font-extrabold text-[#94a3b8] text-center">左眼 OS</div>

平板：1fr 108px 108px（眼格宽度写死，窄屏缩不了）
家长端手机：76px 1fr 1fr（标签写死 76，两眼平分剩余宽）

🔴 记账（9-15 第二轮自检更正）：v0.1 原算式只减了 Sect 卡的 p-3.5（14px×2），漏减了外层页面容器的
px-4（16px×2）。真实嵌套链（已 grep+sed 逐层核实）：

$ cat web/app/h5/family/layout.tsx   （节选）
  <div className="relative w-full md:max-w-[420px] min-h-screen shadow-2xl">
$ sed -n '931p' "web/app/h5/family/[id]/exam/new/page.tsx"
      <div className="px-4 pt-2.5 pb-8">

layout.tsx 上的 md:max-w-[420px] 只在 ≥md（768px）断点生效——手机端真实视口（<768px）走的是
w-full，容器宽 = 设备真实视口宽，不是固定 420px；px-4（16px×2=32px）是在这层 w-full 容器
内部又包了一层，v0.1 算式漏掉了它。

重算（容器宽 − px-4×2(32) − Sectp-3.5×2(28) − 标签列76 − gap-2×2(16)）÷ 2：

⚠️ 结论更正：v0.1 写的"两者都比平板的 108px 宽"是错的，已删除。真实情况是窄屏（360px 附近）
下手机端两眼格反而比平板窄——落地时若目标机型含 360px 附近安卓机，需额外确认这个更窄的眼格是否够放
输入框文字/单位。

360px 仍作为数据点保留的理由：V5 已证"360 是页面容器设计基准"这个说法查无实据，但 360px 作为安卓机型
常见的真实屏幕宽度（经验值，与"代码里有没有写死这个断点"是两回事）依然是本功能要适配的下限场景之一，
故本表按"最窄常见机型经验值，非代码断点"的口径保留它，不因 V5 的证伪而删除这个数据点。

"等价复现真渲染实测"列的方法（9-15 二轮自检真实补测，如实说明局限）：本功能 mockup v1 尚未画出，
无法直接打开本功能的效果图去量；因此改为用 exam/new/page.tsx 已上线组件的真实 className 对应的原生
CSS 数值（px-4/p-3.5/grid-cols-[76px_1fr_1fr]/gap-2）搭建等价静态页面，用 headless Chromium
（playwright-core + @sparticuz/chromium，与 ~/render-env 同款依赖）真跑 getBoundingClientRect()
分别在 420/375/360 三个视口宽度下量得上表数字（与算式相差 ≤1.5px，来自边框 border-box 计算误差）。
这不是打开本功能真实 mockup 或线上页面测的数，是对已上线组件类名的等价复现渲染，如实标注方法与局限，
不冒充"已看过本功能真页面"。

⚠️ 定稿前仍需在真正画出来的效果图 / 落地后的真实页面上重新 getBoundingClientRect() 验证一遍
（见第七节验收项2；不预设具体数值，要求报实测值）。

V10 附带纠错 —— ❌ 一条 find 假象

$ find web/app -maxdepth 2 -name "page.tsx" | wc -l   → 5    # 假象
$ find web/app -name "page.tsx" | wc -l               → 91   # 真实
$ find web/app/h5 -name "page.tsx" | wc -l            → 15

maxdepth 2 把 h5/family/[id]/exam/new/page.tsx 这类深层路由全滤掉了。报数必须写清查询范围。

三、现状全貌

3.1 平板端视光档案（要照搬的源头）

web/app/h5/tablet/pane/panes/refractive-record/ · 27 个文件 / 8548 行

实际要搬 = 8548 − 776 = 7772 行

3.2 后端（零改动）

app/api/refractive_records.py prefix /api/h5/refractive-records，18 端点全 require_store_seat：

数据层：refractive_records + refractive_record_eyes + refractive_record_visual_functions 三表。
机构隔离：org_id 由 JWT 服务端推导，不接受客户端传（refractive_records.py:5 文件头声明）。

⚠️ 别搬错文件：app/api/vision_exams.py（router = APIRouter(prefix="/api/vision-exams", tags=["vision_exams"])——
tag 是英文 vision_exams，"视光档案"字样只出现在模块 docstring 第 2 行，不是 tag；无任何鉴权 Depends）
是另一套医生端/飞轮标注功能，与本功能无关。

3.3 手机端（落地目标）

• 路由：web/app/h5/chat（主）+ web/app/h5/family（家长档案）
• 容器：md:max-w-[420px]（页面容器口径，5 个文件真代码；另有 16 处不限 md: 前缀的其他元素级 max-w-[420px]，两个口径不同，详见 V5）
• viewport：width=device-width, maximumScale:1, userScalable:false（禁双指缩放 · 微信 webview）
• 鉴权：与平板同一个文件 web/app/h5/chat/lib/auth.ts（tablet/page.tsx:24 直接 import）
• 色系：绿系（#157c67 / #2fa37c / #eaf7f0 / #9bdcc8 / 边框 #e3eee7 / 必填红 #d1493f）→ D5 拍板本功能跟随此绿系
• ❌ 无统一设计 token 文件；web/tailwind.config.ts 的 shadcn 语义色在这些页面 0 使用，全内联 hex
• ❌ 无底部 tabbar 可用（MobileTabBar.tsx 真实路径是 web/components/mobile/MobileTabBar.tsx，只被 web/app/mobile/layout.tsx import 使用，跟本功能所在的 web/app/h5/* 路由树无关）
• ❌ 无 middleware.ts，无 UA 分流；平板/手机靠业务侧发不同链接

四、适配方案

4.1 路由与入口

新建  web/app/h5/store-refractive/            ← 路由技术 slug 待长官定（功能显示名已定「视光档案」，见 R2）
      ├─ layout.tsx        仿 family/layout.tsx（md:max-w-[420px] 手机框）
      │                    + 仿 chat/layout.tsx（viewport 禁双指缩放）
      ├─ page.tsx          帧1 儿童列表（落地态）
      └─ [patientId]/…     帧3 档案 / 帧4 查看 / 帧5 录入

ls web/app/h5/ 已证不存在 store/refractive/refractive-record 目录（对照组 family 命中，查法有效）→ 命名空间可用。

入口插入点：web/app/h5/chat/page.tsx 非家长分支 2998-3129 内，新增
{featureFlags.enable_refractive_record && (<button …>视光档案</button>)}，样式仿同排既有 chip。

排位：长官 9-15 已拍板 —— 排第一位（9-15 更正：原方案给的两个候选插入点"报告秒读组后"/
"量身定案后"均已作废，两者都不是"第一位"，需重写为插到 2998-3129 分支最前面，即现有
"报告秒读" chip 之前）。这意味着现有 7 个 chip 依次后移一位，原排第一的"报告秒读"chip 让位到第二位，
需在实施时一并调整。

依据（本仓已有同类先例支持"核心功能排第一位"这个判断，9-15 grep 核实引用）：
chat/page.tsx:3000-3001 注释原文——
「Phase 66.12(长官 2026-08-01)· 报告秒读排最前 —— chip 条横向溢出(实测内容 835px / 视口 375px)，
排第 3 位时只露 28px，4L 报告解读是核心功能不能藏在横滑里。历史解读紧随其后。」
视光档案同样是不能被横滑藏起来的核心功能，故沿用同一条判断逻辑排到最前。

4.2 令牌口径（🔴 禁止自造色值 · D5 拍板走绿系）

决策经过（如实记录，便于日后复盘）：同一天（9-15）经历两次拍板——长官第一次拍板蓝系
（理由：跟平板端同功能视觉统一），随后长官自己推翻第一次拍板、把色系选择权交回本方案，
最终改定为绿系（D5，见第一节）。以下 4.2 全部令牌与配色都按最终定案的绿系写，不含中途蓝系方案。
决定性理由：门店手机端之所以要做，是因为有些门店没有平板；对这批目标用户
不存在一个需要对齐的平板端，他们的全部体验就是绿色的手机应用（从 chat 页绿色 chip 条进入）。
「两端切换不错位」服务的是本功能目标人群里基本不存在的用户。
另：本仓库为「拿平板/PC 色画手机端」已付过学费（见 ~/.claude/rules/prototype-mockup-standards.md §1.2）。

全部取值扒自 web/app/h5/family/[id]/exam/new/page.tsx（已上线的手机端长表单），一个色都不许自造：

🔴 严禁把平板端蓝系带进手机端（平板蓝 = #2563eb / #173a54 / #43617a / #eef4f9）。
🔴 复用 DateWheel 时必须显式传绿系 accent —— date-wheel.tsx:23 注释写着
「平板门店端『视光档案』是蓝色主题」，不传就会继承平板蓝。

⚠️ 绿系的已知代价与补法（尚未落进 mockup v1，留给 v2）

绿色在本功能里同时是语义色，底色变绿会让这几处信号变钝：

mockup v1 用的仍是「全绿」口径，上述补法未实施。 看图时这三处的信号强弱请按「待优化」看待。

4.3 逐帧改造清单

4.4 复用 vs 改写（lib 层）

跨端 import 合法性：exam/new/page.tsx:26-28 注释原文称 va-map.ts 是
「门店端唯一事实源（严禁改动该文件/严禁复制新表）」→ import 纯逻辑文件是本仓既定模式。
而 menu-sidebar.tsx:4 的红线「平板独立组件 · 不碰移动端」只针对平板专属 UI 组件，两者不冲突。
另：render-bold.tsx:9-11 注释已记载「理想位置是 web/app/h5/lib/，但该目录不存在，本次不新建顶层共享目录」
→ 本方案沿用同一做法，不新建共享目录（除非长官另有指示）。

4.5 文案改动（全仓仅 1 处）

web/app/(dashboard)/admin/orgs/page.tsx:458

- 开启后，本机构席位可在平板端使用视光档案功能；默认关闭
+ 开启后，本机构席位可在平板端和手机端使用视光档案功能；默认关闭

settlement 两处（orgs/new/page.tsx:41、orgs/[orgId]/switches/page.tsx:68）文案未提"平板端"，不用改（V11 已证）。

五、工作量与分批

D2 拍板全量对等。按防丢失策略拆批，每批可独立 commit。

批0-6 预估合计 6100 行，与 §3.1「实际要搬 7772 行」不是同一口径，差额 1672 行的来源：

• 已量化的一块（198 行）：§4.4 已证 lib 层 600 行里，除 api.ts（402 行，本次只改跳转参数化，不整体重写）外，
  另外 6 个文件共 198 行是零改写、直接 import 复用（gate.ts11 + age.ts24 + va-map.ts45 + vision-format.ts42 +
  clinical-data.ts54 + render-bold.tsx22），批次估算里不计入"新写/改造"工作量。
• 未单独量化的一块（剩余约 1474 行）：批次预估是"预估最终改造/新写代码量"的经验值，不是对 7772 行源文件做逐行迁移对账——
  手机端专属新增结构（返回 pill、底部 Sheet 容器、420px 信息架构重排等）在平板端源文件里本就不存在，无法从行数里扣出来对应，
  这部分差额本质是"新写"而非"改造"，经验估算法天然给不出精确来源行区间。
  两个数字统计口径本身不同，不做强行相减对账，此处仅如实说明差额构成。

🔴 记账（9-15 第二轮自检更正，详见 §八 #14）：此前版本在这里还写过一句"另一方面 §4.3 末行'左菜单
240/60px'混在 refractive-record-pane.tsx 整体 1037 行里，没有可单独 grep 出的行区间"——
这句话本身没有 grep 验证过。真跑 grep -n "240\|60px\|menu\|sidebar\|Menu\|Sidebar" refractive-record-pane.tsx
是 0 命中（该文件确认 1037 行，通篇不含 240/60px 或菜单字样）。240/60px 真实出处是
web/app/h5/tablet/pane/panes/menu-sidebar.tsx:85（width: collapsed ? 60 : 240）——这是平板
通用 pane 壳组件 TabletMenuSidebar，被 pane/page.tsx 引入，与 refractive-record-pane.tsx
是平级的两个不同文件，根本不在本方案 27 文件/8548 行的统计范围内，因此它与这条行数差额无关。
已删掉这句假解释。

六、风险与待确认

七、验收标准（无证据 = 没做）

1. 新建的手机端目录下 grep -rn "1fr 108px 108px" <新建目录> --include="*.tsx" | grep -v "//" | wc -l = 0；
   对照组（真跑过，见 §八）：grep -n "1fr 108px 108px" web/app/h5/tablet/pane/panes/refractive-record/frame5-record-entry.tsx | grep -v "//" | wc -l = 10。
   排除说明：① 过滤掉 // 注释行——frame5-record-entry.tsx:116 是注释提及不是真实样式，裸 grep -c 会把它计进去变成 11；
   ② 对照组不含 record-canvas.tsx（该文件另有 5 处同串命中）——V4 已证 record-canvas.tsx 是 dead code（0 处真实 JSX 渲染），不在迁移范围内，混进对照组会失真。
2. 真渲染跑 getBoundingClientRect，报出 OD/OS 三列实测宽度（不预设具体数值——V13 的 134/111.5/104px
   是"等价复现渲染"的推算值，不是本功能真页面的实测值，拿它当验收基准会在真机量出别的数字时被误判成
   "实现有问题"），并与平板写死的 108px 做对比说明（尤其关注窄屏是否比 108px 窄，见 V13）
3. 溢出自查：判据 document.documentElement.scrollWidth > window.innerWidth（🔴 不得用"子元素 vs 父元素"
   口径——父元素被撑大时该判据会漏报，出处 docs/superpowers/plans/specs/ui-design-spec-dev2-20260824.md:264-265），
   命中数 = 0，报出手机帧宽度集合
4. 色值自查：新建目录 grep -o "#[0-9a-fA-F]\{3,6\}" | sort -u 必须是 §4.2 全部令牌值（含绿系基底 + 必填红 #d1493f / 橙提示 #fde7c7,#fff8ed,#9a4a00 / 黄 4L #c99a2e,#fff3d9 / 紫 4L #7c6bb5 等语义色）的子集；
   平板蓝 #2563eb / #173a54 / #43617a / #eef4f9 命中数 = 0；对照组 #2fa37c 命中 > 0
5. 18 个后端端点在手机端真打通（去 test 环境，非云机）
6. 入口双门：flag 关 / 无 seat token / 家长坐席 三种情况下入口均不显示
7. DOM 闭合标签差值与改动前一致
8. 平板端零回归：git diff --stat 对 web/app/h5/tablet/** 的改动只允许 seat-auth-recovery.ts 一处

附：本次调研的查证边界（如实声明）

• 全部结论基于 worktree feature/store-mobile-refractive-archive（基线 origin/test @ 63972df0）的物理代码
• 后端 18 端点的鉴权覆盖是读代码计数得出，未在本机真打接口（云机不跑全量 e2e）
• V13 的 134/111.5/104px（420/375/360）是算术推演 + 已上线组件类名等价复现渲染，
  不是本功能真 mockup/页面的实测值——本功能 mockup v1 尚未画出，无法直接量；定稿前必须在
  真正画出来的效果图/落地页面上重新真渲染量一遍
• 平板端真机截图另行取证，若取证失败会如实标注，绝不以代码推演冒充"已看过真页面"

八、v0.1 自检发现并修订的问题（9-15）

本节是防再犯的记账钩子。v0.1 交付时 13 处问题全部经本机 grep/wc/sed 真跑核实后修订，逐条如实列出，不美化、不省略。

九、新增需求 · 门店结论已读回执（9-15 长官提）

9.1 需求与背景

长官原话：「门店推给家长的结论，现在推完像掉进黑洞。加个『已读/未读』，没读的店员去跟进。平板和手机端都要加。」

调研发现的关键事实（决策依据，9-15 grep 核实）：

POST /api/h5/refractive-records/records/{id}/conclusion/push 对应的服务层函数
push_conclusion（app/services/refractive_record_service.py:2699-2715）实际只做两件事——
把 store_conclusion_text 快照成 store_conclusion_pushed_text、写 store_conclusion_pushed_at，
不调用任何通知渠道（微信模板消息 / 公众号 / 站内信全无）：

$ grep -n "def push_conclusion" app/services/refractive_record_service.py
2699:async def push_conclusion(db: AsyncSession, org_id: int, record_id: UUID) -> dict[str, Any]:
$ grep -n "wechat\|notify\|模板消息" app/services/refractive_record_service.py
（0 命中）
# 对照组（证明查法有效——同一文件里确实能查到东西）：
$ grep -n "pushed_at" app/services/refractive_record_service.py | wc -l
3

含义：家长完全是"主动进来才看得到"，已读回执上线后大概率满屏未读——这是真实现状，如实写明，不粉饰。

仓库现状：全仓 0 个已读回执先例：

$ grep -rn "read_at\|is_read\|viewed_at" app/ web/ | wc -l
16
$ grep -rn "read_at\|is_read\|viewed_at" app/ web/ | grep -v "reviewed_at" | wc -l
0
# 对照组（证明这 16 处命中确实全部来自 reviewed_at 子串，不是查法漏了别的字段）：
$ grep -rn "reviewed_at" app/ web/ | wc -l
16          # 与上面 16 完全相等 → 16 处命中全部是 reviewed_at，没有第二种已读字段

唯一沾边的 web/app/h5/components/voice-bar.tsx 未读红点
（:62 {!played && <span className="wx-voice__unread" aria-label="未读语音" />}）
是纯前端 useState 变量 played（:23），刷新即丢，不落库、不跨会话持久，不是已读回执的先例。

9.2 🔴 这条需求改变了本期性质

原方案 §〇 写着「这活是纯前端，后端零改动」——加了已读回执之后不成立了。
§〇 已补更正说明（见文档开头），本期起本方案包含后端改动，范围见下。

9.3 技术方案（只写方案，不写代码）

• 字段：RefractiveRecord 新增 store_conclusion_read_at，类型 TIMESTAMP(timezone=True)、nullable=True，
  语义「NULL = 未读」。理由：跟现有批5三个字段同款风格 ——
  app/models/refractive_record.py:166-174 现有 store_conclusion_text（:166-168）、
  store_conclusion_pushed_text（:169-171）、store_conclusion_pushed_at（:172-174）
  全部走"有时间戳=发生过"的语义，不加 is_read 布尔列（多一列冗余、破坏风格一致）。

• 迁移：down_revision 挂在当前 refractive_records 所在分支的尾节点上。

$ alembic heads 34ec94466f0c (head) demo_profile_data_fix1 (head) phase79_001 (head)

⚠️ 仓库当前是三头分叉状态。已顺着 down_revision 链条逐个 grep/sed 核实（不是猜测）：

batch5_ai_conclusion（新增 store_conclusion_* 三列的那次迁移，down_revision="seat_remark_name"）
→ org_hero_image（down_revision="batch5_ai_conclusion"，其自身注释明确记载
「当前 test 队尾实为两个未合并的 head：34ec94466f0c…与 batch5_ai_conclusion…
batch5_ai_conclusion 在 main 上存在，34ec94466f0c 不在 main 上（尚未晋级）」）
→ org_hero_image_toggle（down_revision="org_hero_image"）
→ patient_is_sample_flag（down_revision="org_hero_image_toggle"）
→ demo_profile_seed_data（down_revision="patient_is_sample_flag"）
→ demo_profile_data_fix1（down_revision="demo_profile_seed_data"，head）

即三个 head 里，demo_profile_data_fix1 是唯一挂在"含 store_conclusion_* 列这条分支"尾端的 head；
另两个 head 都不是同一条线——34ec94466f0c 是 org_hero_image.py 注释里明确记载的"未晋级 main 的孤头"；
phase79_001 的 down_revision="phase63_001" 走的是 refractive_records 表更早创建时的另一条平行分支
（phase63_001_refractive_record.py，建表迁移本身，不含批5字段）。
新迁移应挂 down_revision = "demo_profile_data_fix1"。

• 打点端点：新增 POST /api/parent/patients/{patient_id}/records/{record_id}/conclusion/mark-read
  （app/api/parent_patients.py 路由前缀 :57 router = APIRouter(prefix="/api/parent/patients")；
  与同文件里已有的同风格端点对齐——:913 @router.post("/{patient_id}/records", status_code=201)、
  :1212 @router.post("/{patient_id}/records/from-report")），
  鉴权 Depends(_require_parent)。

⚠️ _require_parent 全仓有两处同名定义（app/api/parent_patients.py:65 与
app/api/parent_ocr.py:54，各自文件内独立定义、不是同一个函数、不共享）。
新端点放进 parent_patients.py，必须用该文件自己的 :65 版本（与同文件里其它家长端点保持依赖一致，
不跨文件 import 另一份）。

幂等写法 UPDATE ... SET store_conclusion_read_at = now() WHERE store_conclusion_read_at IS NULL
（只记第一次已读时间，后续重复调用不覆盖）

• 🔴 明确禁止：不许在家长端 GET 详情接口里"顺手"写库标记已读。
  该接口是 my_child_record_detail（GET /{patient_id}/records/{record_id}，定义于
  app/api/parent_patients.py:607-608），家长端 store_conclusion 字典正是它在 :742-753 拼出来、
  在 :809 塞进响应体的。理由：GET 不应有副作用（缓存/预取/重试会误标）、并发会冲掉首次已读时间、
  且该函数被多处复用职责会变复杂。仓库里也没有"GET 顺手写库"的先例：

$ sed -n '608,889p' app/api/parent_patients.py | grep -n "db.commit" （0 命中——已验证：my_child_record_detail 当前确实是纯读、函数体内无任何 db.commit， 加已读回执时不应打破这个特性）

• 出参：门店端与家长端两处都要加，漏一处就是两端不同步：
• 门店端 _record_dto（app/services/refractive_record_service.py:871-905）——现有字典末三个键就是
  store_conclusion_text/store_conclusion_pushed_text/store_conclusion_pushed_at（:903-905），
  照此风格追加 store_conclusion_read_at

• 家长端 store_conclusion 字典（app/api/parent_patients.py:750-753 字典字面量，:809 塞进响应体）
  加 read_at

• 两端展示：

• 平板端：frame4-record-view.tsx:1446-1448 现有「已推送 · 时间」那行
  （{record.store_conclusion_pushed_at ? (... 已推送 · {...} ...) : ...}）之后追加
  「· 家长未读」/「· 已读于 x」
• 手机端：本方案新建的手机端记录查看页（对应平板"帧4"，见 §4.3 表格 · 属于批4）对应位置同款展示——
  该页面在本 worktree 尚未创建物理文件，具体行号待实施时确认，此处不编造
• 家长端：不需要给家长看"已读"标记（他自己看过自然知道），只有门店需要

9.4 要动的文件清单表

9.5 分批建议

已在 §五 工作量与分批表补一行「批8：已读回执（D9 新增需求·字段+迁移+端点+两端 DTO 出参+两端 UI 展示，详见 §九）｜~150」。

依赖关系：字段/迁移/新端点/两端 DTO 出参/平板端 frame4 展示可独立先行，不阻塞其他批次；
手机端记录查看页的已读展示依赖批4（该页面本身要先存在）。