技术选型

母体形态（完整前后端 + PostgreSQL，R13 先行交付形态）的技术栈裁决：语言、逐轴选型、分层落地、验收标准与回退预案。范围：功能全集在母体上设计与实现；CFW 抽取版为 R13 后续阶段，待功能全集实现后启动——本稿不覆盖其形态面（Workers / D1 / Cron Triggers / Pages），只保留其中现阶段零成本的预留（§5）。选型总原则：一项选择既要是母体上的好选择，也不给后续抽取挖坑。

项目	内容
状态	定稿（2026-10-02）
关联	`需求清单.md`（R13/R14 · 裁决记录——PBKDF2 两形态统一实现）· `交互设计-总览与共性.md`（§3.7 组件能力清单——前端验收标准）· `README.md`
取代	无（首篇选型文档）

1. 结论总览

全栈 TypeScript，一套语言贯穿前端与后端。

层	选定
运行时与工具链	Bun（runtime + 包管理 + 测试 + 打包一体化）
HTTP	Hono
数据访问	Drizzle ORM + postgres.js + PostgreSQL
调度	独立进程 `apps/engine`：手写 `setTimeout` 循环（细则见《同步引擎设计》）
加密	WebCrypto（Bun 原生）
前端	Vue 3 + antdv-next + Vite

2. 语言：TypeScript 全栈

前端横竖是 JS 家族（Vue 3）——前后端同语言，类型系统、模块、异步语义一份学完，DTO 类型前后端共用一份契约；
作者点名学习目标（Bun + Hono + Drizzle + PostgreSQL）即 TS 生态；
R13 后续的 CFW 形态原生运行时也只有 JS/TS——全栈 TS 顺带保留了那扇门（现阶段不作为选型依据，零成本预留见 §5）。

3. 逐轴选型与依据

轴	选定	依据	回退
运行时与工具链	Bun	runtime + 包管理 + 测试 + 打包一体化，学习只认一个工具；作者点名学习目标，认可其生产可用性	Node——业务代码不动（§7）
HTTP 框架	Hono	TS 原生、极轻、中间件模型干净；Bun 原生适配	`@hono/node-server`（Node）
数据访问	Drizzle ORM	TS 优先、查询保持 SQL 形态（不藏 SQL，利于学与审计）；schema 即代码，drizzle-kit 迁移配套齐全	Kysely / 裸驱动 + 手写仓储
pg 驱动	postgres.js	Drizzle 文档主推；查询构建器式 API；内置连接池；Bun 兼容好	node-postgres
前端框架	Vue 3	作者近年常用栈；实现期自由度（共性 §3.5「作者即前端」）	—
组件库	antdv-next（作者指定尝试项）	Vue 3 企业组件库、对齐 ant-design（React 上游）设计体系；已核验通过（§6.1）：活跃周更、§3.7 清单逐项有对应组件、Agent 文档齐备	Element Plus / ant-design-vue（§3.7 全覆盖）
加密	WebCrypto	HKDF / AES-256-GCM / HMAC-SHA256 / PBKDF2 与裁决一致（密钥体系见各表设计）；Bun 原生	HKDF 若 Bun 覆盖滞后：基于 HMAC 的纯 TS 垫片（同原语）
构建 / 测试	Vite（web）；质量门 = `typecheck` + `build` + 人工验收	前端构建走 Vite 生态默认；自动化测试不在当前范围	需要时再引入测试框架
API 文档与校验	zod + @hono/zod-openapi + Scalar（作者确认）	一源三用：TS 类型 / 请求校验（`422` 与 `fields` 的机器来源）/ OpenAPI 生成；Scalar 为 Hono 官方搭档，规范与渲染器解耦	Swagger UI（规范不动、换皮即可）

4. 分层落地：monorepo（Bun workspaces）

（仓库根）
├─ apps/
│  ├─ server/     # 母体后端：Hono serve 装配 · Drizzle/pg · 环境变量与密钥注入
│  ├─ engine/     # 同步引擎：独立进程（《同步引擎设计》）
│  └─ web/       # 前端：Vue 3 + antdv-next + Vite
├─ packages/
│  ├─ core/      # 业务核心：轮询与 request_id 去重 · 折算链 · 加密体系 · API 语义与 DTO 类型
│  └─ db/        # 数据访问层：Drizzle schema（pg 方言）+ 仓储 + 迁移 CLI
├─ scripts/      # 打包/构建 CLI（naku pack / build）

