bid-doctor/docs/decisions.md

# 决策记录

按时间倒序记录用户拍板的产品与工程决策。格式：编号 · 日期 · 决策 · 理由 · 影响。

---

## 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 行，第四行只有股市和标博士两个。
- **理由**：白边让图标在主屏幕上显得小而虚，和其他应用放在一起不像一枚印章；铺满后红色块面完整，辨识度更高。
- **影响**：`logo/scripts/build_logo.py` 新增 `svg/app-icon.svg`，`build_assets.sh` 由它渲染 180 / 192 / 512 / 1024px 图标；VI 手册 v1.1 第 22 页重排（邮件签名移到左栏）。Apple 素材不进 git，用 `vi/mockup/fetch.sh` 获取，机身需本人同意 Apple Design Resources 许可后手动放入。

## P1–P2 · 2026-11-02 · 原型阶段的待确认事项：全部按建议

- **P1 24 小时免扣的起算点**：从**上一次扣了额度的检查**算起；窗口内的复查不扣点，也不重新计时。理由：如果从上一次检查算起，每天复查一次就能一直不扣点，额度规则形同虚设。**影响**：FR-M3-02。
- **P2「需人工核对」的勾选按项目存**：整个项目共用一份勾选结果，复查时保留；报告写明勾选人和时间。理由：份数、CA 加密、递交回执这类事项和投标文件版本无关，每次检查重新勾选只会增加负担。**影响**：FR-M3-04。

## U1–U4 · 2026-11-02 · 产品界面设计规范 v0.1 的待确认事项：全部按建议

规范见 `docs/design/design-system.md`（第 12 节）。

- **U1 红色只给致命问题**：表单错误、系统错误、额度用完、截止临近都用赭色（小字 #8A5200），不用红。理由：让红色只代表「可能导致投标无效」；色弱模拟显示红 / 赭本来就要靠形状和文字区分，错误提示照样有文字和图标。
- **U2 只做桌面 Web**：MVP 最小宽度 1280，不做手机适配和暗色模式。理由：读标和查标需要原文并排；变量已按语义分层，以后可加暗色。
- **U3 图标用 Lucide**（ISC 许可）：线性风格和校样方向一致，可商用。
- **U4 致命问题「确认无误」也要写说明**：对致命问题说「没问题」等于认为系统判断错了，说明既用于审计，也作为误报反馈。**影响**：FR-M3-07 已同步修改。

## B5 · 2026-11-02 · 口号改为「标博士，你的AI投标专家」

- **决策**：品牌口号由「每一条，都有出处。」改为 **「标博士，你的AI投标专家」**，固定写法：AI 两侧不加空格，结尾不加标点。
- **范围**：品牌策略、VI 手册（品牌概述、名片、演示文稿、网站、封底、字体样张）、方向对比板等所有出现口号的地方。
- **保留**：「每一条，都有出处」作为产品原则「出处看得见」保留（可复核是核心差异），不再作为口号。
- **注意**：「专家」只表示懂行、查得细；产品和报告里的结论仍然只用「辅助检查」「风险提示」，不承诺结果（产品红线不变）。

## B4 · 2026-11-02 · 横版比例 H2，中文字标用思源宋体 SemiBold（英文待选）

- **比例 H2**：印章的实心边缘上下对齐文字块（中文顶端到拼音底部），再放大 2%，补偿颗粒边缘显虚的问题。
  - 依据：v5 实测印章只有文字块的 96%，原因是抠图时印章四周各留了 2% 的透明边。中国银行、招商银行、中华老字号等「图形 + 中英两行文字」的组合，图形高度通常和整个文字块相同；方形本身就比圆形显大，所以不需要再放大。
  - 对比见 `docs/design/logo/compare/index.html`。
- **中文字标**：思源宋体 SemiBold（F2），比 Black 更清秀，和印章的轻重对比更明显。
- **英文字体**：中英文用不同字体（这是品牌组合里的常见做法）。用户选定 **E5 Libre Caslon**（OFL，Caslon 类老派衬线），候选对比见 `compare/english.html`。
- **英文视觉对齐**：几何上两端对齐时，英文看起来比中文宽。原因是「标」「士」两端只有细横画尖，而英文两端是 B、I 的粗竖画，按墨迹浓度算英文左超 6.5、右超 7.7（中文字高 = 100）。真实品牌两种做法都有：中银香港内缩了英文；清华、进出口银行只做了几何对齐。排版理论主张按视觉边缘对齐。补偿档位 C0–C3 见 `compare/alignment.html`。用户选定 **C2**（左内缩 5.0、右内缩 5.8，约为完全补偿的 3/4）。
- **已执行**：全套正式资产按 H2 + F2 + E5 + C2 重新生成（logo v5.1）。排版逻辑集中在 `docs/design/logo/scripts/logo_lib.py`，正式资产由 `build_assets.sh` 生成，对比页由 `wordmark_compare.py` 生成，三者共用同一套参数。

## B3 · 2026-11-02 · Logo 暂定 v5：AI 生成的白文印 + 矢量字标

- **决策（暂定）**：印章采用用户用 ChatGPT 图像生成的白文印「标」（`docs/design/logo/image-gen/exec-8232d0a3-…png`），经脚本处理后作为正式 logo；字标用思源宋体 Black + Cinzel（W1）。规范见 `docs/design/logo/logo-spec.md`。
- **过程**：v1 由 Codex 精细化草稿 1；v2–v4 尝试用 SVG 程序化模拟印泥质感，效果都不理想（调研见 `seal-research.md`）。结论是印泥质感本质上是位图，所以改用位图生成，再矢量化。
- **颜色调整**：印章红从 #D2282E 改为朱砂色 **#D9291C**（原图实测 #E21B0A，偏亮、超出印刷色域，略压深）。界面「致命」红 #C4122F 不变，两者一橙一洋红，可以区分。
- **小尺寸**：16px 仍用方案 B（加粗简化的「标」字），32–64px 用白色笔画加粗的印章。
- **待办**：AI 生成图形的著作权认定有不确定性，商标注册前要做检索并咨询知识产权顾问；以后可以考虑照这个设计刻一方真章，扫描后替换。

