结算管理

优先级: P1（业务增长模块）
开发周期: 2-3 周

目标

自动化管理平台与代理商（收款）和供应商（付款）之间的财务结算，包括对账、佣金计算、发票管理。

核心功能

功能	描述
对账管理	供应商账单与平台订单自动匹配对账
佣金计算	根据合同约定的佣金率自动计算佣金
结算周期	按日/周/月生成结算单
发票管理	发票申请、开具、登记
付款管理	付款申请、审批、打款记录
应收应付	代理商应收、供应商应付的账龄分析
财务报表	收入/支出/利润报表

结算流程

订单完成 → 进入结算队列 → 自动对账
    → 生成供应商应付账单（采购成本）
    → 生成代理商应收账单（售价）
    → 佣金计算: 平台收入 = 应收 - 应付
    → 结算单生成（按周期汇总）
    → 发票开具
    → 付款/收款

数据模型

-- 结算单表
CREATE TABLE settlement_bills (
    id                  BIGSERIAL PRIMARY KEY,
    bill_no             VARCHAR(32) NOT NULL UNIQUE,  -- SET-YYYYMMDD-XXXXX
    bill_type           VARCHAR(32) NOT NULL,          -- payable(应付)/receivable(应收)
    party_code          VARCHAR(32) NOT NULL,          -- 供应商/代理商编码
    party_name          VARCHAR(255) NOT NULL,

    period_start        DATE NOT NULL,
    period_end          DATE NOT NULL,

    order_count         INT DEFAULT 0,
    total_amount        DECIMAL(14, 2) DEFAULT 0,
    commission          DECIMAL(14, 2) DEFAULT 0,
    net_amount          DECIMAL(14, 2) DEFAULT 0,     # 实际结算金额
    currency            VARCHAR(3) DEFAULT 'CNY',

    status              VARCHAR(20) DEFAULT 'draft',  -- draft/pending_approval/approved/paid/cancelled
    approved_by         VARCHAR(64),
    approved_at         TIMESTAMPTZ,
    paid_at             TIMESTAMPTZ,

    notes               TEXT,
    created_at          TIMESTAMPTZ DEFAULT NOW(),
    updated_at          TIMESTAMPTZ DEFAULT NOW()
);

-- 结算明细表（每笔订单的结算记录）
CREATE TABLE settlement_items (
    id                  BIGSERIAL PRIMARY KEY,
    bill_id             BIGINT REFERENCES settlement_bills(id),
    order_id            BIGINT NOT NULL REFERENCES orders(id),
    order_no            VARCHAR(32) NOT NULL,
    hotel_name          VARCHAR(255),
    check_in            DATE,
    check_out           DATE,
    nights              SMALLINT,

    gross_amount        DECIMAL(12, 2) NOT NULL,     # 应收金额
    net_amount          DECIMAL(12, 2) NOT NULL,     # 应付金额
    commission          DECIMAL(12, 2),              # 佣金
    currency            VARCHAR(3) DEFAULT 'CNY',

    reconciliation_status VARCHAR(20) DEFAULT 'matched', -- matched/unmatched/disputed
    dispute_reason      TEXT,

    created_at          TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_settlement_items_bill ON settlement_items (bill_id);
CREATE INDEX idx_settlement_items_order ON settlement_items (order_id);

-- 发票表
CREATE TABLE invoices (
    id              BIGSERIAL PRIMARY KEY,
    invoice_no      VARCHAR(32) NOT NULL UNIQUE,     -- INV-YYYYMMDD-XXXXX
    bill_id         BIGINT REFERENCES settlement_bills(id),
    party_code      VARCHAR(32) NOT NULL,
    party_name      VARCHAR(255) NOT NULL,

    invoice_type    VARCHAR(32) NOT NULL,            -- sales(销售发票)/purchase(采购发票)
    amount          DECIMAL(14, 2) NOT NULL,
    tax_amount      DECIMAL(14, 2) DEFAULT 0,
    total_amount    DECIMAL(14, 2) NOT NULL,
    currency        VARCHAR(3) DEFAULT 'CNY',

    # 发票信息
    invoice_title   VARCHAR(255),                   # 发票抬头
    tax_number      VARCHAR(32),                    # 税号
    status          VARCHAR(20) DEFAULT 'pending',  -- pending/issued/cancelled

    file_url        VARCHAR(512),                   # 发票文件URL

    issued_at       TIMESTAMPTZ,
    created_at      TIMESTAMPTZ DEFAULT NOW()
);

-- 付款记录表
CREATE TABLE payments (
    id              BIGSERIAL PRIMARY KEY,
    payment_no      VARCHAR(32) NOT NULL UNIQUE,     -- PAY-YYYYMMDD-XXXXX
    bill_id         BIGINT REFERENCES settlement_bills(id),
    party_code      VARCHAR(32) NOT NULL,

    amount          DECIMAL(14, 2) NOT NULL,
    currency        VARCHAR(3) DEFAULT 'CNY',
    payment_method  VARCHAR(32),                     -- bank_transfer/credit/alipay
    payment_ref     VARCHAR(128),                    # 付款参考号/银行流水号

    status          VARCHAR(20) DEFAULT 'pending',  -- pending/processing/completed/failed
    paid_at         TIMESTAMPTZ,
    confirmed_by    VARCHAR(64),

    notes           TEXT,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    updated_at      TIMESTAMPTZ DEFAULT NOW()
);

接口设计

# 结算 API
GET    /api/v1/settlements/bills                 # 结算单列表
POST   /api/v1/settlements/bills/generate        # 手动生成结算单
GET    /api/v1/settlements/bills/:id             # 结算单详情+明细
PUT    /api/v1/settlements/bills/:id/approve     # 审批结算单
PUT    /api/v1/settlements/bills/:id/cancel      # 取消结算单

# 对账 API
GET    /api/v1/settlements/reconciliation        # 对账结果列表
POST   /api/v1/settlements/reconciliation/run    # 触发对账
GET    /api/v1/settlements/reconciliation/disputes  # 争议列表

# 发票 API
GET    /api/v1/settlements/invoices              # 发票列表
POST   /api/v1/settlements/invoices              # 创建发票申请
PUT    /api/v1/settlements/invoices/:id/status   # 更新发票状态

# 付款 API
GET    /api/v1/settlements/payments              # 付款列表
POST   /api/v1/settlements/payments              # 记录付款
PUT    /api/v1/settlements/payments/:id/confirm  # 确认付款

# 财务报表 API
GET    /api/v1/settlements/reports/profit        # 利润报表
GET    /api/v1/settlements/reports/receivables   # 应收账龄分析
GET    /api/v1/settlements/reports/payables      # 应付账龄分析

与其他模块的关系

关联模块	关系
订单管理	已完成订单进入结算
销售管理	获取合同条款（佣金率、账期）
价格管理	获取价格数据用于结算计算
管理后台	结算管理、审批、报表界面
数据智能	财务数据用于 BI 分析

技术选型建议

事务: 结算操作必须强事务，确保账单+明细+发票一致性
Asynq 定时任务: 每日自动对账、自动生成结算单
PDF 生成: 使用 Go 库（如 go-pdf）生成结算单和发票 PDF