# code-notes-kb

**Repository Path**: template-warehouse/code-notes-kb

## Basic Information

- **Project Name**: code-notes-kb
- **Description**: 个人全栈技术知识库：系统化笔记 + 面试题卡，覆盖主流前后端与工程化技术栈。包含 JavaScript/Vue/React/Flutter/Python/Java/TypeScript 等 35+ 技术栈模块，以精美题卡形式呈现核心知识点，适合面试复习与日常学习。
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-08-28
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Code Notes KB — 全栈刷题平台（前后端分离 Monorepo）

![Vue3](https://img.shields.io/badge/web-Vue3%20%2B%20Vite-42b883.svg)
![Node.js](https://img.shields.io/badge/server-Node.js%20REST-339933.svg)
![Flutter](https://img.shields.io/badge/mobile-Flutter%20App-027DFD.svg)
![MySQL](https://img.shields.io/badge/db-MySQL%208-4479A1.svg)
![Commitlint](https://img.shields.io/badge/commit-Conventional%20Commits-orange.svg)

> 把 3300+ 张前端技术题卡从「静态 HTML 仓库」升级为「可学习、可刷题、可录题」的全栈产品：PC Web 学习端 + Flutter 刷题 App + Node.js REST API + MySQL 统一数据层，一个仓库全部搞定。

---

## 🔎 亮点速览

一页看完「这个项目凭什么值得花你二十分钟」，右列全部可在仓内复核：

| 看什么 | 是什么 | 去哪复核 |
|--------|--------|----------|
| 规模 | **3389 道题 / 35 个知识模块 / 5 表 1 视图**（种子 SQL 行数，演示库当前存 3370），题目统一七要素（题号·题目·类型·场景·答案·逻辑·代码演示）+ 出现频率 | `db/seed/import-report.md` 有逐模块对账；起库后 `SELECT COUNT(*) FROM question` |
| 接口 | **28 个路径 / 42 条 method+path**（从真实装配出的 Express 路由表数出来，不是文档表格数）、`GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS` 全动词覆盖，连 `OPTIONS` 都自述能力；写动词默认要票 | 后端自托管 `/api-docs`（Swagger UI，不依赖外网 CDN） |
| 数据哲学 | **仓库零大图**：库里只有文本，题卡 PNG 由 Web 前端实时渲染导出；Web 与 Flutter 共用同一套设计令牌与题卡配色（移动端负反馈不导出图片） | `docs/card-spec.md`（逐值采自旧仓库 3285 张卡，不是设计稿意图值） |
| 数据自由度 | 整库 SQL / 题目 CSV·JSON / 题卡图片 zip（按勾选或按筛选），导出的 SQL 可直接回灌新库 | `/api/export/sql` 的 DDL 取自实库 `SHOW CREATE TABLE`，`ngram` 全文索引一起带走 |
| 学习闭环 | 看书模式（每题 `?q=题目id` 深链可分享）、错题本「答对即出本 + 手动移出 + 再答错自动回本」、技术栈脑图 `/map`（分类 → 技术栈 → 题目逐层展开，点题直达看该题） | `web/README.md` 的「错题本的学习闭环」与「技术栈脑图」 |
| 质量闸 | `pre-commit` 三道：ESLint 9 扁平配置 + `vue-tsc --noEmit` + vitest（**120 例**）；`yarn build` 内置类型检查 | 单测不是摆设：新用例都拿改动前的旧代码跑过，确实会红 |
| 部署 | 自建 MySQL + systemd + Nginx，一份可复制的落服务器流程 | 下文 [🚢 部署到自己的服务器](#-部署到自己的服务器)，每条期望输出都是实测 |
| 诚实度 | 哪些面已经收了（写接口要票、整库导出要票、CORS 白名单）、哪些面仍然开着（读接口匿名可访问、令牌无从吊销）—— 全写在文档里；每个断言标明「实测」还是「推演」 | [🔒 部署边界（外发前必读）](#-部署边界写面已收鉴权外发前必读) |

> 💡 如果这套「四端一体 + 处处实测」的写法帮你在自己的项目里省下了搭脚手架与踩坑的时间 —— 点个 **Star** 就是最直接的支持。内容有误或想要某个模块深讲，欢迎提 [Issue](https://gitee.com/template-warehouse/code-notes-kb/issues/new)；想改题目、加接口，看 [如何贡献](#-如何贡献)。

---

## 📑 目录

[项目特色](#-项目特色) · [系统架构](#-系统架构) · [目录结构](#-目录结构) · [各端定位](#-各端定位) · [快速开始](#-快速开始) · [封板后只加数据](#-封板后只加数据日常维护路径) · [部署边界](#-部署边界写面已收鉴权外发前必读) · [部署到自己的服务器](#-部署到自己的服务器) · [题卡设计规范](#-题卡设计规范) · [提交规范](#-提交规范) · [如何贡献](#-如何贡献) · [常见问题](#-常见问题) · [更新日志](#-更新日志)

> Gitee 网页会另生成一份自动大纲侧栏，读长文时可配合使用。

---

## ✨ 项目特色

- **前后端分离** — Web / Flutter 双端共用同一套 REST API，后端无状态、纯接口
- **纯文本数据层** — 数据库只存题目文本与作答记录，题卡图片全部由前端渲染生成，仓库零大图
- **一键取走数据** — 录入后台头部导整库 SQL（可直接回灌新库）或题目 CSV/JSON；题目分节的题卡图片有两种范围：**表格里勾哪几道就只出哪几张**（跨页保留），没勾选则按当前筛选（含搜索结果）全量出图，逐张渲染成 PNG 后打成一个 zip，规格与旧仓库题卡一致
- **三位一体场景** — 看书模式（一页一题）、刷题模式（顺序/随机/错题本）、录入后台（题目/知识库/字典三分节 CRUD，粘贴识别 + 去重 + 状态流转）
- **同源设计令牌** — `docs/card-spec.md` 定义尺寸/字号/四色主题（含第 8 节 CSS Variables 清单），Web 与 Flutter 生成的题卡视觉 1:1 对齐；卡面颜色**刻意不引用站点 `--kb-*` 令牌**，保证同一道题在任何主题下拍出同一张图
- **规范化工程** — Husky + commitlint 强制 Conventional Commits，Yarn 统一包管理，docker-compose 一键起库

---

## 🧩 系统架构

```mermaid
flowchart TD
    A[🖥️ web<br/>Vue3 + Vite<br/>PC 端：学习 / 刷题 / 录入后台] -->|REST API| S[🚀 server<br/>Node.js<br/>题目 / 练习 / 导入模块]
    B[📱 mobile<br/>Flutter<br/>移动端：驾考宝典式刷题] -->|REST API| S
    S -->|SQL| D[🗄️ db<br/>MySQL 8<br/>module / question / answer_log]
    D -.->|seed/ 存量导入| E[📦 3300+ 历史题卡 HTML]
    C[🎨 docs/card-spec.md<br/>设计令牌 · 题卡版式规范] -.同源.- A
    C -.同源.- B
```

- **单一数据源**：题目只在 `question` 表存一份，Web 与 App 各自渲染题卡（Web 端用 `html-to-image` 导出 PNG；移动端只做阅读与刷题，题卡导出属后台能力不在手机上做）
- **去重体系**：录入题目时后端做归一化 `content_hash` 唯一索引 + ngram 全文近似重复检测
- **状态流转**：新题为「草稿」，人工确认后转「已确认」，只有已确认题目进入刷题池

---

## 📁 目录结构

```
code-notes-kb/
├── web/                    # 🖥️ PC 前端（Vue3 + Vite）
│   └── README.md           #    学习端 / 刷题端 / 录入后台说明
├── server/                 # 🚀 后端（Node.js REST API）
│   └── README.md           #    题目 / 练习 / 存量导入 / 鉴权与可达面说明
├── mobile/                 # 📱 Flutter 刷题 App
│   └── README.md           #    首页 / 刷题 / 统计 三 tab、运行（模拟器/真机/Web）与打包 APK
├── db/                     # 🗄️ 数据库资产（纯文本，不存图片）
│   ├── schema/             #    建表 SQL（module / dict_item / question / answer_log / wrong_book_dismiss）
│   ├── seed/               #    初始化数据与 3389 存量题卡导入产物
│   └── docker-compose.yml  #    本地一键起 MySQL 8
├── docs/
│   └── card-spec.md        # 🎨 题卡设计规范与设计令牌（三端同源）
├── .husky/                 # Git Hooks（pre-commit / commit-msg）
├── commitlint.config.cjs   # 提交信息校验规则
└── package.json            # 根工程：仅承载 hooks 与提交规范
```

---

## 🧱 各端定位

| 端 | 技术栈 | 核心职责 |
|------|--------|----------|
| `web/` | Vue3 + Vite | 看书模式（一页一题，每题 `?q=题目id` 深链可分享）、技术栈脑图 `/map`（35 个技术栈按分类铺成可折叠目录，模块题目懒加载、点题直达该题）、题卡预览、录入后台 `/admin`（题目 / 知识库 / 字典三分节 CRUD，粘贴自动识别、实时去重提示、草稿→已确认流转），后台入口需顶栏登录拿票、按勾选 / 按筛选一键批量导出题卡图片（zip）、错题本就地重做与移出（学习闭环）、个人中心 `/me`（身份卡 + 我的成绩/近 14 天趋势/模块分布/最近流水/错题待复习，消费只读接口 `GET /api/stats/me`） |
| `server/` | Node.js REST | 题目增查（hash 去重 + 近似重复检测）、分类、分页、答题记录、错题本（答对即出本 + 手动移出标记）、统计、存量 HTML 题卡批量摄取、数据导出（整库 SQL 转储 + 题目 CSV/JSON）、**写面鉴权**（HMAC 令牌 + 登录限速 + CORS 白名单，全部只用 Node 内置能力） |
| `mobile/` | Flutter | 三 tab 客户端：首页（概览 + 一键开练 + 模块宫格 + 全站错点榜）、刷题（顺序/随机/模拟组卷/错题本四模式 → 一题一屏「记住了/没记住」自评 → 答题卡回跳 → 交卷小结与整卷成绩）、统计（我的成绩/题库构成/掌握度分布/热点错点榜/设备身份）；详情页代码示例走 `flutter_highlight` 语法高亮，主题与 Web 同源。刻意**不做**录题/题卡导出/后台（属 Web 后台能力） |
| `db/` | MySQL 8 | 五表一视图；题目统一七要素：题号/题目/类型/场景/答案/逻辑/代码演示 + 出现频率（必学/熟悉/已掌握）；类型与场景由字典表开放用户维护 |

---

## 🚀 快速开始

### 环境要求

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| Node.js | **>= 18.18**，推荐 20 LTS | 这不是拍脑袋的保守值：Vite 5 的 `engines` 要 `^18.0.0 \|\| >=20.0.0`，ESLint 9 要 `^18.18.0 \|\| ^20.9.0 \|\| >=21.1.0`，取交集。低于 18.18 时 `yarn lint` 与 `yarn build`（内置 `vue-tsc`）跑不起来。后端本身只依赖 Express，但三端统一到一个版本最省心 |
| yarn | >= 1.22 | 统一包管理器；`web/` 与 `server/` 各自 `yarn install`，根 `package.json` 只承载 hooks |
| MySQL | 8.0.x（**不接受 5.7 与 MariaDB**） | 建库写死 `utf8mb4_0900_ai_ci`（MySQL 8 才有该排序规则）+ `ngram` 全文解析器（MariaDB 无），5.7 上跑 `01-init.sql` 会直接报错 |
| Docker | >= 20.x | 只在走 `db/docker-compose.yml` 一键起库时需要；本机已有 MySQL 服务就不必装 |
| Flutter SDK | 最新 stable（Dart `^3.11`） | 移动端 `mobile/` 是**完整可构建工程**（Android + Web 已实测）；一行 `bash mobile/scripts/run-emu.sh` 按「后端→模拟器→attach」拉起，跑法与三个构建坑见 `mobile/README.md` 第四节 |

### 三步跑起来

```bash
# 1️⃣ 起数据库（二选一）
# 方式 A：Docker 一键起（宿主端口 3307、root 密码 kb_dev_2026）
#   自动执行的只有 db/schema/ 下的建表与模块种子（compose 只挂了 ./schema 到 initdb.d），
#   存量 3389 题在 db/seed/ 下、不属自动初始化范围，必须自己灌进去：
cd db && docker compose up -d && cd ..
docker exec -i code-notes-kb-mysql mysql -uroot -pkb_dev_2026 --default-character-set=utf8mb4 < db/seed/questions.imported.sql
# 方式 B：本机 MySQL80 服务（3306），手动执行建表与种子脚本
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 < db/schema/01-init.sql        # 建库建表
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 < db/schema/02-seed-module.sql # 35 模块 + 字典种子
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 < db/seed/questions.imported.sql # 存量 3389 题卡（幂等）
# （若源仓库题卡有变更，可重跑 node server/scripts/ingest-cards.js 重新生成上述 SQL）

# 2️⃣ 起后端
cd server && yarn install
cp .env.example .env                 # 填写数据库连接；鉴权那几行的用法见代码块下方 🔑 那条说明
yarn dev                             # REST API 服务（http://localhost:6000/api，接口清单见 server/README.md）

# 3️⃣ 起前端
cd ../web && yarn install
yarn dev                             # PC 端页面（http://localhost:6001）
```

> 🔑 后端默认就开着写接口鉴权（`AUTH_ENFORCED` 缺省为 true）：浏览题库、刷题、交卷都不必登录，而**录入后台的增删改与整库导出要先到顶栏「管理员登录」填 `ADMIN_PASSWORD`**（就是 `.env` 里那一行，`.env.example` 给的是占位示例，自用建议换成真随机值）。图省事不想带票的本机开发可在 `.env` 写 `AUTH_ENFORCED=false`，代价是启动面板会红字标出「写接口裸开放」，且顶栏会显示「鉴权未启用」而不是登录入口。

### 一键起全栈（日常开发推荐）

环境就绪后，不必分三个终端，在 `web` 目录一条命令按「数据库 → 后端 → 前端」顺序拉起（端口规划：后端 6000 / 前端 6001 / 数据库沿用本机 MySQL 3306）：

```bash
cd web && yarn serve                 # 逐级检测并启动未运行的服务，已运行的打印 PID 并跳过
cd web && yarn serve:check           # 只检测三个服务状态，不启动任何东西
```

> 🧭 仓库根目录另有一套统一脚本 `scripts/`（`start` / `stop` / `doctor` / `check` / `build` / `mobile` / `db-ingest`），
> 把四端命令收敛成一个根目录入口并套用统一控制台样式（品牌红横幅 + ○●✗◐ 加载状态），功能与用法见 [`scripts/README.md`](./scripts/README.md)。

| 行为 | 说明 |
|------|------|
| 数据库 | 探测 `server/.env` 的 `DB_HOST:DB_PORT`；未运行时启动本机 `MySQL80` 服务，终端权限不足会弹 UAC 请求授权，无该服务才回落 `db/docker-compose.yml` |
| 后端 | 探测 `PORT`（默认 6000），并校验该端口上确实是本项目后端（读根路径导览比对服务标识）；被其它程序占用时会报出占用程序名与 PID，未运行则在 `server` 目录跑 `yarn dev`（nodemon 热重载） |
| 前端 | 探测 6001；未运行则在 `web` 目录跑 `yarn dev`（Vite 自动打开浏览器） |
| 日志 | 子进程输出带 `[server]` / `[web]` 前缀透传至当前终端 |
| 退出 | Ctrl+C 仅停止本次启动的进程，检测时已存在的服务不动 |

> ⚠️ Docker 方式的宿主端口是 3307、密码 `kb_dev_2026`，与 `server/.env` 默认的 3306 / `123456` 不一致，走该方式需同步修改 `.env`。

> 📱 **移动端（Flutter）** 与 PC 前端共用同一 REST API，开发期把 baseUrl 指到本机即可，无需单独起一套后端。模拟器一行拉起（默认 6100 后端 + 已跑的 AVD，幂等不抢端口）：
>
> ```bash
> bash mobile/scripts/run-emu.sh          # 后端 → 模拟器 → flutter run（r 热重载 / R 热重启 / q 退出）
> ```
>
> 模拟器里 baseUrl 用 `http://10.0.2.2:6100/api`（`10.0.2.2` 是模拟器 NAT 里代表宿主机的固定别名，写 `127.0.0.1` 会连到模拟器自己）；真机换成电脑局域网 IP。完整的模拟器/真机/Web 调试与打包步骤见 `mobile/README.md`。

---

## 📦 封板后只加数据（日常维护路径）

代码面自 `seal-2026-10-27` 起冻结，依赖同样不追新（策略见 `docs/CONVENTIONS.md`）。此后日常维护只剩三种动作，全部在 `/admin` 后台完成，**不需要改一行代码**：

| 想做的事 | 操作 | 各端何时看到 |
|----------|------|--------------|
| 加几道题 | 录入后台 → 题目分节 → 新建（缺省存草稿）→ 列表里点「确认」 | 草稿在任何学习端都不可见；确认后首页 / 看书 / 刷题 / 统计 / 脑图按接口口径立即计入 |
| 加一个技术栈 | 知识库分节新建模块（名称 / slug / 分类 / 图标 / 排序） | 模块列表多一行；脑图多一根分支，已确认题为 0 时不给展开箭头（点了没反应才不误导） |
| 加一个分类 | 不用单独建表 —— 把某模块的「分类」改成新值即可（`module.category` 是自由字符串，只要求非空） | 首页分组与脑图各多出一类；分类色带按分类名排序取色，超过 8 个分类才回绕撞色 |

「只加数据」这条链路 2026-10-27 实测过一轮（走 API：录草稿 → 确认 → 删除 → 复原）：Linux 模块 `confirmed 84 → 85`、全库 `3370 → 3371`、`GET /api/questions?status=confirmed&pageSize=100` 回包里含新题、脑图头部与根节点同步显示 3371、画布上 Linux 变 85 题且新题就在首屏；删除后各级计数复原到 3370。新题题号按模块内 `MAX(card_no) + 1` 自动续排，所以删过题的模块会出现跳号（实测有一条显示 `#91` 而模块共 85 题），属预期不是丢题。

三处**不会自动生效**的地方，加完数据记得手动刷：

| 位置 | 为什么不自动 | 怎么刷 |
|------|--------------|--------|
| 脑图 / 首页的模块列表 | 模块 store 全站共享且带 `loaded` 去重，本次进站拉过就不再请求 | 刷新页面，或点脑图头部「重新加载」（带 force） |
| 脑图里已展开模块的题目 | 首屏 100 条缓存在 `stores/map.ts`（不落 localStorage），同一会话内收起再展开直接吃缓存 | 点「重新加载」：清空题目缓存 + 强拉模块列表 |
| 单个模块的超出部分 | 每模块只铺前 100 条（后端 `pageSize` 上限就是 100），其余折叠成「还有 N 题」 | 点那个节点进看书模式看全量 |

草稿态是唯一的人工闸：`status='draft'` 的题不进学习端、不进脑图、不计入「全库 N 张」，所以批量摄取（`server/scripts/ingest-articles.js`）产出的题必须在 `/admin` 逐条确认后才算发布。

---

## 🔒 部署边界：写面已收鉴权（外发前必读）

本项目定位仍是**个人本地知识库**，但接口不再等于「谁都能改」：写动词与整库导出统一要一张服务端签发的 Bearer 令牌，`cors` 的 origin 也从 `*` 收成白名单。下面两侧都得读完 —— 只看到收了哪几面就丢出公网，和只看历史文档以为还是裸开放，都是误判。

**已经收起来的**（下列每一条均为实测，取证命令见本节末尾）：

| 面 | 现在的行为 | 实测结论 |
|----|------------|----------|
| 写接口 | `POST / PUT / PATCH / DELETE` 在 `/api` 汇总路由最前面统一拦截，口径是**默认拒绝**而不是逐条登记 | 未带票一律 `401`，原文 `{"code":40100,"message":"写接口需要登录：POST /questions（未登录：缺少 Bearer 令牌）"}`；新增一个写接口忘了处理只会退成 401（调用方当场发现），不会静默退回可改数据 |
| 免登录名单 | 写动词里只放开三条 | `POST /api/auth/login`（换票入口自己要票就死锁）、`POST /api/practice/submit` 与 `DELETE /api/practice/wrong-book/:id`（匿名刷题动作，按 `user_key` 隔离）；三条实测都能进到业务校验层（各自回 400/404 而不是 401） |
| 整库导出 | 两个导出接口虽是 GET 仍要票（路由级 `requireAuth`） | 未带票 `401`，原文 `{"code":40100,"message":"该接口需要登录（未登录：缺少 Bearer 令牌）"}`；带票 `200` 出文件流；`OPTIONS` 能力自述豁免，否则模块层丢掉自述能力 |
| 跨域 | `cors` 只回白名单内的 origin，缺省只放本机前端开发端口 | 白名单外 origin 的响应根本不带 `Access-Control-Allow-Origin`；预检 `Allow-Headers` 显式含 `Authorization`（漏了这一项登录后写请求全站阵亡）；要回到任意来源必须自己显式写 `ALLOW_ORIGINS=*`，配漏一行不会自动放开 |
| 令牌 | HMAC-SHA256 签名（`kb1.<payload>.<sig>`），只用 Node 内置 crypto，无第三方依赖；带 `exp`，缺省 12 小时 | 改一个字符 / 自己拼 payload / `Basic` 写法 / 把票塞进 `?token=` 全部 `401`：只认 `Authorization: Bearer`（URL 里的票会落进访问日志与浏览器历史，所以刻意不支持） |
| 暴破 | 同一来源 15 分钟内 8 次失败口令即锁，文案不回「还差几次」 | 第 8 次起 `429` + `42900`，且锁定期内正确口令也被挡；未配 `TRUST_PROXY` 时伪造 `X-Forwarded-For` 换不来新槽位 |
| 配置 | 开了鉴权却缺 `AUTH_SECRET` / `ADMIN_PASSWORD`，或密钥短于 16 字符 → **拒绝启动** | 三种坏配置各自报对应项并 `exit 1`，不会带病上线成「以为上了锁、其实锁是空的」；`AUTH_ENFORCED=false` 则照常起，但启动面板红字标出「写接口裸开放」 |

**仍然开着的（外发前必须知道的另一半）**：

- **读接口全部匿名开放**：`GET /api/questions`（含答案字段）、`/api/stats/*`、`/api-docs` 无需登录。这是产品形态决定的 —— 刷题站要对匿名访客开门；要不要收紧成「登录才能看题」是产品决策，不在本次收口范围内。
- **单一管理口令，没有账号体系**：能登录的就是「知道口令那个人」，无从区分谁改的，也无从给某人单独开/收权限。
- **令牌无从服务端吊销**：服务端不建会话表，退出只是客户端丢弃本地那份；票在到期前一直有效。想一次性作废全部只能换 `AUTH_SECRET`（代价是所有客户端同时掉线重登）。
- **监听地址默认仍是 `0.0.0.0`**：同网段设备仍能连进来读题库（但改不了）。真机联调靠的就是这一档；只想本机用则在 `.env` 写 `HOST=127.0.0.1`，启动面板 `◉ 监听范围` 一行实时告诉你当前是哪一档。
- **登录限速计数在进程内存**：多实例各记一份、重启即清零，它不是分布式限流（本项目的既定边界是除 MySQL 外无外部依赖，没引 Redis）。
- **CORS 不是访问控制**：它只约束浏览器能不能读到响应，curl / Flutter 这类客户端根本不送 Origin，也不受白名单影响，它们的门槛是上面那道令牌。

取证口径（服务端跑起来后逐条可复，本次共 52 条全绿）：

```bash
B=http://127.0.0.1:6000/api
curl -s $B/questions -X POST -H 'Content-Type: application/json' -d '{"title":"x"}'   # 401：写接口要票
curl -s $B/export/sql                                                                  # 401：整库转储要票
curl -s $B/practice/submit -X POST -H 'Content-Type: application/json' -d '{"items":[]}' # 400：名单内，进到业务层而不是被鉴权挡住
curl -s -D - -o /dev/null $B/questions?size=1 -H 'Origin: http://evil.example'           # 响应头里没有 Access-Control-Allow-Origin
TOKEN=$(curl -s $B/auth/login -X POST -H 'Content-Type: application/json' -d "{\"password\":\"你的 ADMIN_PASSWORD\"}" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
curl -s -H "Authorization: Bearer $TOKEN" $B/auth/me                                    # code 0：带票自检
curl -s -H "Authorization: Bearer ${TOKEN%?}X" $B/auth/me                               # 401：签名无效（只改一个字符也不行）
```

> ⚠️ 最后一条探针是故意的：改一个字符即被拒，而这条探测会让本机进入失败计数。它不会吃满 8 次阈值，但连续复跑本段要记得限速这件事。

三种场景的处置：

- **只在本机用（默认场景）**：`server/.env` 里填一组真的 `ADMIN_PASSWORD` + `AUTH_SECRET`（生成命令就写在 `.env.example` 对应行上方）即可；连「能连进来」也想关掉就再加 `HOST=127.0.0.1`（实测收口后走本机局域网 IP 直接拒连，`localhost` 照常 200，PC 前端走 Vite 代理不受影响）。
- **要与真机联调（需要对局域网开放）**：保持 `HOST=0.0.0.0`。mobile 端用到的写动作（交卷、移出错题）本就在免登录名单里，客户端不必存票；若将来要它调管理写接口，就得在 Dio 里带上 `Authorization`。这一档下仍建议在路由器/防火墙层限制可访问 6000 的 IP，不要把服务抛在公共 WiFi 下。
- **确实要多人/公网部署**：现在这一层已经挡住「任何网页替浏览器改题库」与「任何能连到端口的人删题」，但仍是一个口令大家用、没有 per-user 隔离与吊销。要做账号体系请在本层之上加用户表并在签发时绑定 `sub`（`core/auth.js` 已留了这个位），网关层的 `HOST` 收口 / 只开 80-443 / 给整库导出加仅本地放行按下面 [🚢 部署到自己的服务器](#-部署到自己的服务器) 继续。

> 🔒 另：`server/.env` 现在存着数据库口令、管理口令与令牌签名密钥三样，已被 `.gitignore` 忽略（仓内只提交 `server/.env.example` 占位版）；外发包前确认自己没把它加进提交，也别把真 `.env` 拷进对外分享的项目压缩包。

---

## 🚢 部署到自己的服务器

> 按「一台 Linux 云主机 + 自建 MySQL 8 + Nginx 同时托管前端静态资源与反代后端」的单机形态写，命令以 Ubuntu 22.04 / Debian 12 为例（CentOS 系把 `apt` 换 `dnf`、`ufw` 换 `firewalld`，其余一致）。三件事说在前面：
>
> 1. **本项目已收写面鉴权**（见[上一节](#-部署边界写面已收鉴权外发前必读)）：写接口与整库导出都要 Bearer 令牌，但读接口仍匿名开放、且只有一把管理口令。下文把 `HOST` 收口到 `127.0.0.1`、只开 80/443、给 `/api/export/sql` 单独加一道仅本地放行的限制 —— 这些不是可选装饰，而是这套流程能安全成立的前提。
> 2. 每条 `curl` / `SELECT` 的期望输出都取自实测（本机 MySQL 8.0.46 + Node 22），不是你所在环境的未知值；对不上就是环境有差异，按「常见故障对照」查。
> 3. 开发用的 `yarn serve`（`web/scripts/serve-all.mjs`）**上不了服务器**：它探的是 Windows 服务名 `MySQL80`、提权走 UAC。服务器上数据库与后端各按下面的步骤常驻。

### 端口规划（先定这一件事，后面全是它的推论）

| 端口 | 谁在听 | 该对谁开放 | 依据 |
|------|--------|------------|------|
| 80 / 443 | Nginx | 公网 | 唯一该开的入口：静态站点 + `/api` 反代 |
| 6000 | server（Node） | **只 `127.0.0.1`** | 由 `HOST` 环境变量控制，不需改代码；留 `0.0.0.0` 且安全组放行 = 任何人可增删题目、可 `DELETE /api/questions/:id` |
| 3306 / 3307 | MySQL | 只本机（或内网网卡） | 跨机部署走内网 + 安全组白名单；永远不对公网开 |

开发期的「前端 6001」在服务器上不存在：Vite dev server 不进生产，静态资源由 Nginx 直接吐 `web/dist/`。

### ① 服务器准备

```bash
# 1) 基础工具 + 专用系统用户（服务被攻破时爆炸半径小；不给它登录 shell）
sudo apt update && sudo apt install -y git nginx curl ca-certificates
sudo useradd -r -s /usr/sbin/nologin kb
sudo mkdir -p /opt/code-notes-kb && sudo chown -R kb:kb /opt/code-notes-kb

# 2) Node 20 LTS：优先用系统包而不是 nvm —— systemd 里要写绝对路径，nvm 装的 Node 每次升级路径会变
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs && node -v          # 期望 v20.x；>= 18.18 才跑得动 lint 与 build

# 3) yarn（项目统一包管理器）
sudo npm i -g yarn && yarn -v

# 4) 时区：库里的 created_at / answered_at 是 DATETIME DEFAULT CURRENT_TIMESTAMP，
#    写入的是 MySQL 进程时区，「今日刷题数」这类按日分组统计跟着它走 —— 系统与库必须一致
sudo timedatectl set-timezone Asia/Shanghai

# 5) 先把仓库拉下来：② 步要执行的 SQL 脚本就在仓里，③④ 步也都在这同一个目录里做
sudo -u kb git clone https://gitee.com/template-warehouse/code-notes-kb.git /opt/code-notes-kb
ls /opt/code-notes-kb/db/schema                      # 能看到 01-init.sql / 02-seed-module.sql 才算拉干净
```

### ② 数据库落地

#### 路线 A：裸装 MySQL 8（推荐生产）

```bash
sudo apt install -y mysql-server
sudo mysql_secure_installation         # 设 root 口令、删匿名账号与 test 库、禁止 root 远程登录
mysql -uroot -p -e "SELECT VERSION()"  # 必须 8.0.x。Debian 12 官方源默认给 MariaDB，需加 MySQL APT 源，
                                       # 否则 01-init.sql 里的 utf8mb4_0900_ai_ci 与 ngram 都不存在，建库直接报错
```

写配置文件再启动 —— **`ngram_token_size` 是只读变量**（实测 `SET GLOBAL ngram_token_size = 2` 报 `ER_INCORRECT_GLOBAL_LOCAL_VAR`），只能在这里设，而且必须在建表**之前**设对：

```bash
sudo tee /etc/mysql/mysql.conf.d/zz-code-notes-kb.cnf >/dev/null <<'EOF'
[mysqld]
character-set-server = utf8mb4
collation-server     = utf8mb4_0900_ai_ci
ngram_token_size     = 2          # 只读变量，与 schema 里的 FULLTEXT ... WITH PARSER ngram 约定一致
default-time-zone    = '+08:00'   # 与上面的系统时区对齐
max_allowed_packet   = 64M        # 整库转储回灌时单条 INSERT 批可能较大，本机实测默认即为 64M
EOF
sudo systemctl restart mysql
mysql -uroot -p -e "SELECT @@version, @@ngram_token_size, @@character_set_server, @@collation_server, @@time_zone\G"
# 期望：@@ngram_token_size = 2，@@collation_server = utf8mb4_0900_ai_ci
```

按顺序执行三个脚本（都自带 `USE \`code-notes-kb\``，所以命令行不必再指定库名）：

```bash
cd /opt/code-notes-kb
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 < db/schema/01-init.sql
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 < db/schema/02-seed-module.sql
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 < db/seed/questions.imported.sql
```

顺序不能换也不能跳：`01` 建库建表 → `02` 灌 35 个模块与字典项（`question` 的 `module_id` / `type_id` / `scene_id` 要引用它们）→ `seed` 才是 3389 道题。后两个都是 `INSERT IGNORE`，中途断了可重跑。

灌完必须对账，不要只看命令退出码：

```bash
mysql -h127.0.0.1 -uroot -p -e "SELECT (SELECT COUNT(*) FROM \`code-notes-kb\`.question) q, (SELECT COUNT(*) FROM \`code-notes-kb\`.module) m, (SELECT COUNT(*) FROM \`code-notes-kb\`.dict_item) d;"
# 实测期望：q=3389 / m=35 / d=11（字典项会随你在后台增删而变，不当硬指标）

mysql -h127.0.0.1 -uroot -p -e "SELECT COUNT(*) AS ngram_hit FROM \`code-notes-kb\`.question WHERE MATCH(title,answer) AGAINST('闭包' IN NATURAL LANGUAGE MODE);"
# 实测期望：7（与接口口径一致：GET /api/questions?keyword=闭包 也回 total=7）—— 这一步同时也验证了 ngram 分词按 2 生效
```

建一个只给后端用的运行账号（**不要用 root 跑服务**）：

```sql
CREATE USER 'kb_app'@'localhost' IDENTIFIED BY '换成你自己的强密码';
GRANT SELECT, INSERT, UPDATE, DELETE, SHOW VIEW ON `code-notes-kb`.* TO 'kb_app'@'localhost';
FLUSH PRIVILEGES;
```

这五项不是猜的，是照着后端真实会跑的语句倒推出来再实测过的：常规读写只需前四项；`/api/export/sql` 要 `SHOW FULL TABLES` 与 `SHOW CREATE TABLE`（只要 SELECT 就够）和 `SHOW CREATE VIEW`（**实测：只授前四项时这一步报 `ER_TABLEACCESS_DENIED_ERROR`，补上 `SHOW VIEW` 才通过**）。`CREATE` / `DROP` 是刻意不给的：运行账号持有 DDL 权限，等于允许它把「重跑建表脚本」变成可能。

> ⛔ **生产库严禁重跑 `db/schema/01-init.sql`**。两条都是实测而不是推演：
> ① 脚本开头紧跟 `USE` 的那三行会 `DROP VIEW v_module_stat` / `DROP TABLE answer_log` / `DROP TABLE question` —— 线上重跑一次，题库与作答流水全没；
> ② 第 5 张表 `wrong_book_dismiss` 的外键指向 `question`，所以上面那次误操作「连删都删不动」：`DROP TABLE question` 直接报 `ER_FK_CANNOT_DROP_PARENT`（实测）—— 那句「可整体重复执行」只在对一个空库首跑时成立（脚本头部注释已按此更正）。
>
> 表结构要演进就走 `ALTER TABLE` 增量（建议存 `db/schema/migrations/`，一条一个文件、带日期前缀）；确实要整库重置：先备份 → `DROP DATABASE` → 再按顺序重跑。（建库语句含 `CREATE DATABASE IF NOT EXISTS`，跑它需要全局 `CREATE` 权限 —— 这也是上面让建库用 root、日常跑服务用 `kb_app` 的原因。）

#### 路线 B：用 `db/docker-compose.yml` 起库

```bash
cd /opt/code-notes-kb/db
# 先 export：只写在单条命令前的环境变量不会活到下一行，否则下面取 $KB_DB_PASSWORD 会拿到空串
export KB_DB_PASSWORD='换成你自己的强密码'
docker compose up -d && cd ..
# ⚠️ compose 只把 ./schema 挂进 /docker-entrypoint-initdb.d，所以自动执行的只有建表 + 模块种子；
#    存量 3389 题必须手动灌，别相信「一键起库就有题」：
docker exec -i code-notes-kb-mysql mysql -uroot -p"$KB_DB_PASSWORD" --default-character-set=utf8mb4 < db/seed/questions.imported.sql
```

走这条路线要同时知道四件事（都是 `docker-compose.yml` 里的真实配置）：

| 项 | 现状 | 服务器上该怎么做 |
|----|------|------------------|
| 宿主端口 | `3307:3306` | `server/.env` 的 `DB_PORT` 跟着写 3307，否则后端连不上 |
| 发布面 | `ports` 不加地址前缀会把端口绑到宿主所有网卡，**而 Docker 发布的端口走 iptables 的 DOCKER 链，ufw 规则拦不住** | 改成 `"127.0.0.1:3307:3306"`，或干脆删掉 `ports` 走容器网络 |
| 启动参数 | `--ngram_token_size=2` 与 `--default-time-zone=+08:00` 已在 `command` 里 | 这比路线 A 省心：不用改 my.cnf，也不会忘 |
| 数据卷 | named volume `kb_mysql_data` | `docker compose down` 不删数据，**`down -v` 会连卷一起删**；备份按下面第 ⑥ 步对库做逻辑备份，而不是拷卷目录 |

### ③ 后端常驻（systemd）

```bash
# 仓库已在 ① 步拉到 /opt/code-notes-kb
cd /opt/code-notes-kb/server
yarn install --frozen-lockfile      # server 是 CommonJS 直跑，无构建产物，这一步只装依赖（含 devDep 中的 nodemon，用不上但不碍事）
cp .env.example .env
```

`.env` 在生产上该长这样（键集就是 `.env.example` 里那十三个，没有隐藏开关；前八个与 `server/src/core/db.js` 一一对应，后五个是接口鉴权与跨域，外加一行默认注释掉的 `TRUST_PROXY`）：

```bash
# 先现场生成两个随机值，别用占位符里那个示例串上线
ADMIN_PWD=$(node -e "console.log(require('crypto').randomBytes(16).toString('base64url'))")
AUTH_SEC=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
echo "ADMIN_PASSWORD=$ADMIN_PWD"   # 记进你的密码管理器：前端顶栏登录时就要填它
```

```ini
PORT=6000
HOST=127.0.0.1            # ← 生产必改：默认 0.0.0.0 是为真机联调准备的；写接口已要票，但同网段仍能匿名读全库，没必要留着
DB_HOST=127.0.0.1
DB_PORT=3306               # 走上面的 Docker 路线则改成 3307
DB_USER=kb_app
DB_PASSWORD=上一步建的那个强密码
DB_NAME=code-notes-kb
DB_POOL_SIZE=10

AUTH_ENFORCED=true         # 缺省就是 true；只有显式写 false 才关掉（关掉后写接口回到裸开放，面板会红字提醒）
ADMIN_PASSWORD=$ADMIN_PWD  # 上面生成的那个；缺它服务根本起不来（启动自检会拦）
AUTH_SECRET=$AUTH_SEC      # 令牌签名密钥，不少于 16 字符；换了它 = 之前签发的票全部立刻作废
AUTH_TOKEN_TTL=43200       # 票有效期（秒），12 小时；调大等于给泄漏的票更长的可用窗口
ALLOW_ORIGINS=https://你的站点域   # 逗号分隔、精确匹配、含协议与端口、结尾不带斜杠；Nginx 同源反代下前端请求根本不送跨域头，这一行主要保护的是「万一有人把别的网页递到用户浏览器里」
# TRUST_PROXY=1            # 只有确认前面就是同机 Nginx 时才设：不设则限速按 socket 地址记账（⑦ 上线自检清单里会验这件事），设错等于任何人都能靠一个请求头换限速槽位
```

**先在前台跑一次**再交给 systemd —— 启动时先跑鉴权配置自检（缺 `AUTH_SECRET` / `ADMIN_PASSWORD` 或密钥过短直接 `exit 1`，决不会带病上线成一个「以为上了锁其实锁是空的」的实例），接着 `collectBootInfo()` 探库（`SELECT DATABASE()` + 题目/模块计数），连不上也直接 `process.exit(1)`，前台能立刻看到原因；而后端不存 session、不写本地文件，无状态，所以重启不丢任何东西（已签发的票也不受重启影响，它只靠签名校验）：

```bash
node src/server.js
# 别看面板好看就以为健康，同时另开一个终端：
curl -s http://127.0.0.1:6000/api/health
# 实测原文（已含 auth 段，前端顶栏靠它判定“这台实例到底上没上锁”）：
# {"code":0,"message":"ok","data":{"status":"ok","db":{"connected":true,"name":"code-notes-kb","questions":3389,"modules":35},"uptime":86,"auth":{"enforced":true,"tokenTtl":43200}}}
curl -s -X POST http://127.0.0.1:6000/api/questions -H 'Content-Type: application/json' -d '{"title":"x"}'
# 实测原文：锁真装上了 —— {"code":40100,"message":"写接口需要登录：POST /questions（未登录：缺少 Bearer 令牌）","data":null}
```

两个不要：不要 `yarn start`（它带 `--open`，在无图形环境的服务器上会去调 `xdg-open`，失败是静默吞掉的，不报错但没意义），也不要 `yarn dev`（那是 nodemon 热重载，开发专用）。Ctrl+C 停掉前台进程，转交 systemd：

```bash
sudo tee /etc/systemd/system/kb-server.service >/dev/null <<'EOF'
[Unit]
Description=Code Notes KB REST API
After=network-online.target mysql.service
Wants=network-online.target

[Service]
Type=simple
User=kb
Group=kb
WorkingDirectory=/opt/code-notes-kb/server
ExecStart=/usr/bin/node src/server.js
Restart=always
RestartSec=3
Environment=NODE_ENV=production
# 不需要 EnvironmentFile：dotenv 在 core/db.js 里按 __dirname 定位 server/.env，从哪个目录启动都不会飘
# 日志直接交给 journald，不必自己拼重定向与轮转
StandardOutput=journal
StandardError=journal
NoNewPrivileges=true
ProtectSystem=full
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now kb-server
systemctl status kb-server --no-pager | head -12
journalctl -u kb-server -f                 # 启动面板（含◉ 监听范围与题量实况）就在里面
ss -lntp | grep 6000                       # 必须是 127.0.0.1:6000；出现 0.0.0.0:6000 就是 HOST 忘改了
```

不用 systemd 的话 pm2 一样能跑（`pm2 start src/server.js --name kb-server`），但记得 `pm2 save && pm2 startup` 才会随系统拉起；升级代码后 `systemctl restart kb-server` 或 `pm2 reload kb-server`。

要开多实例：后端无状态可直接横向扩展（Nginx `upstream` 轮询），但每个进程都会开一个 `DB_POOL_SIZE`（默认 10）的连接池，实例数 × 池上限必须留在 MySQL `max_connections` 以内，否则高峰时新连接只能排队。

`.env` 里现在是数据库口令，给它上一道文件权限（它已被 `.gitignore` 忽略、不会进仓库，但它是明文口令文件，也不要拷进对外分享的项目压缩包）：

```bash
sudo chown kb:kb /opt/code-notes-kb/server/.env && sudo chmod 600 /opt/code-notes-kb/server/.env
# 现在这个文件里是数据库口令 + 管理口令 + 令牌签名密钥三样，600 权限不是仪式而是底线
```

### ④ 前端构建与 Nginx 站点

```bash
cd /opt/code-notes-kb/web
yarn install --frozen-lockfile   # 必须全量安装：build 脚本是 vue-tsc --noEmit && vite build，vue-tsc 在 devDependencies 里
yarn build                       # 类型不过就构建失败 —— 这是刻意的质量闸，不要绕过它去单跑 vite build
ls -lh dist/index.html           # 产物：dist/index.html + dist/assets/*
```

两条已写进仓库的配置，决定了部署形状，先弄清再动手：

- `web/.env.production` 里 `VITE_API_BASE_URL=/api`（同源相对路径），该文件**随仓库提交**。所以只要前端由同一个域名下的 Nginx 提供，换域名、换服务器都不需要重新构建；反过来，把 `dist/` 丢到纯静态 CDN 而 `/api` 在另一个域，就得改这个变量重新构建并处理跨域。
- `vite.config.ts` **没配 `base`**（默认 `/`）→ 站点必须挂在域名根路径。塞进 `/kb/` 这类子目录会因为资源绝对路径 404 而白屏；真要用子目录，自己加 `base: '/kb/'` 再构建。

```bash
sudo tee /etc/nginx/sites-available/code-notes-kb >/dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name kb.example.com;          # 换成你的域名；没域名就填公网 IP（那 certbot 签不了证书）

    root /opt/code-notes-kb/web/dist;
    index index.html;

    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
    gzip_min_length 1k;

    # 刻意大于后端的 express.json 2mb 上限：超限应该由后端给出读得懂的 413 信封，
    # 而不是被 Nginx 默认的 1m 在反代入口提前掩掉（那会是一个没有正文的 413，排障时根因不在了）
    client_max_body_size 4m;

    # 前端路由是 createWebHistory（/study/:moduleId、/practice、/admin?tab=…、/stats），
    # 这些地址只存在于浏览器地址栏，磁盘上没有同名文件；不回落 index.html，用户一刷新就 404
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 带 hash 的构建产物可以放心长缓存；index.html 反过来必须每次校验，
    # 否则发版后旧页签会拿着新 index.html 去追已被替换的 chunk（前端虽有 router.onError 兜底刷新，不该把事故当机制用）
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    location = /index.html {
        add_header Cache-Control "no-cache";
    }

    location /api/ {
        proxy_pass http://127.0.0.1:6000;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;            # 批量导题卡与存量导入都是长请求，默认 60s 够用，不要随手加到几分钟
    }

    # 整库转储接口：现在它本身已要票（没带 Authorization 直接 401），这一层 deny 是纵深防御而不是唯一那道锁：
    # 两道锁的好处是「忘配其中一道仍有人挡着」，代价是备份脚本必须从本机跑（要票 + 只让 127.0.0.1 过）
    location = /api/export/sql {
        allow 127.0.0.1;
        deny  all;
        proxy_pass http://127.0.0.1:6000;
    }

    # 接口交互文档（swagger-ui，后端自托管，不依赖外部 CDN）：内部用可以留着；
    # 公网实例建议直接注掉这三行，或同上面那样加 Basic Auth —— 它会把全部接口目录列给来访者
    location /api-docs {
        proxy_pass http://127.0.0.1:6000;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/code-notes-kb /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default        # 不删也行，但它会抢未匹配的域名/IP 直接访问
sudo nginx -t && sudo systemctl reload nginx
```

防火墙：先放行 SSH 再启用 ufw，顺序错了会把自己关在门外；6000 / 3306 / 3307 一个都不放行（云主机还要在控制台安全组里做同一件事，`ufw` 管不到厂商层）。验证以 `ss` 与外网探端口两道为准：

```bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status verbose
```

### ⑤ HTTPS 与访问控制

```bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d kb.example.com    # 自动改 server 块：加 443、签证书、把 80 重定向到 443
sudo certbot renew --dry-run              # 证书只给 90 天，先把续期定时器验通再收工
curl -sI https://kb.example.com | head -1 # 期望 HTTP/2 200
```

- 域名必须先解析到这台机器：HTTP-01 校验要求 certbot 能从公网访问到你的域名，否则直接失败。
- 只有一个 IP、没域名时签不了这种证书：要么买个域名，要么自签 + 客户端自己信任（只适合自用），要么挂在云厂商 CDN / 负载均衡后面由它出边缘证书。
- **HTTPS 只解决传输加密，不解决身份**。`curl https://你的域/api/questions` 照样把题库吐出去 —— 读接口本来就是匿名开放的（产品形态决定），锁住的是写面与整库转储；想让「看题也要登录」是另一个产品决策，得把守卫改成也校 GET。
- 口令与票在 https 下才不算明文传输：走 `http://` 时请求体就是裸文本（`curl -v` 里直接看得到 `"password":"..."`），在公网上等于把它吐给同一条链路上的任何人；所以「先 HTTPS 再登录」不是建议而是前提（回环地址 `127.0.0.1` 上的本机与备份脚本不在此列）。
- 想再加一道低成本的门：给 `/api/` 挂 `auth_basic`，或在安全组/WAF 按源 IP 收紧。这不改变「读接口本身对匿名开放」的事实，只是把可达面缩回到你自己；而 `auth_basic` 与接口令牌是两套凭据，叠上去就要接受两套密码各自会过期。

### ⑥ 备份与恢复

两条路线都实测过（本机 MySQL 8.0.46，数据为 3389 题 + 作答流水）：

| 路线 | 命令 | 实测产物 |
|------|------|----------|
| 项目自带 | 见下方代码块（**该接口现在要票**：登录取票 → 带票转储） | 3.26 MB；5 张基表 DDL + 全部数据 + 视图，**视图排在全部基表之后**，并跳过 `*_bak*` 历史备份表（本库实测跳过了 `question_bak_logic_1016`） |
| mysqldump | `mysqldump -h127.0.0.1 -ukb_app -p --single-transaction --default-character-set=utf8mb4 code-notes-kb > /backups/kb.sql` | 5.16 MB；按表名字母序输出，视图 `v_module_stat` 排在 `wrong_book_dismiss` 之前 —— 本视图只引用 `module` + `question`（已回读定义确认），所以还原照样成立；若将来新增的视图引用了更靠后的表，字母序就会翻车，而内置导出不会 |

`--no-tablespaces` 这个网上几乎必带的参数，**实测不需要**：MySQL 8.0.21 起 mysqldump 不再默认查 tablespace 信息，用上面那个只有五项权限的账号不加它也能导成功。只有你的客户端可能停在更老版本时才需要补。

项目自带导出现在要带票，所以脚本得每次先登录再取（票 12 小时到期，但定时备份不该靠「上一轮取的票还没过期」这种假设）：

```bash
# ADMIN_PASSWORD 从 600 权限的 server/.env 里取，不写进脚本也不进 shell 历史
PWD_LINE=$(sed -n 's/^ADMIN_PASSWORD=//p' /opt/code-notes-kb/server/.env | head -1)
TOKEN=$(curl -s http://127.0.0.1:6000/api/auth/login -X POST -H 'Content-Type: application/json' \
  -d "{\"password\":\"$PWD_LINE\"}" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:6000/api/export/sql -o /backups/kb-$(date +%F-%H%M).sql
head -c 200 /backups/kb-*.sql   # 看一眼产物开头：如果是一段 {"code":40100,...} 信封而不是 SQL，就是票没取到（口令错或已被限速）
```

> ⚠️ 这条路线有一个真实陷阱：**401/429 的响应体也是文本**，`curl -o file.sql` 不判状态码就把信封写进了 `.sql` 文件，于是备份目录里会躺着一堆「看起来像备份」的垃圾，等到真要恢复才发现。上面那句 `head -c 200` 就是防这个；追求更紧的写法是 `curl -f`（非 2xx 直接失败）或干脆走 mysqldump 那条不经过 HTTP 与鉴权的路线。

> ⚠️ 两份产物都**含 `DROP TABLE IF EXISTS`** 而**不含 `CREATE DATABASE` / `USE`**。也就是说：指向一个有数据的库执行就是覆盖，而还原前必须先有库。

```bash
# 定时备份：每天 03:30，留 7 天，口令走 defaults 文件（不进命令行、不进 ps、不进 shell 历史）
sudo mkdir -p /backups && sudo chmod 700 /backups
sudo tee /etc/mysql-kb-backup.cnf >/dev/null <<'EOF'
[client]
user=kb_app
password=你的强密码
EOF
sudo chmod 600 /etc/mysql-kb-backup.cnf

sudo tee /etc/cron.d/kb-backup >/dev/null <<'CRON'
30 3 * * * root mysqldump -h127.0.0.1 --defaults-extra-file=/etc/mysql-kb-backup.cnf --single-transaction --default-character-set=utf8mb4 code-notes-kb | gzip > /backups/kb-$(date +\%F-\%H\%M).sql.gz; find /backups -name 'kb-*.sql.gz' -mtime +7 -delete
CRON
```

cron 文件里的 `%` 必须写成 `\%`，否则会被当成换行符吃掉、任务永远不执行 —— 这是 cron 的经典坑，不是本项目特有的，但写完不验证就没人发现。

恢复（新机器 / 灾难恢复）：

```bash
# 1) 只需要一个同名空库（备份里已带全部 DDL，不必再跑 schema/seed 脚本，也别去碰那个不可重跑的 01-init.sql）
mysql -h127.0.0.1 -uroot -p -e "CREATE DATABASE \`code-notes-kb\` DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_0900_ai_ci;"
# 2) 灌回去
mysql -h127.0.0.1 -uroot -p --default-character-set=utf8mb4 code-notes-kb < /backups/kb-2026-10-20-0330.sql
# 3) 核对，别只看退出码：题量、模块量、作答流水是否回到你以为的那个数量
mysql -h127.0.0.1 -uroot -p -e "SELECT (SELECT COUNT(*) FROM \`code-notes-kb\`.question) q, (SELECT COUNT(*) FROM \`code-notes-kb\`.answer_log) a;"
curl -s http://127.0.0.1:6000/api/health
```

备份文件就是「第二个全库副本」，它的敏感度等于数据库本身：放站点目录之外（尤其别落进 `web/dist/`，那等于把库挂在 `/kb-2026-10-20.sql` 这个 URL 上等人下载）、`chmod 600`、异机再存一份、不要提交进仓库。

### ⑦ 上线自检清单

逐条跑，每条都有实测基线；全绿才算「部署完成」。

| 检查 | 命令 | 期望 | 不对说明什么 |
|------|------|------|--------------|
| 后端活着且连对库 | `curl -s http://127.0.0.1:6000/api/health` | `"code":0`，`db.name` = `code-notes-kb`，`questions` = 3389 | 库名不对＝`.env` 写错；题量对不上＝灌库没灌完 |
| 路由装配完整 | `curl -s http://127.0.0.1:6000/` | 含 `"name":"code-notes-kb server"` 与 `docs` / `spec` | 404 信封＝`routes.js` 没挂上 |
| 静态站点 | `curl -sI https://你的域/ \| head -1` | `200`，`Content-Type: text/html` | 502/403＝`root` 路径或权限错 |
| history 回落 | `curl -sI https://你的域/practice \| head -1` | `200`（不是 404） | 404＝`try_files` 没生效 |
| 反代同源 | `curl -s -o /dev/null -w '%{http_code}' https://你的域/api/health` | `200` | 502＝后端未起或 `proxy_pass` 写错；404＝缺 `location /api/` |
| 中文全文检索 | `curl -s 'https://你的域/api/questions?keyword=%E9%97%AD%E5%8C%85'` | `total` > 0（本机基线 7） | 0 或数量离谱＝`ngram_token_size` 不是 2 |
| 后端没裸奔 | `ss -lntp \| grep -E ':(6000\|3306\|3307)'` | 只出现 `127.0.0.1:` | 出现 `0.0.0.0:`＝`HOST` 没收口或 compose 端口发布了 |
| 公网探端口 | 从**另一台机器** `curl -m5 http://公网IP:6000/` | 超时或拒连 | 拿到 JSON＝安全组放行了 6000，马上去关 |
| 整库出口收口 | 从公网 `curl -s -o /dev/null -w '%{http_code}' https://你的域/api/export/sql` | `403`（Nginx 拦下）或 `401`（网关放行但没带票，后端拦下） | `200`＝两道锁都没了：先查 Nginx 那个 `location =` 是否生效，再查 `.env` 是否写了 `AUTH_ENFORCED=false` |
| 写面确实要票 | 从公网 `curl -s -X POST https://你的域/api/questions -H 'Content-Type: application/json' -d '{"title":"x"}'` | `401` + `"code":40100` | `200/400`＝鉴权没生效（要么 `.env` 写了 `AUTH_ENFORCED=false`，要么你改的是另一个实例的 `.env`）；`403`＝被 Nginx 提前拦了，这一档下后端还好不好用要另验 |
| 能换到票 | `curl -s -X POST https://你的域/api/auth/login -H 'Content-Type: application/json' -d '{"password":"你的管理口令"}'` | `"code":0` 与 `data.token`（前缀 `kb1.`），并回 `expiresAt` | `40100`＝口令错（连错 8 次会换回 `429`，锁 15 分钟）；`40000` 说「未启用鉴权」＝这台实例 `AUTH_ENFORCED=false` |
| 限速记账来源 | 本机直连实例上连错 8 次口令触发 `429`，再带 `-H 'X-Forwarded-For: 8.8.8.8'` 试一次 | 仍是 `429`，伪造头不起效（＝没配 `TRUST_PROXY` 时限速按 socket 地址记账） | 这一行是**实测**（本机 6000 直连实例）。反代拓扑下配了 `TRUST_PROXY=1` 后 XFF 会被采信 —— 那是 Express `proxy` 选项的确定行为，**本仓未实测**；真正要防的是另一个方向：上了反代却不配，所有用户会挤进同一个限速桶 |
| 浏览器实机 | 打开 `/study/1` 按 F5；看书模式点「下一题」看地址栏；顶栏应能「管理员登录」并拿到票 | 页面正常、`?q=` 随题变化；登录后导出一按钮能下文件 | 刷新 404＝回落没配；资源 404＝挂在子目录却没配 `base`；登录按钮没反应＝后端不可达或 `ALLOW_ORIGINS` 漏了你的站点 |

### ⑧ 常见故障对照

| 现象 | 根因 | 处置 |
|------|------|------|
| `systemctl` 拉起就退出，日志一句 `ER_ACCESS_DENIED_ERROR` 或 `ECONNREFUSED` | `.env` 的账号/口令/端口不对 | 启动时 `collectBootInfo()` 先探库，探不到就 `process.exit(1)`（刻意：宁可不起，也不起一个连不上库的服务）。先前台 `node src/server.js` 看完整报错 |
| 日志里 `EADDRINUSE`，面板给中文提示 | 6000 被其它程序占用 | 改 `.env` 的 `PORT` 并同步改 Nginx `proxy_pass`（两处必须一起动），或干掉占用进程：`ss -lntp \| grep 6000` |
| 启动面板显示 `◉ 监听范围 0.0.0.0:6000 局域网可达` | `.env` 没写 `HOST=127.0.0.1` 或写错位置 | 补上后 `systemctl restart kb-server`；面板这一行就是为这个检查而做的，不用自己拿 netstat 对 |
| 中文关键词搜不到 / 结果离谱 | 建表时 `ngram_token_size` 不是 2（默认 3） | 先按 ② 改配置文件重启；已建的索引不会自动重分词，需 `ALTER TABLE question DROP INDEX ft_question_search, ADD FULLTEXT KEY ft_question_search (title, answer) WITH PARSER ngram;`（先备份再执行） |
| 刷新 `/study/9` 直 404 | 没配 `try_files ... /index.html` | 按 ④ 补上并 `nginx -s reload` |
| 整页白屏、控制台报静态资源 404 | 站点被放在子路径而 Vite 的 `base` 仍是 `/` | 放根路径；或给 `vite.config.ts` 加 `base: '/子目录/'` 重新构建 |
| 交卷 / 批量导入偶发 `413` | 请求体超过 `express.json` 的 2mb 上限（或 Nginx 默认 1m 先掩） | 单批题量降下来；确需大请求体则同时改 `app.js` 的 `limit` 与 Nginx `client_max_body_size`，不要只改一边 |
| `yarn build` 报 `vue-tsc` 类型错 | 构建脚本内置了类型闸 | 这不是部署问题，是代码问题：本地先 `yarn type-check` 修完再发 |
| 页面正常但接口全失败，横幅报「后端无响应」 | 反代不通（后端挂了 / `proxy_pass` 写错 / SELinux 下 `httpd_can_network_connect` 未开） | `curl 127.0.0.1:6000/api/health` 先证后端本身好，再看 nginx error log；CentOS 系上 `setsebool -P httpd_can_network_connect 1` |
| 多个用户同时用，作答记录全挤在 `guest` 下 | `user_key` 默认 `guest`，它只是预留字段位、不是登录态 | 写面现已要票，但只有一把共享管理口令、不代表身份；要按用户隔离得分两层：先补用户体系（登录时绑定 `sub`、下发 per-user 票），再让客户端把 `userKey` 从那个身份派生而不是写死 |

### ⑨ 各端的部署边界（不编不存在的东西）

| 端 | 能部署什么 | 现状 |
|----|------------|------|
| `web/` | `dist/` 纯静态产物 | 无 SSR、无 Node 运行时依赖；除了本节的 Nginx 不需要任何服务器进程 |
| `server/` | 一个 Node 常驻进程 | 无状态、不写本地文件、无 session（令牌靠签名校验，重启不作废已发的票）；可多实例，但登录限速计数各实例各记一份。接口清单见 `server/README.md` |
| `db/` | MySQL 8 一个库 | **除 MySQL 外无任何外部依赖**（不接 Redis / MQ / 对象存储），所以上面那份备份就是唯一的那份备份 |
| `mobile/` | 一个 Flutter 客户端 APK / Web 产物 | 已是**完整可构建工程**（Android + Web 实测）。`flutter build apk --release --dart-define=BASE_URL=https://你的域/api` 产出的是纯客户端，不需要服务器；它连的就是本节部署的 `https://你的域/api`。目前只调读接口与两条免登录的匿名刷题动作（交卷、移出错题），故不必带票；一旦要调管理写接口就得在 Dio 里统一带 `Authorization: Bearer …`（票不能写死在 APK 里，12 小时就到期，得走登录取票并处理 401 重登）。注意 release 包默认锁死明文 HTTP，线上 `BASE_URL` 必须是 HTTPS 域名 |

---

## 🎨 题卡设计规范

三端题卡视觉统一由 `docs/card-spec.md` 约束（每个数值都是从旧仓库 `styles/cards.css` 与旧库 3285 张题卡 PNG 实测采出来的，不是设计稿意图值）：

| 项目 | 规范 |
|------|------|
| 版式 | 竖版卡片（CSS 宽 448px，高度随内容生长），深色主题，圆角 20px |
| 配色 | card-blue / card-cyan / card-purple / card-orange 四色循环 |
| 结构 | 作者水印 + 题号 + 频率标签 + 中英题面 + 答案 + 逻辑分节要点 + 代码演示 + 页脚 |
| 频率 | 必学（紫）｜熟悉（青）｜已掌握（绿），对应 question.frequency 枚举 `must` / `familiar` / `master`（色与文案的唯一入源：`web/src/utils/format.ts` 的 FREQ_LABEL / FREQ_TONE）；而题卡图片上的胶囊沿用旧卡面那一套红/黄/紫，与站点徽章不同色属有意为之（见 `docs/card-spec.md` 第 6 节） |
| 导出 | **仅 Web 端**：`html-to-image`（448 CSS px × `pixelRatio` 2 = 出图宽 896px，宽高显式写死 —— 不让浏览器算，dpr 非整时它推出来的边框宽会把图偏成 895px）+ JSZip 打包，单次上限 150 张；移动端刻意不导出图片（属后台能力，不列接口） |

---

## 📝 提交规范

本项目使用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，由 Husky + commitlint 在 `commit-msg` 钩子自动校验：

```
<type>(<scope>): <subject>

示例：
feat(web): 录题后台支持粘贴自动识别题型
fix(server): 修复 content_hash 归一化未剔除空白的问题
docs(db): 补充 answer_log 索引说明
chore(hooks): 接入 husky 与 commitlint
```

| type | 用途 | 常用 scope |
|------|------|------------|
| `feat` | 新增功能 | `web` / `server` / `mobile` / `db` |
| `fix` | 修复 Bug | `hooks` / `scripts` / `docs` |
| `docs` / `style` / `refactor` | 文档 / 格式 / 重构 | 兼容按技术栈命名（如 `Vue3`） |
| `perf` / `test` / `build` / `ci` / `chore` / `revert` | 性能 / 测试 / 构建 / CI / 杂项 / 回滚 | — |

约束：type 必须在枚举内且小写、subject 非空且不以句号结尾、header ≤ 80 字符、scope 大小写不限。

首次克隆后执行 `yarn install` 即自动注册 Git Hooks（`prepare: husky`）。

### 提交前质量闸（pre-commit）

`.husky/pre-commit` 在 `commit-msg` 之前跑三道前端检查（均切到 `web/` 目录、走 `npx --no-install` 强制吃本地依赖），任一步非零即中断提交：

| 步 | 命令 | 卡什么 |
|----|------|--------|
| 1 | `eslint .` | error 级：未使用声明、`console.log`（只放行 `warn`/`error`）、控制字符正则等；现存 7 条 `no-explicit-any` 记 warning，不阻塞提交 |
| 2 | `vue-tsc --noEmit` | 模板与脚本的类型一致性（`strict` + `noUnusedLocals`） |
| 3 | `vitest run` | 核心纯函数与插件的行为契约（`format` / `pasteParse` / `persist`） |

后端 `server/` 是 CommonJS 无构建产物，不进本闸，改动仍靠 `yarn serve` 自测。

配置在 `web/eslint.config.js`（ESLint 9 扁平配置），**刻意未引入 prettier** —— 自动格式化会把上千行排版噪音混进真实 diff，掩盖改动本体。

手工执行：

```bash
cd web && yarn lint          # ESLint 全量检查
cd web && yarn lint:fix      # 可自动修复项
cd web && yarn test          # 跑单测（vitest run，jsdom 环境）
cd web && yarn test:watch    # 监听模式
```

---

## 🤝 如何贡献

1. Fork / 克隆本仓库：`git clone https://gitee.com/template-warehouse/code-notes-kb.git`
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 按提交规范提交：`git commit -F msg.txt`（Windows Git Bash 下中文建议走 `-F` 文件方式）
4. 推送分支并发起 Pull Request

> 📘 **动手前先读 [开发规范基线 `docs/CONVENTIONS.md`](./docs/CONVENTIONS.md)**：四端的架构边界、命名、注释格式、接口契约、设计令牌、质量闸与「新增功能拓展清单」都收敛在那里，封板即基线，新功能照此执行。
> 本地开发入口统一在 [`scripts/`](./scripts/README.md)：`bash scripts/doctor.sh` 体检 → `bash scripts/start.sh` 起全栈 → `bash scripts/check.sh` 提交前全栈质量闸。
> 已立项待实施的功能设计见 [`docs/payment-plan.md`](./docs/payment-plan.md)（收费支付方案）与 [`docs/review-engine-plan.md`](./docs/review-engine-plan.md)（间隔重复记忆引擎 + 最小账号体系地基，留存向）——其中**最小账号体系地基已落地**（`user` 表迁移 + server `user-auth` 模块注册/登录/游客认领 + 令牌角色闸），记忆引擎仍仅设计未落地；教程文章→题卡自动摄取方案见 [`docs/ai-content-ingest-plan.md`](./docs/ai-content-ingest-plan.md)（P0 骨架 + P1 章节筛选 + P1 改写出题**已并入 master**：首源 AI Agent 精选 19 题入库 confirmed；改写因无可用 key 走 `--from-json` 手工路径，P2 补代码 / P3 导入向导待实施）。

> ⚠️ 贡献约定：题库数据只进 `db/seed/`（纯文本），任何端生成的图片不纳入版本控制；新增接口需同步更新对应子目录 README。

---

## ❓ 常见问题

**Q: 为什么仓库里看不到题卡图片？**
A: 遵循「纯文本数据」原则，图片全部由前端实时渲染生成，`.gitignore` 已排除 `images/` 产物。

**Q: 存量题卡从哪来？**
A: 由 `server/scripts/ingest-cards.js` 将历史 HTML 题卡解析为 `db/seed/questions.imported.sql`，归一化 hash 去重后幂等入库，共 **3389 张**（覆盖 35 个模块）。得分要点 `logic` 同时采集题卡内的 `key-point` 列表与 `compare-table` 对比表两种结构，详见 `db/README.md`。

**Q: 提交被 commitlint 拒绝了怎么办？**
A: 检查格式是否为 `type(scope): subject`、type 是否在枚举内、subject 非空且不以句号结尾、header ≤ 80 字符。

**Q: 能直接部署到公网吗？**
A: 能部署，写面也已要票（见[🔒 部署边界](#-部署边界写面已收鉴权外发前必读)），但**不等于可以随手往外抛**：读接口全库匿名可访问、只有一把共享管理口令、票也无法在服务端吊销。把 `HOST` 收口到 `127.0.0.1`、只开 80/443、给整库导出加仅本地放行、`.env` 里用真随机口令与密钥，是自己用的最低要求（步骤见[🚢 部署到自己的服务器](#-部署到自己的服务器)）；要给不信任的人用，先补用户体系再谈开放注册。

**Q: 内容有误如何反馈？**
A: 欢迎提交 [Issue](https://gitee.com/template-warehouse/code-notes-kb/issues/new) 或直接提 PR。

---

## 📋 更新日志

| 日期 | 内容 |
|------|------|
| 2026-10 | 仓库重构为前后端分离 Monorepo：`web / server / mobile / db` 四端骨架初始化 |
| 2026-10 | 接入 Husky + commitlint 提交规范校验 |
| 2026-10 | db 数据层落地：七要素题目表 + dict_item 字典表 + 模块种子；存量题卡全量摄取 **3389 张**（35 模块）入库并通过全库健康复查 |
| 2026-10 | server 后端落地：Express + mysql2 REST API，按功能模块划分目录（modules/ + core/），17 个路径全动词覆盖（题目/模块/字典 CRUD 两级查重与引用保护、练习组卷交卷、错题本、批次报告、统计，含 HEAD/OPTIONS），端到端自测通过 |
| 2026-10 | 端口规划迁至 6000 系：后端 **6000** / 前端 **6001**（MySQL 沿用本机 3306 未动），避开 3000 被其它程序占用；env、Vite 代理、一键起脚本、OpenAPI servers 与文档同步更新 |
| 2026-10 | 题卡解析器修复两处根因（`key-point` 非贪婪截断、`compare-table` 未被识别）并全库补录得分要点：252 题由空补齐 + 102 题追加「对比要点」分节，`logic` 空值归零 |
| 2026-10 | 前端确立**取数四态范式**（加载中 / 有数据 / 失败可重试 / 确实无内容）：解析面板、看书目录、错题本、首页、统计均不再把接口故障渲染成「暂无 XX」，统一带失败原因与重试入口（约定见 `web/README.md`） |
| 2026-10 | 看书模式接入**题目级深链** `?q=题目id`：按钮 / 目录 / 键盘 ←→ 切题均同步地址栏，支持分享直达与浏览器后退切题；脏 q（不存在 / 跨模块）自动清洗，约定见 `web/README.md` |
| 2026-10 | web 录入后台 `/admin` 落地：题目 / 知识库 / 数据字典三分节 CRUD 与草稿↔已确认流转；七要素抽屉表单带粘贴识别（题卡 HTML 走高置信结构解析、纯文本走低置信启发式）、题面实时查重、模块内题号留空自动续排；字典接口新增 `includeInactive`，停用项不再从管理页消失、可启用回来；分节 `?tab=` 深链与取数四态范式同步落地（约定见 `web/README.md`） |
| 2026-10 | web 修正四处展示语义各自重定义（频率文案/配色收敛到 `utils/format.ts` 单一入源，同时消除刷题端「必学/熟悉」配色写反）、题目详情缓存加**失效代号 + invalidate** 并接进写操作（后台改题不再需要刷新页面）、退出练习拦住确认并新增**提前交卷**、`router.onError` 兜住发版后旧 chunk 404 白屏 + `scrollBehavior` + 全局异常兜底（约定见 `web/README.md`） |
| 2026-10 | web 接入质量闸：**ESLint 9 扁平配置**（不引入 prettier）+ **vitest/jsdom 单测**（format / pasteParse / persist 共 29 例），`yarn lint` / `yarn test` 与 vue-tsc 一同进 `.husky/pre-commit`，任一步非零即中断提交 |
| 2026-10 | server 下发口径治本三处：连接池开启 `decimalNumbers`（`SUM()` 回的是 DECIMAL，默认下发字符串会让同一行里数字与文本混发，客户端比全文本更容易踩「"0" 为真值」）、`HEAD /api/questions/:id` 改为主键点查并前移到 `GET /:id` 之前（写在后面的 HEAD 会被先注册的 GET 截走，之前是永不执行的死代码）、`moduleId/typeId/sceneId` 等引用 id 类查询参数非法一律 400（空串仍视为不参与过滤，与后台可清空下拉框同一口径），不再静默当成不限 |
| 2026-10 | web 接上两条长期悬空的断链：`fetchHealth` 接成**全站服务状态横幅**（按离线 / 后端无响应 / 数据库异常三档给结论，靠「响应体是不是本站信封」分开后两者），`fetchBatchReport` 接成**组卷成绩批次回看**（批次号 `lastBatchId` 落本地，刷新后仍能展开逐题明细）；顺手把请求底座在 HTTP 4xx/5xx 上的 `error.message` 换成后端中文原因，并删掉三个零调用封装 |
| 2026-10 | web 导航语义修正：后台题目详情改为**同页签**打开（不再 `target="_blank"` 开新窗口），看书页「← 返回」回到**来路**而不是写死回首页（读 `history.state.back`，只在进入本页时取一次，保住「同页切题靠后退 = 上一题」的既有语义） |
| 2026-10 | web 根治遮罩的「看不见却吃得要命」残留：全屏加载遮罩把命中测试从过渡生命周期里摘出来（常驻外壳默认 `pointer-events: none`、仅加载态开 `auto`，动画交给 `<Transition>` 的内层），于是即便标签页隐藏时 rAF 挂起、`transitionend` 不触发导致 leave 过渡没收尾，也不会再留下一层 `opacity:0` 的全屏遮罩吃掉全站点击；同时清掉最后四处 `target="_blank"`：后台知识库名称改同页签、加题抽屉的两处相似题去掉链接只留就地「对比解析」（不给「跳走会丢未提交表单」留口子）、`KbCard` 那条零调用的 `href` 死分支连 `prop` 一并删除 |
| 2026-10 | web 刷题端补上「答法要点」选填录入：自评之外把当时答出什么、卡在哪一步随本条记录写入 `answer_log.user_answer`（留空存 NULL），错答进复习态后继续补写也会在推进/交卷前同步上报，组卷批次回看逐题可看到原话 |
| 2026-10 | web 录入后台修一处**校验态残留**：抽屉被必填拦住后取消、再点开会看到一屏空表单挂着上轮满屏红字 —— EP 的程序性赋值只复位数据不复位校验态，复位 watch 里补 `nextTick(() => formRef.value?.clearValidate())`；同轮实测另记一条 `el-drawer` 开关判据（节点挂载即常驻 DOM，不能拿它的存在判「抽屉还开着」，否则会把正常的「取消」误报成「点了不关」），两条均见 `web/README.md` |
| 2026-10 | web 修一处会写脏数据的双击缺陷：答题页只节流翻页、而 `markCorrect` 本身不受控，250ms 内的第二击仍会给「刚切过去的下一题」凭空记一条几十毫秒的「答对」（界面看不出来，交卷直接进 `answer_log` 并抬高 `practice_count`）—— 现将推进本体抽成 `advance()`，让「写记录 + 推进」共用同一个节流窗口；单题耗时同时改为 `Math.max(0, …)` 取非负（`Date.now()` 会被改表/NTP 回拨推回过去），并补上要点行的 `word-break` 硬换行与收回一个零消费的 `ALL_KEY` 导出 |
| 2026-10 | server 交卷接口把可选入参也卡成 400 同档：`userAnswer` 限字符串且 UTF-8 不超 60000 字节、`durationMs` 限 0~86400000 的整数。库上 `sql_mode` 含 `STRICT_TRANS_TABLES`（实测），而 `user_answer` 是 TEXT（65535 字节）、`duration_ms` 是 `int unsigned`，且逐题流水包在同一事务里写 —— 越界值不会静默截断而是在事务中途报错，整批交卷回滚后抛到兜底中间件变成 500，被前端横幅归成「数据库异常」，一个入参问题就此伪装成挂库；现在入口直接点名是哪一条 `items[i]` |
| 2026-10 | 文档补上**部署边界**（外发前必读）：根 README 新增「全栈零鉴权」一节、server/README 新增「零鉴权与可达面」一节。两条可达面事实均为实测而非推演：`app.listen(PORT)` 未绑 host（`netstat` 显示 `0.0.0.0:6000` 与 `[::]:6000`，**同局域网设备可直接读写题库**）、`cors` 未限 origin（响应 `Access-Control-Allow-Origin: *`，预检回 `Allow-Methods` 含 `DELETE`）；并写明 CORS 不是访问控制（只约束浏览器读响应，写请求照发照执行），给出只本机 / 真机联调（防火墙或 Nginx + Basic Auth）/ 公网部署（先补鉴权）三种处置 |
| 2026-10 | 零鉴权暴露面收口不再需要改代码：后端新增 `HOST` 环境变量（默认 `0.0.0.0` 保住 mobile 真机联调，需要时 `.env` 写 `HOST=127.0.0.1` 即只留本机），启动面板新增 `◉ 监听范围` 一行实时画出当前暴露面。实测：默认实例走局域网 IP 与 `localhost` 都 200；收口实例只监听 `127.0.0.1`，走局域网 IP 直接拒连。`.env.example` 同步注释，根 README / server/README / mobile/README 三处文档跟着从「改代码」改为「改配置」并互相点明代价 |
| 2026-10 | server 新增 `/api/export` 导出模块：整库 SQL 转储（DDL 取自实库 `SHOW CREATE TABLE`、视图排在全部基表之后、历史备份表 `/_bak(_\|$)/i` 跳过）+ 题目按筛选导 CSV/JSON（参数名与 `GET /api/questions` 一致，含 `keyword` 且走同一洗词口径 —— 屏幕上搜到多少条就能导多少条；上限 8000 行）。两个接口**成功时递的是文件流而不是 JSON 信封**，失败时照旧回信封，客户端需按 `Content-Type` 分流 |
| 2026-10 | web 录入后台接上两类一键导出：头部「导数据」面板（整库 SQL / 题目 CSV·JSON，走 `<a download>` 直链）；题目分节「导出题卡」把当前筛选命中的题目逐张渲染成 PNG 并用 JSZip 打包。图片走前端渲染而不是后端截图：版式与站点共用一份代码，也不必为一张图在服务端挂浏览器二进制。规格逐值对齐旧仓库题卡（宽 896px、右上角作者水印胶囊），单次上限按实测体积倒推取 150 张（单张约 1 MB / 0.6 秒），带进度、当前题面与中途取消（约定见 `web/README.md`） |
| 2026-10 | server 的题目导出接口新增 `ids=1,2,3` 主键点导（给题目表格的行勾选）：`core/params.js` 的 `parseIdList` 去重、容忍多余逗号，但**任一项非法就整条 400**（静默丢掉坏 id 会变成「勾了 12 道只导回 11 道」这类最难发现的错），与既有筛选是 AND；下载文件名加上 `ids-N` 维度（只标个数，十几个 id 拼进名字没人读得完）。个数上限单设 `IDS_MAX = 2000` 而不是沿用行数上限 8000：清单得先装进 URL 走请求头，实测 3000 个 id（约 14 KB）能进到本模块解析、4000 个（约 19 KB）被 Node 默认的 16 KB 上限直接回一个无正文的 431。openapi 与 server/README 同步 |
| 2026-10 | web 题目表格改造成「勾选行→按勾选导题卡」：首列复选框 + `reserve-selection` 跨页保留、常驻「已勾选 N 道」提示条（跨页勾选是屏幕外看不见的，不能指望用户自己看到对勾），`AdminCardExport` 两态范围（勾选优先、只发 `ids` 不叠当前筛选、按勾选序取前 150 道）。为此补三处底座：`KbTable` 转发 `selection-change` 并 `defineExpose({ clearSelection })`（自定义组件的 emit 不是 DOM 事件，不转发就等于把行选择锁死在壳层）、`api/export.ts` 的 `filterToParams()` 在客户端就把 ids 折成逗号串（axios 缺省写成 `ids[]=1`，Express 解成对象后后端当未传 —— 静默按全库导）、**加载态只在首屏接管整块**（表格一卸载重挂就把 el-table 的内部选中集带走，实测「第 1 页勾 2 道 → 翻页 → 再勾 1 道」退化成只剩 1 道）。标题计数另改为「命中 N / 全库 M 道（筛选生效中）」：`questions.total` 本就是筛选后的命中数，搜索框里残留一个词就会被读成「题库只剩 17 题」而全库 3389 道一道没少；新增 `filterToParams` 单测 4 例（共 33 例），端到端实测勾选 3 道跨两页 → 请求 `ids=1066,1067,1086` → zip 内 3 张 PNG 均为 896 宽（约定见 `web/README.md` 与 `docs/card-spec.md`） |
| 2026-10 | web 导出题卡入口补一道判断：一道没勾时不直接开弹窗，先走 `utils/notify` 的 `confirmAction` 把真实范围说清（无筛选「全库 N 道」/ 有筛选「当前筛选命中的 N 道」，连同单次 150 张上限），点「先去勾选」则弹窗压根不出现；勾了行仍直开弹窗，这道判断只挡零勾选（没勾选并不等于想导全库，而“范围被悄悄换成整片命中”原本要等拿到图才暴露）；另补一道 `scopeUnsettled` 拦截：本地筛选值与 store 已生效 `query` 不一致（关键词 500ms 防抖未到点）或列表正在取数时，连确认框都不弹、只 `toast.warning` 一句稍等 —— 拿一个即将作废的命中数跟用户保证「本次导这么多」比让他多等半秒贵得多（只判 loading 会漏防抖期，只判筛选不一致会漏首屏 `total` 还是 0） |
| 2026-10 | 错题本接上学习闭环（只进不出的断链在前端，不在判定）：后端口径本就是「每题 `MAX(id)` 那次作答为错」，答对即出本早已成立，而练习按模块抽题不保证再抽到错题，所以面板上只会积题。现每条错题递出两个出口 —— **就地重做**（答对写一条真流水自然出本、没答上留在本里并自动展开解析）与**手动移出**（二次确认后写标记，不是假答对）。新增第 5 张表 `wrong_book_dismiss`（主键 `(user_key, question_id)`，实库已建并 `SHOW CREATE TABLE` 回读核对）+ `DELETE /api/practice/wrong-book/:questionId`（幂等 upsert、非法 id 400、从未作答 404）；失效基准用**流水 id 而不是时间**（`answered_at` 只到秒，同秒内「答错又移出」用时间比判不出），下次再答错的新流水 id 更大→ 标记自动失效、题目自动回本，不需清理任务；移出也不伪造流水，因为 stats 正确率是 `SUM(is_correct)/COUNT(*)`，补一条 `is_correct=1` 会同时虚增正确率与 `practice_count`（后端探针 8 步全通，含「再答错自动回本」「移除不污染计数」）。端到端另拓出三处真缺陷：① `KbButton` 只 `emit('click')` 不带事件，消费方挂 `@click.stop` 一点就抛 `TypeError: … stopPropagation`（按钮完全不可用）→ 改为透传原生事件并同步 `KbButtonEmits` 声明，而按钮本就是「展开解析」行的兄弟节点、本来不需要 `.stop`；② 写操作成功提示叠两层（拦截器弹后端 `message`、视图又弹一次）→ 移除接口走拦截器、单题重做转 `silent` 并**由视图兼着失败提示**（`silent` 连 error 一起吞，不补就是点完什么都没发生）；③ `await` 防抖壳子的 promise 在防抖体执行前就 resolve，使「没答上后自动展开解析」只闪 ~400ms 就被重拉抹掉 → 拆成无防抖的 `refreshWrongBook()` 本体 + 防抖壳子两层（约定见 `web/README.md`「错题本的学习闭环」、`server/README.md`、`db/README.md`，openapi 与 OPTIONS 能力自述同步补上 `DELETE`） |
| 2026-10 | 请求底座的失败提示改为**先判归因**：`error.config` 缺失（如扩展把 `XMLHttpRequest.send` 改成同步抛错）时 `kb.silent` 根本读不到，旧写法会把一个程序错误弹成「网络异常，请稍后重试」并与视图自己那条叠成两条。现在这类异常只留一条 `[kb-request]` console 告警、原对象抛回调用方，也不改写 `message`（那句中文原因不是后端给的）；**加载计数仍照常回收** —— 请求拦截器已经 +1，不减就把全屏遮罩永久留在页面上。配套新增 `src/api/__tests__/request.test.ts`（给单次请求打桩 `adapter`，不发真请求就能把成功信封/失败形状塞进拦截器链）7 例，web 单测共 **40 例**；新用例已拿改动前的旧代码跑过，确实会红，不是空过 |
| 2026-10 | 清零全站 `<KbButton size="sm">`：`KbButtonProps` 没有 `size`、样式里也没有 `size` 属性选择器，它不生效却看着像「按钮小一号」 —— 属于写了不亏、读代码的人上当（它给下一个维护者传递了一份不存在的契约）。删除后渲染零差异（实测 `.practice-quiz__foot` 两个按钮的 outerHTML 已不含 `size=`，退出练习的二次确认与提前交卷进成绩页均正常） |
| 2026-10 | 文档补上**部署到自己的服务器**全流程（新增 🚢 章节）：端口规划 → 服务器准备 → MySQL 8 落地（`ngram_token_size` 实测为只读变量、必须写进配置文件再建表；三脚本的执行顺序与对账读数）→ 专用运行账号（五项权限，实测少 `SHOW VIEW` 就导不出视图）→ systemd 常驻 → Nginx 静态托管 + `/api` 反代 + history 回落 → HTTPS → 备份与恢复（两条路线产物的体积与对象顺序均实测对拍，并实测 `--no-tablespaces` 在 MySQL 8.0.21+ 已不再必需）→ 上线自检 10 条与常见故障 10 条；并如实标注 `mobile/` 目前无可部署产物（仓内只有设计说明，没有 Dart 代码） |
| 2026-10 | 修正三处与实测不符的文档自述：环境要求的 Node 版本（原写 `>= 16.0`，而 Vite 5 与 ESLint 9 的 `engines` 取交集要求 **≥ 18.18**）、「Docker 一键起库免手动导入」（compose 只挂 `db/schema/`，存量 3389 题在 `db/seed/` 下、不属自动初始化范围）、`01-init.sql` 头部「可整体重复执行」（第 5 张表的外键使二次执行在 `DROP TABLE question` 处报 `ER_FK_CANNOT_DROP_PARENT`，脚本头注释同步修正）。另给 README 头部加上 🔎 亮点速览与 📑 目录，并把两个含变体选择符的 emoji 标题（🏗️ / ⚠️）换成单码点图形，以保证锚点跳转可写可达 |
| 2026-10 | server 把写面从「谁都能改」收成「知道口令的人才能改」，**不留一个需要手动登记的口子**：`core/authGuard.js` 挂在 `/api` 汇总路由最前面按**默认拒绝**裁决（`GET/HEAD/OPTIONS` 放行，其余动词一律要票），免登录名单只有三条且逐条写明为什么必须放开（`POST /auth/login` 是换票入口、`POST /practice/submit` 与 `DELETE /practice/wrong-book/:id` 是匿名刷题动作按 `user_key` 隔离）—— 选这个形状而不是逐条登记，是因为新增写接口漏登记的后果必须是 401（调用方立刻发现）而不是数据被改。令牌用 Node 内置 crypto 手写 HMAC（`kb1.<payload>.<sig>`，不引 jsonwebtoken：无第三方供应链），**先验签再解 JSON**（载荷是客户端可控字节串，先 parse 等于让外人决定服务端解析什么）、定长摘要比较（先 SHA-256 再 `timingSafeEqual`，不给靠响应时间猜签名留缝）、`exp` 留 5 秒时钟余量。整库导出虽是 GET 也单独卡 `requireAuth`（没带票不进转储逻辑），但 `OPTIONS` 能力自述豁免；`cors` 的 origin 从 `*` 收成 `ALLOW_ORIGINS` 精确匹配（缺省只放本机 6001）且**显式列上 `Authorization`**（不列则登录后全站阵亡）。登录限速同来源 15 分钟 8 次（计数只存进程内存，多实例各记一份，它不是分布式限流）、文案不回「还差几次」、`TRUST_PROXY` 不默认开启（否则一个请求头就能伪造 IP 换槽位）。启动自检把三种坏配置（缺密钥 / 缺口令 / 密钥短于 16）挡在 `exit 1`，而不是静默降级成没锁
| 2026-10 | web 接上带票链路，同时拆掉一个鉴权下必然挨饿的设计：新增 `utils/authToken.ts`（本地存储 + 30 秒到期提前量 + 隐私模式下写不进就退回内存兜底）、`stores/auth.ts`（顶栏登录弹窗与「先有票再干活」的 `ensureLogin`）、`KbAuthEntry.vue`（三态入口：已登录到期时刻 / 鉴权未启用 / 管理员登录）；请求拦截注入 `Bearer`，401 分三档收口（登录接口自身的 401 是「口令错」不能清票不能广播、`silent` 自检不广播、其余才清票 + 广播且**不叠 toast**，原因由登录框当场说）。**关键发现**：导出原本是 `<a download>` 直链，而浏览器导航递不出 `Authorization` —— 鉴权一开导出就静默失效，所以改成带票取 blob 再 `createObjectURL`（代价是 3.4 MB 转储先进一次内存，但绝不为了绕鉴权把口令拼进 URL：那里会落到浏览器历史、代理日志与 Nginx access.log）；为此新增 `kb.raw` 透传档与后端 `Access-Control-Expose-Headers: Content-Disposition`（不配这个跨源前端就读不到下载名）。顺手修掉两处：导出失败时中文原因被 Blob 挡住、用户只能看到 axios 英文状态码（现按 `readBlobText` 解信封，并兼容无 `Blob.text()` 的环境），以及 `promptLogin` 重入时会顶掉上一轮结算回调（造成永久悬着的 `await`）—— 新增 `authToken` 12 例 + 登录态 store 15 例 + 底座令牌/401 相关 8 例，web 单测 **40 → 79 例**，新用例均拿旧实现跑过确认会红；鉴权与 CORS 两面 52 条 curl 逐条实测全绿（包含过期票端到端、四种坏票写法、启动自检三种坏配置、限速与 XFF 伪造）
| 2026-10 | 文档把「零鉴权」这个已经不再成立的事实从各处同步掉：根 README 的「部署边界」改写为「写面已收鉴权」并拆成**已收的 / 仍开着的**两半（读接口仍匿名、单口令无隔离、票无从吊销、限速不分布式 —— 这四条是本次仍然成立的代价），附 52 条取证命令；🚢 部署章节的生产 `.env` 样例从八个键补到十三个（`AUTH_ENFORCED`/`ADMIN_PASSWORD`/`AUTH_SECRET`/`AUTH_TOKEN_TTL`/`ALLOW_ORIGINS`/`TRUST_PROXY`）并给了现场生成随机值的命令；**备份脚本得改**（项目自带导出接口现在要票）补出「先登录再转储」与一个真实陷阱：401/429 的响应体也是文本，`curl -o x.sql` 不判状态码就会把信封写成「看起来像备份」的垃圾；上线自检清单从 10 条补到 13 条（写面要票 / 能换到票 / 限速记账来源），并把这一行里未实测的那半标明是推演；`server/.env.example`、`server/README.md`、`mobile/README.md` 与 openapi 的 `securitySchemes` / 401 / 429 同步 |
| 2026-10 | `mobile/` Flutter 刷题 App 落地为完整可构建工程：首页 / 刷题 / 统计三 tab，接 `../server` 同一套 REST API；主题与 Web 同源（`AppTextStyles` 文字梯度 / `AppButtonSize` 按钮三档 / `AppSyntax`「紫夜」代码高亮 + `KbCodeBlock`），Android 模拟器与 Web 均实测；底部导航贴底通栏、去掉 M3 过度滚动拉伸 |
| 2026-10 | **封板 v1.0.0**：新增统一脚本层 `scripts/`（`start`/`stop`/`doctor`/`check`/`build`/`mobile`/`db-ingest` + 共享样式库 `lib/kb.sh`），控制台样式收敛为一套（品牌红横幅含项目名/作用/加载状态/作者，与 `serve-all.mjs`、`server banner.js` 同源）；后端端口被占不再提示改端口而是**自动杀掉旧实例重绑**（`server.js` 与 `serve-all.mjs` 同步）；沉淀开发规范基线 [`docs/CONVENTIONS.md`](./docs/CONVENTIONS.md)（四端架构/命名/注释/接口契约/质量闸/依赖版本策略 + 新增功能拓展清单）供后续增量 |
| 2026-10 | 修 Swagger 文档「浏览器打不开」的根因：后端 6000 是 Chromium 不安全端口（`ERR_UNSAFE_PORT`），文档入口统一改走前端 6001 Vite 代理 —— `openapi.js` 的 `servers` 从写死 6000 改同源相对 `/`（否则页内 Try it out 必挂），`vite.config.ts` 显式新增 `/api-docs` 代理，`server.js` 新增 `WEB_PORT`/`DOCS_URL` 常量供面板与 `--open` 使用，`serve-all.mjs` 汇总补可点击文档地址；`.env.example` 登记 `WEB_PORT`，`server/README.md` 与 `docs/CONVENTIONS.md`（新增第十节「已知坑」）同步 |
| 2026-10 | 收费功能支付方案落盘 [`docs/payment-plan.md`](./docs/payment-plan.md)（仅设计未写代码，封板后首个候选新功能）：三端产品路由（电脑网站支付 / 手机网站支付 / App 支付，后续商家扣款）、服务端唯一事实源架构、三张库表草案（金额存分 / 订单状态机 / 权益表）、`modules/pay` 路由草案与鉴权豁免、6 条安全红线与实施顺序 |
| 2026-10 | **教程文章→题卡自动摄取 P0 骨架落地**（新分支 `feature/ingest-articles`）：新增 `server/scripts/ingest-articles.js` + 源清单 `db/seed/ingest-sources.json`（多源并行、新增源=加配置不改代码），按 `article-body` 的 `<h2>/<h3>` 分节把 runoob 教程切成七要素**草稿题**（`status='draft'`，代码优先取文章自带实例），去重口径与 `ingest-cards.js` 一致（`content_hash` 精确 + `INSERT IGNORE`）；已在真实 schema 上跑通「抓取→解析→去重→生成 SQL→事务导入 26 行→回滚零残留」闭环，**未接 LLM**（P1 再接 qwen 出题）；方案见 [`docs/ai-content-ingest-plan.md`](./docs/ai-content-ingest-plan.md) |
| 2026-10 | 修 P0 代码采集乱码（根因：runoob `<pre>` 由客户端 JS 从 `noteContent` 还原注入，静态 HTML 残缺不可信）：`parseSection` 改为只探测有无 `<pre>`（判 type）、不再采其内容，`code_demo` 恒置 NULL（代码留 P2 由 LLM 补+人工跑）；源清单剔除软文页 `first-ai-agent.html`、补入 3 个概念页；另修 `htmlToText` 漏归一化 `\r` 导致代码混进正文 |
| 2026-10 | **P1 章节筛选落地**：新增 `db/seed/ingest-filter.json` 按页编码人工 A/B/C 分级（drop 剔除跨页重复/纯复述、merge 子节要点并入父题、keep 保留出题），`ingest-articles.js` 加载并应用筛选（未命中项告警）；首场景 4 页 55 题经筛→ **30 道精选题**，真实 schema 事务验证 `logic` JSON_VALID 30/30、`code_demo` 全空、回滚零残留；P1 下一步逐节接百炼 qwen3.8-flash 改写出题（需 `DASHSCOPE_API_KEY`，已入 `.env.example` 与方案第九节） |
| 2026-10 | **P1 改写出题落地（无 key 手工路径）**：`ingest-articles.js` 新增 `--llm`（百炼改写）/`--dry`（提示词预览）/`--from-json`（把人工改写的严格 JSON 渲染为 draft SQL）三种模式；因当前无可用的 `DASHSCOPE_API_KEY`，首源 `runoob-ai-agent` 的 30 道规则粗题改由人工逐条改写（问句化题面 + 结构化答案 + 剥离代码），并对 module 35 现有 60 题语义查重→ 精选 **19 题**（13 互补 + 6 入门改写）导入 draft、经 `/admin` 人工审核全部 `confirmed`；产物见 `db/seed/ingest-manual.runoob-ai-agent.json` 与 `questions.llm.draft.runoob-ai-agent.sql`。**适用边界实测结论**：代码密集型教程（如 runoob Vue2）因 runoob 代码抽不到 + 存量题已覆盖而性价比极低，不纳入自动摄取 |
| 2026-10 | 教程→题卡摄取 **P0/P1 全量并入 `master`**（`--no-ff` 合并，`feature/ingest-articles` 特性分支本地+远程已清理） |
| 2026-10 | 新增设计稿 [`docs/review-engine-plan.md`](./docs/review-engine-plan.md)：**间隔重复记忆引擎**（SM-2 起步→FSRS 二期，`review_schedule` 到期排期表 + 今日复习/评分/统计接口 + 双端离线合并）与其**共用的「最小账号体系」地基**（`user` 表 + 游客 `user_key` 认领，`answer_log`/错题本零迁移）；`payment-plan.md` 悬置的「权益跟谁走」据此定稿、复用同一地基。**均为仅设计、未落地** |
| 2026-10 | **最小账号体系地基落地（increment 1，仅 server + db）**：`db/schema/migrations/0001_add_user.sql` 新增 `user` 表（`user_key`/`identity` 双唯一、`pwd_hash` scrypt、`status` 软封）；`core/auth.js` 加 `issueToken(sub,{role})`+`roleOf()`+scrypt 散列/校验（零新依赖）；新增 `modules/user-auth`（`POST /auth/register`、`POST /auth/user/login`、`POST /auth/claim-guest` 游客认领零迁移、`GET /auth/me` 按角色分流）；**角色闸与安全同批**：`enforce()` 由「任何有效票放行写面」改为「非管理票只能命中用户级写名单」，整库导出 `requireAuth`→`requireAdmin`（防注册用户越权改题/拖全库）。18 项启动冒烟全绿（含用户票写题/导出的 403 越权拦截）；web/mobile 消费与记忆引擎待后续 |
| 2026-10 | **web 新增个人中心页 `/me`**：身份卡（昵称 / 标识 / 票归属 / 到期 / 认领与退出）+ 成绩墙 + 近 14 天作答趋势 + 模块分布前 8 + 最近流水 + 错题待复习；配套 server 只读接口 `GET /api/stats/me`（汇总 / 趋势 / 模块分布 / 最近流水四组一次回齐，`days` 与 `limit` 走 `clampSize` 钳制）；趋势日期骨架由 MySQL 递归 CTE 生成（避开进程与库时区错位导致的头尾多一天），正确率与 `/stats/overview` 同口径且把「已自评条数」单列下发；`stores/me.ts` 以「请求时的身份」而不是布尔作已加载标记，换账号/退出后自动重拉。web 单测 9 文件 **103 例**。 |
| 2026-10 | **web 新增技术栈脑图页 `/map`**：把 7 个分类 / 35 个技术栈 / 全库题卡画成一张可折叠目录（根 → 分类 → 模块 → 题目），点题目直接进看书模式定位该题。画布用 **mind-elixir 5.15.1**（MIT、框架无关，依赖写死版本 —— 该包 `latest` 目前指向 `6.0.0-next.x` 预发布），`/map` 路由懒加载，库与库样式只进这个 chunk。分层与懒加载：首屏只铺 43 个节点，点模块 `+` 才拉 `GET /api/questions?moduleId=&status=confirmed&pageSize=100`（后端上限就是 100），一模块一条请求、并发去重、收起再展开走缓存；首屏之外还有题时补一个「还有 N 题 · 点此进看书模式」节点，不让模块悄悄少题；未拉 / 加载中 / 失败各有自己的占位子节点（`metadata.action` = `load` / `retry` / `more`），失败原地重试 —— 没有 children 就没有展开箭头，失败渲染成空又会被读成「这个模块没题」。只读与交互：`editable / contextMenu / toolBar / keypress` 全关 + `allowUndo: false`（全站唯一写入口是录入后台，画布能拖能改却没有持久化通道等于让人白改）；点击走事件委托读 `[data-nodeid]` 元素上的 `nodeObj.metadata`，因为库的 `selectNewNode` 只在键盘导航时触发，鼠标点击没有等价事件。三处浏览器实测才暴露的问题一并修掉：① 首屏 100% 时左右两翼被 `overflow: hidden` 裁掉 → 建实例后 `scaleFit()` 到一屏；② 展开 84 题后整棵树被顶到视口下方 —— `refresh()` 改了画布自然尺寸却不重算 translate，现每次重排先 `toCenter()`，再按模块题目标签量一次即时平移 `move(dx/scale, dy/scale)`（`scrollIntoView` 拿的是含整棵子树的 `me-parent` 矩形，且 300ms 过渡会吞掉连续两次调用）；③ 52% 下 12px 题面只剩 6px 高读不了 → 展开后回到 100% 再居中。可测部分：树装配抽成纯函数 `utils/mindmap.ts`，跨页状态（题目缓存 / 加载态 / 展开与分类收起集合）全部落在 `stores/map.ts`，新增单测 14 例（装配 9 + store 5，并发只发一条请求、失败不落缓存、force 可覆盖错误态均有断言），web 单测 11 文件 **117 例**（约定见 `web/README.md` 的「技术栈脑图」） |
| 2026-10 | **封板终检 `seal-2026-10-27`**：把「封板后只加数据」这条路真跑了一轮并写成章节（新增 📦 一节）—— 走 API 录草稿 → 确认 → 查各级计数 → 删除复原：Linux 模块 `confirmed 84 → 85`、全库 `3370 → 3371`、`GET /api/questions?status=confirmed&pageSize=100` 回包含新题、脑图头部与根节点同步显示 3371、画布上 Linux 变 85 题且新题就在首屏，删除后复核回到 3370；题号按模块内 `MAX(card_no) + 1` 续排，删过题的模块会跳号（实测新题显示 `#91`）属预期。数据体检：35 模块 / 3370 已确认 / 草稿 0 / 零确认题模块 0。同时修掉一处「只加数据也会踩到」的缺陷：脑图分类配色原按分类在模块列表里的出现顺序取色，改任一模块 `sort_order` 或新增分类会把后面整片分类换色，现按分类名排序稳定取色（`categoryColorMap`），web 单测 11 文件 **120 例** |

---

## 👨‍💻 作者

**Forever 丿顾北-Byte**

- Gitee: [template-warehouse](https://gitee.com/template-warehouse)

---

**Code Notes KB** · 一端录入 · 三端同源 · 持续更新