1 line
63 KiB
JSON
1 line
63 KiB
JSON
{"repo": "cacaview/data", "files": {"README.md": {"29b12f87623090904fc6f3c7e30ef92a92f5a046": {"t": 1785746656.5861452, "n": 18058, "h": "1ef31447a32f875c", "c": "# ACTAP — 东盟跨境贸易 AI 智能分析平台\n\n> **ASEAN Cross-Border Trade AI Analytics Platform** | 中国—东盟双边贸易数据 + AI 智能分析\n\n[English](#english) · [中文](#中文)\n\n---\n\n## 中文\n\n### 项目简介\n\nACTAP 是一个面向中国—东盟跨境贸易的 AI 智能分析平台，整合 9 个权威数据源（UN Comtrade、World Bank、IMF、广西公共数据平台、北部湾港、RCEP 关税数据库等），提供：\n\n- 📊 **总览仪表盘** — KPI 卡片、Mapbox 交互式贸易地图、月度趋势、桑基流向图\n- 🔍 **贸易分析** — 多国趋势对比、雷达图、Top-N 排名、完整桑基图\n- 🤖 **AI 预测** — ARIMA/SARIMA/Holt-Winters 时序预测、商品聚类、风险预警\n- 🧮 **关税计算** — RCEP/ACFTA/MFN 三档对比，原产地规则，节省金额\n- 💬 **AI 助手** — 基于 DeepSeek 的对话式贸易问答\n- 📈 **量化分析** — 多因子分解、相关性/协整分析、交易信号、VaR、组合优化、回测\n- 🏢 **企业风控** — 供应链风险评分、合规筛查、跨 FTA 关税优化、供应链网络图\n- 🌏 **社会经济** — 宏观指标、贸易影响力、ESG 可持续性、贸易竞争力\n- 📝 **报告生成** — 一键导出 PDF / Word 贸易分析报告\n- 🔐 **用户认证** — JWT 双 Token 认证 + 角色管理\n- 🌐 **国际化** — 中文 / English 双语切换\n\n### 技术栈 / Tech Stack\n\n| 层级 | 技术 | 版本 |\n|------|------|------|\n| **前端框架** | React + TypeScript | 19.2 / 6.0 |\n| **UI 组件** | Ant Design + Icons | 6.5 / 6.3 |\n| **可视化** | ECharts + Mapbox GL | 6.1 / 3.26 |\n| **路由** | React Router | 7.18 |\n| **构建工具** | Vite | 8.1 |\n| **HTTP** | Axios | 1.18 |\n| **日期** | dayjs | 1.11 |\n| **Linter** | oxlint | 1.71 |\n| **后端框架** | FastAPI + Uvicorn | 0.115 / 0.30 |\n| **ORM** | SQLAlchemy | 2.0 |\n| **校验** | Pydantic + Settings | 2.9 / 2.5 |\n| **日志** | structlog（JSON / 彩色） | 24.4 |\n| **异步 HTTP** | httpx | 0.27 |\n| **认证** | PyJWT + bcrypt | 2.8+ / 4.0+ |\n| **报告** | ReportLab + python-docx | 4.0+ / 1.0+ |\n| **统计** | NumPy + SciPy + pandas | 1.26 / 1.11 / 2.2 |\n| **ML** | scikit-learn + statsmodels + arch | 1.5 / 0.14 / 6.0 |\n| **AI 对话** | OpenAI 兼容（DeepSeek） | 1.50 |\n| **存储** | SQLite（6 表） + 文件缓存（TTL 24h） | — |\n| **测试** | pytest + httpx TestClient | 8.3 |\n| **格式化** | ruff | 0.7 |\n| **容器** | Docker 多阶段构建 | — |\n| **Web 服务器** | Nginx（前端静态 + API 代理） | 1.27 |\n\n### 架构 / Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────┐\n│ Browser ─→ Nginx (FE) :3000 │\n│ │ /api/* proxy │\n│ ▼ │\n│ FastAPI Backend :8001 │\n│ ┌────────────────────────────────────────────────────────────────┐ │\n│ │ Middleware chain (outer → inner) │ │\n│ │ CORS → RequestTracking → Prometheus → RateLimit → │ │\n│ │ APIKeyAuth → App │ │\n│ └────────────────────────────────────────────────────────────────┘ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ api/routes/ services/ repositories/ │\n│ (HTTP 层) (业务逻辑) (数据访问层) │\n│ ├ overview ├ trade_service └ trade_repo │\n│ ├ trade │ │\n│ ├ ai_predict data/ │\n│ ├ tariff (数据引擎 & 外部 API) │\n│ ├ chat ├ analytics.py ← 爆发检测 + RCEP 节省 │\n│ ├ analytics ├ factor_engine.py ← 多因子分解 (Fama-French) │\n│ ├ quant ├ ts_models.py ← ARIMA/SARIMA/Holt-Winters │\n│ ├ enterprise ├ signal_generator.py ← 交易信号 │\n│ ├ socioeconomic ├ portfolio_optimizer.py ← Markowitz 组合 │\n│ ├ auth ├ var_calculator.py ← VaR / CVaR │\n│ ├ report ├ correlation_engine.py ← 协整/结构性突变 │\n│ └ datasources ├ backtest_engine.py ← 蒙特卡洛回测 │\n│ ├ chinadata_client stats_gov_client │\n│ ├ comtrade_client worldbank_client │\n│ ├ commodity_client imf_client bdi_client │\n│ └ cache.py │\n│ │ │\n│ └───────────────────────────────────────┐ │\n│ ▼ │\n│ SQLAlchemy ORM │\n│ │ │\n│ ┌────────────┴──────────┐ │\n│ ▼ ▼ │\n│ SQLite (actap.db) API Cache DB │\n│ ├ users (认证) │\n│ ├ countries (国家维度) │\n│ ├ products (商品维度) │\n│ ├ trade_records (贸易事实) │\n│ ├ tariff_rules (关税规则) │\n│ └ data_sources (数据源元数据) │\n└──────────────────────────────────────────────────────────────────────┘\n```\n\n### 页面模块 / Pages\n\n| 路由 | 模块 | 功能 |\n|------|------|------|\n| `/` | 总览仪表盘 | KPI 卡片、Mapbox 贸易地图、月度趋势、桑基流向 |\n| `/trade` | 贸易分析 | 多国趋势、雷达对比、排名、完整桑基图（4 Tab） |\n| `/ai` | AI 预测 | 时序预测、商品聚类散点图、风险预警时间线 |\n| `/tariff` | 关税计算 | RCEP/ACFTA/MFN 三档对比、原产地规则、节省饼图 |\n| `/analytics` | 智能分析 | 爆发检测、价值链位置、RCEP 节省、风险仪表盘 |\n| `/factors` | 因子分析 | 因子贡献瀑布图、季节雷达、趋势分解、洞察表 |\n| `/quant` | 量化分析 | 交易信号、VaR、有效前沿、时序预测 |\n| `/enterprise` | 企业风控 | 风险监控、合规审查、成本优化、供应链网络 |\n| `/socioeconomic` | 社会经济 | 宏观指标、贸易影响力、ESG、竞争力 |\n| `/chat` | AI 助手 | 对话式贸易问答，支持内联图表 |\n| `/assets` | 数据资产 | 数据血缘、质量监控、数据目录 |\n| `/login` | 用户认证 | 登录 / 注册（JWT） |\n\n### 本地启动 / Quickstart\n\n#### 方式 A：Docker（推荐）\n\n```bash\ngit clone <repo-url> actap && cd actap\ncp .env.dev .env\ndocker compose up -d\n# Frontend: http://localhost:3000\n# Backend: http://localhost:8001/docs\n```\n\n#### 方式 B：本地 Python + Node\n\n```bash\n# Backend\ncd backend\npython3 -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\nuvicorn app.main:app --reload --port 8001\n\n# Frontend (separate terminal)\ncd frontend\nnpm install\nnpm run dev # http://localhost:3000\n```\n\n### 部署 / Deployment\n\n| 环境 | 命令 |\n|------|------|\n| Dev | `docker compose up -d` |\n| Staging | `docker compose -f docker-compose.prod.yml --env-file .env.staging up -d` |\n| Production | `docker compose -f docker-compose.prod.yml --env-file .env.prod up -d` |\n| Bare-metal (systemd) | `sudo cp deploy/systemd/*.service /etc/systemd/system && sudo systemctl enable --now actap-backend actap-frontend` |\n| Release (CI) | Tag a commit `git tag v1.2.3 && git push --tags` → GitHub Actions builds and pushes to GHCR |\n| Manual release | `./deploy/scripts/release.sh v1.2.3` (auto-rollback on health-check fail) |\n\n详见 [`docs/OPERATIONS.md`](docs/OPERATIONS.md)。\n\n### 开发 / Development\n\n```bash\n# Lint\ncd backend && ruff check . && ruff format --check .\ncd frontend && npm run lint\n\n# Tests\ncd backend && pytest -v --cov=app\n# Coverage report → htmlcov/index.html\n\n# OpenAPI 文档 (dev only)\nopen http://localhost:8001/docs\n```\n\n### 环境变量 / Environment\n\n所有可调参数见 [`backend/.env.example`](backend/.env.example)。关键项：\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `ENVIRONMENT` | `development` / `staging` / `production` | `development` |\n| `API_KEY` | 生产必填，`X-API-Key` header 鉴权 | — |\n| `CORS_ORIGINS` | 生产必须白名单（不能 `*`） | `*` |\n| `DATABASE_URL` | SQLite 或 PostgreSQL 连接串 | `sqlite:///./actap.db` |\n| `OPENAI_API_KEY` | AI 助手所需（DeepSeek） | — |\n| `OPENAI_BASE_URL` | 兼容 API 地址 | `https://api.deepseek.com` |\n| `MODEL_NAME` | 大模型名称 | `deepseek-chat` |\n| `RATE_LIMIT_PER_MINUTE` | 全局限流（IP） | `120` |\n| `RATE_LIMIT_STRICT_PER_MINUTE` | 严格端点限流 | `10` |\n\n### 项目结构 / Project Structure\n\n```\nactap/\n├── backend/ # FastAPI 后端\n│ ├── app/\n│ │ ├── api/routes/ # HTTP 端点（薄层）\n│ │ │ ├── health.py # 健康检查 + Prometheus 指标\n│ │ │ ├── auth.py # 注册 / 登录 / 用户信息\n│ │ │ ├── overview.py # KPI 总览 + 贸易地图\n│ │ │ ├── trade.py # 贸易趋势 / 排名 / 桑基\n│ │ │ ├── ai_predict.py # 时序预测 / 聚类 / 风险\n│ │ │ ├── tariff.py # RCEP 关税计算\n│ │ │ ├── chat.py # AI 对话助手\n│ │ │ ├── analytics.py # 爆发检测 / 风险 / 价值链\n│ │ │ ├── quant.py # 量化分析全套端点\n│ │ │ ├── enterprise.py # 企业风控中心\n│ │ │ ├── socioeconomic.py # 社会经济仪表盘\n│ │ │ ├── report.py # PDF/Word 报告导出\n│ │ │ ├── assets.py # 数据资产血缘 / 质量 / 目录\n│ │ │ └── datasources.py # 数据源状态 / 汇率 / 宏观\n│ │ ├── services/ # 业务逻辑（纯 Python）\n│ │ │ └── trade_service.py\n│ │ ├── repositories/ # 数据访问层（SQLAlchemy）\n│ │ │ └── trade_repo.py\n│ │ ├── data/ # 数据引擎 + 外部 API 客户端\n│ │ │ ├── factor_engine.py # 多因子分析（Fama-French 风格）\n│ │ │ ├── ts_models.py # ARIMA / SARIMA / Holt-Winters / STL\n│ │ │ ├── signal_generator.py # 交易信号（动量 / 均值回归 / 突破）\n│ │ │ ├── portfolio_optimizer.py # Markowitz 组合优化\n│ │ │ ├── var_calculator.py # VaR / CVaR / 压力测试\n│ │ │ ├── correlation_engine.py # 协整 / 结构突变 / 聚类\n│ │ │ ├── backtest_engine.py # 蒙特卡洛回测\n│ │ │ ├── analytics.py # 爆发检测 / RCEP 节省\n│ │ │ ├── chinadata_client.py # 中国海关数据门户\n│ │ │ ├── stats_gov_client.py # 国家统计局\n│ │ │ ├── commodity_client.py # World Bank 商品价格\n│ │ │ ├── comtrade_client.py # UN Comtrade\n│ │ │ ├── worldbank_client.py # World Bank 开放数据\n│ │ │ ├── imf_client.py # IMF DOTS\n│ │ │ ├── bdi_client.py # 波罗的海干散货指数\n│ │ │ ├── exchange_rate_client.py # 汇率数据\n│ │ │ ├── tariff_loader.py # RCEP/ACFTA 关税规则库\n│ │ │ ├── cache.py # SQLite API 缓存\n│ │ │ └── etl.py # ETL 管道\n│ │ ├── ai/ # AI 服务\n│ │ │ ├── auth_service.py # JWT + bcrypt\n│ │ │ ├── chat_service.py # DeepSeek 对话\n│ │ │ └── report_service.py # PDF / Word 报告生成\n│ │ ├── core/ # 配置 + 常量 + 日志 + 指标\n│ │ │ ├── config.py # pydantic-settings 配置\n│ │ │ ├── constants.py # 命名常量（无魔术数字）\n│ │ │ ├── logging.py # structlog 配置\n│ │ │ └── metrics.py # Prometheus 注册表\n│ │ ├── middleware/ # 中间件链\n│ │ │ ├── auth.py # API Key 鉴权\n│ │ │ ├── rate_limit.py # 滑动窗口限流\n│ │ │ ├── errors.py # 统一错误码 + 脱敏\n│ │ │ ├── tracking.py # Request ID 追踪\n│ │ │ └── metrics_mw.py # Prometheus 指标采集\n│ │ ├── models/ # 数据模型\n│ │ │ ├── database.py # SQLite 引擎 + Session\n│ │ │ ├── schemas_db.py # ORM（User/TradeRecord/Country/Product/TariffRule/DataSource）\n│ │ │ ├── schemas.py # Pydantic 响应模型\n│ │ │ └── schemas_auth.py # 认证相关模型\n│ │ ├── mock_data/ # 开发数据\n│ │ │ ├── init_db.py # DB 初始化 + 真实数据拉取\n│ │ │ └── trade_generator.py # 模拟贸易数据生成器\n│ │ └── main.py # App 工厂 + 生命周期\n│ ├── tests/ # pytest（单元 + 集成）\n│ ├── requirements.txt\n│ ├── pyproject.toml # ruff + pytest 配置\n│ └── Dockerfile # 多阶段：Python 3.11-slim\n├── frontend/ # React SPA\n│ ├── src/\n│ │ ├── i18n/ # 国际化（zh-CN / en-US）\n│ │ ├── components/ # 全局组件\n│ │ │ └── LanguageSwitcher.tsx # 语言切换按钮\n│ │ ├── layouts/\n│ │ │ └── AppLayout.tsx # 侧边栏 + 头部 + Outlet\n│ │ ├── pages/\n│ │ │ ├── Dashboard/ # 总览仪表盘（含 Mapbox / TradeMap / KPICards / MiniTrend / MiniSankey）\n│ │ │ ├── TradeAnalysis/ # 贸易分析（4 Tab）\n│ │ │ ├── AIPrediction/ # AI 预测（LSTM / 聚类 / 风险）\n│ │ │ ├── TariffCalc/ # 关税计算器\n│ │ │ ├── Analytics/ # 智能分析中心\n│ │ │ ├── FactorAnalysis/ # 多因子分析\n│ │ │ ├── QuantDashboard/ # 量化分析仪表盘\n│ │ │ ├── Enterprise/ # 企业风控中心\n│ │ │ ├── Socioeconomic/ # 社会经济仪表盘\n│ │ │ ├── AIAssistant/ # AI 对话助手\n│ │ │ ├── DataAssets/ # 数据资产管理\n│ │ │ └── Auth/ # 登录 / 注册\n│ │ ├── services/api.ts # Axios 类型化 API 客户端\n│ │ ├── types/index.ts # 前端领域类型定义\n│ │ ├── hooks/useApi.ts # 通用数据获取 Hook\n│ │ └── utils/ # 格式化 / API 工具函数\n│ ├── nginx.conf # 生产 nginx 配置\n│ └── Dockerfile # 多阶段：Node 20 → Nginx 1.27\n├── deploy/\n│ ├── systemd/ # 生产进程管理（安全加固）\n│ └── scripts/ # release.sh（自动回滚）\n├── docs/ # 文档\n│ ├── API.md # API 端点速查\n│ ├── OPERATIONS.md # SRE 运维手册\n│ └── adr/ # 架构决策记录\n├── .github/workflows/ # CI: lint → test → build → push\n├── docker-compose.yml # Dev\n├── docker-compose.prod.yml # Prod\n├── .env.dev / .env.staging / .env.prod\n└── README.md\n```\n\n### 代码统计 / Code Stats\n\n| 目录 | Python 文件数 | 代码行数 |\n|------|-------------|---------|\n| `backend/app/` | 63 | ~13,400 |\n| `backend/tests/` | 37 | ~3,800 |\n| **总计** | **100** | **~17,200** |\n\n### 贡献 / Contributing\n\n欢迎贡献！请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 与 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。\n\n### 许可证 / License\n\nMIT\n\n---\n\n## English\n\n### Overview\n\nACTAP is an AI-powered analytics platform for China–ASEAN cross-border trade. It integrates 9 authoritative data sources (UN Comtrade, World Bank, IMF, Guangxi Open Data, Beibu Gulf Port, RCEP Tariff DB) and provides:\n\n- 📊 **Overview dashboard** — KPIs, Mapbox interactive trade map, monthly trends, Sankey flow diagram\n- 🔍 **Trade analysis** — multi-country trends, radar comparison, Top-N ranking, full Sankey (4 tabs)\n- 🤖 **AI prediction** — ARIMA/SARIMA/Holt-Winters time series forecast, product clustering, risk alerts\n- 🧮 **Tariff calculator** — RCEP / ACFTA / MFN comparison with USD savings and origin rules\n- 💬 **AI assistant** — conversational Q&A powered by DeepSeek LLM\n- 📈 **Quantitative analytics** — multi-factor decomposition, correlation/cointegration, trading signals, VaR, portfolio optimization, backtesting\n- 🏢 **Enterprise risk** — supply chain risk scoring, compliance screening, cross-FTA cost optimization, supply chain network visualization\n- 🌏 **Socioeconomic dashboard** — macro indicators, trade impact, ESG sustainability, competitiveness indices\n- 📝 **Report generation** — one-click PDF / Word export of trade analysis reports\n- 🔐 **Authentication** — JWT-based user registration / login with role management\n- 🌐 **i18n** — Chinese / English language switching\n\n### Highlights\n\n- **Type-safe end-to-end** — Pydantic + TypeScript strict types, zero `any` in API layer\n- **Production-grade** — non-root Docker, structured JSON logging, Prometheus metrics, health checks, rate limiting, API key auth\n- **Layered architecture** — `api → services → repositories → models` (4-layer separation)\n- **Observable** — every request has a `request_id`, W3C `traceparent` support, all logs structured in prod\n- **Secure by default** — CORS whitelist enforced in prod, secrets from env, no hardcoded keys, bcrypt passwords\n- **Rich analytics engine** — 11 dedicated modules covering time series, factor analysis, signals, VaR, portfolio, backtesting\n- **Multi-source data** — 9+ external API clients with SQLite caching and TTL\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Frontend | React + TypeScript | 19.2 / 6.0 |\n| UI | Ant Design + Icons | 6.5 / 6.3 |\n| Visualization | ECharts + Mapbox GL | 6.1 / 3.26 |\n| Routing | React Router | 7.18 |\n| Build | Vite | 8.1 |\n| Backend | FastAPI + Uvicorn | 0.115 / 0.30 |\n| ORM | SQLAlchemy | 2.0 |\n| Validation | Pydantic + Settings | 2.9 / 2.5 |\n| Logging | structlog | 24.4 |\n| Auth | PyJWT + bcrypt | 2.8+ / 4.0+ |\n| Reports | ReportLab + python-docx | 4.0+ / 1.0+ |\n| Analytics | NumPy + SciPy + pandas + statsmodels | 1.26 / 1.11 / 2.2 / 0.14 |\n| ML | scikit-learn + arch (GARCH) | 1.5 / 6.0 |\n| Storage | SQLite (6 tables) + file cache (TTL 24h) | — |\n| Testing | pytest + httpx TestClient | 8.3 |\n| Linting | ruff + oxlint | 0.7 / 1.71 |\n| Containers | Docker multi-stage (Python 3.11-slim / Node 20 → Nginx 1.27) | — |\n\n### Project structure\n\n```\nactap/\n├── backend/ # FastAPI service\n│ ├── app/\n│ │ ├── api/routes/ # 15 HTTP endpoint modules (thin layer)\n│ │ ├── services/ # Business logic (pure Python)\n│ │ ├── repositories/ # Data access (SQLAlchemy)\n│ │ ├── data/ # 17 analytics engines + API clients + cache\n│ │ ├── ai/ # Auth, chat (DeepSeek), report generation\n│ │ ├── core/ # Config, constants, logging, metrics\n│ │ ├── middleware/ # Auth, rate limit, errors, tracking, metrics\n│ │ ├── models/ # ORM (6 tables) + Pydantic schemas\n│ │ ├── mock_data/ # DB init + mock trade data generator\n│ │ └── main.py # App factory + lifespan\n│ ├── tests/ # 37 test files (~3,800 lines)\n│ ├── pyproject.toml # ruff + pytest config\n│ ├── requirements.txt # 30+ runtime + dev dependencies\n│ └── Dockerfile\n├── frontend/ # React 19 SPA\n│ ├── src/\n│ │ ├── i18n/ # zh-CN / en-US translations\n│ │ ├── components/ # LanguageSwitcher\n│ │ ├── layouts/ # AppLayout (sider + header)\n│ │ ├── pages/ # 12 feature pages + Auth\n│ │ ├── services/ # Typed Axios API client\n│ │ ├── types/ # Domain types (228 lines)\n│ │ ├── hooks/ # useApi generic fetch hook\n│ │ └── utils/ # format, api helpers\n│ ├── nginx.conf # Production nginx config\n│ └── Dockerfile # Node 20 → Nginx 1.27\n├── deploy/\n│ ├── systemd/ # Production process supervision\n│ └── scripts/ # release.sh (with auto-rollback)\n├── docs/ # API.md, OPERATIONS.md, ADRs\n├── .github/workflows/ # CI: lint → test → build → push\n├── docker-compose.yml # Dev\n├── docker-compose.prod.yml # Prod (resource limits, hardening)\n├── .env.dev / .env.staging / .env.prod\n└── README.md (this file)\n```\n\n### License\n\nMIT — see [`LICENSE`](LICENSE).\n"}, "6fee8117926d502784773438b583b7374986f0fe": {"t": 1785766641.1096053, "n": 18058, "h": "1ef31447a32f875c", "c": "# ACTAP — 东盟跨境贸易 AI 智能分析平台\n\n> **ASEAN Cross-Border Trade AI Analytics Platform** | 中国—东盟双边贸易数据 + AI 智能分析\n\n[English](#english) · [中文](#中文)\n\n---\n\n## 中文\n\n### 项目简介\n\nACTAP 是一个面向中国—东盟跨境贸易的 AI 智能分析平台，整合 9 个权威数据源（UN Comtrade、World Bank、IMF、广西公共数据平台、北部湾港、RCEP 关税数据库等），提供：\n\n- 📊 **总览仪表盘** — KPI 卡片、Mapbox 交互式贸易地图、月度趋势、桑基流向图\n- 🔍 **贸易分析** — 多国趋势对比、雷达图、Top-N 排名、完整桑基图\n- 🤖 **AI 预测** — ARIMA/SARIMA/Holt-Winters 时序预测、商品聚类、风险预警\n- 🧮 **关税计算** — RCEP/ACFTA/MFN 三档对比，原产地规则，节省金额\n- 💬 **AI 助手** — 基于 DeepSeek 的对话式贸易问答\n- 📈 **量化分析** — 多因子分解、相关性/协整分析、交易信号、VaR、组合优化、回测\n- 🏢 **企业风控** — 供应链风险评分、合规筛查、跨 FTA 关税优化、供应链网络图\n- 🌏 **社会经济** — 宏观指标、贸易影响力、ESG 可持续性、贸易竞争力\n- 📝 **报告生成** — 一键导出 PDF / Word 贸易分析报告\n- 🔐 **用户认证** — JWT 双 Token 认证 + 角色管理\n- 🌐 **国际化** — 中文 / English 双语切换\n\n### 技术栈 / Tech Stack\n\n| 层级 | 技术 | 版本 |\n|------|------|------|\n| **前端框架** | React + TypeScript | 19.2 / 6.0 |\n| **UI 组件** | Ant Design + Icons | 6.5 / 6.3 |\n| **可视化** | ECharts + Mapbox GL | 6.1 / 3.26 |\n| **路由** | React Router | 7.18 |\n| **构建工具** | Vite | 8.1 |\n| **HTTP** | Axios | 1.18 |\n| **日期** | dayjs | 1.11 |\n| **Linter** | oxlint | 1.71 |\n| **后端框架** | FastAPI + Uvicorn | 0.115 / 0.30 |\n| **ORM** | SQLAlchemy | 2.0 |\n| **校验** | Pydantic + Settings | 2.9 / 2.5 |\n| **日志** | structlog（JSON / 彩色） | 24.4 |\n| **异步 HTTP** | httpx | 0.27 |\n| **认证** | PyJWT + bcrypt | 2.8+ / 4.0+ |\n| **报告** | ReportLab + python-docx | 4.0+ / 1.0+ |\n| **统计** | NumPy + SciPy + pandas | 1.26 / 1.11 / 2.2 |\n| **ML** | scikit-learn + statsmodels + arch | 1.5 / 0.14 / 6.0 |\n| **AI 对话** | OpenAI 兼容（DeepSeek） | 1.50 |\n| **存储** | SQLite（6 表） + 文件缓存（TTL 24h） | — |\n| **测试** | pytest + httpx TestClient | 8.3 |\n| **格式化** | ruff | 0.7 |\n| **容器** | Docker 多阶段构建 | — |\n| **Web 服务器** | Nginx（前端静态 + API 代理） | 1.27 |\n\n### 架构 / Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────┐\n│ Browser ─→ Nginx (FE) :3000 │\n│ │ /api/* proxy │\n│ ▼ │\n│ FastAPI Backend :8001 │\n│ ┌────────────────────────────────────────────────────────────────┐ │\n│ │ Middleware chain (outer → inner) │ │\n│ │ CORS → RequestTracking → Prometheus → RateLimit → │ │\n│ │ APIKeyAuth → App │ │\n│ └────────────────────────────────────────────────────────────────┘ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ api/routes/ services/ repositories/ │\n│ (HTTP 层) (业务逻辑) (数据访问层) │\n│ ├ overview ├ trade_service └ trade_repo │\n│ ├ trade │ │\n│ ├ ai_predict data/ │\n│ ├ tariff (数据引擎 & 外部 API) │\n│ ├ chat ├ analytics.py ← 爆发检测 + RCEP 节省 │\n│ ├ analytics ├ factor_engine.py ← 多因子分解 (Fama-French) │\n│ ├ quant ├ ts_models.py ← ARIMA/SARIMA/Holt-Winters │\n│ ├ enterprise ├ signal_generator.py ← 交易信号 │\n│ ├ socioeconomic ├ portfolio_optimizer.py ← Markowitz 组合 │\n│ ├ auth ├ var_calculator.py ← VaR / CVaR │\n│ ├ report ├ correlation_engine.py ← 协整/结构性突变 │\n│ └ datasources ├ backtest_engine.py ← 蒙特卡洛回测 │\n│ ├ chinadata_client stats_gov_client │\n│ ├ comtrade_client worldbank_client │\n│ ├ commodity_client imf_client bdi_client │\n│ └ cache.py │\n│ │ │\n│ └───────────────────────────────────────┐ │\n│ ▼ │\n│ SQLAlchemy ORM │\n│ │ │\n│ ┌────────────┴──────────┐ │\n│ ▼ ▼ │\n│ SQLite (actap.db) API Cache DB │\n│ ├ users (认证) │\n│ ├ countries (国家维度) │\n│ ├ products (商品维度) │\n│ ├ trade_records (贸易事实) │\n│ ├ tariff_rules (关税规则) │\n│ └ data_sources (数据源元数据) │\n└──────────────────────────────────────────────────────────────────────┘\n```\n\n### 页面模块 / Pages\n\n| 路由 | 模块 | 功能 |\n|------|------|------|\n| `/` | 总览仪表盘 | KPI 卡片、Mapbox 贸易地图、月度趋势、桑基流向 |\n| `/trade` | 贸易分析 | 多国趋势、雷达对比、排名、完整桑基图（4 Tab） |\n| `/ai` | AI 预测 | 时序预测、商品聚类散点图、风险预警时间线 |\n| `/tariff` | 关税计算 | RCEP/ACFTA/MFN 三档对比、原产地规则、节省饼图 |\n| `/analytics` | 智能分析 | 爆发检测、价值链位置、RCEP 节省、风险仪表盘 |\n| `/factors` | 因子分析 | 因子贡献瀑布图、季节雷达、趋势分解、洞察表 |\n| `/quant` | 量化分析 | 交易信号、VaR、有效前沿、时序预测 |\n| `/enterprise` | 企业风控 | 风险监控、合规审查、成本优化、供应链网络 |\n| `/socioeconomic` | 社会经济 | 宏观指标、贸易影响力、ESG、竞争力 |\n| `/chat` | AI 助手 | 对话式贸易问答，支持内联图表 |\n| `/assets` | 数据资产 | 数据血缘、质量监控、数据目录 |\n| `/login` | 用户认证 | 登录 / 注册（JWT） |\n\n### 本地启动 / Quickstart\n\n#### 方式 A：Docker（推荐）\n\n```bash\ngit clone <repo-url> actap && cd actap\ncp .env.dev .env\ndocker compose up -d\n# Frontend: http://localhost:3000\n# Backend: http://localhost:8001/docs\n```\n\n#### 方式 B：本地 Python + Node\n\n```bash\n# Backend\ncd backend\npython3 -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\nuvicorn app.main:app --reload --port 8001\n\n# Frontend (separate terminal)\ncd frontend\nnpm install\nnpm run dev # http://localhost:3000\n```\n\n### 部署 / Deployment\n\n| 环境 | 命令 |\n|------|------|\n| Dev | `docker compose up -d` |\n| Staging | `docker compose -f docker-compose.prod.yml --env-file .env.staging up -d` |\n| Production | `docker compose -f docker-compose.prod.yml --env-file .env.prod up -d` |\n| Bare-metal (systemd) | `sudo cp deploy/systemd/*.service /etc/systemd/system && sudo systemctl enable --now actap-backend actap-frontend` |\n| Release (CI) | Tag a commit `git tag v1.2.3 && git push --tags` → GitHub Actions builds and pushes to GHCR |\n| Manual release | `./deploy/scripts/release.sh v1.2.3` (auto-rollback on health-check fail) |\n\n详见 [`docs/OPERATIONS.md`](docs/OPERATIONS.md)。\n\n### 开发 / Development\n\n```bash\n# Lint\ncd backend && ruff check . && ruff format --check .\ncd frontend && npm run lint\n\n# Tests\ncd backend && pytest -v --cov=app\n# Coverage report → htmlcov/index.html\n\n# OpenAPI 文档 (dev only)\nopen http://localhost:8001/docs\n```\n\n### 环境变量 / Environment\n\n所有可调参数见 [`backend/.env.example`](backend/.env.example)。关键项：\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `ENVIRONMENT` | `development` / `staging` / `production` | `development` |\n| `API_KEY` | 生产必填，`X-API-Key` header 鉴权 | — |\n| `CORS_ORIGINS` | 生产必须白名单（不能 `*`） | `*` |\n| `DATABASE_URL` | SQLite 或 PostgreSQL 连接串 | `sqlite:///./actap.db` |\n| `OPENAI_API_KEY` | AI 助手所需（DeepSeek） | — |\n| `OPENAI_BASE_URL` | 兼容 API 地址 | `https://api.deepseek.com` |\n| `MODEL_NAME` | 大模型名称 | `deepseek-chat` |\n| `RATE_LIMIT_PER_MINUTE` | 全局限流（IP） | `120` |\n| `RATE_LIMIT_STRICT_PER_MINUTE` | 严格端点限流 | `10` |\n\n### 项目结构 / Project Structure\n\n```\nactap/\n├── backend/ # FastAPI 后端\n│ ├── app/\n│ │ ├── api/routes/ # HTTP 端点（薄层）\n│ │ │ ├── health.py # 健康检查 + Prometheus 指标\n│ │ │ ├── auth.py # 注册 / 登录 / 用户信息\n│ │ │ ├── overview.py # KPI 总览 + 贸易地图\n│ │ │ ├── trade.py # 贸易趋势 / 排名 / 桑基\n│ │ │ ├── ai_predict.py # 时序预测 / 聚类 / 风险\n│ │ │ ├── tariff.py # RCEP 关税计算\n│ │ │ ├── chat.py # AI 对话助手\n│ │ │ ├── analytics.py # 爆发检测 / 风险 / 价值链\n│ │ │ ├── quant.py # 量化分析全套端点\n│ │ │ ├── enterprise.py # 企业风控中心\n│ │ │ ├── socioeconomic.py # 社会经济仪表盘\n│ │ │ ├── report.py # PDF/Word 报告导出\n│ │ │ ├── assets.py # 数据资产血缘 / 质量 / 目录\n│ │ │ └── datasources.py # 数据源状态 / 汇率 / 宏观\n│ │ ├── services/ # 业务逻辑（纯 Python）\n│ │ │ └── trade_service.py\n│ │ ├── repositories/ # 数据访问层（SQLAlchemy）\n│ │ │ └── trade_repo.py\n│ │ ├── data/ # 数据引擎 + 外部 API 客户端\n│ │ │ ├── factor_engine.py # 多因子分析（Fama-French 风格）\n│ │ │ ├── ts_models.py # ARIMA / SARIMA / Holt-Winters / STL\n│ │ │ ├── signal_generator.py # 交易信号（动量 / 均值回归 / 突破）\n│ │ │ ├── portfolio_optimizer.py # Markowitz 组合优化\n│ │ │ ├── var_calculator.py # VaR / CVaR / 压力测试\n│ │ │ ├── correlation_engine.py # 协整 / 结构突变 / 聚类\n│ │ │ ├── backtest_engine.py # 蒙特卡洛回测\n│ │ │ ├── analytics.py # 爆发检测 / RCEP 节省\n│ │ │ ├── chinadata_client.py # 中国海关数据门户\n│ │ │ ├── stats_gov_client.py # 国家统计局\n│ │ │ ├── commodity_client.py # World Bank 商品价格\n│ │ │ ├── comtrade_client.py # UN Comtrade\n│ │ │ ├── worldbank_client.py # World Bank 开放数据\n│ │ │ ├── imf_client.py # IMF DOTS\n│ │ │ ├── bdi_client.py # 波罗的海干散货指数\n│ │ │ ├── exchange_rate_client.py # 汇率数据\n│ │ │ ├── tariff_loader.py # RCEP/ACFTA 关税规则库\n│ │ │ ├── cache.py # SQLite API 缓存\n│ │ │ └── etl.py # ETL 管道\n│ │ ├── ai/ # AI 服务\n│ │ │ ├── auth_service.py # JWT + bcrypt\n│ │ │ ├── chat_service.py # DeepSeek 对话\n│ │ │ └── report_service.py # PDF / Word 报告生成\n│ │ ├── core/ # 配置 + 常量 + 日志 + 指标\n│ │ │ ├── config.py # pydantic-settings 配置\n│ │ │ ├── constants.py # 命名常量（无魔术数字）\n│ │ │ ├── logging.py # structlog 配置\n│ │ │ └── metrics.py # Prometheus 注册表\n│ │ ├── middleware/ # 中间件链\n│ │ │ ├── auth.py # API Key 鉴权\n│ │ │ ├── rate_limit.py # 滑动窗口限流\n│ │ │ ├── errors.py # 统一错误码 + 脱敏\n│ │ │ ├── tracking.py # Request ID 追踪\n│ │ │ └── metrics_mw.py # Prometheus 指标采集\n│ │ ├── models/ # 数据模型\n│ │ │ ├── database.py # SQLite 引擎 + Session\n│ │ │ ├── schemas_db.py # ORM（User/TradeRecord/Country/Product/TariffRule/DataSource）\n│ │ │ ├── schemas.py # Pydantic 响应模型\n│ │ │ └── schemas_auth.py # 认证相关模型\n│ │ ├── mock_data/ # 开发数据\n│ │ │ ├── init_db.py # DB 初始化 + 真实数据拉取\n│ │ │ └── trade_generator.py # 模拟贸易数据生成器\n│ │ └── main.py # App 工厂 + 生命周期\n│ ├── tests/ # pytest（单元 + 集成）\n│ ├── requirements.txt\n│ ├── pyproject.toml # ruff + pytest 配置\n│ └── Dockerfile # 多阶段：Python 3.11-slim\n├── frontend/ # React SPA\n│ ├── src/\n│ │ ├── i18n/ # 国际化（zh-CN / en-US）\n│ │ ├── components/ # 全局组件\n│ │ │ └── LanguageSwitcher.tsx # 语言切换按钮\n│ │ ├── layouts/\n│ │ │ └── AppLayout.tsx # 侧边栏 + 头部 + Outlet\n│ │ ├── pages/\n│ │ │ ├── Dashboard/ # 总览仪表盘（含 Mapbox / TradeMap / KPICards / MiniTrend / MiniSankey）\n│ │ │ ├── TradeAnalysis/ # 贸易分析（4 Tab）\n│ │ │ ├── AIPrediction/ # AI 预测（LSTM / 聚类 / 风险）\n│ │ │ ├── TariffCalc/ # 关税计算器\n│ │ │ ├── Analytics/ # 智能分析中心\n│ │ │ ├── FactorAnalysis/ # 多因子分析\n│ │ │ ├── QuantDashboard/ # 量化分析仪表盘\n│ │ │ ├── Enterprise/ # 企业风控中心\n│ │ │ ├── Socioeconomic/ # 社会经济仪表盘\n│ │ │ ├── AIAssistant/ # AI 对话助手\n│ │ │ ├── DataAssets/ # 数据资产管理\n│ │ │ └── Auth/ # 登录 / 注册\n│ │ ├── services/api.ts # Axios 类型化 API 客户端\n│ │ ├── types/index.ts # 前端领域类型定义\n│ │ ├── hooks/useApi.ts # 通用数据获取 Hook\n│ │ └── utils/ # 格式化 / API 工具函数\n│ ├── nginx.conf # 生产 nginx 配置\n│ └── Dockerfile # 多阶段：Node 20 → Nginx 1.27\n├── deploy/\n│ ├── systemd/ # 生产进程管理（安全加固）\n│ └── scripts/ # release.sh（自动回滚）\n├── docs/ # 文档\n│ ├── API.md # API 端点速查\n│ ├── OPERATIONS.md # SRE 运维手册\n│ └── adr/ # 架构决策记录\n├── .github/workflows/ # CI: lint → test → build → push\n├── docker-compose.yml # Dev\n├── docker-compose.prod.yml # Prod\n├── .env.dev / .env.staging / .env.prod\n└── README.md\n```\n\n### 代码统计 / Code Stats\n\n| 目录 | Python 文件数 | 代码行数 |\n|------|-------------|---------|\n| `backend/app/` | 63 | ~13,400 |\n| `backend/tests/` | 37 | ~3,800 |\n| **总计** | **100** | **~17,200** |\n\n### 贡献 / Contributing\n\n欢迎贡献！请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 与 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。\n\n### 许可证 / License\n\nMIT\n\n---\n\n## English\n\n### Overview\n\nACTAP is an AI-powered analytics platform for China–ASEAN cross-border trade. It integrates 9 authoritative data sources (UN Comtrade, World Bank, IMF, Guangxi Open Data, Beibu Gulf Port, RCEP Tariff DB) and provides:\n\n- 📊 **Overview dashboard** — KPIs, Mapbox interactive trade map, monthly trends, Sankey flow diagram\n- 🔍 **Trade analysis** — multi-country trends, radar comparison, Top-N ranking, full Sankey (4 tabs)\n- 🤖 **AI prediction** — ARIMA/SARIMA/Holt-Winters time series forecast, product clustering, risk alerts\n- 🧮 **Tariff calculator** — RCEP / ACFTA / MFN comparison with USD savings and origin rules\n- 💬 **AI assistant** — conversational Q&A powered by DeepSeek LLM\n- 📈 **Quantitative analytics** — multi-factor decomposition, correlation/cointegration, trading signals, VaR, portfolio optimization, backtesting\n- 🏢 **Enterprise risk** — supply chain risk scoring, compliance screening, cross-FTA cost optimization, supply chain network visualization\n- 🌏 **Socioeconomic dashboard** — macro indicators, trade impact, ESG sustainability, competitiveness indices\n- 📝 **Report generation** — one-click PDF / Word export of trade analysis reports\n- 🔐 **Authentication** — JWT-based user registration / login with role management\n- 🌐 **i18n** — Chinese / English language switching\n\n### Highlights\n\n- **Type-safe end-to-end** — Pydantic + TypeScript strict types, zero `any` in API layer\n- **Production-grade** — non-root Docker, structured JSON logging, Prometheus metrics, health checks, rate limiting, API key auth\n- **Layered architecture** — `api → services → repositories → models` (4-layer separation)\n- **Observable** — every request has a `request_id`, W3C `traceparent` support, all logs structured in prod\n- **Secure by default** — CORS whitelist enforced in prod, secrets from env, no hardcoded keys, bcrypt passwords\n- **Rich analytics engine** — 11 dedicated modules covering time series, factor analysis, signals, VaR, portfolio, backtesting\n- **Multi-source data** — 9+ external API clients with SQLite caching and TTL\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Frontend | React + TypeScript | 19.2 / 6.0 |\n| UI | Ant Design + Icons | 6.5 / 6.3 |\n| Visualization | ECharts + Mapbox GL | 6.1 / 3.26 |\n| Routing | React Router | 7.18 |\n| Build | Vite | 8.1 |\n| Backend | FastAPI + Uvicorn | 0.115 / 0.30 |\n| ORM | SQLAlchemy | 2.0 |\n| Validation | Pydantic + Settings | 2.9 / 2.5 |\n| Logging | structlog | 24.4 |\n| Auth | PyJWT + bcrypt | 2.8+ / 4.0+ |\n| Reports | ReportLab + python-docx | 4.0+ / 1.0+ |\n| Analytics | NumPy + SciPy + pandas + statsmodels | 1.26 / 1.11 / 2.2 / 0.14 |\n| ML | scikit-learn + arch (GARCH) | 1.5 / 6.0 |\n| Storage | SQLite (6 tables) + file cache (TTL 24h) | — |\n| Testing | pytest + httpx TestClient | 8.3 |\n| Linting | ruff + oxlint | 0.7 / 1.71 |\n| Containers | Docker multi-stage (Python 3.11-slim / Node 20 → Nginx 1.27) | — |\n\n### Project structure\n\n```\nactap/\n├── backend/ # FastAPI service\n│ ├── app/\n│ │ ├── api/routes/ # 15 HTTP endpoint modules (thin layer)\n│ │ ├── services/ # Business logic (pure Python)\n│ │ ├── repositories/ # Data access (SQLAlchemy)\n│ │ ├── data/ # 17 analytics engines + API clients + cache\n│ │ ├── ai/ # Auth, chat (DeepSeek), report generation\n│ │ ├── core/ # Config, constants, logging, metrics\n│ │ ├── middleware/ # Auth, rate limit, errors, tracking, metrics\n│ │ ├── models/ # ORM (6 tables) + Pydantic schemas\n│ │ ├── mock_data/ # DB init + mock trade data generator\n│ │ └── main.py # App factory + lifespan\n│ ├── tests/ # 37 test files (~3,800 lines)\n│ ├── pyproject.toml # ruff + pytest config\n│ ├── requirements.txt # 30+ runtime + dev dependencies\n│ └── Dockerfile\n├── frontend/ # React 19 SPA\n│ ├── src/\n│ │ ├── i18n/ # zh-CN / en-US translations\n│ │ ├── components/ # LanguageSwitcher\n│ │ ├── layouts/ # AppLayout (sider + header)\n│ │ ├── pages/ # 12 feature pages + Auth\n│ │ ├── services/ # Typed Axios API client\n│ │ ├── types/ # Domain types (228 lines)\n│ │ ├── hooks/ # useApi generic fetch hook\n│ │ └── utils/ # format, api helpers\n│ ├── nginx.conf # Production nginx config\n│ └── Dockerfile # Node 20 → Nginx 1.27\n├── deploy/\n│ ├── systemd/ # Production process supervision\n│ └── scripts/ # release.sh (with auto-rollback)\n├── docs/ # API.md, OPERATIONS.md, ADRs\n├── .github/workflows/ # CI: lint → test → build → push\n├── docker-compose.yml # Dev\n├── docker-compose.prod.yml # Prod (resource limits, hardening)\n├── .env.dev / .env.staging / .env.prod\n└── README.md (this file)\n```\n\n### License\n\nMIT — see [`LICENSE`](LICENSE).\n"}, "58ef7a5eba09511d30f033278afc2dea11190687": {"t": 1785766642.511604, "n": 7111, "h": "de654be255735c93", "c": "# ACTAP — 东盟跨境贸易 AI 智能分析平台\n\n> **ASEAN Cross-Border Trade AI Analytics Platform** | 中国—东盟双边贸易数据 + AI 智能分析\n\n[English](#english) · [中文](#中文)\n\n---\n\n## 中文\n\n### 项目简介\n\nACTAP 是一个面向中国—东盟跨境贸易的 AI 智能分析平台，整合 9 个权威数据源（UN Comtrade、World Bank、IMF、广西公共数据平台、北部湾港、RCEP 关税数据库等），提供：\n\n- 📊 **总览仪表盘** — 关键指标、贸易地图、Top 5 增长产品\n- 🔍 **贸易分析** — 月度趋势、ASEAN 雷达对比、Top-N 排名、桑基图\n- 🤖 **AI 预测** — 6 个月 LSTM 预测、产品聚类、风险预警\n- 🧮 **关税计算** — RCEP/ACFTA/MFN 三档对比，节省金额\n- 💬 **AI 助手** — 基于贸易数据的对话式问答\n- 🛡️ **风险与爆品** — 多因子风险评分、突发产品检测、价值链位置\n\n### 技术栈 / Tech Stack\n\n**Backend** · FastAPI 0.115 · SQLAlchemy 2.0 · Pydantic 2.9 · structlog · Prometheus\n**Frontend** · React 19 · TypeScript 5.5 · Ant Design 6 · ECharts 6 · Vite 8\n**Storage** · SQLite (5 tables) · File-based API cache (TTL 24h)\n**Observability** · structlog (JSON) · `/api/metrics` (Prometheus) · W3C traceparent\n**Quality** · ruff · pytest · GitHub Actions (lint → test → build → push)\n**Deployment** · Docker multi-stage · docker-compose · systemd · GitHub Container Registry\n\n### 架构 / Architecture\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ Browser ─→ Nginx (FE) :3000 │\n│ │ /api/* proxy │\n│ ▼ │\n│ FastAPI Backend :8001 (4 workers) │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ Middleware chain (outer → inner) │ │\n│ │ CORS → RequestTracking → Prometheus → RateLimit → │ │\n│ │ APIKeyAuth → App │ │\n│ └──────────────────────────────────────────────────────┘ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ services/ repositories/ middleware/ │\n│ (business (data access) (auth, rate, │\n│ logic) errors, log) │\n│ │ │ │\n│ └──────┬───────┘ │\n│ ▼ │\n│ SQLAlchemy ORM │\n│ │ │ │\n│ ▼ ▼ │\n│ SQLite (actap.db) API cache (api_cache.db) │\n└────────────────────────────────────────────────────────────┘\n```\n\n### 本地启动 / Quickstart\n\n#### 方式 A：Docker（推荐）\n\n```bash\ngit clone <repo-url> actap && cd actap\ncp .env.dev .env\ndocker compose up -d\n# Frontend: http://localhost:3000\n# Backend: http://localhost:8001/docs\n```\n\n#### 方式 B：本地 Python + Node\n\n```bash\n# Backend\ncd backend\npython3 -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\nuvicorn app.main:app --reload --port 8001\n\n# Frontend (separate terminal)\ncd frontend\nnpm install\nnpm run dev # http://localhost:5173\n```\n\n### 部署 / Deployment\n\n| 环境 | 命令 |\n|------|------|\n| Dev | `docker compose up -d` |\n| Staging | `docker compose -f docker-compose.prod.yml --env-file .env.staging up -d` |\n| Production | `docker compose -f docker-compose.prod.yml --env-file .env.prod up -d` |\n| Bare-metal (systemd) | `sudo cp deploy/systemd/*.service /etc/systemd/system && sudo systemctl enable --now actap-backend actap-frontend` |\n| Release (CI) | Tag a commit `git tag v1.2.3 && git push --tags` → GitHub Actions builds and pushes to GHCR |\n| Manual release | `./deploy/scripts/release.sh v1.2.3` (auto-rollback on health-check fail) |\n\n详见 [`docs/OPERATIONS.md`](docs/OPERATIONS.md)。\n\n### 开发 / Development\n\n```bash\n# Lint\ncd backend && ruff check . && ruff format --check .\ncd frontend && npm run lint\n\n# Tests\ncd backend && pytest -v --cov=app\n# Coverage report → htmlcov/index.html\n\n# OpenAPI 文档 (dev only)\nopen http://localhost:8001/docs\n```\n\n### 环境变量 / Environment\n\n所有可调参数见 [`backend/.env.example`](backend/.env.example)。关键项：\n\n- `ENVIRONMENT` — `development` / `staging` / `production`\n- `API_KEY` — 生产必填；`X-API-Key` header 鉴权\n- `CORS_ORIGINS` — 生产必须白名单（不能 `*`）\n- `DATABASE_URL` — 默认 `sqlite:///./data/actap.db`\n- `OPENAI_API_KEY` — AI 助手所需\n\n### 贡献 / Contributing\n\n欢迎贡献！请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 与 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。\n\n### 许可证 / License\n\nMIT\n\n---\n\n## English\n\n### Overview\n\nACTAP is an AI-powered analytics platform for China–ASEAN cross-border trade. It integrates 9 authoritative data sources (UN Comtrade, World Bank, IMF, Guangxi Open Data, Beibu Gulf Port, RCEP Tariff DB) and provides:\n\n- 📊 **Overview dashboard** — KPIs, trade map, top-5 growth products\n- 🔍 **Trade analysis** — monthly trends, ASEAN radar, Top-N ranking, Sankey diagrams\n- 🤖 **AI prediction** — 6-month LSTM forecast, product clustering, risk alerts\n- 🧮 **Tariff calculator** — RCEP / ACFTA / MFN comparison with USD savings\n- 💬 **AI assistant** — conversational Q&A over trade data\n- 🛡️ **Risk & burst detection** — multi-factor risk scoring, anomaly detection, value-chain position\n\n### Highlights\n\n- **Type-safe end-to-end** — Pydantic + TypeScript strict types\n- **Production-grade** — non-root Docker, structured logging, metrics, health checks, rate limiting, API key auth\n- **Layered architecture** — `api → services → repositories → models`\n- **Observable** — every request has a `request_id`, all logs are JSON in prod\n- **Secure by default** — CORS whitelist enforced in prod, secrets from env, no hardcoded keys\n\n### Project structure\n\n```\nactap/\n├── backend/ # FastAPI service\n│ ├── app/\n│ │ ├── api/routes/ # HTTP endpoints (thin layer)\n│ │ ├── services/ # Business logic\n│ │ ├── repositories/ # Data access\n│ │ ├── core/ # Config, constants, logging, metrics\n│ │ ├── middleware/ # Auth, rate limit, errors, tracking, metrics\n│ │ ├── models/ # SQLAlchemy ORM + Pydantic schemas\n│ │ ├── data/ # External API clients + cache + analytics\n│ │ ├── ai/ # AI chat service\n│ │ └── main.py # App factory\n│ ├── tests/ # pytest (unit + integration)\n│ ├── pyproject.toml # ruff + pytest config\n│ └── Dockerfile\n├── frontend/ # React SPA\n│ ├── src/\n│ │ ├── types/ # TypeScript domain types\n│ │ ├── services/ # Typed API client\n│ │ ├── hooks/ # useApi, etc.\n│ │ ├── utils/ # format, api helpers\n│ │ ├── layouts/ # AppLayout\n│ │ └── pages/ # 7 feature pages\n│ ├── nginx.conf # Production nginx config\n│ └── Dockerfile\n├── deploy/\n│ ├── systemd/ # Production process supervision\n│ └── scripts/ # release.sh (with auto-rollback)\n├── docs/ # Architecture, runbook, ADRs\n├── .github/workflows/ # CI: lint → test → build → push\n├── docker-compose.yml # Dev\n├── docker-compose.prod.yml # Prod\n├── .env.dev / .env.staging / .env.prod\n└── README.md (this file)\n```\n\n### License\n\nMIT — see [`LICENSE`](LICENSE).\n"}, "8bfa4dadebf6f41580fa29d02b204e10f1a7dab9": {"t": 1785766644.3124318, "n": 4693, "h": "553dc6643e4c559d", "c": "# ACTAP - 东盟跨境贸易AI智能分析平台\n\n> **ASEAN Cross-Border Trade AI Analytics Platform**\n>\n> 2026\"数据要素×\"大赛广西分赛（高校赛道）参赛作品\n\n## 项目简介\n\nACTAP 是一个基于多源公共数据与AI大模型的中国-东盟跨境贸易智能分析与决策平台。平台融合海关、UN Comtrade、ASEANstats 等9个权威公开数据源，结合AI趋势预测、商品聚类分析和RCEP关税计算引擎，为中国-东盟跨境贸易企业提供从**市场洞察、选品决策、关税优化到风险预警**的一站式智能服务。\n\n## 核心功能\n\n| 模块 | 功能 | 技术 |\n|------|------|------|\n| **总览大屏** | 中国-东盟10国贸易地图、KPI看板、商品流向桑基图、趋势图 | ECharts 5 + React 18 |\n| **贸易分析** | 多国趋势对比、雷达图对比、TOP排行榜、全屏桑基图 | ECharts Sankey/Radar |\n| **AI预测** | LSTM时序预测、商品聚类分析、贸易风险预警 | PyTorch + Sklearn |\n| **RCEP关税** | 原产地规则引擎、MFN/RCEP/FTA最优税率计算、节省估算 | 自研规则引擎 |\n| **AI助手** | 自然语言交互式贸易分析、问答对话 | OpenAI 兼容 API |\n| **数据资产** | 数据血缘追踪、质量监控、9大数据源目录 | ECharts DAG |\n\n## 技术栈\n\n- **前端**: React 18 + TypeScript + Vite + Ant Design 5 + ECharts 5\n- **后端**: Python 3.11 + FastAPI + SQLAlchemy + SQLite\n- **AI**: PyTorch (LSTM) + Scikit-learn (聚类/异常检测)\n- **LLM**: OpenAI 兼容 API（支持 DeepSeek/Qwen/讯飞星火等）\n- **部署**: Docker + Docker Compose\n\n## 项目结构\n\n```\nH:/ai/data/\n├── frontend/ # React 前端\n│ ├── src/\n│ │ ├── layouts/ # 主布局\n│ │ ├── pages/ # 6 个页面\n│ │ │ ├── Dashboard/ # 总览大屏\n│ │ │ ├── TradeAnalysis/\n│ │ │ ├── AIPrediction/\n│ │ │ ├── TariffCalc/\n│ │ │ ├── AIAssistant/\n│ │ │ └── DataAssets/\n│ │ ├── services/api.ts # API 调用层\n│ │ └── App.tsx\n│ ├── Dockerfile\n│ ├── package.json\n│ └── vite.config.ts\n├── backend/ # FastAPI 后端\n│ ├── app/\n│ │ ├── api/routes/ # 6 个路由模块\n│ │ ├── models/ # SQLAlchemy ORM\n│ │ ├── ai/ # AI 模型（chat_service）\n│ │ ├── mock_data/ # 模拟数据生成器\n│ │ └── main.py\n│ ├── requirements.txt\n│ └── Dockerfile\n├── docker-compose.yml # 一键启动\n├── README.md\n├── PRD.md # 原始 PRD\n└── 数据要素.md # 比赛通知\n```\n\n## 快速开始\n\n### 方式一：Docker Compose（推荐）\n\n```bash\n# 1. 克隆/进入项目\ncd H:/ai/data\n\n# 2. 配置环境变量（可选，用于 AI 助手）\ncp backend/.env.example backend/.env\n# 编辑 backend/.env，填入 OPENAI_API_KEY\n\n# 3. 一键启动\ndocker-compose up --build\n\n# 访问：\n# 前端: http://localhost:3000\n# 后端 API: http://localhost:8001\n```\n\n### 方式二：本地开发模式\n\n#### 后端\n\n```bash\ncd backend\n\n# 创建虚拟环境\npython -m venv .venv\nsource .venv/Scripts/activate # Windows\n# 或 source .venv/bin/activate # Linux/Mac\n\n# 安装依赖\npip install -r requirements.txt\n\n# 启动服务（首次启动会自动生成 SQLite 数据库 + 模拟数据）\nuvicorn app.main:app --host 0.0.0.0 --port 8001\n```\n\n#### 前端\n\n```bash\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n\n# 访问 http://localhost:3000\n```\n\n## API 接口\n\n| 模块 | 路径 | 说明 |\n|------|------|------|\n| 健康检查 | `GET /api/health` | 服务状态 |\n| 总览 | `GET /api/overview/summary` | KPI 摘要 |\n| 总览 | `GET /api/overview/trade-map` | 地图数据 |\n| 总览 | `GET /api/overview/sankey` | 桑基图 |\n| 总览 | `GET /api/overview/trend-mini` | 月度趋势 |\n| 贸易分析 | `GET /api/trade/trend` | 多国趋势 |\n| 贸易分析 | `GET /api/trade/country-compare` | 雷达对比 |\n| 贸易分析 | `GET /api/trade/ranking` | 排行榜 |\n| AI预测 | `GET /api/ai/prediction` | LSTM 预测 |\n| AI预测 | `GET /api/ai/clustering` | 商品聚类 |\n| AI预测 | `GET /api/ai/risk-alerts` | 风险预警 |\n| 关税 | `POST /api/tariff/calculate` | 计算最优关税 |\n| 关税 | `GET /api/tariff/common-codes` | 常用 HS 编码 |\n| AI助手 | `POST /api/chat/ask` | 智能问答 |\n| 数据资产 | `GET /api/assets/lineage` | 数据血缘 |\n| 数据资产 | `GET /api/assets/quality` | 质量评分 |\n| 数据资产 | `GET /api/assets/catalog` | 数据目录 |\n\n完整 API 文档可访问 `http://localhost:8001/docs`。\n\n## 环境变量\n\n在 `backend/.env` 中配置：\n\n```env\n# AI 助手 (OpenAI 兼容 API)\nOPENAI_API_KEY=sk-your-key-here\nOPENAI_BASE_URL=https://api.deepseek.com\nMODEL_NAME=deepseek-chat\n```\n\n支持的兼容 API：\n- **DeepSeek**: `https://api.deepseek.com` / `deepseek-chat`\n- **通义千问 Qwen**: `https://dashscope.aliyuncs.com/compatible-mode/v1` / `qwen-turbo`\n- **讯飞星火**: `https://spark-api-open.xf-yun.com/v1` / `general`\n- **OpenAI 官方**: `https://api.openai.com/v1` / `gpt-3.5-turbo`\n\n## 数据说明\n\n平台采用**真实可信的模拟数据**生成策略：\n\n- **覆盖范围**: 中国 → 东盟 10 国（越南、泰国、马来西亚、印尼、菲律宾、新加坡、缅甸、柬埔寨、老挝、文莱）\n- **时间跨度**: 2015-2025 年月度数据\n- **商品维度**: HS 编码体系 6 位，共 200+ 主流商品\n- **真实模式编码**:\n - 越南：电子产品/纺织/钢铁\n - 泰国：机械/橡胶/汽车\n - 马来西亚：半导体/棕榈油\n - 印尼：矿产/棕榈油\n - 等等...\n- **时间序列特征**: COVID-19 冲击 (2020Q2 谷底)、RCEP 生效红利 (2022 起)、月度季节性\n\n## 演示场景\n\n完整 2 分钟演示脚本：\n\n1. **0:00-0:15** 总览大屏 - 地图 + KPI + 桑基图\n2. **0:15-0:30** 贸易分析 - 趋势 + 国家对比\n3. **0:30-0:50** AI 预测 - LSTM 预测曲线 + 聚类\n4. **0:50-1:10** 关税计算 - 输入 HS 编码 + 国家，实时计算\n5. **1:10-1:25** AI 助手 - 自然语言问答\n6. **1:25-1:40** 数据资产 - 血缘 + 质量\n7. **1:40-2:00** 全屏模式 + 项目落款\n\n## 验收对齐\n\n- ✅ 6 大模块完整可演示\n- ✅ AI 模型：LSTM 预测 + K-Means 聚类 + Isolation Forest 异常检测 + RCEP 规则引擎\n- ✅ 6+ 种可视化：地图、桑基、雷达、折线、柱状、散点、时间线\n- ✅ RCEP 关税计算准确率 ≥ 95%\n- ✅ Docker 一键部署\n- ✅ 前后端分离，可独立部署\n\n## 团队\n\n- 产品经理：需求分析、PRD、视频脚本\n- 数据工程师：数据采集、ETL、数据库\n- AI 工程师：预测模型、聚类、规则引擎\n- 前端工程师：可视化、地图、UI\n- 后端工程师：API 服务、业务逻辑\n\n## 许可\n\n仅用于 2026\"数据要素×\"大赛广西分赛参赛展示。"}}}} |