billing-service/docs/README.md

billing-service docs

This directory holds service-owned documentation for billing-service.

总览

• design.md - 当前实现下的系统设计、主执行流程、幂等约束和模块边界

代码参考

• reference/cmd.md - 进程入口、依赖装配与生命周期
• reference/config.md - 配置结构、环境变量和配置解析函数
• reference/model.md - 全部共享数据模型与字段语义
• reference/exporter.md - exporter 客户端与窗口拉取契约
• reference/repository.md - 仓储接口、PostgreSQL 实现与表映射
• reference/service.md - 业务服务、主流程与内部辅助函数
• reference/httpapi.md - HTTP 路由、handler 与状态码映射

系统边界与外部契约

• architecture.md - deployment topology, billing data flow, and current-vs-target architecture notes
• api.md - task endpoints, upstream snapshot contract, and downstream read-model boundaries
• multi-node-https-plan.md - target-state plan for evolving from a single exporter URL to secure multi-node HTTPS ingestion

SQL 契约

• ../sql/billing-service-schema.sql - reference DDL for the accounting tables billing-service depends on

Scope

These docs describe the billing-service role inside the Cloud Network Billing & Control Plane.

• billing-service is the task-oriented write model
• accounts.svc.plus is the PostgreSQL-backed read model
• console.svc.plus is the presentation layer and does not query billing-service directly

System-wide contracts still live in github-org-cloud-neutral-toolkit/docs/architecture/network-billing-contracts.md.

Deployment Verification

Local or operator dry-run validation:

cd /Users/shenlan/workspaces/cloud-neutral-toolkit/playbooks
export DATABASE_URL=postgres://...
ANSIBLE_CONFIG=./ansible.cfg \
ansible-playbook -i ./inventory.ini -D -C ./deploy_billing_service.yml -l jp_xhttp_contabo_host

Notes:

• DATABASE_URL must be exported before running deploy_billing_service.yml
• on jp-xhttp-contabo.svc.plus, DATABASE_URL should reference the same account database used by accounts.svc.plus
• check mode may report predicted changes; the goal is to pass the preflight assertion and render a valid deployment plan
• GitHub Actions uses the BILLING_SERVICE_DATABASE_URL secret to satisfy the same precondition in the deploy-billing-service job