开发文档索引¶

面向研发、运维与维护者。产品与部署的"事实源"仍以代码与 Prisma migration 为准，本文档与代码冲突时以代码为准，并在同一提交内回改文档（见仓库根 AGENTS.md）。

想找用户视角的说明（怎么传发票、怎么建批次、报错怎么办），去使用手册。

文档索引¶

当前目标架构以 02、03、04、06、08 为准：Web SaaS + PostgreSQL + 工作区隔离。01、07 中仍有桌面版产品与交互表述，保留为早期基线，待 Web UI 完整落地时整体同步。部署与运维细节见 09。

文档	内容	读者
01-product.md	产品定位、核心用户旅程	所有人
02-features.md	功能需求清单（PRD）与优先级	所有人
03-architecture.md	技术架构：Web SaaS、队列管道、多用户工作区与可靠性设计	开发
04-database.md	数据库设计：PostgreSQL/Prisma、工作区隔离、多层防重与 RLS	开发
05-ocr-fields.md	百度 OCR 字段映射与 StandardInvoice 模型	开发
06-roadmap.md	里程碑与任务拆解	所有人
07-ui-guidelines.md	UI 设计规范：Apple HIG 设计 token、组件约定、状态色映射	开发
08-api.md	API 契约：通用约定、错误码、端点定义、SSE 事件格式	开发
09-deployment.md	部署方案：内网 Docker Compose 步骤、密钥、备份与运维	开发/运维
10-zju-yb-daily.md	浙大预约报销日常场景：窗口流程与 Provider 函数契约	开发
11-mcp.md	MCP 产品定义：Agent 工具面、边界、鉴权与分阶段落地	所有人
12-receipt-ocr.md	财务票据 OCR：百度端点全景、统一文档模型与接入架构	开发
13-docs-site.md	文档站：Zensical 构建、Cloudflare Pages 发布流程	维护者

Web SaaS 架构：web 只经 REST/SSE 调 api；api 鉴权和编排，worker 消费 BullMQ 队列；PostgreSQL 是唯一事实源。
工作区隔离：组织 → 工作区 → 成员；每位用户有默认个人工作区，项目/部门可建共享工作区，数据和文件都以 workspace_id 为边界。
访问控制三层兜底：Prisma scope、PostgreSQL RLS、同工作区复合外键；管理员排障使用显式、可审计的访问路径。
全量走百度云 API OCR：不做本地 PDF 解析，统一由 OCR Provider 处理；worker 并发 2 且队列限速 2 QPS。
金额一律存"分"（Integer），展示层再格式化；OCR 原始 JSON 完整保存以支持免付费重放。
双层防重：同工作区文件以 (workspace_id, blob_id) 去重（命中文件的原发票已软删则恢复该发票）；发票号码以组织级规范化键拦截重复报销，且不泄露其他工作区数据。
归档按工作区和报销批次分目录：/data/invoice/{workspace_id}/Archive/ 下的一个批次即一份完整报销材料（发票、附件、导出文件）。
多输入源、单管道：网页上传与 IMAP 邮箱拉取汇入同一 uploads/ + parse_task 管道；用户级密钥用信封加密落库。
通知即分级路由：worker 只 emit(event)，站内通知经 SSE 定向给用户/工作区成员，Webhook 可配钉钉、飞书或通用频道。

docs/
  index.md            # 文档中心（两个入口）
  usage/              # 用户手册：面向报销用户，小白可读的完整流程
  development/        # 开发文档：本文所在目录，编号 01~13