@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.2

package/templates/webapp/csr-bff/README.md

@@ -0,0 +1,81 @@
+# {{APP_NAME}} — 前后端分离（CSR + BFF）参考模板
+
+**形态**：7 个真实静态页（`index/article/blogger/login/signup/admin/profile`）+ `style.css` + `blog.js`，由 proxy 静态分支直发（**不启 worker**）；所有数据/认证走同源 `./api/*` 打到 Deno BFF worker，worker 再转发到实例**内网**的 `/rest/v1`、`/auth/v1`。
+**会话模型**：`proxy-injected` —— 浏览器不直连 Supabase；登录经平台 `./_session/login` 建立 per-mount HttpOnly cookie，proxy 校验后向 worker 注入 `X-App-User-*`，worker 用 `X-App-User-Token` 作为下游 `Authorization`，由 GoTrue/MysqlREST 的 RLS 做最终裁决。
+
+## 为什么 BFF 不能靠"透传浏览器 Authorization"
+
+`/apps/{mount}/api/*` 走 `TRUSTED_INTERNAL` 凭据策略，proxy 会剥掉客户端的
+`authorization / cookie / apikey / x-api-key`。实测判据：同一 token 直连公网 `/auth/v1/user` 得 200，
+经 BFF 透传却得 `403 bad_jwt: invalid claim: missing sub claim` —— 说明中间层剥了头，worker 恒回落 anon。
+因此本模板的身份来源**只有**注入头：
+
+```ts
+const injected = req.headers.get("x-app-user-token") || "";   // 方案 C
+const userAuth = injected || incomingAuth;                     // 兼容 /functions 入口的透传
+```
+
+前端侧对应：登录/注册成功后追加 `fetch("./_session/login")` 建立 cookie，`clearToken()` 时
+`fetch("./_session/logout", { keepalive: true })`（`keepalive` 保证跳转后请求仍能完成）；
+端点不存在时静默忽略，以兼容旧实例与 `/functions` 入口。
+
+## 目录
+
+```
+{{APP_NAME}}/
+├── app.json                  # schemaVersion 2；fallback=null（页面都是真实静态文件）
+├── backend/index.ts          # BFF worker：/api/health /api/config /api/me /api/rest/* /api/auth/*
+├── frontend/dist/            # 7 个页面 + style.css + blog.js（相对路径引用）
+├── db/schema.sql             # 幂等数据层：posts + 5 条 RLS + 3 篇种子
+└── README.md
+```
+
+`fallback: null` 意味着静态未命中即 404（不落到 worker）；BFF 只经 `/api/*` 访问，因此不需要 SSR 探针。
+
+## 部署前必须做的一件事：填 DEPLOY CONFIG
+
+`backend/index.ts` 顶部两个常量默认为空；留空时除 `/api/health` 外一律返回
+`503 {"error":"deploy config missing"}`（刻意设计：绝不回落到任何真实实例）。
+
+```ts
+const INTERNAL_BASE = "";   // 目标实例内网基址（公网 host 去掉 http./https. 中缀）
+const ANON_KEY = "";        // 单租户=实例 anon；多租户=该租户 anon
+```
+
+worker 只用 anon 作 Kong 的 `apikey`，并把用户 JWT 原样带给下游；**从不使用 service_role**，
+因此它拿到的权限不会超过调用者本人。
+
+## 数据层
+
+```bash
+sed 's/__SCHEMA__/public/g' db/schema.sql          # 单租户
+sed 's/__SCHEMA__/tenant_acme/g' db/schema.sql     # 多租户
+```
+
+RLS 元数据写**中心库** `supabase._mysqlrest_rls_*`，`table_schema` = 上面的 `__SCHEMA__`；写错静默失效。
+
+## 部署
+
+```bash
+pxbaas app deploy {{APP_NAME}} --dir .     # appName 必须与 app.json 的 name 一致
+```
+
+走 curl Management API 时：静态文件必须用显式嵌套 `filename=frontend/dist/<name>`，否则路径被压平导致 publish 报缺文件。
+
+## 验收清单
+
+| # | 检查 | 期望 |
+|---|---|---|
+| 1 | 7 个页面 + `style.css` + `blog.js` | 全 200，content-type 正确（`text/css` / `text/javascript`） |
+| 2 | `GET /apps/{m}/api/health` | `{"ok":true,"via":"bff"}`（未配置 DEPLOY CONFIG 时也应可用） |
+| 3 | `GET /apps/{m}/api/config` | 返回的 `anon` **等于目标实例/租户的 anon**（证明参数化生效，没串到别的实例） |
+| 4 | `GET /apps/{m}/api/rest/posts` 匿名 | 只见 published |
+| 5 | `POST /apps/{m}/_session/login` | 200 + `Set-Cookie: pxbaas-app-session; Path=/apps/{m}/; HttpOnly` |
+| 6 | **只带 cookie**（不带 Authorization）`GET /api/me` | 返回完整用户对象 |
+| 7 | 带 cookie 发文（`author_id`=自己 / 他人） | 201 / **403 PGRST302** |
+| 8 | 带 cookie 读 posts | published + 自己的 draft |
+| 9 | `POST /api/../_session/logout` 后 `GET /api/me` | `{"user":null}` |
+| 10 | 双用户交替请求 | 各自只见自己（无共享 jar 串味） |
+
+> 注意：`logout` 页靠内联 JS 调 `./_session/logout`，**curl 不执行 JS**，用 curl 复验时要直接打 proxy 的退出端点。
+> 另：在容器内以 `Host: 127.0.0.1:8000` 打 `/apps/*` 会得到 `APP_HOST_REJECTED`，属预期；验证请从公网侧发起。

