2.5 KiB
2.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 联动父级刷新)。