犀见技术架构文档

版本：v1.0 ｜ 2026-08-16 ｜ 面向：新加入的工程师、业务方技术对接人 上游事实源：CLAUDE.md（ADR 与选型定案）｜ docs/dev-charter.md v1.3（域划分/Schema 三分法/流程分级）｜ docs/dev/msgbridge-contract.md v1.0（消息域契约）｜ docs/dev/influencer-schema-design.md（达人域模型）｜ docs/dev/jixing-api-notes.md（集星 API）｜ 代码实况（server/app/、console/src/、server/.env.example） 本文只写架构，不写业务口径：任何判定数字（达标线/分级/时效）以 docs/business/xijian-business-baseline.md v2.1 为唯一口径源，代码一律 cfg() 取值，本文只指出机制不复述数值。

---

1. 系统总览

一句话定位：达人运营除跑客户之外的全部工作在一个运营台完成，把达运 8–9 人的人力占用压到 2 人乃至 1 人。

产品边界：console（运营台前端）+ server（后端）+ miniapp（达人端）+ 消息台服务是一个产品。消息台深度融入统一运营台——主工作面板就是消息台形态，也是与达人端的主要沟通面板（charter §5、契约 §1 定位澄清）；"集成契约"指的是代码层面的服务间接口（消息台作为企微执行层服务化部署），不是两个系统对接。

┌──────────────────── 统一运营台（一个产品边界） ─────────────────────┐
│                                                                    │
│  运营/管理员 ─▶ console                              消息台服务      │
│               (React19+Vite)      ┌────────────┐   (Flask+gunicorn)│
│                  │ /api           │            │  ┌──────────────┐ │
│                  ▼                │   server   │  │ 企微执行层    │ │
│                nginx ────────────▶│  (FastAPI) │◀▶│ 发送/限流/加人│ │
│                                   │            │  │ SQLite       │ │
│  达人 ─微信─▶ miniapp ────────────▶│            │  └──────────────┘ │
│              (uni-app+Vue3)       └─────┬──────┘  127.0.0.1:5040   │
└─────────────────────────────────────────┼──────────────────────────┘
                                          │
    ┌──────────────┬──────────────┬───────┴──────┬──────────────┐
    ▼              ▼              ▼              ▼              ▼
MySQL xijian   lynoxi 旧库     集星 API      数据中台 API     方舟 ARK
/xijian_test  （跨库只读）   dls.lynoxi.com  ai.iphome.cn   （视频理解）
 新库·权威     历史价/旧订单   达人档案指标    项目经营数据      P1-6 起
                              （现役）      （将来主来源）

外部方向一律只出不入：外部系统不主动写犀见库，犀见也不直连任何外部数据库（§5 铁律）。

---

2. 架构决策（ADR 摘要）

---

3. 技术栈与选型

---

4. 应用架构

4.1 server 分域结构

入口 app/main.py::create_app()：装 envelope 异常处理器 → 请求日志中间件 → 各域 router（统一前缀 /api）→ 可选启动 APScheduler。新接口三件套 = domains 内实现 + tests/contract/ 契约测试 + main.py 登记。

响应壳（envelope 语义，全站唯一出口 app/envelope.py）

domains 清单

横切能力

• 权限：deps.require_perm(perm) 依赖注入，权限码从 JWT 携带的 perms 快照校验。
• 审计：domains/system/audit.py::audit() 是 service 层函数（不是 HTTP 接口），三 sink——结构化日志必写 / 有库 INSERT xijian_audit_log / 无库进程内内存兜底。
• 请求日志：app/middleware.py 一行一请求（method/path/status/耗时/操作人），跳过 /api/health 防灌水。
• 无库模式（DATABASE_URL 空）：health 报 skipped、system 走内存 store、cfg() 走 seed 兜底——前端联调轻路径。例外：msgbridge touch 去重无库直接报错拒绝执行（去重失效的代价是重复骚扰达人/触发风控，不可退化）。
• 分层纪律：router / service / schemas / models 分层但不过度抽象；单模块 ≤200 行有效代码（机检）。

4.2 console 架构

• 路由：hash 轻路由，内核 src/lib/router.tsx（matchRoute 精确表 + :param 段），src/routes.tsx 为 lazy 拆包登记表。新页面三步：routes.tsx → components/layout/nav-items.ts → feature 目录（机检强制两表一致，历史上真出过 nav 有页面无路由的 404）。
• feature 组织：features/<模块>/ = page.tsx（只做拼装）/ api.ts（该模块所有请求）/ types.ts / hooks/（一个 hook 一件事）/ columns/（一列一个文件）/ components/。当前已建：dashboard、auth、influencers、system-users/roles/audit/config。
• 请求出口唯一：src/lib/http.ts 统一解 envelope、带 token（localStorage xijian.token）、15s 超时、401 清 token 跳登录；禁止裸 fetch。
• 组件红线：components/ui/ 基础件不含业务、单文件 ≤80 行有效代码、一个文件 useState ≤6；颜色只出 src/styles/tokens.css——写死 hex 与"tokens 里不存在的语义类"都会被机检拦下。