依赖规则（单向）：apps/* → packages/db → packages/core；core 导出的 DTO 类型可被 web 以纯类型依赖引用（前后端共用一份契约类型）。

代码落点：实现代码与设计文档同仓演进。

5. R14 预留：现阶段零成本，只为后续抽取不挖坑

R13 的 CFW 抽取版仍是长期裁决，功能全集实现后启动，届时按 R14「从母体抽业务核心、换基础设施层」执行。本稿只保留两条现阶段零成本、届时免重写的预留：

Bun 纪律：packages/core 只使用 TypeScript 标准库与 Web 标准 API（fetch / WebCrypto / URL / TextEncoder / setTimeout 等）；Bun.*、bun:*、node:* 与具体数据库驱动只出现在 apps/* 装配层、packages/db 与 scripts/——届时 CFW 形态的绑定物（D1 等）同样只落在新的装配层，core 原样搬运；
方言不外泄：pg 特有物（jsonb 等）只出现在 packages/db 的 schema 与仓储实现内，不进 core——届时补一份 SQLite 方言 schema 即可，core 与仓储接口不动。

Hono（双运行时可跑）与 WebCrypto 本身恰好与 CFW 兼容，属顺手之得，不构成现阶段约束。

6. 风险与回退

风险	评估	对策
antdv-next 项目年轻、维护者 3 人	桌面核验通过（§6.1）；未核验项：社区采用规模	实现期第一步做 §3.7 能力 spike（实测）；锁版本；实测不满足即触发回退（Element Plus / ant-design-vue）
Bun 生态资料少于 Node、边角兼容性	本项目规模小、依赖面窄（Hono / Drizzle / postgres.js 均成熟）	Bun → Node 回退不伤业务代码：换 `@hono/node-server` 装配即可，packages/* 原样
Bun 的 WebCrypto 原语覆盖（HKDF 等）	未逐项实测	实现期首轮加密任务实测；缺失则 HMAC 纯 TS 垫片

6.1 antdv-next 核验记录（2026-10-02，一手源直查）

口径：npm registry / GitHub API / 官网 llms.txt 直查（当轮无浏览器检索通道——社区口碑与采用规模未核验）。

核验点	结果
包与许可	`antdv-next`@1.6.0（2026-10-01 发布）；MIT；ESM + 类型完备（`dist/index.d.ts`）
活跃度	仓库 2025-12 建立、最后推送 2026-10-01；近 15 版分布于 2026-05-17 ~ 10-01（约 1–2 周一版）；951 星 / 115 fork / 开放 issue 仅 7
工程质量	CI + codecov；单测覆盖工件随 release 发布；性能回归基线（每实例响应式计数上限）+ `pnpm bench` 基准；web-types 自 `global.d.ts` 生成、覆盖全部 128 个全局组件；发布说明双语、带性能数据与逐 PR 出处
§3.7 覆盖	清单逐项有对应文档组件：Layout(Sider) / Drawer / Grid；Table（expandable 展开行、scroll 横向滚动）；Modal / Popconfirm / Message / Alert(closable) / Notification；DatePicker(RangePicker) / Input(TextArea) / InputNumber；Badge / Tag / Segmented / Skeleton / Pagination
Agent 友好	llms.txt / llms-full / llms-semantic（中英）+ For Agents / MCP Server / Skills 专用文档——超出「宣称」水平，利好本仓库 AI 协作流程
残留风险	项目约 10 个月、维护者 3 人（单点风险）；minor 版本随依赖下限整体抬升（锁版本对冲）；社区采用规模未核验；官网 llms.txt 一处条目标签笔误（Flex 误标 Empty——工程细节小瑕疵）

结论：通过核验，维持选定；§3.7 spike 与回退预案照旧——桌面核验不替代实测。

7. 待裁决项

前端测试设施是否引入 vitest。

7.7 KiB Raw Blame History Unescape Escape