← 返回文档导航
📝 设计稿(①定义阶段)· 本篇 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_config | admin /rewards · /rules | 直推/间接/团队/课程直·间/邀请奖/带团队/TPB/返佣基金 的 比例·固定额·释放天数·生效版本 | 运营+开发 | 🔴 动钱 |
| 星级规则 | star_rule_config | admin 星级 | 升星门槛 / 星级乘数 / 升星奖 | 运营+开发 | 🔴 动钱 |
| 课程价目 | course_plan_config | admin 课程价目 GET/PUT | 小/大团长课价、被邀价、小升大补差价 | 运营 | 🔴 动钱 |
| 返佣基金 | rebate_fund_config | admin 返佣基金参数 | 默认额度 / 有效期 / 计算键 / 取整粒度 / 封顶 | 运营 | 🔴 动钱 |
| 活动(倍率券等) | activity_campaigns + _rules | admin 活动 | 圈人条件 / 倍率序列 / 单数 x / 时间窗 / 状态 | 运营 | 🔴 动钱 |
| 邀请券活动 | invite_coupon_campaign_rules | admin 邀请券 | 邀请券面值 / 触发条件 / 封顶 | 运营 | 🔴 动钱 |
| 券(发放/核销) | user_coupons · coupon_ledger | 券配置 | 12 种券的面值/门槛/限量/发放/核销 | 运营+系统 | 🔴 动钱 |
| 品牌位 | popular_brand_config | admin 品牌 | 热门品牌 / 搜索词 / 返佣 bps / 排序 / 开关 | 运营 | 🟡 展示 |
| 运营位/投放位 | campaign_placements | admin 投放位 | 启动页/弹框/悬浮/banner/品牌坑位 的位置·素材·时段 | 运营 | 🟡 展示 |
| 配置中心·规则版本 | rule_config(_versions) | admin /rules | 规则的版本化配置(按 ordered_at 命中版本) | 运营+开发 | 🔴 动钱 |
| 配置中心·运行开关 | runtime_feature_config | admin /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.payment | api-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 | 告警阈值 / 日志密钥 / 客户端运行参数 | 开发/SRE | T3/T2 |
🔒 T2 多是密钥/集成:开发改、走 ECS .env、重启生效——不让 NL 改,但可被查询("Xendit 配了吗 / 接了哪些登录",只答配没配、不吐明文)。
五、配置目录 · 元模型(字段定义)技术细节
每个可配项都用这套字段描述,NL 与后台 UI 都读它来「找配置 / 看现状 / 改配置」。
| 字段 | 含义 | 例 |
| domain | 配置域 | 分佣 / 星级 / 活动 / 券 / 品牌位 / 运营位 / 集成 / 鉴权 … |
| key | 配置项唯一标识 | reward_rule_config:DIRECT_COMMISSION |
| name | 人类可读名 | 直推佣金比例 |
| tier | T1DB热改 / 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 读明文/写。