🐙 湛箴 — 凭证到报告的完整审计作业程序

湛箴，吉祥物符号 🐙（八爪抓证据，一脑管风险）；OZ 仅为内部代号。 命名口径与图标设计见 docs/BRAND_OCTOPUS.md 版本：v0.3.0 · 平台化与多受众交付轮 · 发布路线见 VERSIONING.md 上游依据：Ya-MiC/action-tree 总纲 §26 MVP 与《ENGINEERING_SPEC》工程规范。 定位：上传 PDF/图片凭证 → 图文识别 → 凭证覆核 → 序时账分录 → 规则检查 → 可追溯审计报告。 铁律：AI 可以推理，但不能偷改证据 —— 所有证据入库即锁 SHA-256，所有状态迁移追加哈希链事件。

它是什么

湛箴是一个纯 Python、pip 可装、开箱即跑的审计作业程序：

上传凭证(PDF/图片/CSV) → OCR/文本层提取 → VoucherJSON 标准化 → 人工覆核
     → 分录草稿(借贷平衡) → 确认 → 三条 MVP 规则检查 → 序时账/附件索引/异常清单 → HTML 报告

每一份产出都能反向追溯：报告结论 → 风险编号 → 触发凭证 → 原始文件 SHA-256。 内置 AI 助手（可选，默认关闭）：解释风险、建议科目——输出必须过 schema 校验，且永远不能直接改账。

快速开始

方式零：Windows 免安装 exe（双击即用）

# 三步打包，详见 docs/BUILD_WINDOWS.md
pip install -r requirements.txt pyinstaller
pyinstaller zhanzhen.spec
# 产物 dist\zhanzhen.exe —— 双击即启动服务并自动打开浏览器

exe 自动挑空闲端口（环境变量 ZZ_PORT 可固定），数据保存在 exe 同级 data\ 目录；Ctrl+C 或关闭窗口退出。

方式一：pip 直接装（Windows/Linux/macOS 通用）

pip install git+https://github.com/Ya-MiC/zhanzhen.git

# 一键演示：生成示例账套并跑完整管线，输出报告到指定目录
zhanzhen demo /tmp/zz_demo          # Linux/macOS；Windows 用 %TEMP%\zz_demo

# 启动 Web 工作台（浏览器打开 http://localhost:8710；换端口见 .env.example 的 ZZ_PORT）
zhanzhen serve

方式二：源码开发

git clone https://github.com/Ya-MiC/zhanzhen.git
cd zhanzhen
pip install -e ".[dev]"
pytest                # 测试全绿（核心测试零外部依赖）
zhanzhen demo out/    # 跑通后打开 out/report.html

方式三：Docker

cp .env.example .env
docker compose up --build
# 打开 http://localhost:8710

🌐 网页版（Cloudflare Pages，免服务器打开即用）

静态前端独立仓库：Ya-MiC/zhanzhen-web → CF Pages 连接该仓库一键部署（无需构建命令），打开后填你的 API 地址 + Key 即可使用。 数据与桌面/手机端完全同源（同一 PostgreSQL），三端一致。

用户端与管理端（两个入口）

门户	入口	谁用	能做什么
用户端	/（下载 App 或访问工作台）	会计/做账员/客户	上传凭证→OCR→覆核→分录→规则→出报告（按角色收口）
管理台	/admin	仅管理员	平台统计、订阅开通/升级/降级、API Key 发放、到期冻结

• 免费版：下载即用，本地自动是管理员，无登录门槛（ZZ_AUTH_MODE=local 默认）
• 专业版：服务器部署后配 ZZ_USERS=key:名字:角色，用户拿 API Key 登录， 角色四种：admin/accountant/reviewer/viewer——权限矩阵见 zhanzhen/auth.py
• 订阅额度：免费 3 报告/月+100 OCR/月；专业不限量。超量友好提示，数据永不丢
• 服务器放哪、怎么调试：见 SERVER_DEPLOY.md

双端架构（Android + Windows）

端	仓库	职责（ENGINEERING_SPEC §6）
📱 Android 采集端	audit-os-mobile	拍照→本地队列→导出采集包，不做重计算
💻 Windows 工作台	本仓库	批量导入采集包/拖放 PDF → OCR → 覆核 → 序时账 → 规则 → 报告