package/templates/webapp/csr-bff/backend/index.ts

@@ -0,0 +1,168 @@
+// mpa-blog BFF worker (front/back separated).
+//
+//   browser ──./api/*──> THIS worker ──internal DNS──> /rest/v1 + /auth/v1 ──> db / GoTrue
+//
+// The sandbox CANNOT reach the instance's public SUPABASE_URL (egress-filtered), but CAN reach
+// the internal/private DNS entry (pxsp-<id>.pxbaas...:8000 -> 10.x VPC VIP). So the worker proxies
+// browser calls to the internal Kong base. Credential model = JWT PASSTHROUGH: the browser's
+// Authorization header (GoTrue user JWT) is forwarded verbatim so MysqlREST RLS and GoTrue enforce
+// per-user rules server-side. The worker injects only the global `apikey` (anon) for Kong key-auth
+// and NEVER uses service_role, so it gains no privilege beyond the calling user.
+//
+// Static pages/assets are served by the edge-function-proxy static branch (app.json mode=mpa);
+// this worker only handles /api/*.
+
+const CORS: Record<string, string> = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PATCH, PUT, DELETE, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, Prefer, Range, X-Tenant-Id",
+  "Access-Control-Expose-Headers": "Content-Range, Prefer, Location",
+};
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8", ...CORS },
+  });
+}
+
+// ─── DEPLOY CONFIG（平台注入优先；缺失则除 /api/health 外一律 503，绝不回落到任何真实实例）───
+// env 契约（MR #30497903 起）：平台按三键白名单向 App candidate 注入 SUPABASE_INTERNAL_URL /
+//   SUPABASE_ANON_KEY / SUPABASE_URL，spec-lint 的 deno-env-not-allowed 放行这三键。本模板直读
+//   SUPABASE_INTERNAL_URL（数据面唯一可达基址）与 SUPABASE_ANON_KEY（数据面凭据），无需手填明文 key。
+//   若目标实例 sandbox 镜像尚未含该 MR，两值为空 → configError 明确 503，绝不静默连到别的实例/租户。
+//   INTERNAL_BASE —— 平台注入的内网基址（公网 host 去掉 http./https. 中缀）；公网 VIP 在沙箱内因
+//                    egress 过滤不可达（非 hairpin），切勿改填公网地址。
+//   ANON_KEY      —— 单租户=实例 anon key；多租户=**该租户** anon key（自带 tenant_id claim，
+//                    REST/Auth 据此路由，无需 X-Tenant-Id）。anon 是公开值；service_role 严禁入 worker。
+const INTERNAL_BASE = Deno.env.get("SUPABASE_INTERNAL_URL") ?? "";
+const ANON_KEY = Deno.env.get("SUPABASE_ANON_KEY") ?? "";
+
+function configError(): string | null {
+  if (!INTERNAL_BASE) return "SUPABASE_INTERNAL_URL not injected: the sandbox image predates MR #30497903; the platform must inject the internal base before this BFF can reach the data plane";
+  if (!ANON_KEY) return "SUPABASE_ANON_KEY not injected: the sandbox image predates MR #30497903; the platform must inject the anon key";
+  return null;
+}
+
+function anonKey(): string {
+  return ANON_KEY;
+}
+
+/** 服务端转发唯一合法通道：内网基址（见上方 DEPLOY CONFIG）。 */
+function internalBase(): string {
+  return INTERNAL_BASE.replace(/\/+$/, "");
+}
+
+/** Extract the segments after the "api" marker, robust to mount/dispatch prefix differences. */
+function apiTail(pathname: string): string[] {
+  // Mount/webapp dispatch hands the worker the candidate-slug-prefixed logical path
+  // (/{app_<uuid>_r_<rev>}/...); strip that first, then locate the "api" marker.
+  const norm = pathname.replace(/^\/app_[^/]+/, "") || pathname;
+  const segs = norm.split("/").filter(Boolean);
+  const i = segs.lastIndexOf("api");
+  if (i >= 0) return segs.slice(i + 1);
+  return segs; // fallback: whole path
+}
+
+async function readBody(req: Request): Promise<BodyInit | null> {
+  if (req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS") return null;
+  try {
+    return await req.arrayBuffer();
+  } catch {
+    return null;
+  }
+}
+
+/** Forward a request to the internal Kong base, injecting apikey and passing through the user's JWT. */
+async function proxy(req: Request, internalPath: string, search: string): Promise<Response> {
+  const base = internalBase();
+  const url = base + internalPath + (search || "");
+  const anon = anonKey();
+  // /apps/{mount}/api/* runs under TRUSTED_INTERNAL, which strips the browser's
+  // Authorization/Cookie before the worker ever sees them, so plain JWT passthrough
+  // cannot work on that entry. There the proxy validates the per-mount session
+  // cookie and injects the trusted X-App-User-Token instead. Prefer the injected
+  // token, fall back to a passed-through Authorization (/functions entry), then to
+  // anon for public reads.
+  const injected = req.headers.get("x-app-user-token") || "";
+  const incomingAuth = req.headers.get("Authorization") || "";
+  const userAuth = injected || incomingAuth;
+  const authValue = userAuth
+    ? (/^Bearer\s+/i.test(userAuth) ? userAuth : `Bearer ${userAuth}`)
+    : (anon ? `Bearer ${anon}` : "");
+
+  const headers: Record<string, string> = {
+    "apikey": anon,
+    // Forward the caller's JWT (RLS/GoTrue act on it); fall back to anon for public reads.
+    "Authorization": authValue,
+    "Accept": req.headers.get("Accept") || "application/json",
+  };
+  const ct = req.headers.get("Content-Type");
+  if (ct) headers["Content-Type"] = ct;
+  const prefer = req.headers.get("Prefer");
+  if (prefer) headers["Prefer"] = prefer;
+
+  const body = await readBody(req);
+  let upstream: Response;
+  try {
+    upstream = await fetch(url, { method: req.method, headers, body });
+  } catch (e) {
+    const msg = String((e as any)?.message ?? e);
+    return json({ error: "upstream_unreachable", detail: msg, internalBase: base, internalPath }, 502);
+  }
+
+  const respHeaders: Record<string, string> = { ...CORS };
+  const rct = upstream.headers.get("Content-Type");
+  if (rct) respHeaders["Content-Type"] = rct;
+  for (const h of ["Content-Range", "Prefer", "Location"]) {
+    const v = upstream.headers.get(h);
+    if (v) respHeaders[h] = v;
+  }
+  // 204/205/304 are "null body" statuses: constructing a Response with a body throws.
+  // PostgREST returns 204 for DELETE/PATCH without Prefer: return=representation.
+  if (upstream.status === 204 || upstream.status === 205 || upstream.status === 304) {
+    return new Response(null, { status: upstream.status, headers: respHeaders });
+  }
+  const payload = await upstream.arrayBuffer().catch(() => new ArrayBuffer(0));
+  return new Response(payload, { status: upstream.status, headers: respHeaders });
+}
+
+Deno.serve(async (req: Request): Promise<Response> => {
+  if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS });
+
+  const url = new URL(req.url);
+  const tail = apiTail(url.pathname);
+  const head = (tail[0] || "").toLowerCase();
+  const search = url.search || "";
+
+  // ---- worker-local endpoints ----
+  if (head === "health") return json({ ok: true, now: new Date().toISOString(), via: "bff" });
+  const cfgErr = configError();
+  if (cfgErr) return json({ error: "deploy config missing", detail: cfgErr }, 503);
+  if (head === "config") return json({ anon: anonKey(), mode: "bff" });
+  if (head === "me") {
+    // Server-side session check via internal GoTrue, using the caller's JWT.
+    const r = await proxy(req, "/auth/v1/user", "");
+    if (r.status !== 200) return json({ user: null });
+    try {
+      const u = await r.clone().json();
+      return json({ user: u && u.id ? u : null });
+    } catch {
+      return json({ user: null });
+    }
+  }
+
+  // ---- generic authenticated proxies ----
+  // /api/rest/<rest...>  -> internal /rest/v1/<rest...>
+  if (head === "rest") {
+    const sub = tail.slice(1).join("/");
+    return proxy(req, "/rest/v1/" + sub, search);
+  }
+  // /api/auth/<auth...>  -> internal /auth/v1/<auth...>
+  if (head === "auth") {
+    const sub = tail.slice(1).join("/");
+    return proxy(req, "/auth/v1/" + sub, search);
+  }
+
+  return json({ error: "not found", path: url.pathname, tail }, 404);
+});

