配置与路由治理规范¶

目标：按业务域拆分配置/路由/模型，降低多人协作冲突；公共基座专人维护。

一、原则¶

新增域 = 新增文件：禁止在聚合入口堆业务逻辑。
公共基座专人维护：见 .github/CODEOWNERS；非 owner 改保护路径会被 CI 拦截。
配置单一来源：env 片段 → Settings Field → ConfigMap；禁止三处手抄漂移。
末尾追加：共用文件只追加，不删历史块；废弃 KEY 注释保留。
统一格式化：提交走 pre-commit（ruff / prettier）。

二、Backend 目录约定¶

src/backend/
  env/                 # 可追踪的 .env.*.example 片段
  settings/            # Settings mixin 按域拆分
  config.py            # 薄兼容层（re-export）
  api/admin/
    _registry/         # 一域一文件，自动发现挂载
    __init__.py        # 仅 collect_routers，禁止手写业务 include
  db/models/billing/   # 计费模型子包

Env 加载顺序¶

域片段（公共/业务基线）：.env.base → .env.billing → .env.sms → .env.payment → .env.messaging
环境层（按 APP_ENV）：.env.development / .env.test / .env.production
本地覆盖：.env（gitignore，个人密钥与临时覆盖）

后者覆盖前者。APP_ENV 判定：进程环境变量 → .env / .env.base 中的值 → 默认 development。

示例模板：src/backend/env/.env.{development,test,production}.example 复制到 src/backend/.env.development（或 env/ 下同名）后按需改值。

本地切换示例：

# Windows PowerShell
$env:APP_ENV="production"
# 或在 .env 中写 APP_ENV=production 后重启进程

K8s / ACK：ConfigMap 设置 APP_ENV=production，敏感项仍走 Secret，不必依赖仓库内 .env.production。

域注释块模板¶

# ===== billing 开始 =====
PAYMENT_ENABLED=false
# ===== billing 结束 =====

三、K8s ConfigMap¶

backend-config-base：全局非敏感（URL、CORS、日志等）
backend-config-billing / sms / …：业务域非敏感 KEY
Secret 仍按服务拆分，敏感项不进 ConfigMap
Deployment 通过多个 envFrom 挂载

四、Admin 前端路由¶

各 features/<name>/routes.tsx 导出路由 + navItems（路径只出现一次）
app/nav.ts 只做排序/分组
app/routes.tsx 只聚合；Sidebar.tsx 纯 UI

五、冲突处理¶

类型	规则
env / ConfigMap	双方新增全留，删除重复同名 KEY
`_registry` 新文件	双方新增文件全留
拿不准归属	对接对应域开发，禁止私自删除

六、负责人（公共基座）¶

路径	负责人
`src/backend/settings/base.py`、`src/backend/env/.env.base*`	后端负责人
`src/backend/main.py`、`src/backend/api/admin/__init__.py`	后端负责人
`deploy/k3s/base/*/deployment.yaml`、`harness.yaml`	运维 / 后端负责人
`alembic_backend.ini`	后端负责人

新增全局配置：提需求 → 负责人统一追加到 base 文件末尾。

七、校验命令¶

poetry run python scripts/check_protected_paths.py   # CI / 本地
poetry run python scripts/check_env_settings_sync.py # env ↔ Settings ↔ ConfigMap