FAMOS 系统全流程手册（合订本 v1.5）

定位与读法：五大业务主线（营销 / 企业学堂 / 商品数据链 / 品牌资产中心 / 系统设置）× 四级（L1 价值链 → L2 流程域 → L3 子流程 → L4 操作指南）。

对账基线：geo main 7ba36b80（SIMTEST 三卡并入后）+ 20261017 深夜部署窗 ｜ mini v7.17.0。

全局红线：AI 不生成价格（人填白名单）；xhs/douyin 手动发布防限流；不爬平台数据；geo 生产永不 next build；令牌不入库。

源件：MECE-20261016 + 营销板块×2 + 企业学堂 + 商品数据链 + 品牌资产中心 + 系统设置（均 20261017）合并去重，并按 20261017 深夜—20261018 交付刷新（见附录 C 更新记录）。

使用约定：改代码必须回改本文对应段（防文档-代码漂移）；行数/端点/行号锚为源件原值，变动以新实证为准。

FAMOS 是面向时尚零售品牌（服装门店/连锁品牌）的 AI 经营协同平台：把「企划 → 内容 → 审批 → 分发 → 获客 → 复盘」的营销全流程、企业学堂的「生产 → 派发 → 学习 → 考核 → 回收」培训闭环、商品与品牌资产的「收集 → 资产化 → 消费 → 维护」统一到同一套租户/权限/数据底座上。一句话：让总部企划、内容运营、老板、区域经理、店长、导购、学员共用一套内容资产与任务闭环，AI 负责生产，人负责守门。

• PC 运营后台：企划/内容/审批/分发/回收的主工作台（/next 域，运营与总部用）。

• 微信小程序：老板驾驶舱与员工执行端（今日转发/任务/数据总览/企业学堂/商品台账/拍照识别）+ 学员学习考核端 + 顾客 H5 承接页。

• 桌面客户端（GEO Desktop / 兜底执行机）：平台账号授权与公域发布执行体（full/semi 两类）。

• FIP（内部面）：趋势情报与素材采集的内部供给面，不对租户/客户展示（FAMOS 是客户面）。

① 营销全流程（第一部分）

• AI 策划四入口：模板/商品台账选品/活动申报反入口/自定义；AI 简报（V4 Flash，可注入同类型最近复盘基线）→ 人工逐条编辑确认

• 内容矩阵 9 条（短视频脚本×3/朋友圈×3/话术/海报/图文）逐条重生成与审批；FAQ 一场一套；海报渲染 1080×1440 自动落素材库

• 审批双轨：内容按域（GEO 机审直放/social prescreen 分流/leads·groupbuy 全人工），活动走阈值快照路由（5 键，GM-only 写，在途单不随改）

• 公域发布：过审自动/celery 定时/手动三入口建任务 → agent 原子认领（full 兜底机/semi 租户桌面）→ 回传 published+publish_url；失败三分类（账号风控/平台错误/网络）

• 私域传播：活动 effective 钩子自动灌分享任务/涨粉池 active 稿/手动创建 → 今日转发/顾客 H5 得券 → 凭证上传核销；员工与顾客积分双轨

• 复盘：三源聚合效果仪表（total_reach）→ 手工生成复盘件 → 转选题（titles+pool+feedback 同事务）+ 简报可选注入

② 企业学堂（第二部分）

• AI 生产：FAB/商品资料→销冠话术与题目，上新→新品学习包，playbooks→课件，课件→LLM 出题

• 唯一派发通道：PC 建任务（course/series、required/elective、due_at、scope 圈人）→ my-courses 派发驱动可见（范围外私有课排除、未派发私有课原样、逾期标而不隐）

• 双端学习：mini edu 六 Tab + PC 学员端（HMAC 学员令牌）；PDF 页图/视频/文本三形态课件 + 断点续学

• 测验与测评：选择题前置圆圈选中填色（v7.17.0）→ 交卷出分 → 错题本 → 弱项维度 → 针对重练；AI 对练五维评分与回放；能力雷达看变化

③ 商品数据链（第三部分）

• 三入口收集：PC 批量图片（文件名解析 SPU+颜色+VLM 12 维+黄标低置信修正）/ mini 手工登记（confirmed 直登幂等查重）/ mini 拍照识别（草稿不自动入库）

• Excel 批量导入：模板下载→三桶预览（可入/校验失败/重复）→ 直 confirmed；唯一约束 uq_frl_tenant_spu_color 防重复录入

• 素材库：上传/参考导入/FIP 公共池分流 → 两级分组（池/文件夹门店维）→ VLM analyze 打标 → 图生文四模板 + 四态进度反馈

• 消费：上新节拍看板（brand-map 单源）/种草文注入/活动选品桥 goods_item_id 自动拼商品描述/销冠培训 FAB

④ 品牌资产中心（第四部分）

• 画像 10 组分区 + 定位档 tier 预览确认 + AI 生成画像 + 复制参考品牌（seed 5 枚）+ 完成度检查

• RAG 向量库（knowledge_chunks）单源注入所有生成线；缺失走三级回落不阻塞

• 账号授权：媒体账号与 AI 引擎 key 分开，桌面桥抓取，authed/expired 与 cookie 过期预警

• 官网设置：站点名/副标题/Logo/首页文章数 + 模板三选一 + SEO 覆盖 + 预览；门店登记；四域只读总览

⑤ 系统设置（第五部分）

• 建租户 seed 5 岗模板（店长/区域经理/导购/总经理/内容运营）+ 员工/邀请码/角色授权（perm_user_roles/perm_role_perms）

• 权限三件套：菜单键（MENU_TREE+豁免漂移集）/动作键（11 个 action: 高敏键）/组织域（org_rank+store/region/dept 圈数据）

• 费用与设置 9 Tab（账单/订阅/租户/通知/安全/日志/积分/形象区/经营知识库）；写作规则 4 Tab；问答库 FAQ+选题问题库

• 审批阈值在营销侧（ThresholdDrawer 5 键，GM-only，提交时快照），不在本组

⑥ 经营数据与回收（贯穿各主线回收段）

• 数据总览：四域灯+队列+直放+发布，辖区分档（gm 全量/region 本区域/store 本店/staff 403），不可圈定块 fail-closed 置空+note

• 驾驶舱 hero + 活动效果仪表（三源聚合 total_reach，纯读零持久化）

• 门店日填报（店长按本店 upsert 加微/预约）与数据总览/驾驶舱/活动效果三面同源

1. AI 生成，人守门：价格与规则永远人工白名单，内容双轨审核（机审直放/人工分流），AI 不替人做经营承诺。

2. 公私域双链：公域=文章发到平台账号（DistributionTask+agent 执行体），私域=员工/顾客转发得券核销；两链仅共享素材，任务体系零耦合。

3. 组织域权限：gm/region_mgr/store_mgr/staff 四级 + 店/区/部门圈定数据域，辖区不可圈定块 fail-closed 置空，不越权。

4. 单源品牌基因：build_brand_context 一处注入所有生成线，品牌画像/RAG 不另起炉灶。

5. 可实证交付：每个流程节点有端点/表/行数锚点，改代码必须回改手册。

平行链与主链的交接点（且仅这些，互斥）：商品链→主链「企划选品+素材供给」；学堂→主链「内容复用+人员承载」；品牌资产→主链「内容生成的品牌基因注入」；系统设置→全部（权限/组织/配置）。

穷尽校验：PC 侧边栏 11 菜单组、mini 宫格全部模块均落入且仅落入一格；无主链/平行链重复归属。

四级定位：L1 价值链（七段，是什么）→ L2 流程域（六线/双轨/双链，分几路）→ L3 子流程（10 张，怎么流转）→ L4 操作指南（11 个 SOP，每步五要素：操作人/操作动作/系统端点/字段与取值/异常分支与重试）

页面入口速查：PC 活动管理 /marketing/activities（三 Tab）｜ 审批中心 /review-center（五 Tab）｜ 小程序工作台宫格 → 各功能页

①供给 → ②生成 → ③审核 → ④分发 → ⑤触达 → ⑥获客 → ⑦回收
  │        │        │        │        │        │        │
 S1-S4    G1-G6   A1∥A2    D1∥D2    T1-T3    F1-F3    R1-R3

• 每段互斥穷尽：营销板块全部端点/页面恰落一段

• ⑦→① 人工回流已通（期 A 复盘件 + 转为选题）；自动回流属期 B（待 2 周真实使用记录）

• 编排层（O1 活动策划 AI 管线 / O2 手动直建）横向打包 ①-④，出口固定：O1 经 effective 钩子注入 ④D2，O2 直达 ③A2

┌─ 支撑层：选题库 · 素材库 · 品牌RAG · 获客码 · 规则配置(写作/审核/阈值) ─┐
═══ 主链七段（上图）═══
═══ 编排层：O1 活动策划AI管线（四步向导）｜ O2 手动直建 ═══

触发：celery 定时或 POST /content 手动 → RAG 品牌上下文 → TextPipeline（写作规则+季节天气）→ 三道质检（不过不交付不扣费）→ geo_contents → A1 auto_pass 直放/needs_human 入老板队列 → approve 副作用：建分发任务+官网同步+RAG 回流。降级：RAG 缺失纯 LLM；草稿可重生成。

celery 06:13 → 活跃闸（30 天登录/authed 账号，6 演示租户已闸）→ 取租户档位（all_manual/partial 默认/all_auto）→ lead 管线 5 篇（禁转化词命中 502 不交付）→ 生成事务提交后 prescreen_one 逐篇 → suggest_pass 入 active 池 / needs_human 人工队列或直拒。员工领稿（xhs/douyin 手动红线）→ 凭证回传。配套：超龄退役(>14天)、存量补跑（非 beat，默认干跑）。

获客工场 campaign/columns/img2art → lead 管线（允许转化话术，与 G2 分域）→ manual 全人工 → 五码出码（4 渠道+总码 QR）→ Desktop 桥半自动 or 纯手动 → /t/{code} H5 承接。

/viral/script 生成（9 型×3 平台×爆款 few-shot，A/B 双版扣费）→ video_scripts 独立表 → 轻量人审（review_state，租户先审后派开关）→ 成片三路（Canvas-tts/render-server ffmpeg/docx）→ 成片自动落素材库「成片视频」组（幂等 handle）→ 一键派 manual_publish 员工任务 → 手动发布+截图凭证。禁区：不做自动上传。

mini 选 1-9 图 → 上传先行（临时件转存）→ 逐图 VLM → V4 Flash 一次调用产 3-6 条（统一多条核）→ moments_drafts 落库（降级不连坐）→ 复制/朋友圈预览/保存相册/最近生成。手动复制手发为终态。编辑能力在途（MOMENTS-EDITCOPY 卡）。

