问卷上线与数据闭环 / Survey to Live Base

把模糊调研需求变成一条能跑通的链路：题目 → 网页 → 部署 → 数据表 → 安全写入 → 回读验收 → 交付报告。

北极星指标：从用户确认调研目标起，到一条测试答卷成功写入目标数据表并回读字段一致的闭环完成率。

零、不可突破的红线

以下 8 条为硬性约束，任何步骤、任何降级方案都不得违反。违反即中止该步骤并进入 failed_recoverable。

1. 凭据不落前端。飞书 App ID / App Secret / Access Token 只写入部署平台的服务端环境变量。禁止出现在 HTML、JS 产物、Git 文件、日志文件、交付报告、聊天记录中。
2. 凭据不进上下文。Skill 只校验环境变量的「名称」与「环境」（production / preview），从不读取、回显、记录其值。用户在对话中粘贴 Secret 时，立即提示轮换并停止使用该值。
3. 外部影响三道门禁。创建数据表、部署到生产环境、提交测试记录，三类动作必须逐次取得用户明确确认。未确认不执行，不存在「默认继续」。
4. 成功不等于完成。文件生成成功、页面打开成功、接口返回 ok，都不算项目完成。必须取得 record_id 并回读关键字段，一致率 100% 才置 completed。
5. 不破坏现有资产。不覆盖生产表、不删除空记录与测试记录、不修改已有字段类型。结构差异只输出比对结果，由用户决定是否变更。
6. 不自动公开发布。公开链接、生产域名、分享权限须用户确认后才生效。默认先出预览环境。
7. 不伪造调研结论。题目由业务问题反推，不编造样本数据、统计显著性或行业基准。缺数据写「未核实」。
8. 失败不得丢数据。提交失败必须保留本地草稿与 JSON 下载出口；禁止清空 localStorage；禁止显示假成功。

一、核心能力速查

二、标准工作流程

前置检查

非阻塞信息（配色、题量偏好、Logo）缺失时用默认值继续，不打断。

步骤一：需求澄清（create_survey）

读 workflows/create-survey.md。输出三栏清单：事实（用户明确给的）、假设（Skill 推断的）、待确认（必须问的）。再输出调研目标、受众、KPI、题量、隐私等级。

步骤二：题目与Schema

读 references/question-design-guide.md。生成 questionnaire.schema.json，题型限：单选、多选、文本、量表、矩阵。约束：name 唯一、题号稳定、分支禁止循环、必填不得被隐藏分支锁死。

执行 node scripts/validate_schema.js --questionnaire <path>，通过才进入下一步。

步骤三：生成网页（build_web）

读 workflows/build-and-qa-web.md，用 templates/survey.html 作为骨架。产出单文件 HTML：内联 CSS/JS、响应式、进度条只统计相关必答组、localStorage 草稿按 project_id 隔离、提交失败保留下载出口。

步骤四：本地 QA

启动本地静态服务，检查：HTTP 200、DOM 完整性、控制台错误、375px 视口无横向溢出、首屏进度不为 100%、源码无凭据。运行 node scripts/scan_secrets.js --target <dir>。

步骤五：部署（需授权）

读 workflows/deploy-vercel.md。whoami 失败转设备授权；部署后校验根路径 HTTP 200；根路径 404 时自动修一次配置并重部署（最多一次）。

步骤六：数据去向（create_base / connect_base）

读 workflows/connect-lark-base.md。新建：生成 XLSX 模板并导入；已有：读表与字段做差异比对，只输出不修改。资源链接先解析类型，Wiki 链接先展开。

步骤七：写入网关

读 templates/api-submit-survey.js。字段白名单、CORS 限定来源、统一错误码、request_id 幂等。生成后执行 node --check。

步骤八：环境变量向导

只输出变量名清单与配置入口，不回显值。变量：LARK_APP_ID、LARK_APP_SECRET、ALLOWED_ORIGIN、SURVEY_BASE_TOKEN、SURVEY_TABLE_ID。

步骤九：权限就绪

