tupingr
e3f4af9c0c
- 总体架构：新增打印/图像预处理/双飞轮/三环境部署 - 技术选型：调整决策理由（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>
4.2 KiB
4.2 KiB
技术选型
版本: 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