诺梵业务流程知识库文档

Factify 能力复用策略

本方案的核心设计原则是最大化复用 Factify 现有基础设施，避免重复建设。以下为能力复用关系：

Factify 现有模块	复用方式	对本方案的支撑
WDT 数据同步引擎 (`wdtqjsync`)	零修改复用	提供全部原始数据源（销售出库、退货退款、支付宝账单等），对账引擎作为数据消费者读取
WDT 旗舰版 API 客户端 (`wdtqj`)	零修改复用	平台账单、发票等增量数据拉取
宽表引擎 (`wide_table`)	数据源复用	直接读取已建立的销售宽表、佣金宽表、利润宽表、库存宽表
跨库同步 (`dbsync`)	工具复用	从原 Java 系统 MySQL 迁移基础配置数据到 PostgreSQL
应用数据库 (`appdb`)	模式复用	复用 Schema Migration + Run Tracking 的数据库管理模式
HTTP 路由框架 (`httpserver`)	模式复用	复用 ServeMux 路由注册、JSON 处理、Auth Middleware 的标准模式
React + Mantine 前端	组件复用	复用 hash 路由、DataTable 组件、i18n、toast 通知等基础设施

整体数据流架构

Rendering diagram…

核心模块划分

后端新包：`internal/recon/`

对账模块作为 Factify 后端的独立业务包，编译进同一 Go 二进制：

模块分组	核心文件	业务职责
认证安全	`auth.go`, `user.go`, `tenant.go`	JWT 登录/会话（多租户）、用户 CRUD、bcrypt 密码管理
基础设置	`shops.go`, `distributors.go`, `settlement_cfg.go`, `tp_manager.go`, `custom_props.go`	店铺管理、分销商管理、结算配置、TP管理、自定义属性
对账引擎	`engine.go`, `formulas.go`, `on_sale.go`, `after_sale.go`	SQL 模板驱动对账引擎核心、售中对账、售后对账
物流资费	`logistics.go`, `postage.go`	物流资费对账、邮费对账
报表查询	`reports.go`, `status.go`	统一报表 Handler + SQL 模板注册、对账状态管理
结算管理	`settlements.go`, `adjustments.go`, `invoices.go`	结算生成、金额调整审批流、发票管理
发货退款	`shipping.go`, `refunds.go`, `returns.go`, `pre_warehouse.go`	发货、退款、退货、预入库报表
数据管理	`backup.go`	对账结果备份/恢复

数据库 Schema 隔离

数据按业务域严格隔离在独立的 PostgreSQL Schema 中：

Schema	用途	关系
`wdtqj`	WDT 同步原始数据（已有，只读）	对账引擎的数据源
`dbo`	宽表数据（已有，只读）	对账引擎的增强数据源
`app`	应用运行记录（已有）	复用 Run Tracking 模式
`recon`	对账业务数据（新建）	独立管理，与源数据解耦

Schema 隔离的核心好处：对账模块的数据与 WDT 同步数据、宽表数据完全解耦。WDT 同步引擎的任何变更不影响对账结果表；对账模块的升级也不影响数据采集链路。

API 路由设计

新增加在 internal/httpserver/recon.go，遵循现有路由注册模式：


POST /api/recon/auth/login            -- 登录
POST /api/recon/auth/logout           -- 登出
GET  /api/recon/auth/me               -- 当前用户信息

CRUD /api/recon/users                 -- 用户管理
CRUD /api/recon/shops                 -- 店铺管理
CRUD /api/recon/distributors          -- 分销商管理
CRUD /api/recon/settlement-configs    -- 结算配置
CRUD /api/recon/tp-managers           -- TP 管理
CRUD /api/recon/custom-properties     -- 自定义属性

GET/POST /api/recon/formulas          -- 对账公式配置
GET/POST /api/recon/runs              -- 对账执行记录

GET  /api/recon/reports/{type}        -- 统一报表查询（60+ 报表）
GET  /api/recon/reports/{type}/export -- Excel 导出

GET/POST /api/recon/adjustments       -- 金额调整
POST /api/recon/settlements/generate  -- 生成结算
POST /api/recon/backups/create        -- 创建备份

安全认证体系

多租户 + 角色权限

沿用原慧策系统的权限模型，基于 Factify 的 JWT 认证体系扩展：

多租户隔离：recon.tenants 表管理租户，所有查询带租户过滤
JWT 会话管理：登录签发 JWT，reconAuth middleware 统一校验
角色权限：7 大权限类型（shopRight、collectRight、mainRight、warehouseRight、logisticsRight、propRight、recordRight），以 JSON 存储在用户记录中
密码安全：bcrypt 哈希存储，登录失败次数限制

前端架构

复用 Factify 前端的 React + Mantine 技术栈：

通用组件：ReportTable（分页/排序/筛选）、ReportFilters（日期/店铺/状态）、PeriodSelector、ShopMultiSelect
路由扩展：在 App.tsx 中注册对账模块的所有页面路由
Hash 路由：复用现有 hash router，保持一致的导航体验

前端复用策略：一套 ReportTable 通用组件服务 60+ 报表页面，只需配置 columns + data source，无需为每个报表开发独立页面。