package/templates/webapp/csr-bff/db/rls.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Declarative RLS for the CSR/BFF blog webapp. Applied by `pxbaas app db-init` (single-tenant AND multi-tenant). table_schema is NEVER declared here: single-tenant binds it to --schema (default public); multi-tenant binds it server-side to the tenant db.",
+  "tables": [
+    { "table": "posts", "rlsEnabled": true, "rlsForced": false }
+  ],
+  "policies": [
+    { "table": "posts", "name": "posts_select_anon", "role": "anon", "command": "SELECT", "using": "`status` = 'published'", "check": null, "permissive": true },
+    { "table": "posts", "name": "posts_select_auth", "role": "authenticated", "command": "SELECT", "using": "`status` = 'published' OR author_id = {{request.jwt.claim.sub}}", "check": null, "permissive": true },
+    { "table": "posts", "name": "posts_insert_auth", "role": "authenticated", "command": "INSERT", "using": null, "check": "author_id = {{request.jwt.claim.sub}}", "permissive": true },
+    { "table": "posts", "name": "posts_update_auth", "role": "authenticated", "command": "UPDATE", "using": "author_id = {{request.jwt.claim.sub}}", "check": "author_id = {{request.jwt.claim.sub}}", "permissive": true },
+    { "table": "posts", "name": "posts_delete_auth", "role": "authenticated", "command": "DELETE", "using": "author_id = {{request.jwt.claim.sub}}", "check": null, "permissive": true }
+  ]
+}

