Skip to content

NocodeMrLi/mini-program-engineering-skill-suite / skills/mini-program-architecture-skill

mini-program-architecture-skill

Verified

Translate a confirmed mini-program product specification or bounded feature into an implementable architecture covering modules, pages, components, services, canonical state sources, data models, interfaces, permissions, failures, caching, concurrency, idempotency, migration, rollback, external dependencies, and architecture decision records. Use when users ask how to structure a mini program, design data or APIs, divide frontend and cloud responsibilities, evolve an existing system safely, or prepare implementation after product semantics are stable. Preserves product meaning, current repository constraints, user-owned changes, and verifiable acceptance behavior rather than redesigning the product for technical convenience.

references/cloud-state-and-write-contracts.md

View on GitHub
# 云端状态、配置与写入安全合同

## SDK写入与业务读回

同厂商、同方法名不保证不同SDK/版本的参数封装和返回语义相同。先记录目标依赖、原生签名、非抛出错误、影响行数及事务语义;独立协议夹具保留差异,不从实现生成预期。Promise完成/返回成功不证明根业务字段改变,由实际业务读取路径核状态和关联。

测试正常写入/读回、另一SDK多余嵌套封装、返回错误、零影响和关联不符。恢复仅改归属已确认的本次字段并核前置版本,沿原任务/预算接续;不清历史、换身份或改余额掩盖未知。

## 已接收事件的恢复、预算与节奏

仅在可信事件驱动业务且已有获准恢复入口时应用。先鉴权并核最小归属绑定,在查证/应用未完成前持久保存可发现的最小恢复意图;不存完整事件/凭证、不提前改变权益。持久响应未知用原键核结果;停止重推后本地仍可发现。未收到事件仍须独立核账/补查,不能从空日志推完成。

重推与恢复共用业务幂等键,I/O前原子领取租约并持久占用尝试额度,进程终止、超时和响应丢失也计入有界预算。返回后才计次不能证明有限重试。旧租约/结果不覆盖新尝试,耗尽保留待复核/告警且不再外部调用,不新建任务重置预算。

一轮查证、扫描和持久收尾共同适合真实函数时限并留收尾余量,不无条件叠加耗时任务。需限制节奏时在I/O前持久记录下一次允许执行时间;外层失败导致提前重试则跳过I/O且不消耗额度,到期沿原任务恢复。时限、索引、租约、退避按实际运行时/供应商核,不搬常量或强制新增调度。关闭新增业务保留获准存量善后。

反例:停止重推、持久响应丢失、扫描/通知交错、连续进程中断、旧租约、耗尽、伪造入口、成功子任务后外层失败提前重试与到期恢复。核可发现、唯一生效、持久次数、节奏及拒绝零写入;内存注入不证明真实云终止、自然调度或平台时限。

仅在项目涉及云端权威数据、持久化、第三方 SDK、多租户、一次性权益或外部计费服务时应用本合同;未触发的部分标记不适用,不为补表创造能力。

## 权威数据三态与恢复

前台结束尝试与持久远端业务分别收敛,具体可退出条件见[运行时合同](../../mini-program-ui-device-skill/references/runtime-state-and-layout-contracts.md)。符合获准退出条件也须保留原业务、保守占用与查证,不以当前未完成观察写永久终态,不自动重发。再次确认不授权换键重建原未知业务;获准新业务仍在最终写入边界核所有权限/暂停/容量条件,自身未知结果沿自身原键恢复。旧业务晚到权威结果按原键唯一生效,旧客户端失败不覆盖权威成功/退款/终止;局部前台解锁不解除全局限制。不固化错误码、金额、地区、等待常量,不引入支付SDK或恢复服务。

审查多个退出/恢复实现时,分别原样摘出每个方法的完整实际谓词,再核写入后分支,逐条件代入可信/未知、允许/拒绝的反例;不能把相邻方法缺失的检查移植到另一个已有检查的方法,也不能只看最后的待核分支就声称从未校验。提供的规则是核对依据,项目事实仍以实际源码/读回为准。

- `unresolved`:尚未从可信缓存或权威源完成解析,不能展示“确认无数据”的流程。
- `confirmed-existing`:权威记录存在,进入正常路径并刷新可重建缓存。
- `confirmed-absent`:权威源明确确认不存在,才允许首次创建、领用或初始化。

本地无记录不等于云端不存在。创建返回“已存在/重复”时读取并采用持久化赢家结果,恢复缓存和正常路由。离线兜底必须有回写或对账路径,云端恢复后收敛到主数据。

## 配置组与真实依赖

- 对每组可选云能力列出必需变量、互斥 provider、默认禁用行为和校验时点。
- 整组缺失可以按已确认的未启用路径降级;只提供部分变量必须 fail-closed 并列出缺项。
- `.env.example` 只保留变量名和安全占位符,不放真实资源 ID、账号、地址或秘密。
- 导入目标、迁移集合/表、运行时依赖注入和 health 探测从同一配置源解析。
- health 分开报告进程存活与数据库、存储、队列等真实依赖可用性。