工作流：手机拍凭证 → 导出 zhanzhen-capture-*.json → 工作台 POST /v1/vouchers/capture-batch 一键收包 → 后续全流程。

报告写作支持

• 按甲方分型：银行/政府/企业老板/事务所/跨境五类版式差异见 docs/REPORT_KNOWLEDGE.md
• 风格学习：上传你自己写过的历史报告（POST /v1/reports/upload-style-sample），AI 助手按你的笔法起草
• 公开范本地图：SEC EDGAR / 巨潮年报审计报告 / PCAOB / 中注协准则 —— 免费资源清单同上文档
• 导出：HTML（交互追溯，已上线）→ PDF/docx 模板（v0.5-beta，weasyprint/docxtpl）

功能总览

模块	能力	上游规范
zhanzhen.canonical	Canonical JSON + SHA-256（键字节序递归排序，全服务唯一实现）	specs/events-v1.md
zhanzhen.events	append-only 事件日志 + 同聚合哈希链 + 链校验	specs/events-v1.md
zhanzhen.state_machine	12 态凭证状态机，非法迁移抛错，每次迁移强制写事件	specs/voucher-state-machine-v1.md
zhanzhen.voucher	VoucherJSON v1 结构校验 + 归一化	specs/voucher-json-v1.schema.json
zhanzhen.ocr	OCRProvider 协议：PDF 文本层适配器 / 确定性 Stub / PaddleOCR 可选加载	ENGINEERING_SPEC §5
zhanzhen.rules	三条 MVP 规则（金额一致性/疑似重复/完整性），参数来自 rules_builtin.yaml	ENGINEERING_SPEC §8.1
zhanzhen.rules12	12 条完整规则引擎（期末突击收入/大额/方向异常/应收占比/毛利率波动/关联方对挂/供应商集中/周末大额/重复交易/短期冲销），重要性水平自动校准，语义完整移植自 audit-os engine.py	audit-os 12 规则
zhanzhen.journal	分录草稿生成、借贷平衡硬校验、确认后不可变（只能 reversal）	ENGINEERING_SPEC §3.4
zhanzhen.report	HTML 可追溯报告（凭证索引带 SHA-256、风险清单带证据引用）	总纲 §7
zhanzhen.ai_assistant	OpenAI 兼容端点接入（NVIDIA/OpenRouter 可配），schema 约束 + model_runs 留痕	ENGINEERING_SPEC §8.2
web/index.html	Vue3 单页工作台：上传/凭证箱/覆核/分录/风险/报告/AI 助手	ENGINEERING_SPEC §6
dsh-plugin/	DSH (DeepSeek Harness) 插件：一切皆插件架构的接入层	deepseek-harness

安全基线（诚实版）

• ✅ 服务端重算 SHA-256（不信客户端）、原始文件只读、事件链防篡改、确认分录不可 UPDATE
• ✅ 错误统一信封（code/message/details/trace_id），不回传堆栈；日志不落凭证正文
• ⚠️ MVP 为单租户内存+快照存储（ZZ_DATA_DIR），PostgreSQL/RLS/MinIO 是下一步（见 LIMITATIONS.md）
• ⚠️ AI 助手默认关闭；开启需显式配置 ZZ_AI_* 环境变量，且只读访问已确认数据

文档地图

• ARCHITECTURE.md — 架构、模块图、specs↔代码映射表
• LIMITATIONS.md — 做不到什么、需要人类帮什么（诚实清单）
• ACKNOWLEDGEMENTS.md — 致谢与开源协议（我们站在谁的肩膀上）
• docs/OCR_STRATEGY.md — 手机 OCR 三级降级链（系统级→PaddleLite→服务端）
• docs/MOBILE_WORKFLOW.md — 手机拍照→工作台全流程
• docs/PRODUCT_TIERS.md — 免费/专业两档切分 + 注册会计师签发边界
• docs/ASSETS_AND_LICENSE.md — 资产分层：引擎 MIT / 配方闭源 / 数据用户所有
• docs/DOC_MAP.md — 全部文档蓝图与路径索引（18个月规划）
• action-tree 总纲 — 为什么做、做什么（人类亲笔）

许可

MIT © 2026 Ya-MiC。第三方依赖及其协议见 ACKNOWLEDGEMENTS.md。