← 返回文档导航

🗂️ 配置目录 · 用大白话管配置

从「这是什么、为什么、怎么用」一路读到「技术怎么落地」· 非技术也能看懂
📝 设计稿(①定义阶段)· 本篇 0 代码改动 · 由浅入深:先讲清做什么,再到技术方案

一、我们要做什么(一看就懂)人人都懂

🤔 现在的麻烦
系统里「能调的东西」散在 十几个后台页面 + 一堆配置文件 里——分佣比例、星级、课程价、活动、各种券、品牌位、运营位… 运营想「看看现在有哪些活动」「把直推佣金改一下」,得先知道在哪个页、叫什么、单位是啥,记不住、还容易点错。
💡 我们要做两样东西
① 一张「配置地图」:把所有能配的东西收成一张目录,一眼看清「有啥 · 在哪配 · 谁能改 · 改了影响啥」。
② 一个「对话框」(自然语言):运营直接说人话——「现在有哪些新人活动?」「给沉默用户前 3 单 1.5 倍」——系统就帮你查 / 帮你改(改之前先给你看预览,你点确认才生效)。
🎯 一句话
让运营用大白话管配置,而不是在十几个后台页里翻。后台 UI 和对话框,是同一份配置的两个入口,永远一致。
运营要「改个直推佣金」现在 😣以后 😎
怎么做登录后台 → 找到「分佣规则」页 → 找到 DIRECT_COMMISSION → 看懂 bps 单位 → 改 → 存对话框打字「直推佣金从 12% 提到 13%」→ 看预览 → 点确认
要记什么在哪个页、叫什么、什么单位啥都不用记,说人话
查活动自己翻好几个后台页拼问「有哪些新人活动」直接答

二、运营/开发怎么用人人都懂

想干啥(说人话)走哪系统怎么应
「现在有哪些针对新用户的活动?」对话框 / 后台筛「活动」读配置目录 → 过滤新人 → 列出来
「直推佣金现在多少?在哪改?」对话框 / 后台「分佣规则」答「12%」+ 指到改的地方
「这几个购物激励都开了,单均成本多少?」对话框读 3 个活动配置 + 叠加模型 + 封顶 → 估成本
「给沉默 30 天的用户前 3 单 1.5 倍」对话框(动钱·要确认)出草案 → 预览(人群+叠加+成本) → 你确认 → 生效
「Xendit 配了吗 / 接了哪些登录?」对话框(只读)查现状,只答「配没配」,不吐密钥

三、业务实现流程(怎么跑通)半技术 · 看图就懂

两条「人 → 配置」的路径(自然语言 / 后台 UI)读写同一份配置目录。三条核心流程:

A. 查询流程(读 · 安全,先上)

说人话 → 理解 → 查目录 → 取实际值 → 大白话答。全程只读,无风险。

