Supabase Backend

Supabase Backend — SPA 数据层最佳实践

定位

Supabase 是零运维 PostgreSQL 后端，适合作为纯前端 SPA 的数据层——替代 localStorage、OSS JSON、自建代理等方案。

触发条件

• 需要 SPA 多人共享数据
• localStorage/OSS JSON 方案无法满足
• 用户提到 Supabase / PostgreSQL 后端
• 需要免费数据库后端的任何 Web 项目

凭据体系（必读）

Supabase 有 四层凭据，初学者最容易混淆：

关键误区

• Publishable key ≠ Service key：前者只能做 RLS 允许的操作，后者有管理员权限
• PAT 不能替代 Service key：PAT 用于管理项目，Service key 用于操作数据
• PAT 有 scope 限制：创建时选择 read/write/admin 范围，可能无法执行某些操作
• sb_secret_... 不是 DB password：它是 REST API key，不能用于 psycopg2 连接

项目发现

如果用户已有 Supabase 项目，按优先级查找凭据：

# 1. 显式 .env 文件（Linux/Mac）
cat ~/workspace/.env.supabase

# Windows 主机实际路径（实测，本会话验证可用）
cat /c/Users/<user>/.ClawShell/.env.supabase   # 主凭据库：URL/Key/PAT/DB_PASSWORD/Pooler 全套
cat /c/Users/<user>/workspace/.env.supabase    # 备用副本

# 2. Supabase CLI 配置
cat ~/workspace/supabase/config.toml | grep project_id

# 3. 临时文件（项目引用）
cat ~/workspace/supabase/.temp/project-ref
cat ~/workspace/supabase/.temp/pooler-url

# 4. 自定义客户端文件
grep -r "supabase.co" ~/workspace/

# 5. 用 PAT + CLI 列出项目
SUPABASE_ACCESS_TOKEN=*** supabase projects list

建表：两条路径

多应用共享一个 Supabase 项目时，表名必须加应用前缀（如 pm_users、quiz_questions），避免与已有应用的表冲突或语义混淆。前缀即命名空间，前端 REST 路径同步带前缀，RLS 策略名也加前缀。

凭据冲突处理：用户口头提供的 DB password 可能与凭据文件不一致（用户记错）。两个都试一次，以能连通 Pooler 的为准——实测凭据文件中的密码优先级高于用户记忆。找到正确密码后不要追问，继续执行。

路径 A：直连 PostgreSQL（推荐）

适用：有 DB password，可以做任何 DDL。

import psycopg2

conn = psycopg2.connect(
    host="aws-0-us-west-2.pooler.supabase.com",
    port=6543,
    user="postgres.{project_ref}",
    password="{db_password}",
    dbname="postgres",
    connect_timeout=10
)
cur = conn.cursor()

# 建表
cur.execute("""CREATE TABLE IF NOT EXISTS workshops (
  id TEXT PRIMARY KEY,
  round_number INTEGER NOT NULL,
  date TEXT NOT NULL
)""")

# 必须做的三件事：
# ① 开启 RLS
cur.execute("ALTER TABLE workshops ENABLE ROW LEVEL SECURITY")
# ② 创建策略（公开读写）
cur.execute("CREATE POLICY all_workshops ON workshops FOR ALL USING (true) WITH CHECK (true)")
# ③ 授权 schema
cur.execute("GRANT USAGE ON SCHEMA public TO anon, authenticated, service_role")
cur.execute("GRANT ALL ON workshops TO anon, authenticated, service_role")
conn.commit()

路径 B：Management API（需 PAT）

适用：没有 DB password，有 PAT。

# ⚠️ 部分 PAT 可能被 scope 限制，返回 403 error 1010
url = f"https://api.supabase.com/v1/projects/{ref}/query"
req = urllib.request.Request(url, data=json.dumps({"query": sql}).encode(), method='POST')
req.add_header('Authorization', f'Bearer {pat}')

注意：PAT 在 CLI 中可能正常工作（supabase projects list），但 Management API 返回 403。这是 scope 问题，不是 token 格式问题。

RLS 策略模板

-- 公开读写（社区工具、内部应用）
CREATE POLICY "all_access" ON workshops FOR ALL USING (true) WITH CHECK (true);