4.3 miniapp

当前目录是 xijian-legacy/app 的工作区快照（来源 commit 记于 miniapp/README.md），存量页面九个（入驻/报名/任务详情/入园回填等）。按 ADR 8，后续按新定位大量重构，不在旧逻辑上迭代；旧代码作设计风格/样式参考。达人端在架构中的两个硬链路不变：小程序绑定身份（openId/unionId）与 wcid 回流（§6.2）。新信息架构待产品方案落地，标待定。

---

5. 数据架构

5.1 库与表

生产库 xijian、测试库 xijian_test，同 MySQL 实例（115 机容器 33306）与 lynoxi 系解耦。当前仓库默认 DATABASE_URL 留空（无库模式），DSN 已在 .env.example 备妥，正式接线时点由主会话拍板。

命名与类型约定（达人域设计 §0，全域沿用）：新表无 xijian_ 前缀（xijian_config/xijian_audit_log 是前定案时期历史命名，不追改）；枚举用 VARCHAR + 应用层 StrEnum（全小写下划线）；金额列名带 _fen、比率 DECIMAL 标度统一 0–1、多值走 JSON 数组、软删 deleted_at、有旧库映射源的表带 legacy_id 做导入幂等锚；不建物理外键，靠索引 + 应用层保证。

5.2 Schema 三分法（charter §4）

跨库只读纪律：独立只读 engine + 只读账号，SQL 一律写全限定名 lynoxi.xxx（新旧同名表存在），分页按主键游标、禁 OFFSET 深分页。

5.3 配置中心机制（工程铁律 2 的系统化）

• 表 xijian_config（key / value / value_type / description 说明 / source 出处 / updated_by / updated_at），key 命名规范 域.蛇形名；分组由 key 前缀派生（key.split(".")[0]，无独立 group 列）。当前种子 50 键、9 个前缀域（grade / sla / settlement / recommend / msgbridge / data / growth / ark / bf）。
• 读：cfg(key) / cfg_num(key) 是全项目取阈值的唯一入口，模块级缓存惰性全量加载；写接口挂 system.config.write 权限 + 审计打点，写库成功调 invalidate()（下次读自然拿新值，不在写请求路径里现算全量）。
• 演进法：新增/改默认值 = 出新的 Alembic 追加迁移 + 同步改 seed.py；迁移文件是历史快照冻结不改，seed.py 是"当前默认值"的活源，两处漂移由单测挡住。
• 口径缺口处理：占位行 value="待确认"（value_type=str）原样返回字符串，绝不静默转 0；依赖该键的判定短路并显式告警。每个键注明 baseline 出处。

5.4 外部数据源矩阵

铁律：外部数据一律走 API，绝不直连外部数据库。（charter §4，2026-08-17 定案）MCP 只是人与 agent 的调研通道，服务端运行时集成一律 REST API。

---

6. 集成架构

6.1 消息域（产品一体，代码服务化）

6.2 wcid 绑定回流链路

消息台发小程序卡片(wcid) ─▶ 达人点开 ─▶ miniapp 拿 wcid + openId
        │                                        │
        │  ① 权威兑现（先）                        ▼
        └──────────── api.lynoxi.com/qiwe/wcid/redeem（HMAC 自证 + TTL）
                                                 │
                     ② 通知犀见（后，失败不阻塞达人流程）
                                                 ▼
              server 写 influencer_binding 镜像 ─▶ 触发建联入档 + 层级重算
                                                 ▲
                     ③ 兜底：定期对账轮询（synced_at 游标）补齐 ②

签发与兑现留在消息台（密钥不跨服务、绑定权威表单一），犀见只做镜像。绑定关系是"业务身份 → 企微身份"的唯一可靠桥——企微不给外部联系人手机号/微信号，别指望用手机号在企微侧搜人；未命中绑定的达人一律进"无法触达清单"显式呈现，不静默跳过。

6.3 集星 enrich 链路

POST /api/admin/douyin-accounts/{id}/enrich（挂 influencer.write）→ jixing/client.py（120s 超时、重试策略内置、trust_env=False）→ 两接口（档案 + 带货表现）→ parse.py 解 digit_value → 更新 douyin_account 档案字段 + upsert douyin_account_metric；metric 行按 fingerprint 比对，值未变整行不写（零 UPDATE、零 binlog）。批量/定时富化排 P1。

---

7. 安全架构

