99 lines
7.7 KiB
Markdown
99 lines
7.7 KiB
Markdown
# 技术选型
|
||
|
||
> 母体形态（完整前后端 + 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 全栈
|
||
|
||
1. 前端横竖是 JS 家族（Vue 3）——前后端同语言，类型系统、模块、异步语义一份学完，DTO 类型前后端共用一份契约；
|
||
2. 作者点名学习目标（Bun + Hono + Drizzle + PostgreSQL）即 TS 生态；
|
||
3. 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）
|
||
|
||
```text
|
||
（仓库根）
|
||
├─ 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（pack release / build）
|
||
```
|
||
|
||
**依赖规则（单向）**：`apps/*` → `packages/db` → `packages/core`；core 导出的 DTO 类型可被 web 以纯类型依赖引用（前后端共用一份契约类型）。
|
||
|
||
**代码落点**：实现代码与设计文档同仓演进。
|
||
|
||
## 5. R14 预留：现阶段零成本，只为后续抽取不挖坑
|
||
|
||
R13 的 CFW 抽取版仍是长期裁决，功能全集实现后启动，届时按 R14「从母体抽业务核心、换基础设施层」执行。本稿只保留两条现阶段零成本、届时免重写的预留：
|
||
|
||
1. **Bun 纪律**：`packages/core` 只使用 TypeScript 标准库与 Web 标准 API（`fetch` / WebCrypto / `URL` / `TextEncoder` / `setTimeout` 等）；`Bun.*`、`bun:*`、`node:*` 与具体数据库驱动只出现在 `apps/*` 装配层、`packages/db` 与 `scripts/`——届时 CFW 形态的绑定物（D1 等）同样只落在新的装配层，core 原样搬运；
|
||
2. **方言不外泄**：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. 待裁决项
|
||
|
||
1. 前端测试设施是否引入 vitest。
|