@quantacenter/quanta-problem-cli 0.0.0-stage → 1.0.0

package/templates/backend_service/template/pnpm-lock.yaml

@@ -0,0 +1,9 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .: {}

package/templates/backend_service/template/server.js

@@ -0,0 +1,28 @@
+import { createServer } from 'node:http';
+
+// 答案模板：实现待办清单 HTTP API（GET /health → 200 {ok:true}；GET /items → 200 {items:[]}；POST /items → 201 {item}，title 为空 400），改完用 curl 自验。
+const sendJson = (res, status, body) => {
+   const payload = JSON.stringify(body);
+   res.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'content-length': Buffer.byteLength(payload),
+   });
+   res.end(payload);
+};
+
+const server = createServer((req, res) => {
+   const url = new URL(req.url ?? '/', 'http://localhost');
+
+   if (req.method === 'GET' && url.pathname === '/health') {
+      return sendJson(res, 200, { ok: true });
+   }
+
+   // TODO: 实现 GET /items 与 POST /items
+
+   return sendJson(res, 404, { error: 'not_found' });
+});
+
+const port = Number(process.env.PORT || process.env.QUANTA_PORT || 3000);
+server.listen(port, () => {
+   console.log('todo-api listening on ' + port);
+});

package/templates/frontend/README.md

@@ -0,0 +1,34 @@
+# {{title}}
+
+本目录由 `qpc init` 生成，包含出题所需的全部文件。
+
+## 目录结构
+
+```
+problem.config.ts   题目配置（标题、难度、标签、运行命令）
+judge.js            判题脚本（真源；判分逻辑都在这里）
+template/           答案模板：学生从这里开始，通常拿低分
+answer/             参考解：必须拿满分，首屏截图会当作封面
+```
+
+## 标准流程
+
+```bash
+# 1. 本地预检（毫秒级，先挡掉静态错误）
+qpc check
+
+# 2. 上传并等待审计（生成题目版本，审计约 20 秒）
+qpc upload --wait
+
+# 3. 审计通过后发布
+qpc publish <problemId>
+```
+
+## 需要人工确认的事（预检覆盖不到）
+
+- [ ] 参考解真的能拿满分（看 `qpc upload --wait` 的检查点明细）
+- [ ] 答案模板明显低分（证明判题能抓错）
+- [ ] 断言消息写清"期望 vs 实际"（预检只做启发式提醒）
+- [ ] 封面好看（默认封面 = 参考解首屏截图）
+
+更完整的踩坑清单见仓库 `docs/PROBLEM_AUTHORING.md`。

package/templates/frontend/answer/index.html

@@ -0,0 +1,97 @@
+<!doctype html>
+<html lang="zh-CN">
+   <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width, initial-scale=1" />
+      <title>{{title}}</title>
+      <style>
+         :root {
+            color-scheme: light dark;
+            font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
+         }
+         body {
+            margin: 0;
+            min-height: 100vh;
+            display: grid;
+            place-items: center;
+            background: #f6f7f9;
+            color: #1f2328;
+         }
+         .card {
+            width: min(28rem, 90vw);
+            padding: 2rem;
+            border-radius: 1rem;
+            background: #fff;
+            box-shadow: 0 12px 32px rgb(15 23 42 / 12%);
+         }
+         h1 {
+            margin: 0 0 1rem;
+            font-size: 1.25rem;
+         }
+         .count {
+            margin: 0 0 1rem;
+            font-size: 1.5rem;
+         }
+         .actions {
+            display: flex;
+            gap: 0.75rem;
+         }
+         button {
+            padding: 0.5rem 1rem;
+            border-radius: 0.5rem;
+            border: 1px solid #d0d7de;
+            background: #fff;
+            font-size: 1rem;
+            cursor: pointer;
+         }
+         button:disabled {
+            opacity: 0.5;
+            cursor: not-allowed;
+         }
+         #tip {
+            min-height: 1.5rem;
+            margin: 1rem 0 0;
+            color: #1a7f37;
+            font-weight: 600;
+         }
+      </style>
+   </head>
+   <body>
+      <main class="card">
+         <h1>{{title}}</h1>
+         <p class="count">当前计数：<span id="count">0</span></p>
+         <div class="actions">
+            <button id="inc" type="button">+1</button>
+            <button id="reset" type="button" disabled>重置</button>
+         </div>
+         <p id="tip"></p>
+      </main>
+      <script type="module">
+         const countEl = document.querySelector('#count');
+         const tipEl = document.querySelector('#tip');
+         const incBtn = document.querySelector('#inc');
+         const resetBtn = document.querySelector('#reset');
+
+         let count = 0;
+
+         const render = () => {
+            countEl.textContent = String(count);
+            tipEl.textContent = count >= 3 ? '已达标' : '';
+            resetBtn.disabled = count === 0;
+         };
+
+         incBtn.addEventListener('click', () => {
+            count += 1;
+            render();
+         });
+
+         resetBtn.addEventListener('click', () => {
+            count = 0;
+            render();
+         });
+
+         render();
+
+      </script>
+   </body>
+</html>

package/templates/frontend/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+# qpc 的本地缓存（预检产物、审计快照）
+.qpc/
+.DS_Store

package/templates/frontend/judge.js