## 适配器边界与契约测试

领域层依赖能力接口,云适配器负责翻译 SDK 原生输入、输出和错误;不得要求云实现继承或伪装内存仓库。契约测试使用目标 SDK 的真实调用形状做桩,至少断言调用序列、条件表达式、分页、错误映射和事务边界。

## 高风险写入

| 写入类型 | 存储不变量 | 重试结果 |
| --- | --- | --- |
| 一次性领取/兑换/扣减/发货 | 条件更新、唯一约束或事务在存储层阻止第二次生效 | 返回未执行或明确冲突 |
| 创建型幂等 | 幂等键、请求摘要,并持久化首次成功结果 | 同键同载荷返回原结果;同键不同载荷冲突 |
| 多作用域私有读写 | 作用域由服务端会话与成员关系确定,并进入每个存储查询 | 错误作用域返回通用不可见/无权结果 |

客户端字段不能指定私有写入作用域。路由层鉴权不能替代存储查询中的作用域条件。随机会话令牌、API Key、恢复码等完整秘密只在必要创建时返回一次;持久化只保存不可逆摘要,日志、文档和测试快照不记录完整值或摘要值。

## 外部服务有效结果事务

外部评分、识别、OCR、支付、广告、上传等服务按四层判断:请求到达、服务返回、结果通过业务有效性校验、产品状态或计费提交成功。传输成功不等于业务结果有效。

一次用户提交应由一个锁定事务或等价状态机承接。只有有效结果才可写完成态、扣次数或费用;空结果、全零结果、缺字段、业务拒绝、超时或持久化失败都不得扣减,并保留可重试入口。供应商调用量与用户权益次数分开建模。

## 最小验证矩阵

- 权威状态:新用户、老用户、清缓存、换设备、重复创建、离线后收敛。
- 配置:整组缺失、部分缺失、双 provider、真实依赖不可达。
- 写入:并发第二次、同键同载荷、同键异载荷、错误作用域、列表隔离、令牌撤销/过期。
- 外部服务:有效、空/畸形、业务拒绝、超时、重复点击、结果晚到、服务成功但本地提交失败。

## 本地履约与外部确认

本地事务完成与平台/供应商确认是两个状态源。在本地提交事务中原子保存待确认意图、原业务键及恢复信息;外部调用放在事务外。恢复查询与物理索引必须覆盖“本地已完成、外部未确认”,不能只扫未支付或未到账记录。重试复用原业务,不再次发权益或扣库存;按供应商幂等/查单合同处理未知响应。

并发领取、进程中断、租约与晚到结果要按项目合同处理,旧尝试不能覆盖新尝试。有界耗尽进入可发现的人工复核并告警,不能写外部成功。关闭新增业务保留允许的查单、履约、补偿和核账。无业务且确认无在途时才考虑完整基线回退;已受理/结果未知时禁止套回会关闭恢复能力的旧配置,可信终态后才按合同关闭新增任务。

最小反例:本地提交后崩溃、通知拒绝/丢响应、重复扫描/回调、晚到、耗尽及三种回退时点。分别断言本地不变量、待确认可发现、善后可运行及对应证据层;模拟通知不是平台确认。

## 唯一约束的完整生命周期

为每个阶段列文档角色、基数、唯一键、关联键及事务边界。测试桩执行目标库唯一约束语义,覆盖任务到结果的第二次写入、重复结果、并发赢家及关联事务失败。分集合、角色复合键或单记录演进均可,不为测试通过删除唯一约束。

若做隔离库探针,先授权、有界并记录精确清理,读回字段、顺序、方向和唯一性。重复写被拒绝只证明该索引,不证明任务/结果完整生命周期通过。

## 业务控制不依赖诊断

仅在已有权威暂停、权限、额度或风险控制时启用。在最终事务或等价原子写入边界独立检查权威控制,诊断、日志、告警关闭不能跳过保护。控制读取失败/损坏按已确认拒绝策略处理;结案与解除限制分别建模。恢复请求核权限及预期版本,过期请求不能覆盖新控制;重复合法恢复按幂等合同处理。

验证暂停且诊断关闭仍零新增写入,覆盖控制损坏/不可读、无权/过期恢复、结案仍暂停、合法及重复恢复;允许的存量善后另核。不强加来源项目的等级、字段或冻结系统。

## 签名载荷的传输合同

先定义签名绑定原始字节/字符串还是协议规定的结构化值,列发送端、SDK、网关与接收端的解析/重编码边界。原文协议保留同一原文,不排序第三方要求的原文;仅自有或明确允许规范化的协议可双方约定完整字段、键序、数组次序、类型、缺失值及编码规则。不能忽略业务字段或放宽验签求兼容。