package/templates/webapp/csr-bff/db/schema.sql

@@ -0,0 +1,49 @@
+-- =============================================================================
+-- multi-page-blog-csr — 数据层（幂等，可重复执行）
+--
+-- 用法：把 __SCHEMA__ 替换为目标库名后逐条执行
+--   · 单租户实例：__SCHEMA__ = public
+--   · 多租户实例：__SCHEMA__ = tenant_<tenant_id>
+--   sed 's/__SCHEMA__/public/g' db/schema.sql
+--
+-- 执行通道（推荐）：`pxbaas app db-init <name>` —— 单/多租户通用：
+--   单租户 __SCHEMA__→public 经 /pg/query；多租户 __SCHEMA__ 去限定经 /api/tenant-ddl
+--   用 per-tenant service_role key 执行（GRANT 仅本租户库）。本文件只含 DDL + 种子；
+--   RLS 声明在同目录 db/rls.json，由 db-init 一并应用。
+--
+-- ⚠️ RLS 元数据落点（写错静默失效＝RLS 关闭）：永远写中心库 supabase._mysqlrest_rls_*；
+--    db-init 自动绑定 table_schema（单租户=--schema，多租户=服务端强绑），勿手写库名。
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS `__SCHEMA__`.`posts` (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  title VARCHAR(200) NOT NULL,
+  content MEDIUMTEXT,
+  author_id VARCHAR(64) NOT NULL,
+  author_name VARCHAR(100) DEFAULT '',
+  status VARCHAR(16) DEFAULT 'draft',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+-- ---- RLS 注册与策略：声明在同目录 db/rls.json，由 `pxbaas app db-init` 应用 ----
+--   anon 只读 published；authenticated 读 published 或本人；写/改/删限本人（author_id = jwt.sub）。
+
+-- ---- 种子文章（3 篇 published，幂等）----
+INSERT INTO `__SCHEMA__`.`posts` (title, content, author_id, author_name, status)
+SELECT * FROM (
+  SELECT '前后端分离的博客长什么样' a,
+         '静态多页 + BFF worker：浏览器只跟自己同源的 ./api/* 说话，worker 再转发到内网 REST/Auth，凭据由平台注入的身份头承载，RLS 在服务端兜底。' b,
+         'demo-author' c, '架构笔记' d, 'published' e
+  UNION ALL SELECT '为什么浏览器不该直连数据库网关',
+         '直连意味着 anon key 与用户 JWT 都暴露在页面里，跨域与凭据边界都变复杂；走同源 BFF 后前端只需相对路径，权限判定全部落在服务端。',
+         'demo-author', '安全', 'published'
+  UNION ALL SELECT 'CSR 与 SSR 的取舍',
+         'CSR 首屏靠 JS 拉数据，利于交互复杂、SEO 要求不高的页面；SSR 首屏即内容，利于分享与收录。两者可共存于同一套数据层与 RLS 策略之上。',
+         'demo-author', '随笔', 'published'
+) t WHERE NOT EXISTS (SELECT 1 FROM `__SCHEMA__`.`posts` WHERE title='前后端分离的博客长什么样');
+
+-- ---- 验收 ----
+-- 1) anon 读 posts → 只见 3 篇 published；
+-- 2) 用户 token 写 posts（author_id=自己）→ 201；伪造他人 author_id → 403 PGRST302；
+-- 3) 用户读 posts → 3 篇 published + 自己的 draft。