## B2 · 2026-11-02 · 16px 图标与英文名

- **16px 图标**：用方案 B，加粗简化的「标」字。红底白勾（方案 A）是待办类应用的常见图标，辨识度低。
- **英文名**：统一用拼音 **BIAOBOSHI**，不用 Bid Doctor。代码仓库名继续用 `bid-doctor`。
- **logo 第二阶段**：用户要求增加真实印章质感、重新考虑对勾（它破坏了平衡），并给字标换更有性格的开源字体。设计说明见 `docs/design/logo/BRIEF-v2.md`，先出方案对比页，用户选定后再更新正式资产。

## B1 · 2026-11-02 · 视觉方向 A「校样」+ 用户的印章 logo

- **决策**：视觉方向选 A「校样」（`docs/design/brand-directions.html`）：蓝铅笔表示 AI 标注 / 出处，墨表示人工确认，红只用于问题。Logo 不用 A 方向原来的示意，改用用户提供的草稿 1（红色方形印章 + 白色「标」字 + 穿出边框的对勾 + 藏青字标），草稿 2（学士帽）不采用。
- **理由**：盖章是投标人每天都在做的事，印章比「博士帽」更贴近用户、辨识度更高，也适合做应用图标；对勾表达「逐项核对」。
- **约束**：
  - 印章红只用在 logo 上；界面中的「致命」红单独定义，两者要能区分。
  - 「印章 + 对勾」不能当作「通过 / 合格」章用在报告或任何结论上（产品红线：不承诺结果）。
- **执行**：由 Codex 按 `docs/design/logo/BRIEF.md` 精细化，交付物在 `docs/design/logo/`。

## T1 · 2026-11-02 · 大模型策略：国产云端模型，按场景路由

- **决策**：全部使用国内云端的国产大模型，不考虑数据出境。按业务场景匹配模型能力：多模态（扫描件理解、签章检测）、快速（分类、短文本抽取、交互类）、深度思考（复杂条款推理、响应性比对）。
- **影响**：
  - 架构中需要一个**模型路由层**：业务代码只声明「需要什么能力」，由路由配置决定用哪个供应商、哪个模型，方便替换和对比。
  - 解析任务、检查批次都要记下实际使用的模型和提示词版本（04 §4.4）。
  - G11 中「数据出境」一项消除。待办：确认选用的模型都已完成生成式 AI 备案，确认供应商协议里「数据不用于训练」的条款（PRD 7），本产品自身的登记义务请法务确认。
  - 企业版私有化（P2）时，路由层要能切换到客户域内部署的模型。
  - G12（签章检测）交由多模态模型做可行性验证。

## A1 · 2026-11-02 · 需求分析待确认事项 G1–G10：全部按建议

依据 `docs/analysis/06-gaps-and-questions.md`，用户确认全部采纳建议：

| # | 决策 |
|---|---|
| G1 | 区分政府采购 / 招标投标两套法律体系；M2 识别体系，M3 按体系套用规则，术语随体系切换；PRD 1.5 补充政府采购依据 |
| G2 | 修订 PRD 的异常低价口径：政府采购项目适用 87 号令第六十条（现行层）。已出 **PRD v0.9.1** |
| G3 | 多包 / 多标段纳入 MVP（FR-M2-04） |
| G4 | MVP 做最小资质库（FR-M6-08）；资质匹配首先核对投标文件里的证明材料 |
| — | 报价形式检查（超限价、大小写和合计一致）从 P1 拆出，升为 P0（FR-M3-06） |
| G5 | 「检查」是独立计量单位；专业版检查从解析额度扣；24 小时内复查免费；投标文件的解析算在检查里；免费版 1 个项目内检查不限次数 |
| G6 | MVP 不做线上加量包，由运营后台人工调额度 |
| G7 | 清单没确认也能检查，但要提示 |
| G8 | 专业版开通：在线申请 → 对公转账 → 运营人工开通并开发票；线上支付以后再做 |
| G9 | MVP 不做企业认证，注册只填企业名称 |
| G10 | 删除项目时业务内容彻底删除，只保留不含业务内容的审计记录和额度流水 |

## D1 · 2026-11-02 · 首发行业：IT 集成

- **决策**：MVP 首发行业为 IT 集成（信息化系统集成、软硬件设备采购及配套服务类项目），工程类延后。
- **理由**：PRD 第 12 章默认建议；IT 集成类招标文件格式最标准化，★ / ▲ 实质性条款标记、技术参数偏离表等结构便于结构化提取与逐项核对。
- **影响**：
  - M2 提取 schema、M3 检查规则、原型样例数据均以 IT 集成项目为准，详见 `docs/analysis/05-it-integration-domain.md`。
  - IT 集成项目多数走**政府采购**法律体系（《政府采购法》、财政部令第 87 号等），与 PRD 1.5 所引的《招标投标法》体系并存，产品需识别项目适用的法律体系，见 `docs/analysis/06-gaps-and-questions.md` G1。
  - 种子用户获取方向：IT 集成商、软硬件设备供应商、信息化服务商的投标团队。