报告：硬编码根因 · A 端可配置化 · 全局间距令牌

编制：小齐　日期：2026-09-23　状态：已验部分均附可复跑命令；方案部分待刘总拍板

触发：刘总三问——①为什么有硬编码？所有内容要求 A 端可配置 ②写出报告 ③走全局令牌

0. 结论先行

⚠️ 自纠：本报告初稿把"A 端可配置"列进了「待刘总拍板」，并询问"真实数据由谁提供"——这是把铁律降级成了选项，理解错误。已按铁律改写：它不是待办项，是执行前提；需要刘总决定的只剩"派谁做后端接口"，不是"要不要做"。

1. 为什么会有硬编码（根因链，四层）

第一层：工程来历——静态原型整包入仓

git log -S '¥80–160' --oneline -- miniprogram-v2/pages/selection/selection.wxml
git log -S '08978888216' --oneline -- miniprogram-v2/pages/local/local.wxml
git log -S '¥680–980'  --oneline -- miniprogram-v2/pages/local/local.wxml

三条全部指向同一个提交：8d7dc69e（2026-09-14，署名冈子）——「首入仓快照：新版 C 端工程完整入库，pages×92 + components/services/styles/utils，2.9M/406 文件」。

也就是说：这些金额、电话、文案从进仓库的第一天起就写死在页面模板里，不是某次改动引入的缺陷。v2 工程当时是把可运行的前端原型整包搬进来，原型里的数据就是写死的。

第二层：页面至今没有数据层（这是关键）

for p in selection local profile home; do
  printf "%-10s 接口请求命中=%s\n" $p \
    $(grep -acE "request\(|/api/|wx\.request" pages/$p/$p.ts); done

实测结果：

玩法页和我的页从未接过后端的任何数据。所以即便 A 端配置了内容，这两个页面也读不到——它们压根不发请求。

第三层：A 端能力已经存在，但 C 端没接

• A 端页面：admin-console/src/pages/ContentAssets.tsx（894 行，波波 2026-09-23 02:27 推送，提交 ef893f49）
• A 端接口：/api/miniapp/admin/content/*，覆盖 POI / 路线 / 攻略知识 / 规则 四类
• 后端实现：backend/app/routers/admin_content.py
• 波波在文件头的原话：「接口实测可用」；但也注明「攻略知识接口当前实测返回空数组，字段尚未确定」

C 端现有的读取口只有两个（backend/app/routers/feed_demand.py）：

• /api/miniapp/content/private
• /api/miniapp/content/guide

即：A 端能配 POI/路线/攻略/规则，但 C 端没有通用的"读取已配置内容"接口，前端页面也没消费它。 配置与展示之间是断的。

第四层：没有"内容必须可配"的纪律约束

此前的验收口径查的是：视觉规范、路由白名单、文案键覆盖、数据真假（禁 mock）。从来没有人查过"这个数字是不是写在代码里的"。所以硬编码一直合规地活着。

2. 全站硬编码清单（实测）

2.1 金额（47 处，9 个文件）

grep -raoE "¥[0-9]+" --include="*.wxml" --include="*.ts" . | wc -l

2.2 🔴 mock 数据仍在首页（违反禁 mock 红线）

pages/home/home.ts 第 25、27 行：

{ slug: 'mock-pkg-1', ..., priceText: '¥3680 起/人', ... }
{ slug: 'mock-pkg-2', ..., priceText: '¥1980 起/人', ... }

变量直白命名为 mock-pkg-*。上一轮整改我删掉了首页的推荐区块 UI，但数据和请求逻辑仍在（孤儿代码）。这属于我自己留下的尾巴，本次一并报出。

2.3 电话（4 处）

grep -raoE "tel:[0-9]+" --include="*.wxml" .

3. A 端可配置：方案

3.1 目标口径

页面里出现的任何"会变的业务内容"——金额、联系方式、营业时间、服务项目、推荐语、状态文案——都必须能在 A 端改，改完即时生效，不需要改代码、不需要重新提审。

不变的部分（页面结构、图标、交互逻辑）继续写在代码里。

3.2 现有能力盘点（可直接复用，不必从零建）

3.3 建议的内容模型（增量最小）

在现有 admin_content 上扩一个通用内容项表 content_item：

前端规则：

• 取到值 → 显示，并带上「来源 + 更新时间」
• 取不到 / 过期 → 显示中性占位「—」或隐藏该字段，绝不显示写死的兜底数字（这条直接对应禁假数据红线）
• phone 类型必须 status=active 才渲染为可拨打，否则显示为不可点的文本

3.4 落地顺序（建议）

1. 先定字段：金额、电话、营业时间三个类型先上（覆盖已发现的 47+2 处）
2. 补 C 端读取接口：GET /api/miniapp/content/items?keys=...（批量取，减少弱网请求次数——高原场景重要）
3. 前端改造：selection → local → 其余 7 个含金额的文件
4. A 端录入数据：由运营在 A 端自行录入与更新，不由研发在代码里填，也不需要刘总提供数据
5. 清 mock：删 home.ts 的 mock-pkg-*

前端不等待数据：取不到配置值就显示中性占位「—」或隐藏该字段。页面短期出现占位是正确表现而不是缺陷——真实数据由运营在 A 端补齐即可，不需要改代码、不需要重新提审。这正是"A 端可配置"要达到的效果。

4. 全局间距令牌：方案

4.1 现状（实测，不是猜测）

app.wxss:29 已定义：

--space-1: 8rpx; --space-2: 16rpx; --space-3: 24rpx;
--space-4: 32rpx; --space-5: 40rpx; --space-6: 48rpx;

只有 6 档。 而四页实际使用的间距值：

所以根因不是"页面乱写"，是"令牌只有 6 档、不够用"——4rpx、6rpx、12rpx、20rpx 这些小档位根本没有令牌，页面只能硬写数字。

4.2 方案（三步）

第一步 · 补齐档位（在 app.wxss 扩充，不动 vi-tokens 的色彩体系）：

--space-0:  4rpx;   /* 极紧凑：标签内距、图标间隙 */
--space-1:  8rpx;
--space-2: 12rpx;
--space-3: 16rpx;
--space-4: 20rpx;
--space-5: 24rpx;
--space-6: 32rpx;
--space-7: 40rpx;
--space-8: 48rpx;
--space-9: 56rpx;