package/templates/webapp/csr-bff/frontend/dist/admin.html

@@ -0,0 +1,101 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>MPA Blog — 博主管理</title>
+  <link rel="stylesheet" href="./style.css">
+</head>
+<body>
+  <nav><a href="./index.html">← 返回广场</a><a href="./profile.html">我的资料</a><span class="spacer"></span><span id="who" class="muted"></span></nav>
+  <div id="gate"></div>
+  <div id="admin" style="display:none">
+    <h1>写文章</h1>
+    <div class="card">
+      <input id="title" placeholder="标题" maxlength="200">
+      <textarea id="content" rows="5" placeholder="正文（text/markdown，渲染时转义）"></textarea>
+      <select id="status"><option value="draft">draft（草稿）</option><option value="published">published（发布）</option></select>
+      <button id="create">创建</button>
+      <div id="msg" class="muted"></div>
+    </div>
+    <h1>我的文章</h1>
+    <div id="list"><div class="muted">加载中…</div></div>
+  </div>
+  <script src="./blog.js"></script>
+  <script>
+    var gate = document.getElementById('gate');
+    var user = null;
+    BLOG.init().then(function () {
+      if (BLOG.isSharedView()) {
+        gate.innerHTML = '<div class="banner">分享只读视图：管理功能已禁用。请通过函数原始 URL 打开本页进行管理。</div>' +
+          '<div class="muted">下面仅展示公开可见文章。</div>';
+        return BLOG.loadPosts().then(renderList);
+      }
+      return BLOG.me().then(function (m) {
+        if (!m.user) { location.replace('./login.html'); return; }
+        user = m.user;
+        document.getElementById('who').textContent = user.email || user.id;
+        document.getElementById('admin').style.display = '';
+        document.getElementById('create').onclick = create;
+        // 管理列表仅展示本人文章（他人已发布文章在首页/分享视图可见，RLS 服务端强制）
+        return BLOG.loadPosts().then(function (rows) {
+          renderList(rows.filter(function (p) { return p.author_id === user.id; }));
+        });
+      });
+    }).catch(function (e) {
+      gate.innerHTML = '<div class="error">初始化失败: ' + BLOG.esc(e) + '</div>';
+    });
+
+    function renderList(rows) {
+      var el = document.getElementById('list');
+      if (!rows.length) { el.innerHTML = '<div class="muted">暂无文章。</div>'; return; }
+      el.innerHTML = rows.map(function (p) {
+        var ops = '';
+        if (user) {
+          ops = '<span>' +
+            (p.status === 'draft'
+              ? '<button class="ghost" data-act="publish" data-id="' + p.id + '">发布</button> '
+              : '<button class="ghost" data-act="unpublish" data-id="' + p.id + '">转草稿</button> ') +
+            '<button class="danger" data-act="delete" data-id="' + p.id + '">删除</button></span>';
+        }
+        return '<div class="card"><div class="row"><h2><a href="./article.html#id=' + encodeURIComponent(p.id) + '">' +
+          BLOG.esc(p.title) + '</a></h2><span class="badge ' + BLOG.esc(p.status) + '">' + BLOG.esc(p.status) + '</span></div>' +
+          '<div class="row muted"><span>#' + BLOG.esc(p.id) + ' · ' + BLOG.esc(BLOG.fmtDate(p.created_at)) + '</span>' + ops + '</div></div>';
+      }).join('');
+      Array.prototype.forEach.call(el.querySelectorAll('button[data-act]'), function (b) {
+        b.onclick = function () { act(b.getAttribute('data-act'), b.getAttribute('data-id')); };
+      });
+    }
+
+    function create() {
+      var msg = document.getElementById('msg');
+      var body = {
+        title: document.getElementById('title').value.trim(),
+        content: document.getElementById('content').value,
+        status: document.getElementById('status').value,
+        author_id: user.id,
+        author_name: BLOG.displayName() || String(user.email || '').split('@')[0] || '匿名博主',
+      };
+      if (!body.title) { msg.className = 'error'; msg.textContent = '标题不能为空'; return; }
+      fetch(BLOG.rest(), { method: 'POST', headers: BLOG.headers(true), body: JSON.stringify(body) })
+        .then(function (r) {
+          if (!r.ok) return r.text().then(function (t) { throw new Error('HTTP ' + r.status + ' ' + t); });
+          msg.className = 'muted'; msg.textContent = '已创建';
+          document.getElementById('title').value = ''; document.getElementById('content').value = '';
+          return BLOG.loadPosts().then(renderList);
+        }).catch(function (e) { msg.className = 'error'; msg.textContent = String(e); });
+    }
+
+    function act(kind, id) {
+      var patch = kind === 'publish' ? { status: 'published' } : kind === 'unpublish' ? { status: 'draft' } : null;
+      var p = patch
+        ? fetch(BLOG.rest() + '?id=eq.' + encodeURIComponent(id), { method: 'PATCH', headers: BLOG.headers(true), body: JSON.stringify(patch) })
+        : fetch(BLOG.rest() + '?id=eq.' + encodeURIComponent(id), { method: 'DELETE', headers: BLOG.headers(true) });
+      p.then(function (r) {
+        if (!r.ok) return r.text().then(function (t) { throw new Error('HTTP ' + r.status + ' ' + t); });
+        return BLOG.loadPosts().then(renderList);
+      }).catch(function (e) { alert('操作失败: ' + e); });
+    }
+  </script>
+</body>
+</html>