-- 仅认证用户
CREATE POLICY "auth_access" ON workshops FOR ALL 
  USING (auth.role() = 'authenticated') 
  WITH CHECK (auth.role() = 'authenticated');

-- 仅拥有者（配合 auth.uid()）
CREATE POLICY "owner_access" ON topics FOR ALL 
  USING (auth.uid() = user_id) 
  WITH CHECK (auth.uid() = user_id);

-- 公开读 + 认证写
CREATE POLICY "public_read" ON topics FOR SELECT USING (true);
CREATE POLICY "auth_insert" ON topics FOR INSERT WITH CHECK (auth.role() = 'authenticated');

容易漏掉的：

• GRANT USAGE ON SCHEMA public TO anon, authenticated — 漏掉 → 401
• GRANT ALL ON {table} TO anon, authenticated — 漏掉 → 403
• 外键 REFERENCES ... ON DELETE CASCADE — 删父记录时自动清理子记录

种子用户创建（phone+password 模式）

当 Auth 方案是「手机号+密码」且不需要 SMS 验证码时，用直接 SQL 创建用户最快：

import psycopg2, uuid, json

conn = psycopg2.connect(host=HOST, port=PORT, user=USER, password=PW, dbname='postgres')
cur = conn.cursor()

users = [
    ("张三", "13800000001", "supervisor", "dept_green"),
    ("李四", "13900000001", "worker", "dept_green"),
]

for name, phone, role, dept in users:
    uid = str(uuid.uuid4())
    email = f"{phone}@wf.internal"  # ← phone 转 email 的关键
    meta = json.dumps({"name": name, "role": role})
    dept_v = f"'{dept}'" if dept else 'NULL'

    # ① 写入 auth.users（pgcrypto 加密密码）
    cur.execute("""
        INSERT INTO auth.users (id, instance_id, email, phone, encrypted_password,
            email_confirmed_at, phone_confirmed_at, raw_app_meta_data, raw_user_meta_data,
            created_at, updated_at, aud, role)
        VALUES (%s, '00000000-0000-0000-0000-000000000000', %s, %s,
            crypt('88888888', gen_salt('bf', 6)), now(), now(),
            '{"provider":"phone","providers":["phone"]}', %s,
            now(), now(), 'authenticated', 'authenticated')
        ON CONFLICT DO NOTHING
    """, (uid, email, phone, meta))

    # ② 写入 app_users（业务用户表）
    cur.execute(f"""
        INSERT INTO app_users (id, name, phone, role, department_id)
        VALUES ('{uid}', '{name}', '{phone}', '{role}', {dept_v})
        ON CONFLICT (id) DO NOTHING
    """)

conn.commit()

前端登录（用户无感知 email 转换）：

// AuthContext.jsx
async function login(phone, password) {
  const email = `${phone}@wf.internal`
  const { data, error } = await supabase.auth.signInWithPassword({ email, password })
  if (error) throw error
  // 加载 app_users profile
  const { data: profile } = await supabase.from('app_users')
    .select('*, departments:department_id(name)')
    .eq('id', data.user.id).single()
  return { ...data, profile }
}

要点：

• {phone}@wf.internal 的后缀任意，只要不冲突真实邮箱
• encrypted_password 必须用 crypt() + gen_salt('bf', 6) —— 实测 gen_salt('bf', 10) 的成本过高，Supabase Auth 验证时会报 Invalid login credentials。bf,6 兼容所有版本。bf,10 仅在使用 Admin API 创建的用户上可用
• ON CONFLICT DO NOTHING 防止 Admin API 和 SQL 双重创建时的重复键冲突
• 若 pgcrypto 扩展未安装：CREATE EXTENSION IF NOT EXISTS pgcrypto

轻量级应用层认证（无 Supabase Auth）

内部工具/小团队应用不必走 auth.users。直接在业务表存用户名+哈希密码，前端校验——省掉 Auth 配置、email 伪装、RLS 角色判断的整套复杂度。适用：项目管理、看板等低敏感度内部协作工具（实测于 pm_ 前缀项目管理系统，4 用户场景）。

