4.5 KiB
4.5 KiB
API 层与状态管理规范
- 所有请求经统一 request 封装(
src/api/request):注入 JWT、401 统一跳登录、错误统一提示;组件内不直接fetch/裸 axios。 request的body传对象,封装内部统一JSON.stringify;调用方自己 stringify 会双重编码,后端报cannot unmarshal string into …(2026-07-14 ai-settings 开关踩坑)。- 跨页面共享状态才进 Pinia;页面内状态用
ref/computed就地管理,不把一切塞 store。 - 请求函数返回类型化数据(
Promise<Instance[]>),错误向上抛由封装层兜底,不在每个调用点重复 try/catch。 - 消息提示统一走
useToast(src/composables/useToast),禁止组件直接useMessage:超长错误(如 OCI 透传)自动折叠成「标题 + 展开详情」,显式传 detail 可自定义折叠内容。 - 账单域(round14 起):发票/付款方式 DTO 在
types/api.ts,请求走api/billing.ts;发票 PDF 接口带 JWT 不能裸<a href>,统一经downloadInvoicePdf(rawFetch→blob→触发保存)。发票 tab 的 403 不当普通错误弹 toast,转受限卡提示 osp-gateway policy;「未付余额」口径只计 OPEN/PAST_DUE,PAYMENT_SUBMITTED 已提交扣款不计入。 - 发票列表按年懒加载(round15 起):
listInvoices(id, year)初始拉当年、空则自动往前探,手动逐年加载,连空 2 年停;明细/PDF 预览/付款方式一律弹窗(NModal),不用 NDrawer。对象存储 Archive 层:查看器「下载」在非 Restored 时禁用、「分享」一律禁用(PAR 对 Archive 无效);列表有 Restoring 对象时 30s 静默轮询自动停;公共读桶(visibility=ObjectRead)「复制 URI」变「复制 URL」(对象名整体 encodeURIComponent 拼公网直链)。 - Usage API 的成本时序对无出账记录的时段不返回行:图表轴不能用返回数据的 key 排序生成,须前端按范围生成完整标签再补零(CostTab
fullLabels()),否则断轴缺刻度。 - 大列表禁止全量拉取(2026-07-21 PAR 复盘):几千行进
ref+ NDataTable 会全量响应式代理化 + 建树,主线程打满数秒——服务端有游标就走 remote 分页,交互复用 ObjectBrowser 的「游标栈 + 上一页/下一页」模式(游标分页拿不到总数,头部计数用「本页 N(+)」表述);listPars返回{items, nextPage},每页 100。OCI 写后读有秒级最终一致性(换 IP 后 GetVnic 仍回旧值):变更成功不能只重查一次,要带预期值开限时轮询窗口(VnicPanelipExpect90s,收敛后再 emit changed 联动父级刷新)。 - 表单先上传临时远端资源、再创建业务对象时:上传响应保存
{cfgId, domainId, url, fileName}原始元组,用请求序号丢弃迟到响应;替换、放弃表单或提交未引用它时按元组尽力删除, 失败静默(孤儿只是自己租户里一张无入口小图)。创建请求引用了它且返回 2xx (含201 + setupWarning)即视为已采用不再清理;清理复杂度须与资源价值匹配, 勿为低价值资源建冻结所有权/结果未知协议的状态机(2026-07 IdP 图标精简教训)。 域相关异步前置设置未加载完成前禁用提交,后端仍是同一约束的权威校验。 - 可重入异步加载(分页、自动刷新、详情弹窗、依赖切换)不经 useAsync 时必须带请求代次守卫(
let seq = 0; const n = ++seq; … if (n !== seq) return),晚到响应丢弃、loading 只由最新请求清;作用域标识(如 cfg/region/bucket)变更时同步重置从属状态(前缀/游标/选中/弹窗)。会创建远端会话的打开流程,过期响应要就地删除刚建的会话(SerialConsolePanel)。(2026-07-22 审查 #5/#6/#10/#17) - 401 登出前比对发出请求时快照的 token 与当前 token:不一致说明会话已更新(如 OAuth 绑定回跳),旧令牌的迟到 401 不得登出新会话(request.ts
handleUnauthorized)。含时间比较的登录态判定用普通函数,不用 computed(时间流逝不触发重算)。(#4/#15) - 固定周期轮询用
setTimeout自链(上一轮 finally 里排下一轮),不用setInterval:慢响应会堆叠请求且可能永久饥饿。(#16) window.open只能在用户手势内同步调用,异步回调(如签发 PAR 后)现开会被弹窗策略拦截且返回 null:需要新窗口的异步流程在点击处理器里先window.open('', '_blank')预开、拿到结果后location.replace导航,失败关闭空白窗;任何window.open返回 null 都要如实报错并给重试(重试点击是新手势),不得标记成功。(2026-07-22 审查 #19,ObjectBrowser 下载)