• RBAC：权限码是代码常量注册表（domains/system/perms.py，当前 10 个：system.* 7 个 + influencer.read/write/payment.read），角色—权限绑定是运行时数据落 admin_role_perm；JWT 携带 roles/perms 快照，require_perm 不足时 HTTP 200 + code 403（不是会话问题，不踢登录），仅会话失效走 401。
• 审计留痕：audit(username, action, target, detail, ip)。已打点面包括 config.update、influencer.create/update/delete、influencer.grade.change、influencer.blacklist.create/revoke、influencer.payment.create、influencer.payment.reveal、influencer.account.create/update/bind、roles.*、users.*、auth.login、msgbridge 触达（记 scene/mode/trigger/operator/批次）。
• 敏感字段掩码分流：收款信息（银行卡号/身份证）默认掩码返回并带 masked 标记；明文需 influencer.payment.read 权限，且查看动作单独审计。身份证从达人主档下沉到收款表，收敛读取面。
• 密钥纪律：.env 不入库不提交（JWT_SECRET / ARK_API_KEY / DB 密码）；配置中心只存业务口径，不存任何密钥；Alembic 迁移里不得出现明文；机检扫描旧仓泄漏特征前缀（scripts/check_structure.py），console 侧另有 check-pii.mjs 测试库 PII 检查。
• msgbridge 越界收敛防线：库值被写坏（未知 mode）一律收敛 off；业务红线校验与 mode 无关（即使 off 也挡非法调用）；名单发起时快照落库，运行期不允许扩名单；无库拒绝执行；一切 live 触达走全评审链 + dry-run/shadow 先行。

---

8. 部署架构

115.190.214.120（主机，一台机承载全部）

121.196.161.103（大千 ECS，备用）：/var/www/xijian.daqian.ai 预热目录，正式域名 xijian.daqian.ai 切换时只改 nginx；机上另有大千其他系统。

公网固定入口（不可迁）：api.lynoxi.com 上的企微回调 /qiwe/callback、小程序回传 /qiwe/wcid/redeem、卡片封面 /qiwe/share.png、待发送媒体 /qiwe/up/*。

部署纪律：① 生产库写操作前先在测试库实证，生产切流由用户拍板时点；② console scripts/deploy.sh 先跑构建自检、失败即停，产物指纹与线上比对防版本漂移；③ 不擅自动旧 api 服务与容器、不接管消息台部署机的其他系统；④ 危险外呼（企微发送）先 shadow，真实执行走确认机制。

---

9. 工程纪律

测试库策略（澄清，2026-08-17）：犀见生产/测试环境 100% MySQL（xijian / xijian_test）。自动化测试（pytest）用 SQLite 内存临时库跑逻辑正确性——每用例独立建库毫秒级、零污染（Alembic 迁移以 with_variant 保证双方言兼容，MySQL 为权威方言）。SQLite 测试的已知盲区是网络成本被掩盖（本项目两次性能事故的根源），因此配第二道门：qa 验收必须连 MySQL 测试库以真实数据量实测。另注：消息工作台（legacy）自有 SQLite 存储属天择侧现状，犀见只经 API 消费。

三条铁律：① 文件小而专一（server 单模块 ≤200 行、console ≤80 行有效代码）；② 口径数字不硬编码在业务逻辑里——集中配置并标注基线出处；③ 写库前判"值是否真变"，轮询按实体去重（旧仓 binlog 日增 5G 的教训）。

机检（约定变成可执行检查）

测试基线（2026-08-16 实测）：server uv run pytest 315 用例（contract 契约测试 + unit），console npx vitest run 76 用例全绿；CI 每 push 跑两端全链兜底。新接口无契约测试不算完成；涉及口径判定的逻辑，契约测试必须覆盖阈值边界并验证"阈值可配"。

文档双份管线：一切文档 MD 为源进 git；在 docs/render-docs.py 的 REGISTRY 注册即获线上 HTML；docs/sync-docs.sh 一键渲染 + scp 到 115 文档中心。本文件已注册（architecture.html）。

文档驱动开发协议：进度唯一事实源是 docs/dev/execution-plan.md；业务开发会话开局先读它对齐，再读 charter（流程）与基线（口径），不依赖对话记忆；每完成一个子任务在当次提交内更新状态与 commit 号。口径变化 → 先改基线再写代码；基线没有的判定不编，标待确认。

流程分级（charter §6 摘要）：日常功能开发走单 agent 承包 + 自验全绿 + 主会话终验；涉及口径判定加阈值边界测试；写旧库 / 资金相关 / 对外发送（企微）走全评审链；合入生产/切流需全评审链 + 测试环境实证 + 用户拍板。口径数字硬编码 = review 一票否决项。

---

变更记录