建表 + 哈希函数：

CREATE TABLE app_users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  display_name TEXT NOT NULL,
  role TEXT DEFAULT 'member'
);

CREATE OR REPLACE FUNCTION app_hash_password(pw TEXT)
RETURNS TEXT AS $$
BEGIN
  RETURN encode(digest(pw || 'app_salt_constant', 'sha256'), 'hex');
END;
$$ LANGUAGE plpgsql IMMUTABLE;

-- 种子用户
INSERT INTO app_users (username, password_hash, display_name)
VALUES ('admin', app_hash_password('admin123'), '管理员');

前端登录（Web Crypto API 复算哈希，与 DB 比对，零 SDK 依赖）：

const rows = await fetch(API + '/app_users?username=eq.' + encodeURIComponent(username),
  { headers: { apikey: SB_KEY } }).then(r => r.json());
const buf = await crypto.subtle.digest('SHA-256',
  new TextEncoder().encode(password + 'app_salt_constant'));
const hex = [...new Uint8Array(buf)].map(b => b.toString(16).padStart(2, '0')).join('');
if (rows.length && hex === rows[0].password_hash) {
  // 登录成功：profile 存 localStorage，前端路由守卫控制权限
}

注意：① anon key 下 password_hash 列可被读——内部低敏感工具可接受，敏感系统仍需 Supabase Auth；② 权限控制在应用层做（role 字段 + 前端守卫），RLS 用 USING (true) 即可；③ salt 常量在 SQL 函数和前端 JS 中必须完全一致；④ 密码 hash 验证可离线比对——先 crypto.subtle.digest 复算再与查询结果比对，无需调 Auth API。

前端集成

标准初始化

<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2/dist/umd/supabase.min.js"></script>
<script>
// ⚠️ 必须等待 SDK 加载：CDN 脚本可能比 inline script 慢
(function waitForSupabase(){
  if(!window.supabase){setTimeout(waitForSupabase,100);return}
  
  const sb = window.supabase.createClient(
    'https://{project_ref}.supabase.co',
    'sb_publishable_...'  // ← 用 publishable key，不是 secret key
  );
  
  // 查询
  const {data, error} = await sb.from('workshops').select('*').order('date', {ascending: false});
  
  // 插入
  await sb.from('workshops').insert({id: uid(), round_number: 1, date: '2026-08-01'});
  
  // 更新
  await sb.from('workshops').update({date: '2026-09-01'}).eq('id', workshopId);
  
  // 删除
  await sb.from('workshops').delete().eq('id', workshopId);
})();
</script>

前端陷阱

多用户投票模式

// 每个浏览器唯一 ID
let voterId = localStorage.getItem('voter_id');
if(!voterId) { voterId = 'v_' + Math.random().toString(36).slice(2,10); localStorage.setItem('voter_id', voterId); }

// 投票 toggle：检查 voterId 避免重复
const existing = votes.find(v => v.topic_id === topicId && v.voter_id === voterId);
if(existing) await sb.from('votes').delete().eq('id', existing.id);
else await sb.from('votes').insert({topic_id: topicId, voter_id: voterId});

实时同步

// 简单轮询（15 秒间隔即可）
setInterval(loadAll, 15000);

// 或 Supabase Realtime（WebSocket，更省资源）
sb.channel('public:workshops')
  .on('postgres_changes', {event:'*', schema:'public'}, payload => loadAll())
  .subscribe();

完整工作流（从零到上线）

1. 注册/登录 supabase.com
2. 创建项目 → 获取 URL + publishable key
3. 建表：直连 PG 或 Management API
4. 配 RLS 策略 + GRANT 权限
5. 前端集成：init → select → insert → update → delete
6. 部署 HTML 到 OSS（调用 feishu-html 技能，或直接参考 `references/oss-deploy.md`）

重建/清空数据库

当用户说「删除重建，不保留数据」时：

import psycopg2

conn = psycopg2.connect(
    host=env['SUPABASE_DB_HOST'],
    port=env['SUPABASE_DB_PORT'],
    user=env['SUPABASE_DB_USER'],
    password=env['SUPABASE_DB_PASSWORD'],
    dbname='postgres',
    connect_timeout=10
)
cur = conn.cursor()

