docs(architecture): 新增技术架构设计 v0.2,记录选型决策 T2–T5、AR1–AR10
- 架构文档:模块化单体 + 按负载拆进程;后端 Python(FastAPI),前端 Vue 3 + Vite 单页应用;PostgreSQL 做权威数据和任务队列(Procrastinate),Valkey 只存可丢数据;S3 / 本地磁盘存储;Compose 与 Helm 共用镜像;桌面端为客户端外壳 - 文档处理组件参考标擎的做法(§3.13):转换服务、Docling、标书组装与两遍导出 - UI 不引入带样式框架,视觉自写,复杂交互用 Reka UI 打底(§4.3) - decisions.md 记录 T2–T5、AR1–AR10;AGENTS.md 同步技术约束与进度 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -4,6 +4,37 @@
|
||||
|
||||
---
|
||||
|
||||
## AR10 · 2026-11-03 · 不引入带样式的 UI 框架
|
||||
|
||||
- **决策**:用户端不用 Element Plus 这类带样式的 UI 框架。视觉全部用 Vue 单文件组件和 `tokens.css` / `components.css` 自己实现;对话框、下拉选择、日期选择、弹出层、菜单、轻提示、标签页、复选框等交互复杂的组件,用无样式组件库 **Reka UI**(原 Radix Vue,MIT)打底。表格需要排序、筛选时用 TanStack Table,长列表用 TanStack Virtual;表单用 Zod 加一个自写的 `useForm`。不用 Tailwind 和 shadcn-vue。
|
||||
- **理由**:先调研了 Element Plus(推荐)、TDesign 等带样式框架;用户提出产品有一套自己的高保真设计,引入它反而会限制开发。复核后同意:核心业务组件框架都不提供;基础件的默认行为(红色危险按钮、红色必填星号、转圈的加载按钮、固定结构的错误提示)和设计规范第 7 节冲突,改造要覆盖框架内部样式,升级时容易失效;两套样式体系并存,开发时容易偏离设计稿。完全手写又难以保证焦点管理、键盘导航和浮层定位的质量,所以用无样式组件库补上这一块。
|
||||
- **影响**:`packages/ui` 分基础件、交互件、业务组件三层,预计 2~3 人周,可以和页面并行;每个组件有预览页(延续 `components.html`);交互件补键盘操作测试。运营后台的选型等做到时再定。详见架构文档 §4.3。
|
||||
|
||||
## AR1–AR9 · 2026-11-03 · 架构草案的选型:AR2 改为 Vue 3,AR4 复议后修订,其余按建议
|
||||
|
||||
依据 `docs/architecture/architecture.md` 第 11 节。
|
||||
|
||||
| # | 决策 |
|
||||
|---|---|
|
||||
| AR1 | 模块化单体 + 按负载拆进程(api、worker、converter、ocr),不拆微服务 |
|
||||
| AR2 | **前端用 Vue 3 + TypeScript + Vite 单页应用**(用户把建议的 React 改为 Vue 3);不做服务端渲染。UI 组件库另行调研,见 AR10 |
|
||||
| AR3 | 数据库用 PostgreSQL,以兼容 PostgreSQL 的信创数据库作为迁移路线;行级安全策略作为第二层租户隔离 |
|
||||
| AR4 | **任务状态和队列放在 PostgreSQL(Procrastinate),另外引入 Valkey,只存丢了也没关系的数据**(模型接口限速、验证码、登录限流、进度推送、短期缓存),不持久化、不备份;会话放在 PostgreSQL,只存令牌哈希。v0.1 原本建议「MVP 不引入 Redis」,用户追问后复议:不引入能省下的只是一个轻量容器,而限速、防刷、多实例推送三件 MVP 必做的事用 PostgreSQL 做都很别扭(架构文档 §6.1) |
|
||||
| AR5 | 文件存储用 S3 协议 + 本地磁盘驱动,不用 MinIO(社区版已停止发布和维护) |
|
||||
| AR6 | 桌面外壳倾向 Electron,桌面版立项时再定;前端现在就守住 §5.2 的 7 条约束 |
|
||||
| AR7 | 私有化代码保护:Nuitka 编译核心包 + 签名授权文件 + 提示词加密 |
|
||||
| AR8 | 服务端会话,可吊销;网页端用 cookie,桌面端用 Bearer 令牌 |
|
||||
| AR9 | 单一仓库(monorepo) |
|
||||
|
||||
## T2–T5 · 2026-11-03 · 技术架构的四项基础选择:全部按建议
|
||||
|
||||
架构草案见 `docs/architecture/architecture.md`;其余选型(AR1–AR9)待确认。
|
||||
|
||||
- **T2 后端用 Python 单语言**:业务接口(FastAPI)和后台任务是同一套代码、两种进程。理由:团队小;核心价值在文档解析、OCR 和大模型流水线,这些生态 Python 最强,用单语言就不会把领域逻辑拆在两种语言里。代价:私有化交付会暴露源码,用 Nuitka 编译和授权文件缓解(AR7)。
|
||||
- **T3 桌面客户端定位为「连服务端的客户端外壳」**:界面和网页版是同一套,连 SaaS 或私有化服务器;外壳只提供本地文件、通知、钥匙串、更新这些本地能力,不内嵌后端和模型。影响:第一阶段的前端必须守住架构文档 §5.2 的 7 条约束(纯静态构建、接口地址可配置、同时支持 cookie 和 Bearer 鉴权、平台能力走抽象层等)。
|
||||
- **T4 SaaS 先用 Docker Compose,商用再上 K8s**:内测期用 1~2 台云服务器跑 Compose,数据库和对象存储用云厂商的托管服务;公测前用同一批镜像切到托管 K8s(Helm)。理由:Compose 本来就是私有化小客户的交付形态,内测期间顺带打磨。
|
||||
- **T5 云厂商暂不定,按云无关设计**:只依赖 PostgreSQL、S3 兼容的对象存储、OpenAI 兼容的模型接口这三类标准接口;上线前比较价格后再选。
|
||||
|
||||
## B6 · 2026-11-03 · 应用图标改为印泥铺满
|
||||
|
||||
- **决策**:应用图标不再是「白底 + 印章占 80%」,改为印泥铺满整个方形、不留白边;圆角按 Apple 的连续曲率圆角(squircle)由系统裁切,图标文件保持方形、不带透明。VI 手册第 22 页用 iPhone 18 Pro 主屏幕模拟展示:Apple 官方黑色机身、iPhone 18 Pro 深色壁纸 Black、iOS 系统图标只放 4 行,第四行只有股市和标博士两个。
|
||||
|
||||
Reference in New Issue
Block a user