Files

T

tupingr e3f4af9c0c docs(arch): 旧架构合并 — 30项决策落地，5份文档升级至v0.4.0

- 总体架构：新增打印/图像预处理/双飞轮/三环境部署
- 技术选型：调整决策理由（Coze沙盒自动化测试），新增Sharp+PDFKit
- 数据模型：新增code/role/question_type+print_tasks+audit_logs，ID+code并存
- 模块设计：新增Image/Print模块，推荐两阶段匹配（关键词粗筛→AI精排）
- PRD：目标用户扩展为学生+家长，新增PDF打印，年级聚焦小初，图像预处理流程
- ADR-010：题库抽象层Adapter Pattern

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-26 12:00:52 +08:00

4.2 KiB

Raw Permalink Blame History

技术选型

版本: v0.4.0 | 作者: Arch AI | 基于 PRD v0.4.0 + 旧架构合并

1. 技术栈总览

层	选型	版本	选型理由
小程序框架	Taro	4.1.x	跨端能力（微信/抖音/H5），React 生态
UI 框架	React	18.x	Hooks 生态成熟，社区资源丰富
UI 组件库	shadcn/ui (Taro 适配)	—	可定制、无样式锁定、复制即用
样式方案	Tailwind CSS	4.x	原子化 CSS，与 shadcn/ui 深度集成
状态管理	Zustand	5.x	轻量、无 Provider、TS 友好
后端框架	NestJS	10.x	模块化、IoC、企业级 Node.js 框架
ORM	Drizzle ORM	0.45.x	Type-safe、轻量、SQL-like API
数据库	PostgreSQL	15+	关系型、JSON 支持、全文搜索
AI 能力	Coze SDK	—	现成 OCR + NLP 能力，无需自训
文件存储	S3 兼容 (MinIO/Supabase)	—	图片上传，标准化接口
包管理	pnpm	9.x	monorepo 原生支持、磁盘效率高
图像处理	Sharp	0.33.x	Node.js 高性能图像处理，CLAHE/旋转/缩放
PDF 生成	PDFKit	0.15.x	Node.js PDF 生成，A4/300DPI 排版
测试	Jest	29.x	生态最大、React 测试工具链成熟
语言	TypeScript	5.x	全栈类型安全

2. 关键选型决策

2.1 为什么是 Taro 而不是 uni-app？

维度	Taro	uni-app
React 支持	一等公民	Vue 为主
shadcn/ui	社区已有 Taro 适配	无
跨端编译	编译时转译，性能好	运行时适配，有开销
社区	京东维护，活跃	DCloud 维护

决策: Taro。项目已用 React + shadcn/ui 体系，Taro 天然匹配。最终仅发布微信小程序，但 Taro 保留了未来迁移 H5/原生 APP 的灵活性（后端 API 不变，只换前端壳）。

2.2 为什么是 NestJS 而不是 Express/Fastify？

维度	NestJS	Express
架构约束	模块化 + 依赖注入	无约束，需自建
TypeScript	一等公民	需额外配置
测试友好	内置 TestingModule	需自建
微服务支持	内置 Transport 层	需自建

决策: NestJS。自建后端是刚性需求——Coze 沙盒自动化测试需要完整的后端环境（长连接、GPU 调用、流式响应），微信云开发（云函数 10s 超时）无法满足。同时 NestJS 模块化设计降低长期拆分微服务的迁移成本。

2.3 为什么是 Drizzle ORM 而不是 Prisma？

维度	Drizzle	Prisma
Bundle 大小	< 10KB	~500KB+ (engine)
SQL 控制	SQL-like API，接近原生	抽象层厚
边缘运行时	支持	需额外配置
迁移工具	内置	内置

决策: Drizzle。小程序场景对包体积敏感，Drizzle 更轻。且项目初期 SQL 灵活性重要。

2.4 AI 方案: Coze SDK vs 直接调用 API

维度	Coze SDK	直接 Claude/GPT API
开发量	低（工作流已封装）	高（需自建 prompt chain）
OCR 能力	内置	需额外组件
成本	按调用次数	按 token
可定制性	低	高

决策: MVP 用 Coze SDK 快速上线，Phase 3 评估自研模型（P02）。

3. 暂不引入的技术

技术	原因	引入时机
Redis	MVP 无高频读写，PostgreSQL 足够	Phase 3（推荐/排行榜缓存）
Docker/K8s	单实例部署，先跑起来	Phase 3（CI/CD 配套）
GraphQL	REST 足够，前端查询模式简单	Phase 3（复杂查询场景）
Elasticsearch	PostgreSQL 全文搜索够用	Phase 3（题库搜索量大时）
Kafka/RabbitMQ	无异步解耦需求	Phase 3（微服务拆分后）

4. 技术债务记录

债务	说明	偿还计划
P01 项目代码是"代码检测"模板	需要替换为错题本业务代码	Phase 2 开发时自然替换
无 CI/CD	手动测试部署	Phase 3 引入 GitHub Actions
无监控	无 APM/日志收集	Phase 3 引入 Sentry + 阿里云日志

关联: 总体架构.md → 模块设计.md

4.2 KiB Raw Permalink Blame History Unescape Escape