QuantDinger 产品模式与轻量部署审计¶

结论¶

当前仓库已经有 BILLING_ENABLED、ENABLE_REGISTRATION、SINGLE_USER_MODE 和 QUANTDINGER_DEPLOYMENT_MODE，但它们分别控制计费、注册、旧版认证兼容和 Agent Token 策略，没有形成统一的产品模式。关闭计费只会停止扣积分，不会隐藏积分、充值、会员、推荐、 市场入口，也不会阻止所有相关 API 和后台初始化。

建议把“产品模式”和“运行拓扑”分开：

• 产品模式决定用户能看到和调用什么。
• 运行拓扑决定 Docker 启动哪些基础设施和 worker。
• 数据库保持一套迁移，不因模式删除表或维护分支 schema。

产品模式提供三个预设：personal、team、saas。设置页只让普通部署者选择预设， 高级运营者可以在“高级功能”中覆盖少数能力。不要把现有 BILLING_ENABLED 直接当作唯一总开关。

当前规模¶

• 管理设置后端定义了 17 个分组、233 个可编辑项，其中 119 个被标记为高级项。
• .env.example 包含约 410 个配置键。
• 默认 docker-compose.yml 定义了 18 个服务；目前只有 MCP 使用可选 Compose profile。
• PC、移动端和后端分别维护市场、积分、充值和推荐入口，没有共同的能力配置来源。

已确认的问题¶

设置页¶

backend_api_python/app/routes/settings.py 的 _effective_schema() 当前直接返回完整 schema。 它没有根据部署模式、已启用功能或依赖关系裁剪分组。前端设置页再把所有分组固定归入 Core、Research、Operations 和 Organization，所以新部署仍会看到完整运营后台。

QUANTDINGER_DEPLOYMENT_MODE 已经存在，但位于 Agent 分组，当前只影响 Agent Token 策略。它不是全局产品模式。

PC 前端¶

quantdinger_frontend/src/config/router.config.js 总是注册市场、计费、个人资料和用户管理路由。 动态路由只按 admin 权限过滤，不按产品能力过滤。

quantdinger_frontend/src/components/GlobalHeader/AvatarDropdown.vue 总是显示积分和充值，并每 分钟请求一次计费计划接口。个人资料页还固定包含积分、会员和推荐内容。指标与策略编辑器固定 提供发布到市场的入口。

移动端¶