# 1. 删除所有自定义表（CASCADE 处理外键依赖）
cur.execute("""
    DO $$ DECLARE r RECORD;
    BEGIN
        FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname='public') LOOP
            EXECUTE 'DROP TABLE IF EXISTS public.' || quote_ident(r.tablename) || ' CASCADE';
        END LOOP;
    END $$;
""")

# 2. 清空 auth.users（如有测试用户）
cur.execute("DELETE FROM auth.users")

# 3. 清除 Storage 桶（如有）
cur.execute("DELETE FROM storage.objects")

conn.commit()
cur.close()
conn.close()

注意：DROP ... CASCADE 会连带删除依赖该表的所有 RLS 策略、触发器、索引。重建后必须重新 ENABLE ROW LEVEL SECURITY + CREATE POLICY + GRANT。

与已有技能配合

feishu-html（部署管道）
  └── 可选后端：supabase-backend（推荐）或 OSS JSON
        └── supabase-backend（本技能）提供数据层
  
trip-landing（行程落地页）
  └── 报名表单 → supabase-backend 收集数据

踩坑记录

通知触发器

业务事件驱动的站内通知可以用 PostgreSQL 触发器零成本实现——状态变更时自动 INSERT 到 notifications 表，前端 30s 轮询。详见 references/notification-triggers.md。

如果通知需要同时推送到外部平台（钉钉/飞书），使用 pg_net 扩展的 net.http_post() 在同一个触发器内完成。详见 references/pg-net-webhook.md。

⚠️ 单一数据源原则：工单/申领/盘点状态变更通知由 DB 触发器统一管理，前端只做 CRUD。DB 触发器内先调用 send_webhook() 一次再插按用户通知行，避免 N×webhook 爆炸。详见 references/notification-architecture.md 和 references/send-webhook-helper.md。

每条通知应包含该环节的关键业务信息（地点、接单人、类别、评分等）。完整模板映射见 references/notification-templates.md。

修改 webhook 格式后务必全量验证。完整测试方法和 14 种模板清单见 references/testing-webhook-templates.md。

批量修复多张表 id 列无 DEFAULT 的问题，使用 references/batch-fix-id-defaults.md 中的检测与一键修复脚本。

前端：无 CDN SDK 的原生 fetch 模式

当 CDN 加载的 Supabase JS SDK 无法正常工作（window.supabase 始终 undefined、网络环境限制）时，完全绕过 SDK，直接用原生 fetch() 调用 Supabase REST API。零外部依赖，可靠性最高。

const SB_URL = 'https://{project_ref}.supabase.co'
const SB_KEY = 'sb_publishable_...'
const API = SB_URL + '/rest/v1'

async function api(method, table, params = {}) {
  let url = `${API}/${table}`
  const opts = {
    method: method.toUpperCase(),
    headers: { 'apikey': SB_KEY, 'Content-Type': 'application/json', 'Prefer': 'return=representation' }
  }
  if (params.select) url += `?select=${encodeURIComponent(params.select)}`
  if (params.filters) url += (url.includes('?') ? '&' : '?') + params.filters
  if (params.order) url += (url.includes('?') ? '&' : '?') + `order=${params.order}`
  if (params.limit) url += (url.includes('?') ? '&' : '?') + `limit=${params.limit}`
  if (params.body) opts.body = JSON.stringify(params.body)

  const r = await fetch(url, opts)
  if (!r.ok) { const e = await r.text(); throw new Error(e) }
  const txt = await r.text()
  return txt ? JSON.parse(txt) : null
}

COUNT 查询（不拉取数据）：

async function apiCount(table, filter) {
  let url = `${API}/${table}?limit=0`
  if (filter) url += `&${filter}`
  const r = await fetch(url, { headers: { 'apikey': SB_KEY, 'Prefer': 'count=exact' } })
  const range = r.headers.get('content-range')
  if (range) { const m = range.match(/\d+$/); if (m) return parseInt(m[0]) }
  return 0
}

⚠️ PATCH 和 DELETE 必须在 URL filter 中指定条件（如 ?id=eq.xxx），否则操作全表。

动态座位生成模式