测试经过独立重序列化适配器,不让双方共用同一辅助函数自证。允许的对象键重排不误拒绝;嵌套篡改、字段增删、类型改变及有序数组换序均拒绝,非法载荷零业务写入。实际通道行为如需确认,另做授权、有界、无业务副作用探针。

## 仍在线的客户端与共享后端

列线上旧版、新候选、提审版与后端合同的组合,逐组合核请求字段、响应、幂等结果与恢复语义,纳入平台审核时间差。非兼容变更选择有依据的兼容适配、版本接口或维护/发布顺序;不规定统一先端后云或先云后端。

缺身份或幂等字段不能由服务端随机补键、放宽身份或自动重放掩盖。回退核端云组合和在途任务不变量,必要时最小前向修复。候选单样本不证明现网恢复,未执行组合保持未核。发布阶段按 [云发布合同](../../mini-program-release-skill/references/cloud-release-operations.md) 记录矩阵。

## 多来源观测与有界重核

仅对已有异步导出、同步或多来源核验应用;单一原子来源/无此功能标N/A,不新增调度系统。先绑定同一判断集合、请求条件和不变量,分别记录来源快照覆盖截止、取得时间、本地变化及核验时点;下载时间不代表来源覆盖。

分开格式/语义未知、可信身份/权限/数据不变量冲突、有证据支持的暂时可见性差异。只有已获准的最后一种可只读重取本轮所需完整证据集合,不把新旧不兼容来源拼成匹配。沿本文件既有I/O前原子领取租约、持久占用次数与下一次允许时间合同,使用同一预算;中断/重建不重置,提前调用不重复I/O,不重放原业务或给未知请求换键。无法分类或真实冲突保留阻断,耗尽保留可发现复核及原失败。

旧匹配回执只作历史,不能绕过本轮待核。集合、筛选、字段解释或证据合同改变时核旧回执和在途任务适用性;完整新证据与当前本地状态、控制及请求绑定匹配后才解除相应限制。不改旧截止、放宽时效或释放未知占用制造通过。

## 外部结果的状态与身份

结果状态、发起方式、渠道、身份、环境和对象类型分别取证。目标协议或非空可信样本支持的合法文字可在适配层归一,保留原文/依据;未知文字不猜成功。归一不参与身份判定;身份沿本文件多作用域私有读写合同,由服务端会话/成员关系决定并进入实际查询,再核可信请求、关联对象和独立记录。完成文案、设备或自填字段不能证明归属,必要数量/金额不变量不放宽。

先定义应核集合及不变量,再选择目标接口支持的筛选;集合定义、筛选及解释版本共同进入任务/请求摘要与回执。完成集合不把处理中/失败算完成,排除项仍由原业务追踪;不能通过收窄查询漏掉成功记录或隐藏应阻断事实。跨来源覆盖、时间范围及空窗限制仍核;详见[字段证据](../../mini-program-verification-skill/references/evidence-admissibility.md)。

## 破坏性操作的确认与原子执行

仅对已有获准有限删除、级联清除或不可逆迁移应用,复用既有目录/原子失败合同;只读或仅隐藏选项N/A。权威预览覆盖完整作用域、分页外对象及必要关联,绑定真实对象身份、影响用户判断的内容/关系版本和动作模式;复用项目版本/摘要/预览标识,不强制令牌服务。客户端摘要不能替代可信作用域和权限。

最终范围、权限及相关依赖重核与生效写入共用同一可靠原子边界(条件写/事务或已证明的等价保护),不能检查后另按当前条件扩大范围。同数量替换成员、相关内容/关系改变、旧Page提交均使旧确认失效,整体拒绝且零删除/业务生效;刷新可读范围后由用户重新确认。无关对象变化或全局版本递增不单独触发重确认。平台无法保障目标边界则保留缺口,先给具体适配方案,不伪称原子或擅自建任务系统。

按已有保存政策保护相关输入;保存/事务失败保原内容,无部分清除;响应未知沿原请求查证,不换键重删。原键结果仍绑定作用域/动作/载荷,不能跨对象复用。成功清除后既有旧保存、草稿恢复或撤销不得复活对象,无关对象及之后合法修改保留;备份边界从批准政策,业务删除不称安全擦除。

审查与修复建议须闭合上述不变量:把拟修改后的最终校验谓词和实际写入对象一并代入反例,不能把“移入事务并核数量”写成身份绑定已修好。同数换成员、同成员相关版本变化、无关集合变化分别判断;只按可信预览确认的对象及相关版本执行,或整体拒绝,不能重新查询后顺带扩大。成功结果复用先核可信权限及原键载荷绑定;未知结果优先核已有同键恢复路径,只有确有能力缺口且已获准才新增接口。修复说明不以预计行数代替安全边界。
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall