账报工坊 Account Report Workshop

账报工坊是一套面向金蝶云星辰客户和渠道商的经营报表交付方案。它把星辰里的销售、退货、回款、应收、客户和商品数据同步到独立报表库，自动生成老板能看、财务能核、渠道商能交付的经营报表。

项目当前处于第一版验证阶段。公开仓库只保留代码、模拟数据和产品文档，不包含客户数据、内部商务材料或星辰授权信息。

产品界面

页面集中展示净销售额、回款金额和应收余额，并支持按月、季度、日期查看趋势，按客户和业务员筛选。左侧工作台提供账套切换、报表交付、回款跟进、对账验收、口径设置和接口监控入口。

解决什么问题

不少企业已经在星辰中完成日常开单和收付款，但每到月底，财务仍要从多个报表导出 Excel，再手工合并销售、回款和应收数据。账报工坊承接这部分重复加工工作：

• 从星辰 API 同步必要业务数据；
• 按客户确认的口径计算销售、回款和应收指标；
• 把趋势、排行、欠款和明细放在同一个经营工作台；
• 导出 Excel 报表，并保留对账结果和口径说明；
• 支持渠道商使用自己的品牌向客户交付。

它不替代星辰标准报表，也不做财务三大报表。第一版只处理企业每月反复手工制作的经营报表。

第一版范围

第一版聚焦销售回款经营闭环：

能力	当前范围
数据来源	客户、商品、销售出库、销售退货、收款、应收
同步方式	默认最近 12 个月，每日同步，也可手动补同步
经营分析	销售趋势、回款趋势、客户排行、商品排行、业务员排行
财务跟进	应收余额排行、逾期应收明细、回款率
报表交付	8 张标准经营报表、Excel 导出、简版白牌
验收支持	口径设置、简版对账报告、同步状态和失败原因

详细范围见 V1 范围，报表定义见 报表清单。

数据链路

星辰 API
   ↓
PostgreSQL 原始数据层
   ↓
dbt 清洗与经营报表模型
   ↓
FastAPI 报表接口
   ↓
Next.js 经营工作台与 Excel 导出

页面不会在每次打开时直接请求星辰 API。系统先把授权账套的数据同步到本地数据库，再生成报表，便于稳定查询、复核口径和追踪同步结果。

当前技术栈：

• PostgreSQL：保存星辰原始数据和报表结果；
• dbt：清洗数据并生成经营报表模型；
• Cube.js：指标口径层，当前继续收敛中；
• FastAPI：提供同步和报表接口；
• Next.js：经营工作台、筛选和导出页面。

当前状态

第一版已经跑通完整链路：

星辰 API -> 本机数据库 -> 报表数据 -> 后端接口 -> 前端页面

本机默认入口：

• 前端页面：http://127.0.0.1:3000
• 报表接口：http://127.0.0.1:8000/api/reports/dashboard

当前环境只同步了少量数据用于流程验证，不代表完整账套的全量报表。完整交接记录见 项目交接与当前状态。

项目结构

api/          FastAPI 接口、星辰 API 客户端和同步编排
dbt/          数据清洗与经营报表模型
cube/         指标口径定义
web/          Next.js 经营工作台
scripts/      星辰数据同步脚本
docs/         产品范围、口径、对账和交付文档
sample_data/  模拟数据，不存放真实客户数据

本地启动

本机 5432 端口已被其他 PostgreSQL 占用，项目验证环境使用 55432。

1. 准备环境

cp .env.example .env
POSTGRES_IMAGE_TAG=15-alpine POSTGRES_PORT=55432 docker compose up -d postgres
uv sync

星辰连接参数在根目录 .env 中配置：

KINGDEE_CLIENT_ID=
KINGDEE_CLIENT_SECRET=
KINGDEE_INSTANCE_ID=
KINGDEE_API_BASE=https://api.kingdee.com
XINGCHEN_SYNC_PAGE_SIZE=100

不要提交填写过真实凭据的 .env。

2. 启动 API

uv run uvicorn --app-dir api app.main:app --host 127.0.0.1 --port 8000 --reload

3. 构建报表模型

uv run dbt parse --profiles-dir .
uv run dbt build --profiles-dir .

4. 启动前端

cd web
npm install
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000 npm run dev -- --hostname 127.0.0.1 --port 3000

Cube.js 的安装和检查命令：

cd cube
npm install
npm run check

星辰同步命令和完整验证步骤见 星辰 API 同步模块 与 项目交接文档。

文档

• 产品定位
• V1 范围
• 报表清单
• 交付流程
• 报表正确性与对账
• 指标口径治理
• 星辰 API 同步
• 星辰 API 字段设计
• 完整文档索引

仓库规则

• 公开提交前检查文件和 Git 历史；
• 不提交真实客户数据；
• 不提交密钥、Token 或授权信息；
• 不提交渠道合作、报价或其他内部材料；
• sample_data/ 只允许放模拟数据；
• 不从旧星辰指标库整仓复制，只按需要迁移口径和少量可复用代码。