四头入口 → 四步向导（简报/矩阵 9 条/FAQ/申报）→ 双审批 → effective 钩子（content 释放 + moments 自动灌 share_task）。

三入口（approve 自动/celery 定时/手动）→ DistributionTask → agent 原子认领（full 兜底机/semi 租户桌面）→ cookie 随 payload 下发 → 执行回传 published+publish_url → UTM 获客码绑定（同稿同平台共享一码，绑定时刻分界）→ 失败三分类处置。账号健康：heartbeat/活体探测连 2 次判死。

素材三入口（活动钩子/涨粉池/手动）→ share_task（员工）/customer_share_tasks（顾客）→ 今日转发（复制/预览）→ H5 承接 → 凭证上传 → 核销。与 D1 零耦合仅共享素材。

拍照识别（VLM 12 维）→ leads；五码扫码 → /t/{code} 归因（含 publish 维）；凭证核销；门店日填报（店长按日本店录 lead_store_daily_stats）。

三源汇聚 → 活动效果仪表（metrics 三源聚合→total_reach）→ 期 A 复盘件（活动详情「生成复盘」→ retro_reports；「转为选题」→ titles+pool+feedback 同事务；简报可选注入 inject_history）→ 首页 retrospect 收录率卡已修。期 B（自动触发/加权/默认注入）禁区锁死待使用记录。

• 操作人：企划/运营

• 动作与去向：H1 常用模板 Tab（5 枚预填）｜H2 商品台账「策划活动」按钮（携 goods_item_id 桥取名/色/款/材质）｜H3 活动申报详情「AI生成内容」（携 from_mkt_activity_id 类型映射+时间窗预填）｜H4 自定义空白

• 异常：H2 台账桥失败 ⇒ 降级用手输商品描述，不阻塞

• 端点：POST /mini/campaign/brief（201）→ 人工逐条编辑 → PUT /campaign/{bid} 确认

• 字段：campaign_type/product_input/start_end（11-01~11-11 短日期自动补年）；可选 inject_history=true 注入同类型最近复盘基线（不含金额，无复盘静默跳过；默认 false 契约零变化）

• 异常：draft 态调 generate-all ⇒ 422 设计保护（先确认再生成，非故障）

• 端点：POST /campaign/{bid}/generate-all

• 引擎（ENGINE-UNIFY 后）：脚本×3→VideoScriptService（爆款 few-shot）；图文→GenerationPipeline（RAG+三道质检）；朋友圈×3→统一多条核——契约形状/状态机不变，零双倍扣费

• 异常：单条失败仅该条降级，不连坐

• 端点：regenerate（:223）/ approve（:262）/ reject（:270）；PC 审批中心「活动内容」Tab 可批量（跳态条如实报 done/skipped）

• 状态机：pending_review→approved/rejected 不可逆

• 操作：海报条选背景（GET /campaign/{bid}/poster-images 品牌图库）→「生成海报」POST /campaign/{bid}/poster/{cid}/render → 1080×1440 PNG 自动落素材库「活动海报」组 → mini 预览/保存相册，PC 查看/下载

• 异常：未选背景 ⇒ 409 引导先选；渲染失败不连坐其他条目；排版层含禁价校验（¥/元/折/立减/满减记号拒排）

• 端点：POST /campaign/{bid}/faq（整替）；PC 活动详情可编辑

• 端点：POST /campaign/{bid}/submit-declaration——价格字段白名单人填（discount_pct/est_cost 等）+规则必填；类型映射（上新→lead_in/清仓→clearance/节庆→promo/品牌→brand）

• 异常：重复申报 409 ⇒ 查详情页原单

• A2 活动审批：审批中心「活动申报」Tab（阈值 5 键快照，GM-only 写；提交时定稿在途单不随改）

• effective 钩子：content 批量释放 + brief→approved + moments 自动灌 share_task（[campaign:{bid}] 幂等溯源）；钩子 warn 降级不连坐审批

• 端点：GET /campaign/{bid}/metrics（distribution/store_daily/receipts{count}/total_reach 嵌套结构，PC 已归一化渲染）

• 复盘件：活动详情「生成复盘」→ retro_reports 落库 → 「转为选题」回流（同事务）

• 创建：活动管理 Tab「常用营销活动」POST /mkt-activities（类型/时间窗/门店/价格规则全人填）→ submit（:216）→ 审批中心走 A2（approve:223/reject:231）

• 查询：review-queue（:173）/mine（:167）；阈值 GET/PUT /mkt-approval-thresholds（:246/:252）

• 异常：阈值改不影响在途单（快照）

• 触发：PC /content-studio 生成任务（定时）或 /content 手动 POST /content/ai/generate

• 审核：GEO 域 auto_pass 机审直放（auto_release）；needs_human ⇒ 审批中心「GEO 稿」Tab

• 过审副作用：自动建 DistributionTask + 官网增量上站 + RAG 回流

• 降级：质检不过不交付不扣费；草稿重生成

• 档位设置：PC 官网设置页 social 三档（all_manual/partial 默认/all_auto）+ 池页设置弹层 low_conf_action（queue/reject）

• 审核：审批中心「涨粉稿」Tab 批量过/驳（fan_pool.py:123/:133）；featured 主推 :158；手动补生成 POST /gen-now :208（调用者登录即活跃）

• 发布：xhs/douyin 手动红线；gzh/官网可自动；凭证回传 receipts approve/reject

• 批处理：retire_stale_pending/backfill_prescreen 直调服务函数（20261017 队列隔离后：旧 worker 只听 audit,monitor,sync；render 独立单元；publish/webhook 由新单元 geo-celery-publish 独立消费（并发 1、prefetch=1），不再被 monitor 长任务挤占（受控探针：接受→开始 1ms）；celery call 落默认队列仍无人接，一次性操作直调服务函数）；默认干跑，FANPOOL_BATCH_APPLY=1 才写库

• 生成：获客工场 POST /marketing/leads/{cid}/generate（:413）或栏目企划；允许转化话术（与 G2 禁词分域）

• 审核：leads 域 manual 全人工 ⇒ 审批中心「获客稿」Tab

• 出码：LeadLink 4 渠道+总码 → QR 入物料库；GET/PUT /wechat-qr（:68/:77）配置

• 分发：FIP Desktop 桥 lead:publish 半自动（留痕 AuditLog）；Desktop 不在线 ⇒ 纯手动复制+码图下载

• 效果：content-roi by_source 维度（UTM 绑定后访问计 publish）

• 生成：/viral/script → POST /content/video-script/generate（:98）；选题 POST /video-script/topics（:261）；图生脚本 :445

• 人审：开关 GET /video-scripts/review-switch（:567，租户级先审后派，默认免审）→ POST /video-scripts/{id}/review（:634）

• 成片：三路渲染（Canvas-tts / render-server :962 / docx :874）；自动落素材库「成片视频」组（render_url 引用即免 30 天清理）

• 派发：POST /video-scripts/{id}/dispatch-publish（:618）→ boss_tasks(manual_publish)（成片链接+话术+检查项；同脚本同平台幂等）→ 员工手动发布+截图凭证

• 禁区：不做自动上传/不爬平台

• mini 独立页：选 1-9 图（chooseMedia）→ 上传转存 → POST /mini/image-to-moments → 一次产 3-6 条（单品/搭配/生活方式三风格）

• 使用：复制（setClipboardData）/ 朋友圈预览（≥6 行折叠）/ 整图保存相册（权限拒绝兜底引导）/「最近生成」GET .../history

• 落库：moments_drafts；落库失败降级不连坐（draft_id=None 照常返回）

• 在途：编辑存回 + PC 历史/复制（MOMENTS-EDITCOPY 卡执行中）

• 建任务：三入口——过审自动/celery publish_due/POST /distribute/tasks（:56）；管理 GET /tasks（:163）/stats（:245）

• 认领执行：GET /distribute/agent/tasks/next（:812 原子认领，full/semi 双执行体，cookie 随 payload）→ progress（:1194）→ result（:1221，published+publish_url）

• 发布后：UTM 获客码绑定（同稿同平台共享一码，绑定时刻分界）；gzh 效果回填暂缓（订阅号无 freepublish/datacube 权限，48001 实证；IP 白名单 121.43.111.219 已配通，有认证服务号即启用）

• 失败处置：account_risk→probe 复查换号勿频试｜platform_error→看错误码，xhs/douyin 走手动，修内容 retry（:289）｜network→直接 retry

• 卡单：publishing 超时自动回收；人工终止 cancel（:321）

• 执行单元：geo-celery-publish（publish,webhook 专用，20261017 CELERY-PUBLISH-ISOLATE 已上 prod）独立消费发布队列；旧 worker=audit,monitor,sync，render 独立——五队列时代「只听五队列」表述已过时

