Files
marqdo/doc/adr/0007-web-document-endpoint.md
T
cflmyandCursor 67bac1bf02 feat(web): Document/Endpoint/Resource artifact rewrite (ADR 0007)
Replace the monolithic compose_*/configure author surface with file-level
web|endpoint artifacts, split ext/{web,data,security,net}, and lock
no-degrade rules so the model cannot regress to God-object APIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:06:38 +08:00

3.7 KiB
Raw Blame History

ADR 0007:Web Document / Endpoint / Resource(破坏性 · 代码即文档)

Status Accepted
Date 2026-09-28
Related ext-web-artifact.md · ext-web.md · binding.md · ADR 0006 · layers.md · doc/next/007.md

Context

  • ext/web/web.mq.md 已膨胀为小型 Web Framework(Page God Object、configure 垃圾抽屉、碎片 Table DSL、隐式路由),与 Marqdo「代码即文档」冲突。
  • doc/next/007.md 提出 Document / Endpoint / Resource 三原语与拆分 ext/web · ext/net · ext/data · ext/security。
  • 现行 ext-web.md C1 禁止为 web 改核心;Document/Endpoint 装载识别需要 Language/Runtime 参与(复用 Artifact Metadata type,不新增 CORE_CONSTRUCTS 标记)。
  • Binding(ADR 0006)已提供文件级 Metadata;type: prompt 先例在扩展侧消费 metadata。

Decision

  1. 采纳 Document / Endpoint / Resource 为 Web 模型一等公民;正式规范见 ext-web-artifact.md。
  2. 修订 ext-web C1:允许核心在装载期识别 type: web|endpoint(及中文 类型: 网页|端点)并暴露 artifact 分类;装配 / HTTP / DB 语义仍在 ext + plugin。单元格求值、import 句法、CORE_CONSTRUCTS 计数不变。
  3. 文件级 Artifact only:不在 ## 函数体嵌套 --- frontmatter(与 Binding Phase 1 / 解析器一致)。
  4. 破坏性重写作者面:删除 compose_* 碎片 DSL、god # page 变异堆、app.configure 多参数抽屉、作者 ensure_plugin;examples 与 tests/ext/web* 同步重写。
  5. 目录定稿(007 §三十五 + §四十):
    • ext/web/ — page · route · component · dom · client · facade
    • ext/net/ — http · websocket · url
    • ext/data/ — db · cache · storage
    • ext/security/ — auth · oidc · rbac
  6. 统一 View 表:| type | slot | value | attrs | style |;Table = Data,禁止每函数私有方言。
  7. declared vs system routes:用户 route 须声明;/_part · /_form 等为 system,经 web.inspect 可见。
  8. import = capability:import web:… 由 facade 自动加载 native plugin;作者程序不写 ensure_plugin / host_*。
  9. Metadata v1 锁定(原 007 未决项):
    • 发现:web.serve root= 扫描 root/**/*.mq.md,仅注册 type/类型 ∈ {web,网页,endpoint,端点} 的文件;无 type 的库文件忽略。
    • Data:仅 flat 键 data_source · data_order · data_where(text;where 为 col=val 逗号分隔)。嵌套 YAML data: 推迟。
    • Result:{ok: bool, value: any, error: text|None}。
    • Realtime 模块名:ext/net/websocket.mq.md(ZH:实时.mq.md)。
    • ZH metadata:类型←type,路由←route,方法←method,路径←path,请求←request,响应←response,鉴权←auth,数据源←data_source,排序←data_order,条件←data_where。

Consequences

Positive

  • .mq.md 同时是文档、路由、实现与鉴权声明。
  • 与 LLM/Agent Artifact Metadata 统一心智。
  • 职责边界清晰,可独立演化 data/security/net。

Negative / Risks

  • 破坏性:全部现有 web 作者程序与 smokes 必须改写。
  • Endpoint 热路径仍经 plugin → CallLibPath / 文件装载回调;须保持 ABI 稳定演进。
  • flat data 键表达力弱于嵌套 YAML;后续另 ADR。

Neutral

  • 不新增 Markdown 核心标记;${…} 仍仅 Metadata。
  • Go plugins/web 可分波删除死 compose ABI;作者面先断。