双层门禁诊断：应用 scope 层 + 数据表协作者层。读 references/permissions-guide.md。

步骤十：端到端验收

读 workflows/e2e-validate.md。提交带「部署验收测试」标识的记录，取 record_id，运行 python3 scripts/compare_readback.py 逐字段比对。

步骤十一：交付

读 templates/delivery-report.md。输出问卷 URL、数据表 URL、字段映射表、验收结论、限制与维护说明。未完成项如实标注，不夸大上线状态。

三、任务状态机

异常分支

• 任一执行状态 → failed_recoverable（可修复：配置错、变量名错、根路径 404、网络瞬态）
• 任一执行状态 → failed_blocked（外部条件缺失：未登录、缺 scope、非协作者、未提供凭据）
• 任一确认状态 → cancelled（用户取消，保留本地产物）

恢复规则：从 state.json 读当前状态与已完成产物清单，从对应步骤续跑，不重做已验证步骤；已部署或已写入的外部动作不重复执行，除非用户明确要求。

四、数据合规与安全

完整规则读 references/security-boundaries.md。摘要：

五、性能与容量

六、交付形态

| 交付说明 | delivery-summary.md | 含限制与维护说明 |
| 质量报告 | quality-report.md | P1，只标记不删除 |
| 看板配置 | dashboard-config.md | P1，口径可复算 |
| 运营配置 | ops-config.json | P1，键白名单注入 |
| 开放题洞察 | insights.md | P2，证据可追溯 |
| 适配器 | adapters/<kind>/<provider>.json | P2，契约注册 |

所有文件署名「小浣熊肖恩」，使用相对路径，不含主机名与用户名。

七、交付前自检

四维度全绿才可置 completed。任一维未过，如实标注为「未验收」并列出缺口。

八、何时不用本 Skill

九、常见问题

Q1：环境变量配好了，接口仍报 SERVER_NOT_CONFIGURED？
变量名拼写或环境选错。Skill 只校验名称与环境，不读值。检查是否在 Production 环境配置，变量名是否与 .env.example 完全一致。

Q2：接口返回成功但数据表里看不到记录？
两种可能：写入的是预览环境关联的另一张表，或页面缓存了旧 ALLOWED_ORIGIN。以 record_id 回读为准，不要以接口状态判断。

Q3：提示 LARK_SCOPE_MISSING 怎么办？
应用缺少数据表权限。在开放平台开启「查看、评论、编辑和管理多维表格」相关 scope，保存后需重新发布应用版本才生效。

Q4：scope 都有了还是 LARK_RESOURCE_FORBIDDEN？
这是第二层门禁：应用未被添加为目标数据表的协作者。打开数据表右上角「…」→ 添加文档应用为协作者并给编辑权限。

Q5：导入模板后出现了空记录？
导入范围包含了空行。默认不删除，由用户在数据表内确认后清理。Skill 只在报告中标记风险。

Q6：字段全部变成了文本，看板算不了平均分？
P0 模板导入默认文本。P1 的 quality_report 会输出类型优化清单与变更确认单，不自动改结构。

Q7：重复提交会不会产生两条记录？
不会。前端生成 request_id 并持久化，网关查重后返回 DUPLICATE_REQUEST。

Q8：能在聊天里把 App Secret 发给我帮你填吗？
不能，也不要。一旦粘贴，须立即到开放平台轮换该 Secret，旧值停止使用。

Q9：Vercel 未登录怎么处理？
转为官方设备授权流程，用户在浏览器完成 Allow Access。授权未完成时产出可部署包，不声称已上线。

Q10：中途取消了会丢进度吗？
不会。产物与 state.json 保留在本地目录，重新运行时从对应状态续跑。

Q11：能同时接多个数据表吗？
P0 单项目单表。多表请拆成多个 project_id。

Q12：问卷网页能改配色和 Logo 吗？
P1 的 ops_config 支持品牌色、Logo、结束页文案与提交通知，配置驱动，改配置重新生成即可。

十、参考文件（按需读）

作者：小浣熊肖恩 ｜ 许可：MIT-0 ｜ 版本：1.0.0