另设两个语义令牌承接超大值（不要散在页面里）：

--space-hero:  100rpx;   /* 首屏大留白 */
--space-shell: 200rpx;   /* 页面级容器 */

第二步 · 强制消费：四页 wxss 中 margin/padding 数值全部替换为 var(--space-*)；100/200 这类归入语义令牌。

第三步 · 加校验闸门（防止回潮）：新增脚本，扫出所有"写了具体 rpx 数字却没走令牌"的 margin/padding，越界即报错退出。

可复跑判据（改造完成后应全部成立）：

# 期望：四页越界值均为 0
python3 - <<'PY'
import re
tok={4,8,12,16,20,24,32,40,48,56,100,200}
for p in ['home','selection','local','profile']:
    w=open(f'miniprogram-v2/pages/{p}/{p}.wxss',encoding='utf-8').read()
    out=sorted({int(v) for v in re.findall(r'(?:margin|padding)(?:-[a-z]+)?:\s*(?:var\(--[^)]*\)|([0-9]+)rpx)',w) if v})
    print(p,"越界:",[v for v in out if v not in tok])
PY

注：该判据脚本当前尚未落地，属方案；落地后需随闸门一起入库。

5. 三批落地（结合 gpt6 四页评审）

gpt6 明确建议不动的：首页的荒野感视觉、在地页的信任感表达、我的页的工具型布局——页面风格可以不统一，但字号、触控尺寸、色彩语义、间距令牌必须统一。

6. 六大盲区（gpt6 提出，涉后端与权限，超出前端域）

1. 弱网与离线：已加载的安全说明、紧急联系人、行前清单应可离线查看并标注数据时间
2. 低温 / 戴手套 / 身体不适：减少输入、避免小目标操作；身体自查结果应能引导"休息 / 补给 / 求助"，但不得替代医疗判断
3. SOS 误触与误用：需确认、取消、连点防护、无网提示；真正紧急时不能只依赖单一网络接口
4. 电量与权限：定位关闭、电话不可用时的替代路径
5. 隐私生命周期：轨迹、旅客档案、紧急联系人、我的客人——谁可见、存多久、怎么删（材料未涉及现有机制）
6. 示例图信任：换实拍时不得让用户误判为实时路况；图片与服务状态必须分离

7. 待刘总拍板（3 项）

注：原第 2 项「A 端录入真实价格」已删除——按铁律，数据由运营在 A 端录入，不属待办。

不依赖任何人、我可立即开工的：清 home.ts 的 mock → 全局间距令牌改造 → 三页硬编码改走配置占位（接口未到位前先渲染空态）。

8. 本次已验 / 未验声明

已验（均有可复跑命令，见正文）：

• 硬编码引入提交 = 8d7dc69e；全站金额 47 处分布；电话 4 处；home.ts 存在 mock-pkg-*
• selection/profile 接口请求数 = 0；local = 1；home = 5
• A 端 ContentAssets.tsx + /api/miniapp/admin/content/* 存在；C 端通用内容读取口缺失
• 间距令牌 = 6 档；四页越界值 11/14/16/16 个

未验（属方案，尚未落地）：

• 内容项表 content_item 的字段设计（未与后端确认）
• C 端批量读取接口 content/items 的可行性（未与后端确认）
• 间距令牌扩充后的实际渲染效果（未出预览稿）
• gpt6 提出的六大盲区现状（材料未涉及，未做实地核查）