flowchart LR
  U(["运营:「有哪些新人活动?」"]):::u --> L["LLM 理解意图
查 域=活动 · 人群=新人"]:::llm L --> C["配置目录
定位命中的配置项"]:::cat C --> R["按域取当前值
查 分佣 / 活动 / 券 表"]:::read R --> A["LLM 汇总成大白话"]:::llm A --> O(["回复运营"]):::u classDef u fill:#eef6ff,stroke:#3b82f6,color:#1e40af; classDef llm fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6; classDef cat fill:#fff7e6,stroke:#f59e0b,color:#b45309; classDef read fill:#f0fdf4,stroke:#15803d,color:#15803d;

B. 描述 → 创建/改 流程(写 · 动钱,带护栏)

核心:LLM 不直接改,只出「草案」;先把影响人群 + 叠加关系 + 预估成本 vs 单笔封顶给运营看,人点确认才落库,并留审计。

flowchart TD
  U(["运营:「沉默30天用户前3单1.5倍」"]):::u --> P["LLM 出『结构化草案』
倍率券 · 人群=沉默≥30天 · 前3单 · 倍率 1.2/1.3/1.5"]:::llm P --> V{"校验:字段 / 范围 / 人群合法?"}:::dec V -->|不合法| BACK["回问运营澄清"]:::llm V -->|合法| EST["算影响
命中人群 + 和谁叠加 + 预估单均成本 vs 单笔封顶"]:::calc EST --> PRE["预览给运营
草案 + 影响 + 成本"]:::pre PRE --> CONF{"运营确认?"}:::dec CONF -->|否| DROP(["丢弃 · 不生效"]):::dead CONF -->|是| W["写入对应配置(T1 表)"]:::write W --> LIVE(["即时生效"]):::done W --> AUD["留审计:谁 / 何时 / 改了啥"]:::aud classDef u fill:#eef6ff,stroke:#3b82f6,color:#1e40af; classDef llm fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6; classDef dec fill:#fef3c7,stroke:#e07c00,color:#7a4f24,stroke-width:2px; classDef calc fill:#fff7ed,stroke:#fb923c,color:#9a3412; classDef pre fill:#eff6ff,stroke:#3b82f6,color:#1e40af; classDef write fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6; classDef done fill:#f0fdf4,stroke:#15803d,color:#15803d; classDef dead fill:#fef2f2,stroke:#dc2626,color:#991b1b; classDef aud fill:#ffffff,stroke:#e8d9b8,color:#1a1410;

C. 配置目录「读适配」怎么工作(②的实现思路)

目录里每个域注册一个描述符(元数据) + 一个读适配器(把该域的表/properties 映射成统一格式)。查询时按域找适配器读底层——只读、不迁移、不动现有写路径,按域增量接,可停可续。

flowchart LR
  Q["NL / 后台 查询"]:::u --> CAT
  subgraph CAT["配置目录"]
    direction TB
    D1["描述符·分佣 → 读适配器"]:::ad
    D2["描述符·活动 → 读适配器"]:::ad
    D3["描述符·券 → 读适配器"]:::ad
  end
  D1 -. 只读 .-> T1[("reward_rule_config")]:::t
  D2 -. 只读 .-> T2[("activity 表")]:::t
  D3 -. 只读 .-> T3[("user_coupons")]:::t
  classDef u fill:#eef6ff,stroke:#3b82f6,color:#1e40af;
  classDef ad fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6;
  classDef t fill:#f0fdf4,stroke:#15803d,color:#15803d;
🔑 三个关键设计决策:① 读写分离——查询(读)先上、零风险;写入(动钱)永远走「草案→预览→人确认」。② 读适配不动底层——目录是叠在现有表之上的只读视图,不迁移、按域增量。③ 每笔写入留审计——谁/何时/把哪个配置从 X 改成 Y,可追溯、可回滚。

四、全配置地图 · 现有可配项清单半技术 · 配置地图

A. DB 表配置(T1 后台热改 · 运营 NL 主战场)

存储表在哪配/读改什么谁改风险
分佣规则reward_rule_configadmin /rewards · /rules直推/间接/团队/课程直·间/邀请奖/带团队/TPB/返佣基金 的 比例·固定额·释放天数·生效版本运营+开发🔴 动钱
星级规则star_rule_configadmin 星级升星门槛 / 星级乘数 / 升星奖运营+开发🔴 动钱
课程价目course_plan_configadmin 课程价目 GET/PUT小/大团长课价、被邀价、小升大补差价运营🔴 动钱
返佣基金rebate_fund_configadmin 返佣基金参数默认额度 / 有效期 / 计算键 / 取整粒度 / 封顶运营🔴 动钱
活动(倍率券等)activity_campaigns + _rulesadmin 活动圈人条件 / 倍率序列 / 单数 x / 时间窗 / 状态运营🔴 动钱
邀请券活动invite_coupon_campaign_rulesadmin 邀请券邀请券面值 / 触发条件 / 封顶运营🔴 动钱
券(发放/核销)user_coupons · coupon_ledger券配置12 种券的面值/门槛/限量/发放/核销运营+系统🔴 动钱
品牌位popular_brand_configadmin 品牌热门品牌 / 搜索词 / 返佣 bps / 排序 / 开关运营🟡 展示
运营位/投放位campaign_placementsadmin 投放位启动页/弹框/悬浮/banner/品牌坑位 的位置·素材·时段运营🟡 展示
配置中心·规则版本rule_config(_versions)admin /rules规则的版本化配置(按 ordered_at 命中版本)运营+开发🔴 动钱
配置中心·运行开关runtime_feature_configadmin /runtime-config功能开关(灰度/降级/特性 on-off)开发+运营🟠 开关
📌 已有的配置中心(rule_config + runtime_feature_config)已是「通用规则版本 + 运行开关」层,可作为「配置目录」的种子往上长,不用从 0 起。

B. Properties 配置(T2 重启 / T3 开关 · 多为密钥,只查不让 NL 改)

prefix改什么谁改层/风险
联盟/集成seahub.affiliate.{shopee,tiktok,traveloka,share}各平台 AppKey/Secret、token 刷新、订单/转化同步开发T2 🔒
登录鉴权seahub.auth.{apple,google,tiktok,phone,methods}OAuth client/secret、登录方式开关开发T2 🔒
支付(Xendit)seahub.paymentapi-key / callback-token / 回跳 / 发票时长开发T2 🔒
提现seahub.withdraw最小额/上限/日限/手续费/admin-token(限额·费已可经 /withdraw/config 暴露)开发+运营T2/T1
推送 / 短信 / WhatsApp / 飞书push · sms · whatsapp · feishu各渠道密钥 / token / 机器人开发T2 🔒
课程升级seahub.course.upgrade小升大补差价 开关/金额运营/开发T2 🔴
监控 / 日志 / App运行monitor · app-log · app.runtime-config告警阈值 / 日志密钥 / 客户端运行参数开发/SRET3/T2
🔒 T2 多是密钥/集成:开发改、走 ECS .env、重启生效——不让 NL 改,但可被查询("Xendit 配了吗 / 接了哪些登录",只答配没配、不吐明文)。

五、配置目录 · 元模型(字段定义)技术细节

每个可配项都用这套字段描述,NL 与后台 UI 都读它来「找配置 / 看现状 / 改配置」。

字段含义
domain配置域分佣 / 星级 / 活动 / 券 / 品牌位 / 运营位 / 集成 / 鉴权 …
key配置项唯一标识reward_rule_config:DIRECT_COMMISSION
name人类可读名直推佣金比例
tierT1DB热改 / T2properties重启 / T3开关T1
store / readPath / writePath存哪 / 怎么读 / 怎么改表 / prefix · admin GET/PUT · env+重启
editableBy谁能改运营 / 开发 / SRE
scope维度国家 country_code × 环境 env
status状态 / 版本 / 生效时间enabled · effective_from · version
relations关系叠加 / 互斥 / 依赖(倍率券 ↔ 返佣基金 叠加;3 购物激励 运营层互斥)
valueShape / risk值结构·单位 / 改动风险bps·minor·天·枚举 / 🔴动钱·🟡展示·🟠开关·🔒密钥

六、落地路线(三期)技术落地

做什么改动量风险
① 定义(本篇)元模型 + 全配置域清单(本文档)很小(0 代码)0
② 配置目录 + 按域接读在配置中心基础上做「目录」+ 按域增量接只读适配(先接 T1 常用域)+ 统一查询接口;不动写路径、不迁移中小(增量·可停可续)
③ 自然语言层NL 查询(只读,先上安全)→ NL 描述创建(动钱:草案→预览→人确认→落库)查询低 / 写入需护栏
🛡️ 护栏(贯穿):① NL 写入只对 T1 开放、且必须「草案→预览→人确认」;② 任何「动钱」改动显示影响人群 + 叠加关系 + 预估成本 vs 单笔封顶;③ T2 密钥永不经 NL 读明文/写。