diff --git a/docs/prototype/code-reader/figma-plugin/README.md b/docs/prototype/code-reader/figma-plugin/README.md index af0d727..af1bdb8 100644 --- a/docs/prototype/code-reader/figma-plugin/README.md +++ b/docs/prototype/code-reader/figma-plugin/README.md @@ -24,6 +24,8 @@ | `Prototype / routes.py · 编辑 / 预览` | luffy-agent-platform 的 `backend/src/luffy_agent/user/routes.py` | Python:带装饰器、默认值、返回类型的 FastAPI 路由函数,属性表;`is not None` → 不是 空 | | `Prototype / envLock.ts · 预览(编辑区变窄)` | — | 窗口只有 1000 宽时块跟着变窄,长句换行 | | `Prototype / 库规则 · SQLAlchemy 数据表` | luffy 的 `backend/src/luffy_agent/referral/models.py` 里的 `ReferralRelation` | 库规则(文件导入了 sqlalchemy 才启用)把模型类整块换成「数据表」卡片:名称 / 表名 / 说明 / 继承,字段表(字段 / 类型 / 约束 / 说明)和索引表;`__tablename__`、`__table_args__`、各字段块并进卡片 | +| `Prototype / 枚举` | luffy 的 `referral/models.py` 里的 `CommissionStatus` | 枚举卡片:名称 / 访问级别 / 继承,成员收成一张表(成员 / 值 / 说明),说明取行尾注释;Python 用库规则(导入了 enum 才启用),TypeScript 的 enum 由语言插件报结构,画成同一张卡片 | +| `Prototype / 库规则 · Celery` | luffy 的 `backend/src/luffy_agent/celery_app.py` | 库规则(导入了 celery 才启用)两张卡片:「Celery 应用」名称 / 应用名 / 消息队列 / 结果存储;「定时任务」应用 + 任务表(任务 / 频率 / 说明),频率换算成「每 5 分钟」「每天」,说明取行尾注释,`**` 展开的另起一行 | | `Prototype / 遍历 · 推导式` | luffy 邀请码工具的 `"".join(secrets.choice(ALPHABET) for _ in range(length))`,外加带条件的列表、字典推导 | 写在表达式里的遍历原地套一个带循环图标和结果类型(生成器 / 列表 / 字典)的小框,框里按读的顺序重排:「遍历 range(length) 的每个 _,仅当 …,取 …」 | | `Prototype / 筛选 · 默认` | `envLock.ts` | 预览顶部固定一条筛选栏:「筛选」+ 当前文件出现过的属性各一个下拉框(种类、访问级别、异步、仅类型)+ 右边「共 33 块」 | | `Prototype / 筛选 · 按访问级别` | 同上 | 访问级别下拉菜单打开,只勾「公共」:两个私有常量和私有函数 `chmodAll`(连同函数体)藏起来;条件、返回这些没有访问级别的块照常显示;右边「已隐藏 3 块 · 清除」 | @@ -56,7 +58,10 @@ - `Reader / ModeToggle`:编辑器右上角的「编辑 / 预览」。 - `Explorer / TreeRow`:侧栏文件树的一行,文件夹展开 / 收起 / 展开且悬停,文件默认 / 选中 / 有改动 / 有改动且选中 / 悬停,共 8 个。名字后面的注释层默认藏起来,有注释的实例里打开;悬停状态行尾带「添加注释」「编辑注释」两个按钮,实例里按有没有注释显示其中一个。 - `Explorer / Header`:侧栏顶部。 +- `Explorer / Sidebar`:`File=<文件>`,选中某个示例文件时的整个侧栏,各窗口共用;文件注释那几张要改行的状态,单独画。 - `Reader / TableCard`:SQLAlchemy 规则认出的数据表卡片。 +- `Reader / EnumCard`:枚举卡片。 +- `Reader / CeleryAppCard`、`Reader / BeatCard`:Celery 规则的两张卡片。 - `Reader / IterationBlock`:`Sample=generator | list | dict`,三种推导式的返回块。 - `Reader / FilterBar`:`Active=none | access | kind`,预览顶部的筛选栏,打开的下拉菜单是勾选列表,每个值后面是块数。 - `Window / QuickInput`:VS Code 顶部弹出的单行输入框,标题和内容在实例里改。 diff --git a/docs/prototype/code-reader/figma-plugin/code.js b/docs/prototype/code-reader/figma-plugin/code.js index 72cd836..deda714 100644 --- a/docs/prototype/code-reader/figma-plugin/code.js +++ b/docs/prototype/code-reader/figma-plugin/code.js @@ -951,6 +951,88 @@ function tableCard(ctx) { return node; } +// ─── 枚举 ──────────────────────────────────────────────────────────────────── +// +// Python 的枚举来自自带的 enum 库,用库规则认(文件导入了 enum 才启用);TypeScript 的 enum 是语言自己的写法,由语言插件报结构。 +// 两边画成同一张卡片:名称 / 访问级别 / 继承,成员收成一张表(成员 / 值 / 说明),说明取行尾注释或成员下面的三引号说明。 +// 示例:luffy 的 backend/src/luffy_agent/referral/models.py 里的 CommissionStatus。 +const ENUM_SAMPLE = { + name: "CommissionStatus", access: "公共", bases: "str, enum.Enum", + members: [["PENDING", '"pending"', "待结算"], ["AVAILABLE", '"available"', "可提现"], ["WITHDRAWING", '"withdrawing"', "提现中"], + ["WITHDRAWN", '"withdrawn"', "已提现"], ["INVALID", '"invalid"', "已失效"]], +}; +const ENUM_KIND = { label: "枚举", color: "#b180d7" }; + +/** Reader / EnumCard — State=preview:枚举卡片。 */ +function enumCard(ctx) { + const sample = ENUM_SAMPLE; + const { node, content } = cardShell(ctx, "State=preview", ENUM_KIND, { kids: false }); + propRow(ctx, content, "名称", [{ text: sample.name, color: COLORS.tokenType }]); + propRow(ctx, content, "访问级别", [{ text: sample.access, color: COLORS.tokenControl }]); + propRow(ctx, content, "继承", sample.bases.split(", ").flatMap((base, index) => + [...(index ? [{ text: ", " }] : []), { text: base, color: COLORS.tokenType }])); + propRow(ctx, content, "成员", countSegments(sample.members), { twisty: true }); + propTable(ctx, content, "Members", [["成员", 200], ["值", 200], ["说明", 0]], sample.members.map(([name, value, note]) => [`Member / ${name}`, [ + [{ text: name, color: COLORS.tokenConstant }], + [{ text: value, color: COLORS.tokenString }], + [{ text: note, color: COLORS.comment }], + ]])); + return node; +} + +// ─── 库规则:Celery ────────────────────────────────────────────────────────── +// +// 文件导入了 celery 才启用。两张卡片:创建应用(X = Celery(...))和定时任务表(X.conf.beat_schedule = {...}); +// 改配置、自动发现任务这些语句照旧。示例:luffy 的 backend/src/luffy_agent/celery_app.py。 +const CELERY_APP = { name: "celery_app", app: '"luffy_agent"', broker: "settings.CELERY_BROKER_URL", backend: "settings.CELERY_RESULT_BACKEND" }; +const CELERY_APP_KIND = { label: "Celery 应用", color: "#98c379", badgeWidth: 76 }; +const BEAT_KIND = { label: "定时任务", color: "#56b6c2", badgeWidth: 60 }; +// 频率按调度表达式换算成人话:秒数算式 → 每 N 秒 / 分钟 / 小时 / 天,crontab → 每天 hh:mm 这类;换算不了的照原样。 +const BEAT_SCHEDULE = { + app: "celery_app", + entries: [ + ["commerce.cancel_timeout_pending_orders", "每 5 分钟", ""], + ["commerce.retry_failed_fulfillments", "每 10 分钟", ""], + ["commerce.check_pending_refunds", "每 30 分钟", ""], + ["commerce.check_channel_pending_manual_slices", "每 10 分钟", "手动退款切片对账: 微信回调丢失兜底"], + ["deployment.reconcile_inflight", "每 5 分钟", "发布管线 in-flight 行卡死兜底: 按阶段重新派发"], + ["deployment.reclaim_expired_slot_deployments", "每 10 分钟", "到期部署位对账: 换票或拆除 (#159)"], + ["deployment.notify_expiring_deployments", "每天", "每天一轮到期提醒扫描 (#274)"], + ["membership.grant_monthly_entitlements", "每小时", ""], + ["storage.poll_app_data_usage", "每 get_settings().STORAGE_USAGE_POLL_INTERVAL_SEC 秒", ""], + ], + spread: "_ops_beat_entries(settings.OPS_DASHBOARD_ENABLED)", +}; + +/** Reader / CeleryAppCard — State=preview:创建 Celery 应用。 */ +function celeryAppCard(ctx) { + const app = CELERY_APP; + const { node, content } = cardShell(ctx, "State=preview", CELERY_APP_KIND, { kids: false }); + propRow(ctx, content, "名称", [{ text: app.name, color: COLORS.tokenVariable }]); + propRow(ctx, content, "应用名", [{ text: app.app, color: COLORS.tokenString }]); + propRow(ctx, content, "消息队列", pySegments(app.broker)); + propRow(ctx, content, "结果存储", pySegments(app.backend)); + return node; +} + +/** Reader / BeatCard — State=preview:定时任务表,每条一行:任务 / 频率 / 说明(行尾注释);** 展开的另起一行。 */ +function beatCard(ctx) { + const beat = BEAT_SCHEDULE; + const { node, content } = cardShell(ctx, "State=preview", BEAT_KIND, { kids: false }); + propRow(ctx, content, "应用", [{ text: beat.app, color: COLORS.tokenVariable }]); + propRow(ctx, content, "任务", [{ text: `${beat.entries.length} 条,另有展开 1 处`, color: COLORS.desc }], { twisty: true }); + propTable(ctx, content, "Entries", [["任务", 380], ["频率", 170], ["说明", 0]], [ + ...beat.entries.map(([task, every, note]) => [`Entry / ${task}`, [ + [{ text: task, color: COLORS.tokenString }], + every.includes("get_settings") ? [{ text: "每 ", color: COLORS.tokenControl }, ...pySegments("get_settings().STORAGE_USAGE_POLL_INTERVAL_SEC"), { text: " 秒", color: COLORS.tokenControl }] + : [{ text: every, color: COLORS.tokenControl }], + note ? [{ text: note, color: COLORS.comment }] : [], + ]]), + ["Entry / 展开", [[{ text: "展开", color: COLORS.desc }], pySegments(beat.spread), []]], + ]); + return node; +} + // ─── 筛选 ──────────────────────────────────────────────────────────────────── // // 每块带几条「属性 = 值」,由语言插件从语法树换算成各语言统一的属性,翻译插件给属性和值起显示名; @@ -1289,8 +1371,8 @@ function cardShell(ctx, name, spec, o = {}) { node.paddingRight = 10; const fold = append(node, frame(ctx, "Fold", { dir: "HORIZONTAL", width: 14, height: 20, align: "CENTER", justify: "CENTER" })); if (o.kids) append(fold, icon(ctx, "chevron-down", COLORS.desc, 14, { name: "Fold icon" })); - const badge = append(node, frame(ctx, "Badge", { dir: "HORIZONTAL", width: 44, height: 20, radius: 4, align: "CENTER", justify: "CENTER", - fill: spec.color, fillOpacity: 0.18 })); + const badge = append(node, frame(ctx, "Badge", { dir: "HORIZONTAL", width: spec.badgeWidth || 44, height: 20, radius: 4, align: "CENTER", + justify: "CENTER", fill: spec.color, fillOpacity: 0.18 })); text(ctx, badge, "Kind", spec.label, { hug: true, medium: true, size: 11, lineHeight: 14, color: spec.color }); const content = append(node, frame(ctx, "Content", { width: 10, gap: 3 }), true); const toggle = append(node, frame(ctx, "Toggle", { dir: "HORIZONTAL", px: 8, py: 2, gap: 4, radius: 4, align: "CENTER", @@ -1538,6 +1620,9 @@ function createComponents(ctx, page) { lib.block = make("Reader / CodeBlock", BLOCK_VARIANTS.map(([kind, state]) => `${kind}/${state}`), 2, (entry) => codeBlock(ctx, ...entry.split("/")), (item) => item.node); lib.tableCard = make("Reader / TableCard", ["preview"], 1, () => tableCard(ctx)); + lib.enumCard = make("Reader / EnumCard", ["preview"], 1, () => enumCard(ctx)); + lib.celeryApp = make("Reader / CeleryAppCard", ["preview"], 1, () => celeryAppCard(ctx)); + lib.beat = make("Reader / BeatCard", ["preview"], 1, () => beatCard(ctx)); lib.iteration = make("Reader / IterationBlock", ITERATION_SAMPLES.map((sample) => sample.key), 3, (key) => iterationBlock(ctx, ITERATION_SAMPLES.find((sample) => sample.key === key))); lib.filterBar = make("Reader / FilterBar", ["none", "access", "kind"], 3, (active) => filterBar(ctx, active)); @@ -1545,6 +1630,7 @@ function createComponents(ctx, page) { (entry) => treeRow(ctx, ...entry.split("/"))); lib.quickInput = make("Window / QuickInput", ["typing"], 1, () => quickInput(ctx)); lib.explorerHeader = make("Explorer / Header", ["default"], 1, () => explorerHeader(ctx)); + lib.sidebar = make("Explorer / Sidebar", fileKeys, 3, (fileKey) => sidebarComponent(ctx, lib, fileKey)); lib.windowTitle = make("Window / TitleBar", ["active"], 1, () => windowTitle(ctx)); lib.activity = make("Window / ActivityBar", ["reader"], 1, () => activityBar(ctx)); lib.status = make("Window / StatusBar", MODES, 1, (mode) => statusBar(ctx, mode)); @@ -1579,11 +1665,35 @@ function rowVariant(item, selected, hover) { return isSelected ? "file/selected" : "file/default"; } -/** 侧栏:「代码阅读」视图,外观照搬 VS Code 资源管理器。o.hover:鼠标停在哪一行;o.notes:各行的注释。 */ +/** + * 侧栏:「代码阅读」视图,外观照搬 VS Code 资源管理器。 + * 普通窗口放 Explorer / Sidebar 的实例(每个示例文件一个变体,窗口之间共用); + * 文件注释那几张要改行的悬停状态和注释,单独画。o.hover:鼠标停在哪一行;o.notes:各行的注释。 + */ function sidebar(ctx, parent, lib, selected, o = {}) { - const workspace = WORKSPACES[FILES[selected].workspace]; + if (!o.hover && !o.notes) { + const instance = lib.sidebar.get(selected).createInstance(); + instance.name = "Sidebar"; + append(parent, instance); + instance.layoutSizingVertical = "FILL"; + const rows = new Map(WORKSPACES[FILES[selected].workspace].rows.filter((item) => item.file) + .map((item) => [item.file, instance.findOne((node) => node.name === `Row / ${item.name}`)])); + return { pane: instance, rows }; + } const pane = append(parent, frame(ctx, "Sidebar", { width: SIDEBAR_W, fill: COLORS.side })); pane.layoutSizingVertical = "FILL"; + return { pane, rows: sidebarContent(ctx, pane, lib, selected, o) }; +} + +/** Explorer / Sidebar — File=<文件>:选中这个文件时的整个侧栏。 */ +function sidebarComponent(ctx, lib, selected) { + const node = frame(ctx, `File=${selected}`, { component: true, width: SIDEBAR_W, height: MAIN_H, fill: COLORS.side }); + sidebarContent(ctx, node, lib, selected, {}); + return node; +} + +function sidebarContent(ctx, pane, lib, selected, o) { + const workspace = WORKSPACES[FILES[selected].workspace]; pane.clipsContent = true; pane.overflowDirection = "VERTICAL"; const header = lib.explorerHeader.get("default").createInstance(); @@ -1619,7 +1729,7 @@ function sidebar(ctx, parent, lib, selected, o = {}) { } if (item.file) rows.set(item.file, instance); } - return { pane, rows }; + return rows; } /** 编辑模式:VS Code 原生编辑器,整份源码。 */ @@ -1763,6 +1873,18 @@ async function build(api, stage = () => {}) { const tableInstance = lib.tableCard.get("preview").createInstance(); tableInstance.name = `Block / ${SQLA_MODEL.name}`; append(tableBoard, tableInstance, true); + const enumBoard = frame(ctx, "Prototype / 枚举", { width: TREE_W + 2 * VIEW_PAD, pad: VIEW_PAD, gap: 8, fill: COLORS.editor }); + page.appendChild(enumBoard); + const enumInstance = lib.enumCard.get("preview").createInstance(); + enumInstance.name = `Block / ${ENUM_SAMPLE.name}`; + append(enumBoard, enumInstance, true); + const celeryBoard = frame(ctx, "Prototype / 库规则 · Celery", { width: TREE_W + 2 * VIEW_PAD, pad: VIEW_PAD, gap: 8, fill: COLORS.editor }); + page.appendChild(celeryBoard); + for (const [key, name] of [["celeryApp", "Block / celery_app"], ["beat", "Block / beat_schedule"]]) { + const instance = lib[key].get("preview").createInstance(); + instance.name = name; + append(celeryBoard, instance, true); + } const iteration = frame(ctx, "Prototype / 遍历 · 推导式", { width: TREE_W + 2 * VIEW_PAD, pad: VIEW_PAD, gap: 8, fill: COLORS.editor }); page.appendChild(iteration); for (const sample of ITERATION_SAMPLES) { @@ -1816,7 +1938,7 @@ async function build(api, stage = () => {}) { stage("排布画板"); const screens = [...Object.values(boards).flatMap((pair) => [pair.edit.screen, pair.preview.screen]), narrow.screen, - ...Object.values(notes).map((board) => board.screen), ...Object.values(filters).map((board) => board.screen), iteration, tableBoard]; + ...Object.values(notes).map((board) => board.screen), ...Object.values(filters).map((board) => board.screen), iteration, tableBoard, enumBoard, celeryBoard]; let y = 0; for (const screen of screens) { screen.x = 0; @@ -1834,7 +1956,7 @@ async function build(api, stage = () => {}) { { nodeId: filters.none.screen.id, name: "筛选" }]; page.selection = [start]; api.viewport.scrollAndZoomIntoView(page.selection); - return { page, components, boards, narrow, notes, filters, iteration, tableBoard, screens }; + return { page, components, boards, narrow, notes, filters, iteration, tableBoard, enumBoard, celeryBoard, screens }; } async function run(api) { @@ -1853,6 +1975,6 @@ async function run(api) { } if (typeof module !== "undefined") { - module.exports = { SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, blockAttributes, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, parseImport, parseVariable, translateCode, build, run, nextPageName, PAGE_NAME, NAMESPACE, TREE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, typeSegments }; + module.exports = { BEAT_SCHEDULE, ENUM_SAMPLE, SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, blockAttributes, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, parseImport, parseVariable, translateCode, build, run, nextPageName, PAGE_NAME, NAMESPACE, TREE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, typeSegments }; } if (typeof figma !== "undefined") void run(figma); diff --git a/docs/prototype/code-reader/figma-plugin/test.js b/docs/prototype/code-reader/figma-plugin/test.js index 637a8e4..7c3d3ac 100644 --- a/docs/prototype/code-reader/figma-plugin/test.js +++ b/docs/prototype/code-reader/figma-plugin/test.js @@ -2,7 +2,7 @@ const assert = require("node:assert/strict"); const { test } = require("node:test"); const fs = require("node:fs"); const path = require("node:path"); -const { SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, build, run, nextPageName, PAGE_NAME, NAMESPACE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, parseImport, parseVariable, typeSegments } = require("./code.js"); +const { BEAT_SCHEDULE, ENUM_SAMPLE, SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, build, run, nextPageName, PAGE_NAME, NAMESPACE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, parseImport, parseVariable, typeSegments } = require("./code.js"); const { fakeFigma } = require("../../figma-lab/fake-figma"); function action(node) { return node.reactions[0].actions[0]; } @@ -28,11 +28,15 @@ const EXPECTED_SETS = [ ["Reader / ModeToggle", 2], ["Reader / CodeBlock", 18], ["Reader / TableCard", 1], + ["Reader / EnumCard", 1], + ["Reader / CeleryAppCard", 1], + ["Reader / BeatCard", 1], ["Reader / IterationBlock", 3], ["Reader / FilterBar", 3], ["Explorer / TreeRow", 8], ["Window / QuickInput", 1], ["Explorer / Header", 1], + ["Explorer / Sidebar", 3], ["Window / TitleBar", 1], ["Window / ActivityBar", 1], ["Window / StatusBar", 2], @@ -394,6 +398,29 @@ test("the SQLAlchemy rule turns a model class into a table card", async () => { assert.equal(named(named(inviter, "约束"), "Text").characters, "索引 · 外键 sys_user.id(删除时禁止)"); }); +test("enums get their own card with a member table", async () => { + const api = fakeFigma(); + const { enumBoard } = await build(api); + const card = enumBoard.findOne((node) => node.name === `Block / ${ENUM_SAMPLE.name}`); + assert.equal(named(card, "Kind").characters, "枚举"); + assert.equal(card.findAll((node) => node.name.startsWith("Member / ")).length, ENUM_SAMPLE.members.length); + assert.equal(named(named(card.findOne((node) => node.name === "Member / PENDING"), "说明"), "Text").characters, "待结算"); +}); + +test("the Celery rule draws the app and the beat schedule", async () => { + const api = fakeFigma(); + const { celeryBoard } = await build(api); + const app = celeryBoard.findOne((node) => node.name === "Block / celery_app"); + assert.equal(named(app, "Kind").characters, "Celery 应用"); + assert.deepEqual(app.findAll((node) => node.name.startsWith("Prop / ")).map((node) => node.name), + ["Prop / 名称", "Prop / 应用名", "Prop / 消息队列", "Prop / 结果存储"]); + const beat = celeryBoard.findOne((node) => node.name === "Block / beat_schedule"); + assert.equal(named(beat, "Kind").characters, "定时任务"); + assert.equal(beat.findAll((node) => node.name.startsWith("Entry / ")).length, BEAT_SCHEDULE.entries.length + 1); + const entry = beat.findOne((node) => node.name === "Entry / deployment.notify_expiring_deployments"); + assert.equal(named(named(entry, "频率"), "Text").characters, "每天"); +}); + test("boards and sets sit on the page without overlapping", async () => { const api = fakeFigma(); const result = await build(api); @@ -416,7 +443,7 @@ test("the plugin stays small enough for Figma to build quickly", async () => { if (node.type !== "INSTANCE") node.children.forEach(walk); }; result.page.children.forEach(walk); - // 卡死那次是 5000 多个图层,而且每次读宽度都逼 Figma 重排;现在 16 张画板、36 张属性表约 2600 个 + // 卡死那次是 5000 多个图层,而且每次读宽度都逼 Figma 重排;侧栏做成共用组件后,现在 20 张画板约 2800 个 assert.ok(owned < 3000, `page owns ${owned} layers outside instances`); });