适用于票务/选座等需要从行配置批量生成座位的场景。

表结构：zones(区域) → row_configs(排号段) → seats(具体座位 × 每场次)

关键规则：

• 一行可能有多个不连续号段（如 1-9号 + 21-29号）→ 不要对 (zone_id, row_number) 加 UNIQUE，同一排允许多条 row_configs 记录
• 前端渲染座位图时，对同一排的多段号段要合并展示在同一行（按 seat_number 排序后渲染）
• 用 CROSS JOIN LATERAL generate_series(seat_start, seat_end) 批量生成
• admin 后台提供「重新生成座位」按钮，修改区域排配置后一键重建

INSERT INTO seats(show_id, zone_id, zone_name, floor, row_number, seat_number)
SELECT $1, z.id, z.name, z.floor, rc.row_number, s.seat_num
FROM row_configs rc
JOIN zones z ON z.id = rc.zone_id
CROSS JOIN LATERAL generate_series(rc.seat_start, rc.seat_end) AS s(seat_num)

座位模板复用模式

当不同演出日期使用不同的座位布局时，不要直接修改 seats 表。引入 seat_templates + template_rows 两层：

• seat_templates(id, name) — 模板名称（如 "默认448座"、"VIP专场"）
• template_rows(template_id, zone_id, zone_name, floor, row_number, seat_start, seat_end) — 模板内的排配置
• shows.template_id — 每个场次关联一个模板

流程：

1. 在 row_configs 中编辑当前布局 → 确认后「保存为模板」→ 复制到 template_rows
2. 新建演出日期 → 选择模板 → 从模板批量生成该日期的 seats
3. 「重生成」按钮只操作单日：清除该日 seats + bookings → 从模板重新生成
4. 不同日期可关联不同模板，各自独立，互不影响

前端并行加载模式：日期和区域数据独立，登录后并行加载再自动渲染第一个区域：

Promise.all([loadDates(), loadZones()]).then(() => {
  loadSeats()  // 此时 curShow + curZone 均已设置
  loadStats()
  loadBookings()
})

批量操作与 Pooler 连接

通过 Pooler 连接时两个核心坑和最佳实践：

• 批量插入：逐条 INSERT 经 Pooler 延迟 ~100ms/条，448 条 → 60s+。用 execute_values 后 448 条 → <2s（性能 100×）
• autocommit：c.commit() 对 DELETE 可能静默不提交 → 设置 c.autocommit = True
• 验证：DELETE/TRUNCATE 后立即 SELECT count(*) 确认行数为 0 再继续 INSERT

环境依赖

• psycopg2-binary + psycopg2.extras.execute_values — 直连 PostgreSQL + 批量插入
• supabase CLI — 项目管理（可选）
• 前端：Supabase JS SDK（CDN）或 原生 fetch()（推荐，零依赖）

凭据文件

项目凭据（URL、Key、PAT、OSS 等）集中在 references/credentials.md。新项目启动时先从该文件获取凭据。