• 消费：mini「今日转发」——活动卡（[campaign: 前缀暖橙底）复制/朋友圈预览/查看任务；GET /mini/share-tasks

• 顾客链：H5 GET /share/{token} → 转发得券 → 凭证截图 POST /share/{token}/voucher（pending）→ 核销 POST /tasks/{tid}/receipts/{rid}/approve

• 边界：D1 发平台账号（文章），D2 顾客/员工转发运营——仅共享素材零耦合

• 拍照识别：POST /mini/photo-recognize（VLM 12 维草稿）→ 确认入 leads → 工作台跟进

• 五码归因：/t/{code} 承接（leads.py:753）→ 留资/加微；POST /lead/{code}/wechat-click（:767）；发布侧扫码 source=publish

• 门店日填报：lead_roi.py:160 report_store_daily_stats（店长按日本店 upsert；三面同源：数据总览辖区/驾驶舱 hero/活动效果仪表）

• 效果仪表：GET /campaign/{bid}/metrics 三源聚合（R1 分发/R2 凭证回执/R3 门店日表）→ total_reach；纯读零持久化

• 期 A 复盘：活动详情「生成复盘」→ retro_reports（body：period/effect/format_perf/channel_cmp/verdict 人写）→「转为选题」（titles 留溯 retro:<id> + topic_pool + feedback 同事务）

• 简报注入：见 SOP-01 步骤 1.2

• 首页收录率卡：GET /api/v1/marketing/retrospect（inclusion_tasks 本周/上周聚合，已修 404）

• 期 B 禁区：自动触发/选题加权/默认注入——待连续 2 周真实使用记录

在途与挂账：MOMENTS-EDITCOPY（编辑+PC 复制/历史，执行中）｜RETROSPECT 期 B（等使用记录）｜TASKMODEL-CONVERGE（挂账）｜gzh 回填（暂缓待认证服务号）

四级定位：L1 知识生命周期（五段，是什么）→ L2 流程域（六域，分几路）→ L3 子流程（十张，怎么流转）→ L4 操作指南（11 个 SOP，每步五要素：操作人/操作动作/系统端点/字段与取值/异常分支与重试）

全局红线：AI 不生成价格（营销话术/FAQ 的价格与规则由人审）；令牌不入库；geo 生产永不 next build

页面速查：PC /sales-training/courses（课程中心）｜ /sales-training/training（实战训练）｜ /sales-training/assessments（测评管理）｜ /sales-training/public-resources（公共资源库）｜ /sales-training/learn（学员端）｜ 小程序宫格 pages/edu/index（六 Tab：learn/exam/practice/data/rank/faq）

①内容生产 → ②派发与任务 → ③学习与练习 → ④检验与考核 → ⑤数据回收
    │            │              │              │              │
 课件/话术/FAQ   单一派发通道    小程序+PC学员端  测评/AI对练/错题  实时看板/雷达/弱项

• 五段互斥穷尽：学堂所有路由/页面/表恰落一段；学员端两条入口（小程序 pages/edu + PC 学员端 /sales-training/learn）共用学员档案与进度，非两套系统。

• 与营销主链的交接点只有三个：① FAB/商品资料 → 内容生产（销冠话术/题目/新品学习包）；② campaign FAQ → 活动话术 Tab（跨模块借用，不落学堂表）；③ 同一权限体系（perm_registry + org_rank）决定谁能看/派/学/审。

┌─ 支撑层：学员档案 + 权限域 + 品牌 FAB + 商品台账 + 公共桶 ─┐
 ① 内容生产（FAB/上新/手写 → AI 生成/人工编辑 → 课件/话术/题目）
 ② 派发与任务（PC 建任务 → scope 圈人 → my-courses 可见性）
 ③ 学习与练习（mini edu 六 Tab + PC 学员端 + AI 对练）
 ④ 检验与考核（课件测验/测评/错题重练；证书已下线）
 ⑤ 数据回收（实时看板/雷达/弱项/驾驶舱学习块）

FAB/商品资料或手工录入 → from-fab 生成话术点（销冠素材）→ from-playbooks 生成课件 → learning-pack/from-launches 生成新品学习包 → materials/from-playbooks 录入素材库 → gen-quiz 从课件出题（LLM 草稿）→ 人工编辑/复制为我的品牌。降级：RAG 缺失仍可手写；LLM 生成不通过则退回人工编辑。

from-fab 话术点入库 → 话术库伪课程（isTalkCourse 判定）按场景分章 → pages/edu faq Tab「活动话术」借用 campaign FAQ（不落学堂表）→ 员工复制承接。红线：价格/活动规则由人审，不由 AI 决定。

PC 课程中心「学习任务」Tab → 建任务（target_type=course/series、required_count/elective_count、due_at、scope_type=role/learner/store/dept）→ publish → 学员 my-courses 叠加可见（default 桶私有课经总部派发可见）+ 范围外私有课排除 + 未派发私有课原样 → 到期逾期标记（不隐藏）→ 完成判定（course→progress、series→内含课程聚合、elective_count 满额即完成）。降级：预迁移表不存在时 _learning_block 降级为 0，不拖垮驾驶舱。

mini pages/edu learn Tab 或 PC 学员端 → my-courses 取可见课程（公共课/系列/派发课）→ 课件 materials/{mid}/view（PDF 页图三 kind 超集）→ POST /learn/progress 回写进度/断点 → 下次续学。公共课与未派发私有课仍走既有可见性口径。

PC /sales-training/training 或 mini practice → POST /learn/practice/start → 多轮 POST /learn/practice/turn → 五维评分与记录（sales_session）。降级：会话失败可重开新会话；LLM 不替人给最终销售承诺/价格。

materials/{mid}/quiz 取题 → 选择答案（选中态已修复并升级（v7.17.0）：选项前置圆圈（选中填暖橙+内嵌白✓）+暖橙行底+边框+右侧✓+加粗文字；数据层选中与视觉选中一致）→ quiz/submit 交卷 → score/passed/attempt_no → 错题入 wrong_book → wrong-practice 重练。若材料未挂卷，按空态提示不强行生成。

/sales-training/assessments 建测评（CRUD/preview-draw）→ questions 取题 → submit 提交 → result 查看通过与否 → my-wrong-questions 收集错题 → wrong-practice 重练。测评未通过可重考，attempt_no 累加。

my-wrong-questions 错题本 → my-weakness 弱项维度 → wrong-practice 针对弱项练习 → learners/{lid}/radar 能力雷达看变化。错题重练仍是同一套题库与答案校验，不另起一套题库。

admin/progress-overview（进度总览）→ admin/dashboard / dashboard/trends（趋势）→ admin/question-stats（题目正确率）→ learners/{lid}/radar（能力雷达）与 learners/{lid}/weakness（弱项）→ boss 驾驶舱 _learning_block（任务完成度/达标率，SQLite 降级为 0 不拖垮块）。物化汇总表已删，不造第二套口径。

perm_registry 角色/菜单键 + perm_user_org org_rank/store/region/dept → effective_perms 决定宫格与端点权限 → 数据域按 rank/dept 圈定（boss/gm 全租户、region_mgr 辖区、store_mgr 本店、staff 无归属如实 0）。boss_tasks 学习类创建走学堂任务通道，不建第三轨。

• 操作人：总部内容运营/讲师

• 动作：①从 FAB/商品资料做销冠话术（POST /admin/talking-points/from-fab）→ ②从 playbooks 做课件（POST /admin/materials/from-playbooks）→ ③从上新资料做新品学习包（POST /admin/learning-pack/from-launches）→ ④从课件出题（POST /sales/materials/{mid}/gen-quiz）→ ⑤人工审核/编辑/发布

• 字段：FAB 文案/商品款号/颜色/场景；source（fab/playbook/launch）；mtype（doc/text/video）；kind；is_public；brand_profile_id

• 异常：LLM 不通过 ⇒ 退回人工编辑，不写死内容；图片/文档上传失败 ⇒ 单件降级，不连坐其他件

• 复制路径：已有参考品牌可复制为我的品牌（10 组画像分区，含定位档 tier 预览/确认）

• 操作人：内容运营 + 店长（审核价格/规则）

• 动作：话术点按场景分章（chapters）→ 需要时从 FAB 生成话术点 → 活动话术 Tab 查看 campaign FAQ（含 objection 标签）

• 字段：point_text、scene、category='objection'；FAQ question/answer/sort_order

• 异常：话术为空 ⇒ 先补 FAB；价格/活动规则/优惠幅度一律人工审核后才可发布；活动 FAQ 是借用不落学堂表，不能误算学堂资产

• 操作人：总部培训管理员/区域培训负责人

• 动作：PC 课程中心「学习任务」Tab → 新建任务（POST /admin/tasks）→ 选 course/series、required/elective_count、due_at、scope_type（role/learner/store/dept）→ publish

• 字段：target_type、target_id、required_count、elective_count、due_at、scope_type、scope_id、remind_days

• 异常：未发布前学员不可见；范围内指派课叠加可见，范围外私有课排除，未派发私有课原样；逾期仅标逾期不隐藏；boss_tasks 的 type=learn 已被 400 拦截，不要再走那条路

• 重复/关闭：关闭后只读保留，不重开双轨；remind-scan 用于提醒，不代替发布

• 操作人：导购/店长/区域学员

• 动作：mini edu learn Tab 或 PC 学员端（ace.acbri.xin/learn → 301 至 geo.acbri.xin/next/sales-training/learn）→ 打开可见课程 → 查看课件 → 续学

• 端点：GET /learn/my-courses、GET /learn/courses/{cid}/materials、POST /learn/progress（进度回写）、GET /learn/progress（读取）

• 字段：X-Learner-Token（学员令牌）；course_id/material_id/status/pct

• 异常：公共课未挂到本租户 ⇒ 仍走既有公共可见性；PDF 加载失败 ⇒ 换页图/文本模式；my-tasks 仅显示本人任务，不能越权看他人

• 操作人：导购/学员

• 动作：进入实战训练 → POST /learn/practice/start → 多轮 POST /learn/practice/turn → 查看五维评分与回放

• 字段：session_id、turn、score（五维）、created_at

• 异常：单轮失败 ⇒ 不丢会话，可继续；不将对练评分当作最终绩效考核，仅作练习参考

• 操作人：学员

• 动作：GET /learn/materials/{mid}/quiz → 选择答案（选中态已修复并升级（v7.17.0）：选项前置圆圈（选中填暖橙+内嵌白✓）+暖橙行底+边框+右侧✓+加粗文字；数据层选中与视觉选中一致）→ POST quiz/submit 交卷 → 查看 score/passed/attempt_no → 错题重练

• 字段：question_id/options/key/my_answer/correct_answer/is_correct/explanation/anchor

• 异常：未挂随堂检查 ⇒ 空态提示，不硬造；不通过可重考（attempt_no 递增）；选择题若未显示选中态，属 UI 回归需立卡

• 操作人：培训管理员/学员

• 动作：/sales-training/assessments 建卷（CRUD、preview-draw、auto-build）→ 学员 GET /learn/assessments/{aid}/questions → POST /learn/assessments/{aid}/submit → GET /learn/assessments/{aid}/result

• 字段：title/question_ids/status/score/passed/attempt_no

• 异常：题目覆盖不足 ⇒ 用 question-coverage 检查补题；通过线按既有 pass_score 判定，不擅自改

• 操作人：学员/店长

• 动作：GET /learn/my-wrong-questions → 按 my-weakness 选弱项 → POST /learn/wrong-practice → 查能力雷达与弱项变化

• 字段：learner_id/question_id/last_attempt/wrong_count/kind

• 异常：无错题 ⇒ 空态正常；弱项样本 <5 不出图（如实标注）；重练不新造题库

• 操作人：老板/区域经理/培训管理员

• 动作：进度总览（admin/progress-overview）→ 趋势（admin/dashboard/trends）→ 题目正确率（admin/question-stats）→ 学员雷达/弱项 → boss 驾驶舱学习块

• 字段：completed/pct/pass_rate/avg_score/weak_dim

• 异常：sales_metrics_daily 已 DROP（迁移 949，表不存在且零读写），不得再造第二套口径；_learning_block 在 SQLite 测试库降级为 0，不影响 prod 实时看板

• 操作人：系统管理员/区域管理员/店长/导购

• 动作：员工管理（/members）→ 指派角色与 org 归属 → 检查宫格与数据域

• 字段：org_rank（gm/region_mgr/store_mgr/staff）、store_id、region_id、dept_id；perm_user_roles 与 perm_role_perms 键

• 异常：region_mgr 必须同时有 region_id（整数 FK，dept 表）与所需权限键，否则会出现「有 region 标签但无模块」；无归属 staff 数据域如实 0，不越权

• 操作人：系统管理员

• 动作：定期盘点公共桶与写入口径（default 公共桶 vs tenant_id IS NULL AND is_public=true 正典公共课）；核验 tenant_id 写入走 tenant_scope 闸

• 字段：tenant_id/is_public/default/0

• 异常：default 是公共桶约定（共享可见性）而非脏值；0 是全局模板哨兵，不是脏数据；存量 ''/'default' 已于 20261017 迁移 950 归一为 NULL+公共；平台级建课写面仍落 'default' 桶（有意设计，勿误清）

• 已下线：证书链路（迁移 945）与 sales_metrics_daily（迁移 949）；series_cert/认证卷按裁决保留，不在本卡扩面

• 在途：MOMENTS-EDITCOPY（朋友圈编辑+PC 复制/历史）在途，与本学堂无直接耦合

• 期 B：自动复盘/选题加权/默认注入，待连续 2 周真实使用记录

• 挂账：TASKMODEL-CONVERGE（员工任务模型收敛）触发条件未到，不动

• 已下线：证书链路（迁移 945）、sales_metrics_daily（迁移 949）

• 保留：series_cert / 认证卷（测评面证书概念，与本卡下线的独立证书链路不是一回事）

四级定位：L1 商品资产生命周期（四段，是什么）→ L2 流程域（五域，分几路）→ L3 子流程（八张，怎么流转）→ L4 操作指南（10 个 SOP，每步五要素：操作人/操作动作/系统端点/字段与取值/异常分支与重试）

全局红线：台账真理源在 fip_v2 库（geo 后端只做白名单转发桥，不当真理源）；geo 生产永不 next build；FIP 采集数据不进商品台账（只进素材库/趋势画像）

页面速查：PC /knowledge/real-launches（商品图片识别+商品台账+Excel 导入）｜ /launch-rhythm（上新节拍看板）｜ /media（图片生成文章）｜ 小程序「商品台账」与「拍照识别」

①收集 → ②资产化 → ③消费 → ④维护
  │          │           │           │
 图像/表单/  台账+媒体库+  上新看板/  唯一约束/
 拍照/Excel  标签/分组     种草/选品/  幂等/删除/
           品牌FAB      培训/活动AI   镜像/桥

• 台账主表在 fip_v2 库（famos_real_launches），geo 只做白名单桥转发；素材库（material_groups/material_images/lead_images）在 geo_platform 库。

• 与营销主链的交接点只有两个：选品（campaign brief goods_item_id）与素材（图片库→海报/图生文）。

• FIP 采集归口：趋势情报走 trend_profiles，图片公共池走 lead_images（租户 0），均不进商品台账。

┌─ 支撑层：商品 FAB/品牌画像 RAG/品牌图片库/租户组织 ─┐
 ① 收集（PC 批量图片 / mini 手工表单 / mini 拍照 / Excel 导入）
 ② 资产化（VLM 12 维草稿→人工确认→famos_real_launches+material_images 打标分组）
 ③ 消费（上新节拍/种草文/活动选品/销冠培训/活动 AI brief）
 ④ 维护（唯一约束 uq_frl_tenant_spu_color + 幂等查重/删除/桥/镜像）

多选图 → 文件名解析 SPU+中文颜色 → 12 维度 VLM 提取 → 黄标低置信 → 人工确认 → 桥 real-launches/create → famos_real_launches（confirmed）。重复款号+颜色按唯一键拒绝（0104 uq_frl_tenant_spu_color）。

手工表单 POST /mini/launch → confirmed 直登（按款名幂等查重）→ 台账。若桥失败，降级为可读不可写提示，不静默丢数据。

拍照上传 → POST /mini/photo-recognize → VLM 12 维草稿（不落库）→ 人工确认后才入台账。草稿失败可重拍，不自动入库。

GET /real-launches/import-xlsx/template 下载模板 → 填列（款号/颜色/日期必填，价格/FAB 选填）→ POST /real-launches/import-xlsx 解析预览（三桶：可入库/校验失败/文件内重复/台账已存在）→ POST .../confirm 直 confirmed（不过 VLM）→ 重复款号+颜色跳过并列失败报告。示例行先移除，只留目标行。

PC/mini 上传（origin=upload）+ 获客图库参考式导入（≤9 张）+ FIP 公共池同步（tenant0→material_images，origin=fip_ref/upload 分流）→ 两级分组（池/文件夹，门店维度）→ VLM analyze 整图+每套穿搭明细（analyses 73 / looks 87）→ generate-article 4 模板 → 文章入草稿池。提交后四态进度反馈（20261017 已上 prod）：GET /media/material-images/generate-article/{task_id} 归一 queued/running/success/failure（成功附 content_id，失败附脱敏摘要无 traceback；归属不可证统一 404 防跨租户探测）；前端 3s 轮询四态卡：排队中/执行中/已完成（给「去审核」入口）/失败（给重试），离开页面即停轮询、无假百分比。

台账行（FAB 由 FIP fab-generate 或人工）→ real-launches/{rid}/generate-content 注入 TextPipeline → GEO 种草文 → 内容草稿池 → 审核/分发。与 A5 图生文是两条并行链，共用草稿池终点。

商品台账「策划活动」浮动按钮 → brief goods_item_id 桥取名/色/款/材质自动拼 product_input → AI 简报（V4 Flash）→ 矩阵生成/审批/申报。桥失败不阻塞主流程，降级为手输描述。

FIP 采集 → trend_profiles（趋势情报）与 lead_images（公共池）→ 镜像 material_images（可选共享池）；不写 famos_real_launches。prod fip_ref=0 属有意下线（停用共享池写面自动双写+删池组级联清镜像），不是误删也不是未跑。

• 操作人：商品/企划

• 动作：PC /knowledge/real-launches「批量导入」→ 多选图 → 文件名解析 SPU+颜色 → VLM 12 维 → 黄标低置信修正 → 确认入库

• 端点：POST /api/v1/knowledge/real-launches/dims-extract（草稿）→ POST /api/v1/famos/real-launches/create（确认）

• 字段：spu_code、sku_color、dims（12 维 jsonb）、dims_confidence、fab、price、launch_date、status、tenant_id/brand_id

• 异常：黄标低置信必须人工修正后再确认；重复 SPU+颜色按 uq_frl_tenant_spu_color 拒绝，已有则走 already 回查，不重复建行

• 操作人：店长/导购

• 动作：mini「登记上货」→ 填款号/颜色/日期/FAB → POST /mini/launch

• 字段：spu_code、sku_color、launch_date、fab、price

• 异常：按款名幂等查重；桥失败提示可读不可写，不自动建重复行

• 操作人：导购

• 动作：拍照上传 → POST /mini/photo-recognize → 查看 12 维草稿 → 确认入台账

• 字段：spu_code、sku_color、dims、dims_confidence

• 异常：草稿不落库，识别失败可重拍；只有人工确认后才写入 famos_real_launches

• 操作人：商品/企划

• 动作：下载模板（GET .../template）→ 填列 → 上传（POST /real-launches/import-xlsx）→ 预览三桶结果 → 移除示例行 → POST .../confirm 直 confirmed

• 字段：spu_code（必填）、sku_color（必填）、launch_date（必填）、price（选填）、fab（选填）

• 异常：解析 3 行示例时先移除示例行；重复款号+颜色跳过并列失败报告（ok/skipped/failed 逐条）；纯文字行可直 confirmed，不过 VLM

• 操作人：商品管理员

• 动作：POST /famos/real-launches/ledger-update 改价格/FAB/维度；POST /famos/real-launches/ledger-delete 删除

• 字段：spu_code、sku_color、fab、price、status、consumed_count

• 异常：唯一约束 uq_frl_tenant_spu_color(tenant,spu,color) 已上 prod（fip 迁移 0104）——重复写入被拒（ON CONFLICT/already 回查）；删除为硬删除（已沉淀话术/测评题为独立副本不受影响）

• 操作人：内容运营/门店

• 动作：PC/mini 上传（origin=upload）+ 获客图库参考式导入（≤9 张）→ 两级分组（池/文件夹，门店维度）→ VLM analyze 打标 → 选 4 模板生成文章

• 字段：origin（upload/fip_ref）、source_title/url、tags、handle、brand_profile_id、store_id

• 异常：prod fip_ref=0 是有意下线，不追求恢复；上传失败单件降级；VLM 分析失败仍可人工打标

• 操作人：内容运营

• 动作：台账行 → real-launches/{rid}/generate-content → TextPipeline 生成 GEO 种草文 → 草稿池 → 审核/分发

• 字段：fab（FIP fab-generate 或人工）+ brand_profile_id + consumed_count

• 异常：FAB 缺失先补 FAB；与图生文共用草稿池终点但属两条并行链

• 操作人：企划

• 动作：台账「策划活动」→ brief goods_item_id 桥取名/色/款/材质自动拼 product_input → AI 简报 → 矩阵 → 申报

• 字段：goods_item_id（台账主键）、product_input、campaign_type、start_end

• 异常：桥失败降级为手输商品描述，不阻塞主流程；价格/规则仍由人工白名单填写

• 操作人：商品企划/老板

• 动作：/launch-rhythm 看上市节奏折线（launch-trend）与 L3 品类×风格结构（structure-l3）→ 只读分析，不写 report_open 事件

• 字段：launch_date、spu_code、style、category、wave

• 异常：报告端点已改走零副作用 launch-trend，避免 report_open 副作用事件堆积；数据缺失只显示空态不硬造；品牌号由 /famos/marketing/brand-map 单源解析（20261017 LAUNCH-RHYTHM-BRANDMAP 已上 prod，不再硬编码 BRAND_ID=1）；未映射 ⇒ 黄条提示+暂停全部取数+可重试，不回退任何固定品牌

• 操作人：系统管理员/数据管理员

• 动作：核对 FIP 采集归口——trend_profiles 进趋势情报，lead_images 进公共池，不进 famos_real_launches

• 字段：source（fip/upload）、fip_image_id（唯一约束）、tenant_id=0（公共池）

• 异常：prod fip_ref=0 属 20261004 有意下线（停用共享池写面自动双写+删池组级联清镜像）；如需恢复镜像形态须业主裁决，不擅自回滚

• 在途：MOMENTS-EDITCOPY（朋友圈编辑+PC 复制/历史）与商品无直接耦合

• 期 B：自动复盘/选题加权/默认注入，待连续 2 周真实使用记录

• 挂账：TASKMODEL-CONVERGE（员工任务模型收敛）触发条件未到

• 有意下线：prod fip_ref=0（共享池双写停用+池组级联清镜像），不属缺陷

四级定位：L1 品牌基因生命周期（四段，是什么）→ L2 流程域（五域，分几路）→ L3 子流程（七张，怎么流转）→ L4 操作指南（10 个 SOP，每步五要素：操作人/操作动作/系统端点/字段与取值/异常分支与重试）

全局红线：品牌基因单一事实源（brand_profiles + RAG knowledge_chunks）；账号授权写路径依赖桌面客户端（geoDesktop 桥），纯 Web 租户无法完成授权

页面速查：PC /knowledge（品牌资料库三 Tab：品牌/趋势/风格）｜ /knowledge/brand-profiles/[id]（画像详情 10 组分区）｜ /brand-center（四域只读总览）｜ /brand-center/accounts（账号授权）｜ /brand-center/site-settings（官网设置）

①录入 → ②向量化 → ③消费 → ④配置与授权
  │            │             │            │
 画像/RAG   RAG 注入内容生成   官网/账号/门店配置

• 主链：手工表单/AI 生成/复制参考品牌 → brand_profiles（10 组画像）→ embed → knowledge_chunks（RAG）→ 被 content-studio 写作、img2art、种草文等生成链消费。

• 两附属叶：账号授权（媒体账号+AI 引擎 key）与官网设置（站点名/副标题/Logo/首页文章数/模板三选一+SEO 覆盖+预览）。

• 与营销主链的交接点：品牌 RAG 单源注入（build_brand_context），GEO 管道、video_script_service、lead 管线全复用，不另起一套品牌上下文。

┌─ 支撑层：品牌 FAB/商品台账/组织与角色 ─┐
 ① 录入（手工表单 / AI 生成 / 复制参考品牌）
 ② 向量化（brand_profiles → embed → knowledge_chunks）
 ③ 消费（content-studio 写作 / img2art / 种草文 / 活动 AI brief / GEO 文章）
 ④ 配置与授权（账号授权 / 官网设置 / 门店登记 / 四域总览）

手工表单 / AI 生成 / 复制参考品牌（seed 5 枚）→ brand_profiles（10 组画像分区）→ 定位档 tier 预览/确认 → 完成度检查 → embed → RAG 向量库。复制为我的品牌时保留分区结构，不复制品牌 ID。

brand_profiles → embed → knowledge_chunks → build_brand_context 单源注入 → GEO 管道（TextPipeline）、video_script_service、lead 管线、img2art、种草文。降级：画像缺失时走 RAG 三级回落（纯 LLM 不阻塞生成）。

桌面客户端 geoDesktop 桥抓 cookie → platform_accounts（media 24 + llm 12）→ 全自动/半自动分级 → cookie 过期预警（expired 11）。写路径不在 Web 后端，纯 Web 租户无法完成授权。

站点名称/副标题/Logo/首页文章数 → 模板三选一（品牌故事/产品展示/穿搭灵感）→ SEO 覆盖 → 预览 → site_settings 存租户行 → 官网模板渲染（GEO 收录）。修改审核政策 article-review-policy 与积分配置 points-config 也在此前缀下。

品牌详情页门店登记 → brand_stores（6 行）→ 品牌与门店关联可查。原菜单 /stores 已 redirect → /knowledge，登记入口保留在品牌详情页，不再单列菜单叶。

trend_profiles（474，5 类卡片）与 style_profiles（112）→ 趋势情报与风格画像展示 → 「转为选题」人工确认入池（titles）。趋势情报与品牌基因共用知识库，但用途分域：趋势用于企划，画像用于生成品牌基因。

/brand-center 聚合「品牌设置·货·场·人」四域只读总览（原首页搬家，纯客户端聚合跳转页）：品牌画像 / 商品台账（brand-map 单源解析，不再硬编码 brand_id=1）/ 门店与组织 / 账号与官网设置。

• 操作人：品牌运营/企划

• 动作：手工表单 / AI 生成 / 复制参考品牌（seed id35-39）→ 填 10 组画像分区 → tier 预览/确认 → 完成度检查 → 保存

• 字段：name、tier、sections（10 组）、is_public、source_id、tenant_id

• 异常：字段缺失 ⇒ 完成度提示，不强行补齐；复制为我的品牌不复制源 ID 与权限

• 操作人：品牌运营

• 动作：画像详情 → tier 预览（tier-preview）→ 修改 → tier-confirm 确认

• 字段：tier、tier_preview、confirmed_at

• 异常：预览不通过可回退编辑；定位档只在确认后生效，不把预览当正式结果

• 操作人：品牌运营

• 动作：POST /brand-profiles/ai-generate 生成画像草稿 → 人工逐区编辑 → completion 完成度检查 → embed

• 字段：sections、completion、ai_model

• 异常：生成失败可回退手工表单；完成度不足先补关键分区，不盲目向量化

• 操作人：内容运营/数据管理员

• 动作：POST /rag/ingest 或 ingest-source → embed → POST /rag/search 检索 → reindex 重建索引

• 字段：brand_profile_id、chunks、embedding、source

• 异常：RAG 缺失走三级回落（纯 LLM 不阻塞生成）；向量库重建失败先查 embed 任务状态，不重复写库

• 操作人：运营 + 桌面客户端用户

• 动作：桌面客户端 geoDesktop 桥执行授权 → cookie 抓取 → platform_accounts 写入 → 全自动/半自动分级 → cookie 过期预警

• 字段：platform、account_kind=media、auth_status、cookie_blob、last_auth_check_at、probe_dead_streak

• 异常：写路径依赖桌面客户端，纯 Web 租户无法完成授权；cookie 过期先续期再发布，不静默降级为未授权发布

• 操作人：系统管理员

• 动作：/brand-center/accounts AI 引擎 Tab → 配置 8 家引擎 key（media/llm 两类分开）→ 检查 authed/expired 状态

• 字段：account_kind=llm、platform、auth_status、api_key（密文）

• 异常：key 失效只标 expired 不静默放行；不得把引擎 key 写进文档或提交到 git

• 操作人：品牌运营

• 动作：站点名称/副标题/Logo/首页文章数 → 模板三选一（品牌故事/产品展示/穿搭灵感）→ SEO 覆盖 → 预览 → 保存 site_settings

• 字段：site_name、subtitle、logo_url、home_article_count、template、seo_overrides

• 异常：模板不兼容则回退默认模板；article-review-policy 与 points-config 同前缀维护，勿混写

• 操作人：品牌运营/门店管理员

• 动作：品牌详情页门店登记 → brand_stores 写入 → /brand-center 四域只读总览（品牌设置·货·场·人）

• 字段：store_id、brand_id、region_id、org_rank

• 异常：登记入口在品牌详情页（原 /stores redirect 已迁）；总览页品牌号由 brand-map 单源解析，不再硬编码 brand_id=1

• 操作人：企划

• 动作：/knowledge 趋势 Tab → 浏览 5 类趋势卡片（trend_profiles）→ 需要时「转为选题」→ 人工确认入 titles 池

• 字段：trend_category、trend_score、trend_direction、source_id

• 异常：趋势缺失走 FIP 同步 fip-knowledge/sync / sync-news；转为选题必须人工确认，不做自动定时转

• 操作人：系统管理员

• 动作：knowledge_brands 遗留空表与死代码面定期甄别（prod 0 行）→ 实际 CRUD 统一走 brand_profiles；platform_accounts 的 authed/expired 与 cookie 健康巡检

• 字段：knowledge_brands（0 行死代码面）、brand_profiles（13 行活面）

• 异常：knowledge_brands 是死代码面，不要误以为系统没建品牌库；如需清理须先全仓引用 grep 零命中，勿直接删路由

• 在途：MOMENTS-EDITCOPY（朋友圈编辑+PC 复制/历史）与品牌无直接耦合

• 期 B：自动复盘/选题加权/默认注入，待连续 2 周真实使用记录

• 挂账：TASKMODEL-CONVERGE（员工任务模型收敛）触发条件未到

• 死代码面：knowledge_brands 全空（prod 0 行）——实际品牌 CRUD 走 brand_profiles，勿误判为没建库

四级定位：L1 租户与权限生命周期（四段，是什么）→ L2 流程域（五域，分几路）→ L3 子流程（七张，怎么流转）→ L4 操作指南（10 个 SOP，每步五要素：操作人/操作动作/系统端点/字段与取值/异常分支与重试）

全局红线：权限模型 = 菜单键（MENU_TREE）+ 动作键（ACTIONS）+ 四级组织 rank 圈数据域；审批阈值不在本组，在营销「活动申报审批」页阈值抽屉（GM-only 写，提交时快照）

页面速查：PC /members（团队与权限 3 Tab）｜ /billing（费用与设置 9 Tab）｜ /writing-strategy（写作规则与策略 4 Tab）｜ /faqs（问答库 2 Tab）｜ 小程序设置面（阈值只读 + GM 写）

①建租户 → ②授权 → ③圈域 → ④配置与审批阈值
  │            │            │            │
 seed 角色   员工/角色/org   菜单/动作/数据域   费用/写作/问答/阈值

• 主链：建租户 → seed 角色模板（5 岗）→ 发小程序邀请码/添员工（tenant_users）→ 指派角色（菜单键驱动 my-menu→Sidebar + require_perm 门控）+ org 归属（rank/store/region/dept 圈数据域）→ 高敏动作走 action 键 → 租户级配置（积分/审核政策/Banner/经营知识库）→ 审批阈值提交时快照。

• 权限模型三件套：菜单键（MENU_TREE 11 组键 + 叶键）+ 动作键（11 个 action: 高敏键）+ 组织域（perm_user_org：gm/region_mgr/store_mgr/staff + store/region/dept）。

• 审批阈值归口纠偏：不在系统设置组，在营销企划「活动申报审批」页的 ThresholdDrawer（5 键，GM-only 写，提交时快照路由，在途单不变）。

┌─ 支撑层：品牌 FAB/商品台账/租户组织 ─┐
 ① 建租户（seed 角色模板 + 租户信息）
 ② 授权（员工/角色/菜单键/动作键）
 ③ 圈域（org_rank/store/region/dept → 数据域谓词）
 ④ 配置与审批阈值（费用/写作/问答/阈值快照）

建租户 → seed 内置 5 岗模板（店长/区域经理/导购/总经理=全量键快照/内容运营）→ tenant_users 添员工 → 发小程序邀请码 → 员工首次登录。Boss 特判（is_boss）不走角色键快照。

员工管理（单表编辑/重置密码/发邀请码）→ 指派角色（perm_user_roles）与权限键（perm_role_perms）→ 菜单键驱动 my-menu → Sidebar 渲染 + require_perm 门控 → 高敏动作走 action: 键。多数用户权限也可来自 boss 特判或 org 职级（显式角色绑定仅 7 行，使用率低）。

perm_user_org（org_rank/store/region/dept）→ scope_learner_condition 按 rank/dept 子树生成 SQL 谓词 → 圈定学堂学员数据与部分业务数据。门店/区域组织树 = dept（node_type store/region）∪ perm_stores。

MENU_TREE 11 组键 + 叶键 → RELOCATED_LEAVES/EMBEDDED_LEAVES 两个豁免集维护「键命名空间 ≠ 视觉挂载组」漂移（例如 question-bank/keywords 视觉已迁获客工场，键族仍属 menu:system）。权限键命名空间与页面视觉归属长期不完全一致，由豁免集兜底。

营销「活动申报审批」页 ThresholdDrawer → GM-only 写 5 键（区域 %/预算拆两键等）→ 提交时快照路由（在途单不变）。prod 无自定义行（is_default=true 全员默认阈值）。

/billing 9 Tab 承载租户级配置：账单明细/订阅套餐/租户信息/通知设置/账号安全/操作日志/积分设置/工作台形象区/经营知识库。site_settings 16 租户行存积分/审核政策/Banner/经营知识库。

/writing-strategy 4 Tab（GEO 生成策略/内容规范/涨粉生成策略/账号写作策略）与 /faqs 2 Tab（FAQ + 选题问题库）分别承担生成规则与客户应答模板。问答库 FAQ 与客户常问统一回复模板一致，不与学堂课件库混淆。

• 操作人：系统管理员/租户管理员

• 动作：建租户 → seed 角色模板 → 员工管理单表编辑/重置密码/发邀请码 → 员工首次登录

• 字段：tenant_id、email、phone、role、status、password_hash（密文）

• 异常：员工首次未设密码 ⇒ 按「首次使用请找管理员在员工管理设置密码」处理；Boss 特判不走角色键快照

• 操作人：系统管理员/租户管理员

• 动作：角色管理（perm_roles CRUD + 键勾选）→ 指派 perm_user_roles 与 perm_role_perms → 菜单键驱动 my-menu 渲染与 require_perm 门控

• 字段：role_id、perm_key（menu:/action:）、user_id

• 异常：显式角色绑定仅 7 行（多数权限来自 boss 特判/org 职级）；若需键级精细控制，先补角色键再验证 my-menu，不靠 org 职级猜权限

• 操作人：系统管理员/区域管理员

• 动作：门店管理（perm_stores CRUD）→ 配 region/dept → 未归口学员提示 → 组织树（dept node_type store/region）与 perm_stores 对齐

• 字段：store_id、region_id、dept_id、org_rank

• 异常：region_id 必须为整数 FK（dept 表 id），仅写区域文本标签会导致「有 region 标签但无模块」；未归口学员按提示补归属；数据总览辖区档 fail-closed：mini /home/summary 与 /effect 中无法按辖区圈定的块（待拍板队列/直放计数/桥聚合）一律置空+note，不回退全租户值；staff 与无归属 403（20261017 MINI-DATAOVERVIEW-SCOPE 已上 prod）

• 操作人：系统管理员/前端管理员

• 动作：维护 RELOCATED_LEAVES/EMBEDDED_LEAVES 豁免集 → 处理「键命名空间 ≠ 视觉挂载组」的漂移（如 question-bank/keywords 视觉迁获客工场）

• 字段：menu: 组键/叶键、豁免集条目

• 异常：键族与页面归属不一致时先查豁免集，不盲目新增键；视觉迁移动菜单时同步更新豁免集

• 操作人：系统管理员/业务审批人

• 动作：高敏动作（审批/发布/删除/派发）→ 校验 action: 键（11 个）→ 记录审计

• 字段：action:dispatch、action:settings、action:learner.delete、action:learner.invite、action:review.verdict 等

• 异常：动作键与菜单键不同源，展开出的 menu: 叶键进不了动作判定（GROUPKEY-EXPAND 仅读侧展开）；权限不足时回 403，不静默放行

• 操作人：GM/总经理

• 动作：营销「活动申报审批」页 ThresholdDrawer → GM-only 写 5 键（区域 %/预算拆两键等）→ 提交时快照路由（在途单不变）

• 字段：site_settings 单行/租户、is_default（prod 全默认）

• 异常：审批阈值不在系统设置组，勿在系统设置页找；prod 无自定义行（is_default=true 全员默认）；改阈值只影响新提交单，不改在途单

• 操作人：租户管理员/财务/系统管理员

• 动作：账单明细 → 订阅套餐 → 租户信息 → 通知设置 → 账号安全 → 操作日志 → 积分设置 → 工作台形象区 → 经营知识库

• 字段：tenant_subscriptions（21 行）、site_settings（16 租户行）、积分/审核政策/Banner/经营知识库

• 异常：租户信息或订阅缺失时先补租户配置；积分/审核政策/Banner 分别属不同配置键，不混写

• 操作人：内容运营/系统管理员

• 动作：/writing-strategy 4 Tab → GEO 生成策略 → 内容规范 → 涨粉生成策略 → 账号写作策略（原账号写作策略 Tab 化收编）

• 字段：writing_rules（84 行，每租户 6 条）、lead_strategy_config（禁转化词表）

• 异常：涨粉策略与 GEO 策略分域；禁转化词命中即 502 不交付不扣费；勿将写作策略误当内容素材库

• 操作人：内容运营/客服/企划

• 动作：/faqs 2 Tab → FAQ（客户常问统一回复模板）→ 选题问题库（选题候选）→ 审核后复用

• 字段：question、answer、category、sort_order

• 异常：问答库 FAQ 与活动话术/学堂课件库不同源；活动价格与规则仍由人审，AI 只生成模板草案

• 操作人：系统管理员

• 动作：定期盘点 perm_user_roles 与 perm_user_org 权限分布、租户灰度（marketing_enabled）、tenant_subscriptions 与 site_settings 配置一致性

• 字段：perm_roles（54）、perm_role_perms（1534）、perm_user_roles（7）、perm_user_org（20）、perm_stores（4）、dept（7）、tenants（13）、tenant_users（23）

• 异常：显式角色绑定仅 7 行是低使用率而非权限缺失（boss 特判/org 职级也可授权）；site_settings 无任何 threshold/approval 键 ⇒ 全员默认阈值

• 在途：MOMENTS-EDITCOPY（朋友圈编辑+PC 复制/历史）与设置无直接耦合

• 期 B：自动复盘/选题加权/默认注入，待连续 2 周真实使用记录

• 挂账：TASKMODEL-CONVERGE（员工任务模型收敛）触发条件未到

• 权限例外：RELOCATED_LEAVES/EMBEDDED_LEAVES 豁免集用于维护「键命名空间 ≠ 视觉挂载组」漂移，勿当成普通键增删项

• 按你的角色选章节：A 营销（总部企划/内容运营）｜B 商品素材（商品/内容运营）｜C 学堂（培训管理员+学员）｜D 品牌与设置（品牌运营/系统管理员）｜E 员工日常（导购/店长）｜F 数据复盘（老板/区域/店长）。

• 每一步都是「入口 → 操作 → 看图 → 注意点」。截图来源：20261018 prod 真实 PC 页面（uid1 管理员视角，只读导航，路径 guide-shots/）+ mini 真机/IDE 实拍（gm/region_mgr/store_mgr/staff 四角色）。

• 先登录：PC 打开 https://geo.acbri.xin/next/login；小程序从「衣智汇AI」进入。

• 标记约定：🔴 为易错点，🟢 为 20261017-18 新上线功能。

1. 进活动管理：PC 左侧「活动管理」，也可从小程序活动向导进。

2. 选入口：模板（5 枚）/商品台账「策划活动」（自动带商品信息）/活动申报详情「AI生成内容」/自定义空白。

3. 生成简报：点「生成简报」→ 人工逐条修改（AI 只出草稿）→ 点「确认」。

• 🔴 草稿态直接点「一键生成」会 422——先确认再生成是设计保护，不是故障。

• 可选：开 inject_history=true 注入同类型最近复盘基线（不含金额，无则静默）。

4. 生成内容矩阵 9 条：点「一键生成」→ 脚本×3/朋友圈×3/话术/海报/图文，逐条审（过/驳/重生成）。

• 🟢 脚本走 VideoScriptService、图文走 GenerationPipeline（RAG+三道质检），契约不变、零双倍扣费。

• 海报：先选背景图再「生成海报」（未选会 409 引导）；渲染后 1080×1440 PNG 自动落素材库。

5. 补 FAQ：一场一套，可 PC 编辑。

6. 第四步申报：价格/规则人工白名单填写（AI 不生成价格）→ 提交。重复申报会 409，去详情页看原单。

7. 去审批中心通过：活动内容各条终态 + 活动申报审批（阈值 5 键快照，GM-only 写，在途单不随改）。

• 通过后会自动：内容批量释放 + 自动灌分享任务（员工今日转发能看到）+ 自动建公域分发任务。

8. 员工执行：小程序「今日转发」复制卡片/朋友圈预览发出；顾客扫码得券后上传凭证，人工核销。

9. 看效果：活动详情「效果」三源聚合（分发/传播/门店日表）→「生成复盘」→ 可「转为选题」回流企划。

• 🟢 首页收录率卡已修（GET /api/v1/marketing/retrospect 不再 404）。

• 公域=发到平台账号：approve 自动/celery 定时/手动三入口 → agent 认领执行（full 兜底机/semi 租户桌面）→ 成功 published+publish_url；失败分三类处置（账号风控换号勿频试/平台错误修内容 retry/网络直接 retry）。

• 私域=员工/顾客转发：活动卡（[campaign: 前缀暖橙底）复制/预览 → 顾客 H5 得券 → 凭证上传 → 核销。

• 🟢 publish 队列已独立单元 geo-celery-publish，不再被 monitor 长任务挤占（受控探针：接受→开始 1ms）。

1. PC 批量图片：多选图 → 文件名自动解析款号+颜色 → VLM 12 维 → 黄标低置信先修再确认。

2. Excel 导入：同页「Excel 导入」Tab → 下载模板填列 → 上传预览三桶（可入/校验失败/重复）→ 移除示例行 → 确认（直 confirmed，不过 VLM）。重复款号+颜色会跳过并列失败报告。

3. mini 手工登记/拍照识别：小程序「登记上货」confirmed 直登（幂等查重）；拍照识别出草稿，人工确认才入库。

• 🔴 唯一约束 uq_frl_tenant_spu_color：重复款号+颜色会被拒/跳过，别硬重录。

1. PC /media 选图（上传/参考导入/FIP 公共池分流）→ 选 4 模板之一 → 点生成。

2. 看四态进度卡（🟢 新功能）：排队中/执行中/已完成/失败，3s 轮询，离开页面自动停；不要看到「排队」就重复点生成。

3. 成功点「去审核」→ 审批中心处理；失败可重试（错误摘要脱敏无 traceback）。

4. 台账行也可直接「生成种草文」（FAB 由 FIP 或人工）。

• 看上市节奏折线与 L3 品类×风格结构，只读分析不写 report_open。

• 品牌号由 brand-map 单源解析（不再硬编码 1）；未映射会黄条提示+暂停取数+可重试，不会回退到固定品牌。

• 台账行点「策划活动」会自动把商品名/色/款/材质拼进 AI 简报。

1. PC /sales-training/courses →「学习任务」Tab → 新建任务：选 course/series、required/elective_count、due_at、scope_type（role/learner/store/dept）→ publish。

2. 🔴 boss_tasks 的 type=learn 已被 400 拦截，不要走那条老路。

3. 学员端 my-courses 会叠加可见派发课；范围外私有课排除、未派发私有课原样、逾期标而不隐。

1. 学员从 mini edu learn Tab 或 PC 学员端进入 → 打开课程 → PDF 页图/视频/文本三形态课件 → 断点续学。

2. 课件测验/结课考：点选项（前置圆圈选中填暖橙+白✓，整行橙底+右侧✓）→ 交卷 → 看 score/passed/attempt_no。

• 🟢 v7.17.0 起选中态已修复并升级（数据层选中与视觉一致）。

3. 错题本→ 弱项维度→ 针对重练 → 能力雷达看变化。

• 实战训练（PC /sales-training/training 或 mini practice）多轮对练 → 五维评分与回放。

• 「活动话术」Tab 借用 campaign FAQ，不落学堂表；价格/活动规则仍由人审。

1. /knowledge 品牌 Tab → 手工/AI 生成/复制参考品牌（seed 5 枚）→ 填 10 组画像分区 → tier 预览确认 → 完成度检查 → embed。

2. RAG 缺失走三级回落（纯 LLM 不阻塞生成），但先补关键分区再向量化。

3. 趋势 Tab 的「转为选题」要人工确认，不做自动定时转。

1. /brand-center/accounts：媒体账号与 AI 引擎 key 分开看 authed/expired；cookie 过期先续期再发布。

2. 写路径依赖桌面客户端 geoDesktop 桥，纯 Web 租户无法完成授权（登记项）。

3. /brand-center/site-settings：站点名/副标题/Logo/首页文章数 + 模板三选一 + SEO 覆盖 + 预览。

4. 四域总览（品牌设置·货·场·人）：品牌号由 brand-map 单源解析，不再硬编码 1。

1. /members：员工管理（单表编辑/重置密码/发邀请码）+ 门店管理（region/dept 对齐）+ 角色管理（perm_roles 键勾选）。

• 🔴 region_id 必须是整数 FK（dept 表 id），只写区域文本会「有 region 标签但无模块」。

2. 高敏动作走 action: 键（审批/发布/删除/派发），权限不足 403 不静默放行。

3. /billing 9 Tab：账单/订阅/租户信息/通知/安全/日志/积分/形象区/经营知识库；审批阈值在营销侧 ThresholdDrawer（不在本组）。

• 打开「衣智汇AI」小程序 → 先过登录/绑定（已有账号直接进）。

• 首页是工作台：今日任务、今日转发、数据总览、功能宫格都在这里；角色不同看到的范围不同（gm 全量、region 本区域、store 本店、staff 403）。

1. 工作台点「今日转发」或 pages/share-tasks/index。

2. 找任务卡（活动卡是 [campaign: 前缀暖橙底）→ 复制文案 或 朋友圈预览 看效果 → 发到微信/朋友圈。

3. 顾客扫码得券后，你把凭证截图回传（POST /mini/receipts/upload，员工可传，勿挂 boss 闸）。

4. 等人工核销；核销后员工/顾客积分双轨到账。

1. 工作台宫格或 pages/goods-ledger/index查商品台账。

2. 新增两条路：

• 登记上货：手工填款号/颜色/日期/FAB → confirmed 直登（幂等查重）。

• 拍照识别：pages/photo-recognize/index→ 出 12 维草稿（不自动入库）→ 人工确认才入台账。

3. 台账行点「策划活动」→ 自动把商品名/色/款/材质拼进 AI 简报。

1. 进 pages/image-to-moments/index或 PC /media。

2. 选 1-9 图（先上传转存）→ 选模板/风格 → 点生成。

3. 看四态进度卡：排队中/执行中/已完成/失败（3s 轮询，离开页面自动停）——不要看到「排队」就重复点生成。

4. 成功点「去审核」→ 审批中心处理；失败可重试（错误摘要脱敏无 traceback）。

1. pages/edu/index（六 Tab：learn/exam/practice/data/rank/faq）→ 打开派发课 → PDF 页图/视频/文本三形态课件 → 断点续学。

2. 课件测验/结课考：点选项（前置圆圈选中填暖橙+白✓，整行橙底+右侧✓）→ 交卷 → 看 score/passed/attempt_no。

• 🟢 v7.17.0 起选中态已修复并升级（数据层选中与视觉一致）。

3. 错题本→ 弱项维度→ 针对重练 → 能力雷达看变化。

4. 实战对练（practice）多轮 → 五维评分与回放；「活动话术」Tab 借用 campaign FAQ，不落学堂表。

• pages/data-overview/index：gm/boss 看全租户；region_mgr 看本区域门店集合；store_mgr 看本店；staff 与无归属 403。

• 辖区/本店档不可圈定块（待拍板队列/直放计数/桥聚合）会置空+note，不是全量放开。

• pages/mine/index：我的积分/台账/邀请码/设置；pages/cust-points/index 查顾客积分。

• pages/assign/index：三步派单（4 类多选/自由文案+org 树勾选+截止截图要求）。

• pages/store-panel/index：店长面板（本店覆盖+审批队列）。

• pages/cockpit/index：老板驾驶舱（hero 六键+四族 sections）。

• 使用说明图：guide-shots/cockpit-usage-hero.png（hero 六键怎么看）｜guide-shots/cockpit-usage-sections.png（四族 sections 怎么用）｜guide-shots/data-overview-usage.png（数据总览怎么读）。

• gm/boss 看全租户；region_mgr 看本区域门店集合；store_mgr 看本店；staff 与无归属 403。

• 辖区/本店档不可圈定块（待拍板队列/直放计数/桥聚合）会置空+note，不是全量放开。

• 活动效果仪表三源聚合（distribution/store_daily/receipts → total_reach），纯读零持久化。

• 手工生成复盘件 → 转选题（titles+pool+feedback 同事务）；期 B 自动触发/加权/默认注入待连续 2 周真实使用记录。

用法：先按主题找问题，每条都给了「为什么会这样 → 怎么办 → 对应手册位置」。标 🔴 的是真缺陷史（已修），标 ⚪ 的是设计如此（不是 bug）。

Q1 员工/店长/区域经理进某些页面为什么是 403？ A：⚪ 设计如此。数据总览按 org_rank 分档：gm/boss 全量、region_mgr 本区域、store_mgr 本店、staff 与无归属 403。先查员工管理里角色与 org 绑定是否完整（rank/store/region/dept 四件）。

Q2 区域经理「有 region 标签但无模块」？ A：🔴 常见配置错。region_id 必须是整数 FK（dept 表 id），只写区域文本标签不算数。去 /members 门店管理把 region 关联到 dept 整数 id。

Q3 店长能看到数据但都是空的/只有部分块？ A：⚪ 辖区/本店档的「不可圈定块」（待拍板队列/直放计数/桥聚合）会置空+note，是 fail-closed 不是全量放开。先查是否绑店（perm_user_org.store_id）。

Q4 为什么我登录后进的是 /admin/dashboard，其他页面点不动？ A：你用的是平台超管 admin@geo.local（只能进 /admin/* 后台）。租户业务页要用租户账号（TENANT_ADMIN 等）登录。

Q5 员工 bind 小程序时提示「请在 Web 端创建」？ A：bind 只认「主表 boss 或 tenant_users owner/admin/member 关联」。先在 PC 员工管理把人加进租户成员，再用小程序绑定。

Q6 改了密码/管理员重置后，为什么所有设备都被踢下线？ A：⚪ 安全设计。token_version 一变旧 token 全失效（吊销后门已堵）。重新登录一次即可，不是 bug。

Q7 为什么我没有「今日转发」/某菜单入口？ A：权限键没配或角色没绑。查 my-modules 返回与角色模板；menu:acquire.overview 等键要同时给入口和读面（曾有「入口可见读面 403」已修）。

Q8 为什么我看不到「数据总览」的数字，但老板能看到？ A：角色范围不同（gm 全量 vs region/store 分档）。不要跨角色比数字，也别把「员工看不到」当 bug 报。

Q9 AI 写的价格/优惠幅度能直接用吗？ A：🔴 绝对不行。价格与规则是人工白名单字段，AI 禁生成；活动规则人审后才可发布。

Q10 草稿态点「一键生成」为什么报 422？ A：⚪ 设计保护。先「确认简报」再生成矩阵，草稿态直接生成会被 422 拦，不是故障。

Q11 这次生成特别慢，是不是又排队了？ A：不一定。先看「接受→开始」队列时延（隔离后应≈毫秒级）。全程慢多半是外部 AI 回退链耗时（qwen VL 404×~30s→glm），不是队列（QWEN-VL-404-FALLBACK 卡在治）。

Q12 为什么生成的内容没有品牌风格？ A：先补品牌画像 10 组分区 + tier 确认。RAG 缺失会走三级回落（纯 LLM 不阻塞），但品牌感会弱。

Q13 为什么这次生成和上次不一样/结果不可复现？ A：AI 生成有随机性。价格、规则、事实数据不要依赖它写死；重要内容要人工编辑确认。

Q14 导入图片后为什么没有自动出文章？ A：图生文是选模板手动触发的，不是导入自动跑。生成后看四态进度卡，成功点「去审核」。

Q15 复制文章为什么有 *#/HTML 标签？ A：用「复制全文转纯文字」按钮（HTML/markdown 双格式剥离），不要直接复制富文本。

Q16 审批通过后为什么没有自动发出去？ A：公域=approve 自动建 DistributionTask，由 agent 认领执行；私域=自动灌 share_task。先查 agent 在线与任务状态（publishing/published/failed）。

Q17 发布任务一直排队，是不是又堵了？ A：publish 已独立单元 geo-celery-publish（并发 1），不再被 monitor 长任务挤占。若仍积压，查到达率（周期任务突发），不是隔离失效。

Q18 发布失败怎么处理？ A：分三类：account_risk 换号+probe 复查（连 2 次判死）；platform_error 看错误码修内容后 retry；network 直接 retry 并查 agent 心跳。

Q19 为什么 xhs/douyin 不能自动发？ A：⚪ 手动发布红线（防限流）。走员工手动任务+截图凭证，不要试图绕过。

Q20 「账号发布」菜单为什么是空的？ A：现状空转（回执端点从未被写过）。已立卡改「手动发布台账」并入内容面（MANUAL-PUBLISH-LEDGER-MENU 在途）。

Q21 提交后一直显示 generating，是不是卡死？ A：别只看 toast。用四态状态端点看真实状态（queued/running/success/failure），成功会给 content_id 和「去审核」入口。

Q22 Excel 导入为什么有行失败？ A：看三桶预览（可入库/校验失败/文件内重复/台账已存在）。重复款号+颜色会跳过并列失败报告；示例行先移除再确认。

Q23 拍照识别后为什么没有自动入台账？ A：⚪ 设计如此。VLM 出的是草稿，不自动入库，人工确认后才写入 famos_real_launches。

Q24 重复商品为什么录不进去？ A：唯一约束 uq_frl_tenant_spu_color 拒绝/跳过（ON CONFLICT/already 回查）。不要硬重录，先查是否已存在。

Q25 FIP 公共池镜像图片为什么是 0？ A：⚪ 有意下线（20261004 停用共享池写面自动双写+删池组级联清镜像），不是误删也不是未跑。要恢复须业主裁决。

Q26 图生文的文章里图片为什么不显示？ A：检查正文 img src 是否相对地址（已修绝对化）与 cover_image 是否配置；「存全部图」现在会收封面+正文图（HTML <img> 与相对 src 都已兼容）。

Q27 上新节拍看板为什么是空的？ A：品牌号由 brand-map 单源解析。未映射会黄条提示+暂停全部取数+可重试，不会回退到固定品牌 1。先补品牌映射。

Q28 点选项为什么没有高亮/像没选中？ A：🔴 旧版 WXML 不支持方法调用导致「数据已选中但视觉失明」。v7.17.0 起前置圆圈选中填暖橙+白✓，整行橙底+右侧✓，数据层与视觉一致。

Q29 交卷后为什么没有成绩？ A：先看是否真点了提交（探针 SUBMIT_CALLS=0 已证）。失败看 result 是否为空与网络；未通过可重考（attempt_no 累加）。

Q30 学员为什么看不到派发的课？ A：检查任务是否 publish、scope 是否圈到人（role/learner/store/dept）。范围外私有课排除，未派发私有课原样，公共课走既有可见性。

Q31 学习进度为什么丢了？ A：断点续学靠 POST /learn/progress 回写。看完课件会自动保存，重进应回到断点；若丢，查进度回写是否 200。

Q32 错题重练为什么还是错？ A：重练是同一题库与答案校验，不另起题库。看 explanation 与 anchor（错因），别只刷次数。

Q33 为什么没有证书入口了？ A：⚪ 证书链路已下线（迁移 945，prod 0 行）。series_cert/认证卷是另一概念，保留不扩面。

Q34 为什么「活动话术」里的 FAQ 不属于学堂资产？ A：它是借用 campaign FAQ（跨模块），不落学堂表。别把它算进课件/题库行数。

Q35 数据总览为什么有的块是空的？ A：⚪ 辖区/本店档 fail-closed：不可圈定块置空+note。gm 全量才看得到全部，别拿辖区空块当 bug。

Q36 活动效果为什么 total_reach 是 0？ A：三源（分发/传播/门店日表）任一为空都会拉低。先查是否有分发、是否有凭证/核销、是否有门店日填报。

Q37 本周收录率为什么是 0？ A：首页 retrospect 已修（不再 404）。inclusion_tasks 是收录任务口径，不是搜索引擎收录，别按搜索引擎收录理解。

Q38 「数据总览」「驾驶舱」「活动效果」数字为什么不一样？ A：三面同源但角色范围不同（gm 全量 vs region/store 分档）。不要跨角色比绝对值，看趋势和结构。

Q39 为什么没有自动复盘/自动转选题？ A：期 A 只做了人工回流（手工生成复盘件→人工转选题）。自动触发/加权/默认注入属期 B，待连续 2 周真实使用记录。

Q40 官网改了为什么不生效？ A：检查 site_settings 是否保存+预览；模板三选一+SEO 覆盖要一致；改的是哪个租户行（16 行按租户分）。

Q41 媒体账号 cookie 老过期怎么办？ A：用桌面客户端 geoDesktop 桥续期；auth_probe 连 2 次判死才翻 expired，单次抖动不误判。过期先续期再发布。

Q42 员工改密码后还是登录不了？ A：先分清账号（test@geo.local 租户 vs admin@geo.local 平台超管），再重登（token 可能已失效）。

Q43 region_id 为什么填不进去/不生效？ A：必须整数 FK（dept 表 id），不是文本标签。去 /members 门店管理配 dept 关联。

Q44 为什么我的小程序还是旧功能？ A：删小程序重扫体验码（当前 v7.17.0），并看 mine 页版本水印。体验版未设新版/手机缓存旧版都常见。

Q45 401 是为什么？ A：令牌无效/过期/类型不对。重登；mini 端点要 type=mini_access，Web access 型必 401；ver 必须与 users.token_version 实值一致。

Q46 403 是为什么？ A：权限不足（org_rank/权限键/org 绑定）。staff 与无归属 403 是设计，先别当 bug 修。

Q47 404 是为什么？ A：路由不存在或任务不存在。未知 task_id 统一 404（防跨租户探测）；检查路径前缀（新 API 前缀 location 要么不带尾 slash 要么两条都写）。

Q48 409 是为什么？ A：重复申报/未选海报背景/重复款号+颜色。分别去详情页看原单/先选背景/跳过重复行。

Q49 422 是为什么？ A：draft 态一键生成（先确认简报）或字段校验失败（缺 title 等）。

Q50 500/白屏/转圈怎么排查？ A：先看 geo-platform 日志与 nginx 301/308（新前缀 location 配置），再看是否半部署（只部署了前端没部署后端），最后看是否新路由未重启（改码必重启且重启晚于提交）。

附：本 FAQ 与手册的对应关系

• 操作步骤：第六部分（A-F 角色指南）与第一至第五部分（五主线 L1-L4）。

• 新功能四态/圆圈/brand-map/publish 隔离：见附录 C 更新记录（20261017-18）。

• 若你的问题不在此列：先按「入口→角色→数据范围→报错码」四步定位，再带 指南 截图与端点状态码问 Kimi/运维。

• 《营销板块-L4流程全集》与《营销板块-全流程手册-L1L4》SOP-01~11 同族，已并入第一部分主体去重；此处仅保留其独有的对照表。

• MECE 文档的分板块细节与附录 A（L3 十张）亦与主体同族，保留其总框架/接口总表/缺口清单/未核实声明，其余去重。

• Codex 四卡（在飞）：WEBHOOK-ARCHIVE（出站租户 webhook 归档下线，prod 双表零行）｜MANUAL-PUBLISH-LEDGER-MENU（「账号发布」改「手动发布台账」并入内容面，键路径不动）｜DISTRIB-POOL-SPLIT-DESIGN（渠道分发按池分服务设计，拍板后拆实施卡）｜QWEN-VL-404-FALLBACK（图生文 qwen VL 404 死跳+慢失败治理，404 应 ≤2s 切链）。

• MOMENTS-EDITCOPY 已闭环：朋友圈轻编辑（编辑存回+历史/复制）已随 v7.17.0 出包，源件「在途」表述已过时。

• mini v7.17.0 已上传（测验选中态修复+圆圈填色）：待 mp 设体验版+真机验收（圆圈选中/多选/切题草稿恢复）。

• 小修候选：test_content_loop 947 链序断言基线红（存量，与本批各卡零交集），建议 0.1 天小卡修期望。

• 期 B / TASKMODEL-CONVERGE / gzh 回填：同各主体「在途与挂账」原口径，不重复展开。

1. 企业学堂选中态升级：课件测验/测评选择题由「暖橙行底+边框+右侧✓」升级为「前置圆圈选中填暖橙+内嵌白✓」并保留原高亮（EDU-QUIZ-SELECTED-FIX 修复 WXML 不支持方法调用导致的选中失明 + 圆圈 UI 方案 A；mini 594327ab，verify 480→485/0）。

2. 图生文四态进度反馈：新增 GET /media/material-images/generate-article/{task_id} 与前端四态追踪卡（排队/执行/成功/失败，3s 轮询，离开即停，成功给「去审核」、失败给重试）；归属不可证统一 404，失败摘要脱敏无 traceback（MEDIA-GENERATE-TASK-STATUS 14f53e04 已上 prod）。

3. 上新节拍/四域总览品牌号单源：BRAND_ID=1 硬编码已清除，改 /famos/marketing/brand-map 单源解析；未映射⇒黄条+暂停取数+可重试，禁止固定品牌回退；「无租户过滤(跨租户全量)」旧文案证伪删除（LAUNCH-RHYTHM-BRANDMAP 781ce1c2 已上 prod）。

4. 发布队列隔离：publish,webhook 由新单元 geo-celery-publish 独立消费（并发 1），旧 worker=audit,monitor,sync；受控探针「接受→开始」由 17 分 14 秒降至 1ms；「worker 只听五队列」旧表述已全部改为四单元分工（CELERY-PUBLISH-ISOLATE 已上 prod）。

5. 数据总览辖区作用域：region/store 由「入口可见读面 403」修成「按 org_rank 分档可见+fail-closed 置空+note」，不可圈定块不回退全租户；staff 与无归属 403（MINI-DATAOVERVIEW-SCOPE fad3dba9 已上 prod）。

6. mini 版本号续正：本合订本基线为 v7.17.0（含选中态修复+圆圈 UI+MOMENTS 轻编辑）；版本号以 walkthrough 全目录最高值为序列，勿用旧 upload.js VERSION 直觉续号。

7. 源件去重：MECE 分板块细节/附录 A、营销 L4 流程全集 SOP-01~11 与主体同族已去重；保留总框架/接口表/缺口清单/对照表。

• 小程序前端页面路径部分取自后端注册表反推（未逐页翻 mini 仓源码）

• FIP 采集轨内部表未深挖（按甄别口径仅查归口）

• material_images prod 无 fip_ref 行的成因（清理 vs 镜像未跑）未追溯日志

• dev 与 prod 部署代码逐文件一致性未 diff

• 本合订本为合并整理版：源件 7 份的主体内容未逐字改写（仅做去重与上述 6 处增量刷新），若与最新代码冲突，以最新实证为准并回写本文。

• 研发/部署/测试的工程纪律不在本手册范畴，见《FAMOS-研发运维流程总纲-v1.0-20261018.md》（六主线工程面）。