package/templates/webapp/csr-bff/frontend/dist/article.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>MPA Blog — 文章详情</title>
+  <link rel="stylesheet" href="./style.css">
+</head>
+<body>
+  <nav><a href="./index.html">← 返回广场</a><span class="spacer"></span><button id="copylink" class="ghost">复制分享链接</button></nav>
+  <div id="copymsg" class="muted"></div>
+  <div id="view"><div class="muted">加载中…</div></div>
+  <script src="./blog.js"></script>
+  <script>
+    document.getElementById('copylink').onclick = function () {
+      var msg = document.getElementById('copymsg');
+      BLOG.copyText(location.href).then(function (ok) {
+        msg.textContent = ok ? '已复制：' + location.href : '复制失败，请手动复制地址栏：' + location.href;
+        if (!ok) prompt('复制分享链接：', location.href);
+      });
+    };
+    var raw = location.hash.replace(/^#/, '');
+    var id = raw.indexOf('id=') === 0 ? raw.slice(3) : raw;
+    var el = document.getElementById('view');
+    if (!/^\d+$/.test(id)) {
+      el.innerHTML = '<div class="error">缺少文章 ID（正确形式：article.html#id=1）</div>';
+    } else {
+      BLOG.init().then(function () { return BLOG.loadPost(id); }).then(function (p) {
+        if (!p) { el.innerHTML = '<div class="error">文章不存在或不可见（未发布且非作者）。</div>'; return; }
+        if (BLOG.isSharedView() && p.status !== 'published') {
+          el.innerHTML = '<div class="error">该文章尚未发布，分享只读视图不可见。</div>'; return;
+        }
+        el.innerHTML =
+          '<h1>' + BLOG.esc(p.title) + ' <span class="badge ' + BLOG.esc(p.status) + '">' + BLOG.esc(p.status) + '</span></h1>' +
+          '<div class="muted">博主: ' + BLOG.esc(BLOG.authorLabel(p)) + ' · #' + BLOG.esc(p.id) + ' · ' +
+          BLOG.esc(BLOG.fmtDate(p.created_at)) + '</div>' +
+          '<p class="content">' + BLOG.esc(p.content || '') + '</p>';
+      }).catch(function (e) {
+        el.innerHTML = '<div class="error">加载失败: ' + BLOG.esc(e) + '</div>';
+      });
+    }
+  </script>
+</body>
+</html>