| 44 | select('*') 不指定 .limit() 导致数据截断 | 题库 187 条记录但页面显示不全，选项字段缺失 | Supabase JS SDK 默认不分页但 PostgREST 的 max-rows 配置可能被调低；部分行因超出限制未被返回 | 所有 select('*') 必须显式加 .limit(1000)。即使数据量在默认限制内，这是防御性实践 | | 45 | JSONB options 字段在 Supabase JS Client 中类型不稳定 | 单选题无选项显示（空白区域），但数据库内 options 为正常 JSON 数组 | SDK v2 对 JSONB 列的解析可能因网络/缓存返回 JSON 字符串而非已解析数组 | 前端必须用 ensureOptionsArray() 包装函数：检查 Array.isArray() → 尝试 JSON.parse() → 降级处理。不能假设 q.options 总是数组 | | 46 | Dedup 用前缀截取而非完整文本 hash | 去重逻辑用 question_text[:60] 作为 key，导致 110+252 道合法题目被误删 | 后缀不同的题目（"根据《民法典》规定，下列哪项..."）前缀相同被当作重复 | 去重必须用完整内容 hash：hashlib.md5(question_text + '|'.join(options)).hexdigest()，而非前缀截取 | | 47 | LLM 生成选项后答案字母错位 | 38 道题显示错误答案——正确选项被 LLM 移到了其他字母位置 | LLM 补全缺失选项（如补 D）时重排了选项顺序，但 correct_answer 字母未更新。例如原答案为 B，但选项重排后正确内容移到了 A | 必须交叉验证答案内容而非字母：用原始 docx 中正确选项的文本内容去匹配当前 DB 选项文本，重新映射答案字母。不能假设字母不变 | | 48 | 多选题被误标为单选题 | 题型列显示"单选题"但正确答案为 "ABC" | docx 解析器未识别多选题标记，或 LLM 补全选项后未回头修正 question_type | 入库后做 constraint 校验：LENGTH(correct_answer) > 1 → question_type 必须为 '多选题'，自动批量修正 | | 49 | 选项渲染正则不稳定 + 分隔符不统一 | 部分单选题选项不显示，或个别字母（A/B/C/D）消失 | 选项分隔符有 . 、 ， ) ） ． : ： 等 8+ 种格式，正则疲于兼容 | ① 入库前标准化所有选项为 A.xxx 格式（数据库迁移脚本）；② 前端只用 replace(/^[A-D]\.\s*/, '')；③ 字母用 String.fromCharCode(65+i) 硬编码，不依赖正则匹配 | | 50 | fetch() 直调 Supabase REST API 比 CDN SDK 更可靠 | select('*') 缺数据、JSONB 解析异常、CDN 加载失败 | supabase-js v2 CDN 在全球不同网络下表现不一致；JSONB 字段类型可能因版本返回 string 而非 array | 前端完全绕过 SDK，用原生 fetch() + limit=1000 + 类型安全包装函数。参考 references/quiz-display-fetch.md |

| 35 | apiCount 加 _t 时间戳参数导致 COUNT 全返回 0 | 统计四栏全是 0，但数据存在 | 给 REST API URL 追加 &_t=${Date.now()} 意图破缓存，但 Supabase REST API 将其视为有效查询参数，干扰 count=exact 的 content-range 响应头解析 | apiCount 的 URL 只保留 limit=0 + 业务 filter，不追加任何额外参数。REST API 默认无缓存，无需手动破缓存 | | 36 | apiCount 加 Cache-Control 头导致 COUNT 返回 0 | 同 #35，统计全显示 0 | fetch(...,{headers:{'Cache-Control':'no-cache'}}) 在 Supabase REST API 中干扰 count=exact 响应 | apiCount 的 fetch headers 只保留 apikey + Prefer: count=exact，不额外加任何缓存控制头 | | 37 | PostgreSQL NOT IN (NULL, ...) 不匹配任何行 | WHERE col NOT IN (SELECT col FROM t) 预期删除孤儿行但 0 row affected，而子查询返回了 NULL | SQL 标准：NOT IN 子查询含 NULL 时，对所有外行返回 UNKNOWN，WHERE 当作 FALSE 执行 | 避免 NOT IN (subquery) 当子查询可能返回 NULL。改用 NOT EXISTS (SELECT 1 FROM t WHERE t.col = outer.col) 或在子查询中加 WHERE col IS NOT NULL | | 38 | PostgREST 嵌入资源别名不作用于 FK 列 | shows(date,template:seat_templates(name)) 返回的 shows.template 为 null | PostgREST 中 alias:table(cols) 别名仅适用于自定义 join，FK 列的嵌入资源键名是引用表名而非别名 | FK 嵌入用实际表名：shows(date,seat_templates(name)) → 前端取 b.seats?.shows?.seat_templates?.name | | 39 | 座位排号段合并覆盖问题 | 同一排添加第二段时第一段被覆盖 | 前端 DELETE FROM row_configs WHERE zone_id=X AND row_number=Y 清空同排旧记录再 INSERT 新记录 | 合并算法：收集同排所有现有段 + 新段 → 按 start 排序 → 相邻/重叠段合并（end+1>=next.start）→ DELETE 旧记录 → INSERT 合并后的段。详见 references/seat-range-merge.md | | 40 | 区域名不统一导致三端不一致 | 订座页/后台/票根页显示不同区域名 | 数据库 zone.name 被多轮操作覆盖，但 seats.zone_name 是生成时快照的旧值 | 修改 zone.name 后必须同步更新 seats.zone_name 和 template_rows.zone_name（三条 UPDATE）。后台「重新生成座位」会重建 seats，但 template_rows 和已有 bookings 不会自动刷新。zone_name 改为数字标识（如 168/128/108）后确认三端显示统一再继续 | | 41 | ES6 模板字符串在微信浏览器中不解析 | 页面按钮点击无响应，JS 完全不执行 | 微信内置浏览器（特别是 Android 端）的 WebView 内核可能不支持 ES6 模板字面量 `${}`，导致脚本解析失败，整个页面的 JS 停摆 | 全部改用普通字符串拼接 'text ' + var + ' more'，不使用模板字面量。同时检查箭头函数兼容性，必要时降级为 function(){}。验证时在微信中实际扫码测试，不能仅依赖 Chrome DevTools | | 42 | html2canvas CDN 脚本阻塞页面加载 | 页面空白或长时间 loading，特别是微信扫码环境下 | html2canvas CDN（jsDelivr）在部分网络环境下加载极慢或被墙，<script src> 在 <head> 或页面顶部时会阻塞 DOM 解析，导致整个页面白屏 | 改为按需动态加载：在 saveStub() 函数内部先检查 typeof html2canvas === 'undefined'，不存在时用 document.createElement('script') 动态插入 <head> 并 await onload。页面首屏不再依赖 html2canvas CDN | | 43 | 按钮在操作中 disabled 导致用户困惑 | 用户反馈「按钮点不了」「没有反馈」 | 按钮 disabled=true 后变灰且不可再点击，用户不知道操作是否在进行中，也无法取消或重试 | 按钮永远不禁用。操作中仅修改 btn.textContent（如「查询中...」「生成中...」），完成后恢复原文。按钮始终可点击让用户有主动控制感。这是用户的明确偏好——不得违反 |

