云端小应用 + 本机桥接
把一条线下已在跑的流程（门店填单、同事提报、内部审批），变成能发链接就用的小网页应用；云端管数据、管页面、管发布，本机进程补上云端碰不到的那一段。
先判断该不该做
回答三个问题，三个都是「是」才继续：
- 这件事现在靠群里刷消息、Excel 传来传去、或者一个人手工汇总？
- 填的人不固定，或者填的人不在你身边（门店、外勤、其他部门）？
- 你愿意接受「网页链接 + 一个后台审核页」这种形态，而不是装个 App？
有一个是「否」，先说明不做的理由，不要硬做成网页。判断细则见 references/architecture.md。
流程
1. 定形态：纯云端，还是云端 + 本机
- 纯云端：只做「填表 → 存库 → 查表 → 导出」。做完就能上线，不需要任何本机进程。
- 云端 + 本机桥接：一旦出现下面任意一条，就必须加本机进程，因为云端沙箱里没有这些能力：
- 读写本机或企业网盘里的文件
- 调只能在内网或需登录环境的命令行工具
- 发企业 IM 消息、写企业在线表格
- 定时抓某个桌面客户端才能导出的数据
判据、取舍和三种形态的边界见 references/architecture.md。先按纯云端设计，把所有外部动作抽成「待办队列」接口；确认真的需要了再接本机进程。这样以后加桥接不用改数据模型。
2. 设计数据模型
一张主表走完全程，不要一开始就拆多表。主表至少包含：
- 主键、对外令牌（长随机串，给外部链接用，不要暴露自增 id）
- 业务字段（提交人、单号、金额、理由、附件路径）
- 状态字段（
pending / approved / rejected之类的枚举字符串，不要用布尔） - 一组「做过标记」字段，见下
「做过标记」用时间戳，不用布尔。每个需要「只做一次」的外部动作配一个 xxx_at 列：没做过就是空，做过就写时间。查询待办永远是「条件 + 该列 IS NULL」，天然幂等、可审计、可回放。要记录在外部系统里的位置（第几行、第几个块），再加一个 xxx_row 之类的整型列。
字段命名、状态机、并发抢占的写法见 references/data-model.md。
3. 写后端接口
一个进程内按路由分派即可，不要上框架。必须有的接口类型：
- 公开提交接口：校验必填、校验枚举值、落库、返回令牌
- 令牌查询接口：凭令牌读单条，用于外部链接打开的那一页
- 审核动作接口：先抢状态（
update ... where status = pending），抢不到就返回「已被处理」，不要静默成功 - 后台接口：列表、统计、导出，走一个独立的鉴权头
- 桥接接口：
/api/bridge/*，只给本机进程用，走独立密钥头
所有「分配资源」的动作都要能回滚：先抢占唯一键（主键冲突即抢占失败），后续步骤失败就把抢占的记录删掉，最后才改主状态。
并发安全靠数据库约束，不靠先查后写。先查再写必然有竞态；用唯一键冲突、条件更新影响行数来判断成败。
4. 做页面
最多三个页面，多一个都说明设计没想清楚：
- 提交页：手机优先，下拉选门店/部门这类长列表必须能边打边筛
- 外部动作页：凭令牌打开，展示信息 + 两个动作按钮
- 后台页：表格 + 筛选 + 导出
不要用浏览器原生的候选列表控件（datalist 这类），移动端基本不弹。用输入框 + 自己渲染的下拉层。
外部链接里的分享码、租户参数要全局透传：所有接口调用和静态资源都要带上，否则一换环境就 403。
5. 发布上线
上线前跑一遍 references/publish.md 里的检查清单：路由、静态资源、分享码、环境变量、数据库连接、健康检查。
发布前必须本地跑通全链路，包括失败分支。云端没有本地控制台，第一次上线才调试会非常痛苦。
6. 接本机桥接
只有当第 1 步确认需要时才做。本机进程是一段循环脚本，每 N 秒做四件事：
- 拉待办：
GET /api/bridge/pending-xxx - 做外部动作（写文件、发消息、写表格）
- 成功就回写标记：
POST /api/bridge/xxx-done - 失败分两类处理：可重试的留空下一轮再试；不可重试的走兜底（通知人、写日志），然后也要标记，否则会死循环
写这类进程必须遵守四条：幂等（重复跑不产生重复结果）、可重入（中途崩了重启能续）、有兜底（自己通知不了人就通知负责人）、有日志（每条动作一行，含 id 和结果）。
轮询间隔、抢占写法、兜底话术、开机自启配置见 references/bridge-worker.md。
7. 上线自检
逐条对照 references/pitfalls.md 的清单过一遍，重点确认：
- 每个
xxx_at标记都有人写、有人判，没有「只写不判」或「只判不写」 - 外部动作失败时，用户看到的是人话，不是 500
- 并发点（两人同时审核、同时点提交）实测过
- 关机/断网后恢复，积压的待办能自动补做，不会丢也不会重
参考文件
| 什么时候打开 | 文件 |
|---|---|
| 判断该做纯云端还是加本机桥接 | references/architecture.md |
| 建表、定状态机、做并发抢占 | references/data-model.md |
| 写本机守护进程、定桥接接口 | references/bridge-worker.md |
| 发布上线前的检查 | references/publish.md |
| 出问题、踩坑、诡异现象 | references/pitfalls.md |
| 配环境、装依赖、授权凭据 | references/setup-guide.md |
环境不确定时先跑 scripts/check_environment.py，它只读、不写文件、不打印任何密钥。
停止条件
遇到下列情况停下来问人，不要自行推进：
- 需要删除或覆盖已有数据、已有文件
- 需要对外群发消息
- 需要读取或使用他人凭据
- 业务规则本身没定清楚（谁审、什么条件通过、金额怎么算）
- 外部系统没有可用的写入接口，只能整份文件覆盖
质量清单
交付前逐条确认：
- [ ] 手机打开提交页，能正常选到长列表里的目标项
- [ ] 外部链接换环境后仍可用（分享码透传完整）
- [ ] 两人同时点同一个动作，只有一个成功，另一个看到明确提示
- [ ] 所有外部动作失败都有人话提示，且不会卡在待办里死循环
- [ ] 本机进程关掉再打开，积压待办自动补做，无重复无遗漏
- [ ] 数据库里每个
xxx_at列都有对应的写入点和判断点