移动端固定注册 /market/*、/profile/credits 和 /profile/referral，个人中心会主动读取购买 记录和积分状态。关闭后端计费后，移动端产品表面仍然是 SaaS 形态。

后端语义¶

计费关闭时，主要 AI、回测和复盘路径会跳过扣款，这部分行为可以保留。但是：

• /api/billing/plans 仍可被调用，并会触发会员计划相关读取或初始化。
• 推荐奖励 API 没有统一的计费能力守卫。
• Community 和 Billing blueprint 始终注册。
• 市场购买在计费关闭时把有效价格改为 0，仍会交付原本的付费商品。这不等价于“关闭市场”， 也可能违背运营者预期。
• USDT worker 会进入空闲循环，但相关路由、配置和表仍然对用户可见。

数据库¶

基础迁移包含用户积分、积分流水、会员订单、会员计划、Stripe、USDT、推荐奖励、市场购买和评论 等表。保留这些表的成本很低，并且能让安装实例以后无损切换到 SaaS。删除或按模式跳过这些表会 产生 schema 分叉、升级顺序和回滚问题。

部署拓扑¶

默认 Compose 同时包含 PostgreSQL、两个 Redis、Kafka、Kafka 初始化、API、交易 worker、 Kafka 审计、策略调度与评估、调度器、Celery worker/beat、PC 和移动端。对于只做研究、指标、 回测或少量本地交易的用户，这个默认拓扑过重。

目标产品模式¶

Personal 不应自动启用 SINGLE_USER_MODE=true。该变量是旧版环境账号认证兼容路径。 新的单机模式仍使用 PostgreSQL 用户和首个管理员，只关闭公开注册和多用户管理界面，避免降低 认证与凭据安全性。

统一能力模型¶

继续使用 QUANTDINGER_DEPLOYMENT_MODE，把规范值扩展为：

personal
team
saas

兼容值：hosted 映射为 saas。升级旧实例时，不能把空值直接视为 Personal，否则会突然隐藏 现有用户和运营入口。建议迁移规则为：

1. 明确设置了 saas 或 hosted：保持 SaaS。
2. 未设置且 BILLING_ENABLED=true：迁移为 SaaS。
3. 未设置且计费关闭：迁移为 Team，保持现有多用户行为。
4. 新安装模板明确写入 personal。

增加集中式 SystemCapabilities 服务。所有组件都从这里读取派生能力，禁止自行散落读取多个环境变量。 建议能力键：

auth.public_registration
users.management
billing.credits
billing.checkout
billing.referrals
marketplace.catalog
marketplace.publish
marketplace.commerce
branding.customization
runtime.distributed

高级覆盖使用 auto/on/off，例如 FEATURE_MARKETPLACE=auto。auto 继承模式预设。依赖关系由 后端强制验证：

• billing.checkout 依赖 billing.credits。
• billing.referrals 依赖 billing.checkout。
• marketplace.commerce 依赖 marketplace.catalog 和 billing.credits。
• 关闭市场时，发布、购买、作者中心、审核和同步全部关闭。

API 与前端改造¶

新增安全的启动配置接口，例如 GET /api/system/capabilities，登录前即可返回：

{
  "product_mode": "personal",
  "capabilities": {
    "auth.public_registration": false,
    "users.management": false,
    "billing.credits": false,
    "billing.checkout": false,
    "billing.referrals": false,
    "marketplace.catalog": false,
    "marketplace.publish": false,
    "marketplace.commerce": false
  }
}

响应不得包含密钥、价格内部配置或基础设施信息。它可以逐步合并现有 security-config 和 public-config 中的公开开关，避免启动时重复请求。

后端需要同时在路由层和服务层守卫能力。路由层返回统一的 feature_disabled，服务层防止内部调用 绕过路由。不能只靠前端隐藏。

PC 路由增加 meta.capability，动态路由生成器按权限和能力共同过滤，导航守卫阻止手输 URL。 顶部积分、充值、个人资料标签、市场发布按钮都读取同一个 capability store。关闭后不请求计费和 市场 API。

移动端在应用 bootstrap 时加载相同接口，过滤市场、充值、推荐路由和个人中心卡片。默认首页不能 固定重定向到市场；Personal 应进入研究、指标或上次使用的工作区。

设置页重构¶

设置首页增加“运行方式”卡片，优先显示三种预设及其影响，不直接展示环境变量名：

• 个人使用：一个管理员，功能直接可用，无积分、充值和市场。
• 私有团队：管理员创建成员，无公开注册和商业计费。
• SaaS 运营：用户注册、积分、会员、支付和市场运营。

选择模式后只展示适用设置。Schema 的 group 和 item 增加：

modes: [personal, team, saas]
requires_capabilities: [billing.checkout]
setup_level: essential | optional | advanced

Personal 的首次设置只需要：管理员、语言与时区、一个 AI Provider、使用的市场，以及可选的交易 账户。公共行情可用时不要强迫用户配置额外数据源。其余 200 多项放在“可选能力”和“高级设置”。

切换模式时先显示变更预览：将隐藏哪些入口、停止哪些新操作、哪些服务需要重启。SaaS 切回 Team 只停止新收费、充值和市场交易，保留余额、订单、购买记录和审计数据。

首次启动向导¶

增加一次性 Setup Wizard，不要求用户先理解完整设置页：

1. 选择 Personal、Team 或 SaaS。
2. 设置管理员和访问方式；Personal/Team 默认关闭公开注册。
3. 配置一个 AI Provider；允许跳过并先使用非 AI 功能。
4. 选择需要的市场和是否启用实盘组件。
5. 运行连接检查并进入产品。

向导保存后生成明确配置，不通过是否访问过某个页面来猜测状态。建议增加 INITIAL_SETUP_COMPLETED=true。管理员仍可从设置页重新运行向导。

Compose 运行档位¶

产品模式不应直接等于 Compose profile，因为个人用户也可能需要实盘 worker，团队也可能只做研究。 建议拆成以下运行档位：

默认快速启动使用 core + jobs，不启动 Kafka 和分布式 worker。完整 SaaS 示例显式启用全部所需 profile。修改 Compose 前要为核心研究、回测和本地交易分别做端到端验证，确认关闭 Celery 或 Kafka 时存在明确的同步/本地执行路径。

数据与停用规则¶

• 保留统一 init.sql 和后续迁移中的所有表。
• 能力关闭时停止新写入，不删除历史数据。
• 支付订单处于 pending 时禁止直接关闭 checkout，或要求管理员确认并先处理订单。
• 市场关闭时已购买代码仍保留在用户工作区；市场 API 不再提供新的购买和同步。
• 重新开启能力时复用原有余额、会员、订单和购买记录。
• 审计日志记录模式变更、操作者、变更前后值和时间。

实施顺序¶

P0：建立正确边界¶

1. 新建集中式 capability 服务和模式兼容映射。
2. 新增 /api/system/capabilities。
3. 给 Billing、Referral、Community 的路由和服务增加能力守卫。
4. 修正“计费关闭即付费市场商品免费”的语义。
5. 添加模式矩阵测试，覆盖手输 URL 和直接调用 API。

P1：真正减轻产品表面¶

1. PC bootstrap capability store，过滤路由、顶部积分、个人资料和发布入口。
2. 移动端应用相同过滤。
3. Settings schema 增加 mode、capability 和 setup level 元数据。
4. 设置首页加入三种运行方式和变更预览。

P2：缩短首次启动¶

1. 增加 Setup Wizard 和最小连接检查。
2. 新安装模板默认 Personal；安装脚本只询问必要参数。
3. 补充 Personal、Team、SaaS 三条独立快速开始文档。

P3：减轻基础设施¶

1. 为 Compose 增加 core、jobs、live、distributed、mobile 和 ops profiles。
2. 验证缺少 Kafka、Celery beat 和分布式 worker 时的降级路径。
3. 让关闭的支付和运营 worker 不初始化、不轮询，并在健康状态中报告 disabled。

验收标准¶

• 新 Personal 安装只填写少量必要项即可进入研究、指标和回测。
• PC 与移动端均不出现积分、充值、会员、推荐、市场及其空白入口。
• 直接访问被关闭的前端路由会跳回可用首页。
• 直接调用被关闭的后端 API 返回统一错误，不产生写入或免费交付。
• Personal 使用 AI、回测和策略时不读取或扣除积分。
• Team 可由管理员创建用户，但不暴露公开注册和商业计费。
• SaaS 能完整启用充值、会员、推荐和市场，并验证所有依赖配置。
• 从 Personal/Team 切换到 SaaS 不需要数据库迁移分支或数据搬迁。
• 默认轻量 Compose 不启动 Kafka 和分布式策略 worker，核心工作流仍通过测试。