@@ -0,0 +1,41 @@
+// 判题脚本必须写成 `export default defineTestHandler(...)`：判题机会把 "export default " 替换成 "const run = " 再执行。
+export default defineTestHandler(async ({ page, $ }) => {
+   const text = async (selector) => {
+      const element = await page.$(selector);
+      if (!element) throw new Error('找不到元素 ' + selector);
+      return (await element.textContent()).trim();
+   };
+
+   // 目标按钮可能 disabled：Playwright click 会重试到 30 秒超时，需要"即使禁用也点一下"时改用合成事件。
+   const clickEvenIfDisabled = async (selector) => {
+      await page.$eval(selector, (element) => {
+         element.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+      });
+      await page.waitForTimeout(150);
+   };
+
+   $.defineCheckPoint('初始计数为 0', 5, async () => {
+      const actual = await text('#count');
+      $.expect(actual === '0', '期望 #count 为 "0"，实际为 "' + actual + '"');
+      return 5; // 必须 return 本检查点得分：不返回即使断言全过也记 0 分
+   });
+
+   $.defineCheckPoint('点击 3 次后计数为 3', 10, async () => {
+      for (let i = 0; i < 3; i += 1) {
+         // 这个按钮本就应该可用：用真实 click 并加短超时，失败时快速暴露
+         await page.click('#inc', { timeout: 3000 });
+      }
+      const actual = await text('#count');
+      $.expect(actual === '3', '期望 #count 为 "3"，实际为 "' + actual + '"');
+      return 10;
+   });
+
+   $.defineCheckPoint('计数达到 3 后提示已达标', 5, async () => {
+      const actual = await text('#tip');
+      $.expect(actual === '已达标', '期望 #tip 为 "已达标"，实际为 "' + actual + '"');
+      return 5;
+   });
+
+   // 需要验证"禁用状态下点击不生效"时用：await clickEvenIfDisabled('#reset');
+   void clickEvenIfDisabled;
+});

package/templates/frontend/problem.config.ts

@@ -0,0 +1,34 @@
+import { defineProblemConfig } from '@challenge/problem-creator-cli';
+
+// 出题配置。字段说明见 packages/problem-creator-cli/README.md
+export default defineProblemConfig({
+   title: '{{title}}',
+   detail: [
+      '## 题目要求',
+      '',
+      '用一两句话写清"学生要做什么"，以及判分关注的行为。',
+      '',
+      '- 点击 +1 按钮，当前计数加一',
+      '- 计数达到 3 时显示"已达标"',
+      '- 计数为 0 时重置按钮不可用',
+      '',
+      '## 提示',
+      '',
+      '题面支持 Markdown，会原样展示给学生。',
+   ].join('\n'),
+   difficulty: '{{difficulty}}',
+   tagIds: [{{tagIds}}],
+   // totalScore 留空时以检查点之和为准，填写则必须与之相等，否则审计失败（见 CFG001）。
+   cover: { mode: 'default' },
+   // 后端题型需自定义封面：cover: { mode: 'custom', generate: { bg: '#0F172A', bgTo: '#14432A', subtitle: 'GET /health' } }，再跑 qpc cover --upload --write。
+   runtime: {
+      // 判题打包目录，同时决定快照键前缀（/project/...）
+      judgeUploadPath: '{{mountPath}}',
+      initCommand: '{{initCommand}}',
+   },
+   paths: {
+      template: 'template',
+      answer: 'answer',
+      judge: 'judge.js',
+   },
+});

package/templates/frontend/template/index.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="zh-CN">
+   <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width, initial-scale=1" />
+      <title>{{title}}</title>
+      <style>
+         :root {
+            color-scheme: light dark;
+            font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
+         }
+         body {
+            margin: 0;
+            min-height: 100vh;
+            display: grid;
+            place-items: center;
+            background: #f6f7f9;
+            color: #1f2328;
+         }
+         .card {
+            width: min(28rem, 90vw);
+            padding: 2rem;
+            border-radius: 1rem;
+            background: #fff;
+            box-shadow: 0 12px 32px rgb(15 23 42 / 12%);
+         }
+         h1 {
+            margin: 0 0 1rem;
+            font-size: 1.25rem;
+         }
+         .count {
+            margin: 0 0 1rem;
+            font-size: 1.5rem;
+         }
+         .actions {
+            display: flex;
+            gap: 0.75rem;
+         }
+         button {
+            padding: 0.5rem 1rem;
+            border-radius: 0.5rem;
+            border: 1px solid #d0d7de;
+            background: #fff;
+            font-size: 1rem;
+            cursor: pointer;
+         }
+         button:disabled {
+            opacity: 0.5;
+            cursor: not-allowed;
+         }
+         #tip {
+            min-height: 1.5rem;
+            margin: 1rem 0 0;
+            color: #1a7f37;
+            font-weight: 600;
+         }
+      </style>
+   </head>
+   <body>
+      <main class="card">
+         <h1>{{title}}</h1>
+         <p class="count">当前计数：<span id="count">0</span></p>
+         <div class="actions">
+            <button id="inc" type="button">+1</button>
+            <button id="reset" type="button" disabled>重置</button>
+         </div>
+         <p id="tip"></p>
+      </main>
+      <script type="module">
+         // TODO: 实现计数逻辑：点击 #inc 加一并更新 #count，达到 3 时 #tip 显示"已达标"，为 0 时禁用 #reset。
+
+      </script>
+   </body>
+</html>