多渠道用户模式（多对多）

当账号需要绑定多个渠道时，用 junction table 而非单列外键：

CREATE TABLE user_channels (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES admin_users(id) ON DELETE CASCADE,
  channel_id UUID REFERENCES channels(id) ON DELETE CASCADE,
  UNIQUE(user_id, channel_id)
);

查询：admin_users?select=*,channel:channels(name),user_channels:user_channels(channel_id,channel:channels(name))

| 50 | fetch() 直调 Supabase REST API 比 CDN SDK 更可靠 | select('*') 缺数据、JSONB 解析异常、CDN 加载失败 | supabase-js v2 CDN 在全球不同网络下表现不一致；JSONB 字段类型可能因版本返回 string 而非 array | 前端完全绕过 SDK，用原生 fetch() + limit=1000 + 类型安全包装函数。参考 references/quiz-display-fetch.md | | 51 | DDL: CREATE POLICY IF NOT EXISTS 语法错误 | 整批 DDL 执行中断报 syntax error at or near "NOT"，后续建表语句全部未执行 | PostgreSQL 的 CREATE POLICY 不支持 IF NOT EXISTS（截至 PG17） | 先 DROP POLICY IF EXISTS xxx ON tbl; 再 CREATE POLICY xxx ...。幂等且可重复执行 | | 52 | 多应用共享项目时表名冲突 | 新建 users/projects 等通用表名与已有应用表冲突或语义混淆 | 同一 Supabase 项目承载多个应用，通用表名互相覆盖 | 表名加应用前缀（pm_users、quiz_questions），RLS 策略名同步加前缀 |

关联工具

• Playwright HTML-to-PDF：当文档需导出为排版精良的 PDF 时，参考 references/playwright-pdf.md
• 票务验证 SPA：扫码→查询→多票选择→票根→截图保存，参考 references/ticket-verify-spa.md
• 座位排号段合并算法：参考 references/seat-range-merge.md
• Docx 题库解析：从多套 docx 提取结构化数据，参考 references/quiz-docx-parsing.md
• 竞赛答题展示页：fetch() + options 渲染 + 白底大屏投影，参考 references/quiz-display-fetch.md