# 问题集扩展（Question Expansion）设计

**Date:** 2026-05-12  
**Status:** Draft for Review  
**Author:** assistant  
**Module:** admin-web · server (tenant-api)  
**Target Branch:** `main`

---

## 1. Overview

本设计把原来的“先管理词，再挂问题”的页面心智改成**问题驱动**：

1. 用户进入 **品牌管理**。
2. 先看品牌卡片列表。
3. 选中一个品牌后，默认进入 **问题集** Tab。
4. 问题以全宽表格展示，右侧提供 **「批量扩展问题」** 与 **「新增单条问题」**。
5. 用户新增、批量生成、保存的对象都是“问题”，不是中间层实体。

用户可见的信息架构只保留四个概念：**品牌、问题集、竞品库、问题**。

系统仍会在后台保留自动标签和内部兼容记录，用于下游 GEO 监测、漏斗分析、来源追踪和老表结构兼容。但这些不再成为用户创建问题时必须理解的产品概念。

**用户可见原则**：

- 页面标题是 **品牌管理**，不是独立扩展页。
- 主按钮是 **新增单条问题**，旁边提供 **批量扩展问题** 进入 page 向导。
- 主表列为 **问题集 / 创建时间 / 操作**。
- 不展示列表、卡片或表单字段来要求用户先选择中间层实体。
- `brand_keywords` / `brand_questions.keyword_id` 只作为后端兼容实现细节出现。

> 本文只改设计文档，不包含实施代码。

---

## 2. Current State

现有品牌库模块已经具备：

- `brands` / `brand_keywords` / `brand_questions` / `competitors` 四张表。
- 品牌、问题、竞品的 CRUD。
- 租户配额、Redis 缓存、审计日志。
- 既有 LLM 客户端与 AI 点扣减能力。
- `apps/admin-web/src/views/BrandsView.vue` 作为品牌管理入口。

主要问题：

1. 页面模型过于工程化，用户需要先理解内部层级，再维护问题。
2. 旧 UI 是左侧实体列表 + 右侧问题表的两栏结构，不符合“图二”的品牌卡 + 问题表布局。
3. 批量创建问题能力不足，用户仍需要一条条录入。
4. 问题缺少统一的来源、意图、层级等元数据，下游分析能力受限。
5. 现有表结构里 `brand_questions.keyword_id` 为必填，短期不能直接删除，需要用内部默认桶兼容。

---

## 3. Goals & Non-Goals

### 3.1 Goals

| ID | Goal |
| --- | --- |
| G1 | 把品牌管理页改成问题驱动：品牌卡片 → 问题集 Tab → 全宽问题表 → 单条新增 / 批量扩展 |
| G2 | UI 对齐图二：顶部品牌管理标题、品牌卡片列表、`问题集 / 竞品库` Tab、右侧 `批量扩展问题` 与 `新增单条问题` |
| G3 | 用户新增的是问题；批量生成、AI 扩展、手动批量都只产出问题候选 |
| G4 | 用户可见文案不要求理解 `brand_keywords` / `keyword_id` 等内部实现 |
| G5 | 后端保持低风险兼容：继续写入 `brand_questions`，并用内部默认问题桶满足旧外键 |
| G6 | 问题文本在同一品牌下唯一，DB 层兜底防重复 |
| G7 | 系统自动补充 `layer` / `intent` / `source` 元数据，但主表默认不展示这些高级标签 |
| G8 | 所有写入保留审计日志、配额检查、缓存失效和并发保护 |

### 3.2 Non-Goals

- 不在本次设计中删除 `brand_keywords` 表或 `brand_questions.keyword_id` 外键。
- 不重写下游监测 pipeline。
- 不做语义向量召回；V1 用规则 + LLM 生成问题候选。
- 不引入新的前端状态管理框架。
- 不做实时协作编辑。
- 不做第三方数据源接入。

---

## 4. Approach Comparison

| 维度 | 方案 A：继续暴露旧层级 | 方案 B：立即重构数据库 | 方案 C：问题驱动 UI + 内部兼容桶 |
| --- | --- | --- | --- |
| 用户心智 | 仍复杂 | 最干净 | 干净 |
| 工程风险 | 低 | 高 | 中低 |
| 数据迁移 | 少 | 大 | 少 |
| UI 是否贴图二 | 否 | 是 | 是 |
| 是否影响旧服务 | 否 | 是 | 否 |
| V1 落地速度 | 快但产品不对 | 慢 | 推荐 |

### 4.1 Chosen: 方案 C

选择方案 C：

- 前端彻底按问题驱动改造，用户不再看到旧层级。
- 后端短期继续使用现有表，不做破坏性迁移。
- 写问题时自动确保当前品牌有一个内部默认问题桶。
- 未来若要彻底移除内部层，可单独做数据库迁移。

---

## 5. User-Facing Outcome

完成后，用户路径如下：

1. 左侧导航进入 **品牌管理**。
2. 页面顶部显示标题 **品牌管理**，右上角 **+ 创建新品牌**。
3. 标题下方显示可折叠的 **品牌管理说明**。
4. 下方是品牌卡片列表，每张卡展示品牌名、状态、问题数量、竞品数量等摘要。
5. 用户选中某个品牌后，下方详情区默认停在 **问题集** Tab，旁边是 **竞品库** Tab。
6. **问题集** Tab 右侧固定展示 **批量扩展问题** 与 **新增单条问题**。
7. 表格展示：
   - 问题集
   - 创建时间
   - 操作
8. 点击 **新增单条问题** 后，在当前页弹出轻量表单，只保存一条问题。
9. 点击 **批量扩展问题** 后，进入问题创建 page 向导：
   - 拓词工具生成问题。
   - AI 扩展生成问题。
   - 手动批量粘贴问题。
10. 用户在候选预览中勾选、编辑、删除，确认后保存到当前品牌的问题集。
11. 保存成功后刷新问题表；重复、过短、超配额的问题进入跳过明细。

---

## 6. Requirements

| ID | Requirement |
| --- | --- |
| R1 | 前端用户可见入口统一从 `BrandsView.vue` / 品牌管理路由进入；新建问题使用品牌管理下的子向导页，不新增独立扩展模块 |
| R2 | 页面主按钮必须叫 **新增单条问题**，用于新建单条问题；旁边放 **批量扩展问题** 进入新建问题 page 向导 |
| R3 | 主表只按品牌维度展示问题，不再按内部中间层分组 |
| R4 | 主表列为 `问题集 / 创建时间 / 操作`，可后续追加状态列，但不恢复旧分组列 |
| R5 | 拓词工具采用五列输入：地域词 / 前缀词 / 核心词 / 行业词 / 后缀词；核心词与行业词必填 |
| R6 | 拓词工具候选由后端计算，默认最多返回 500 条候选 |
| R7 | AI 扩展单次最多返回 20 条候选，30s 超时 |
| R8 | AI 扩展必须使用 JSON Schema 强约束输出 |
| R9 | AI 扩展失败必须退还 AI 点：未配置不预留，超时/解析失败已预留则 refund |
| R10 | 用户保存前，所有候选都只是前端临时态；只有点击保存后才写库 |
| R11 | 物化分两阶段：事务外预校验，事务内重算配额和重复；事务异常则本次 accepted 全回滚 |
| R12 | 后端 API 不接受用户选择 `keyword_id` / `keyword_name`；service 内部使用默认问题桶兼容旧表 |
| R13 | 必须新增品牌级问题文本唯一索引：`(brand_id, lower(btrim(question_text))) WHERE deleted_at IS NULL` |
| R14 | 重复判定与 R13 一致：预校验命中返回 `duplicate`，并发命中返回 `duplicate_concurrent` |
| R15 | `layer`、`intent`、`source` 是系统元数据，默认自动补齐；主表 V1 不展示，不要求用户填写 |
| R16 | 入库后元数据只读；用户只能改问题文本，元数据纠错路径是删除后重建 |
| R17 | Handler 必须校验枚举：`layer ∈ {L1..L5}`、`intent ∈ {informational,evaluative,decisional}`、`source ∈ {manual,combination,ai_distill}` |
| R18 | `source=auto` 仅允许内部默认问题桶使用，外部请求传入一律 `400 invalid_enum` |
| R19 | 所有写入必须走既有 `auditlog.AsyncWriter` |
| R20 | 写入后必须失效当前品牌相关缓存 |
| R21 | 账号级问题配额是硬限制；同一账号下所有品牌共享 `question_limit`；额度来自 `brand_library.question_limits_by_plan` YAML 配置，按套餐 code 可配置，默认 `free=5`、`plus=25`、`pro=50` |
| R22 | 如果本次没有任何可写入问题，返回 `400 no_valid_questions`，不得写入空数据 |
| R23 | 旧 `CreateQuestion` / `UpdateQuestion` 命中品牌级唯一索引时必须返回 `409 question_exists` |
| R24 | i18n 必须同步维护 `zh-CN.ts` 和 `en-US.ts` |
| R25 | 图二品牌管理页及其数据聚合必须过滤内部默认问题桶（`source=auto`），避免系统兼容记录进入用户可见 UI |
| R26 | 配额配置必须热更新友好：`ConfigStore` reload 后新保存请求读取最新额度，不把 5/25/50 硬编码进 service；旧 `max_keywords` / `max_questions_per_keyword` 不再作为问题驱动页面的额度来源 |

---

## 7. UI Design

### 7.1 主视图：品牌管理

```
┌──────────────────────────────────────────────────────────────────────────────┐
│ 品牌管理                                                    [+ 创建新品牌]   │
│                                                                              │
│ ┌─ 品牌管理说明 ──────────────────────────────────────────────────────────┐ │
│ │ 管理品牌、问题集和竞品库。用于后续 AI 平台监测与 GEO 分析。        [收起] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│ │ 省心推       │ │ 全屋定制Pro  │ │ 某教育品牌   │ │ + 添加品牌    │        │
│ │ 问题 18      │ │ 问题 42      │ │ 问题 9       │ │              │        │
│ │ 竞品 4       │ │ 竞品 7       │ │ 竞品 2       │ │              │        │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘        │
│                                                                              │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ [问题集]   [竞品库]                         [批量扩展问题] [新增单条问题] │ │
│ ├──────────────────────────────────────────────────────────────────────────┤ │
│ │ 问题集                                                   创建时间   操作 │ │
│ │ ─────────────────────────────────────────────────────────────────────── │ │
│ │ 省心推是什么平台？                                      2026-05-09  编辑 │ │
│ │ 省心推怎么帮品牌做 GEO 优化？                           2026-05-09  编辑 │ │
│ │ 省心推和传统 SEO 工具有什么区别？                       2026-05-10  编辑 │ │
│ │ 中小企业如何用省心推监测 AI 搜索曝光？                  2026-05-10  编辑 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘
```

**关键设计约束**：

- 品牌卡是上层选择器，不是问题分组容器。
- 问题表使用全宽布局，适合扫描和批量操作。
- 右侧主按钮固定为 **新增单条问题**，旁边放次按钮 **批量扩展问题**。
- 表格操作区只放编辑、删除、更多菜单。
- L1-L5 / intent 等系统标签不放在主表首版里，避免页面重新回到工程化心智。

### 7.2 新建问题向导页

```
┌─ ← 新建问题                         省心推 ────────────────────────────────┐
│ 按向导生成候选，确认后一次性保存到当前品牌的问题集。                         │
├──────────────────────────────────────────────────────────────────────────────┤
│ [配置生成方式] ─────────────── [确认候选]                                    │
│                                                                              │
│ 创建方式                                                                     │
│ [拓词工具]  [AI 扩展]  [手动批量]                                           │
│                                                                              │
│ 问题内容 / 拓词工具 / AI 主题 / 批量文本                                      │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 省心推适合哪些企业做 GEO 监测？                                          │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│ 候选预览                                                                     │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ ☑ 省心推是什么平台？                                                     │ │
│ │ ☑ 省心推怎么监测 ChatGPT 里的品牌曝光？                                  │ │
│ │ ☑ 中小企业如何判断 AI 搜索有没有提到自己？                               │ │
│ │ ☐ 省心推                                                                 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│ 共 24 条候选 · 已选择 21 条 · 过短 1 条 · 重复 2 条                           │
│                                                                              │
│                                           [取消] [上一步] [保存问题 (21)]     │
└──────────────────────────────────────────────────────────────────────────────┘
```

**交互规则**：

- 三种批量方式互斥，切换方式会清空当前未保存候选。
- 单条新增不放在向导页内，由品牌管理页的 **新增单条问题** 按钮直接完成。
- 候选行支持勾选、编辑文本、删除。
- 过短、重复、明显不像问题的候选默认不勾选并标灰。
- 高级元数据不在默认视图中展示；如后续产品需要，可放入“高级信息”折叠区。

### 7.3 拓词工具面板

```
┌─ 拓词工具 ─────────────────────────────────────────────────────────────────┐
│                                                                              │
│ ┌─1.地域词─┐ ┌─2.前缀词─┐ ┌─3.核心词(必填)─┐ ┌─4.行业词(必填)─┐ ┌─5.后缀词─┐ │
│ │ 合肥  │ │ 好用的│ │ GEO        │ │ 工具        │ │ 哪家好│                 │
│ │ 上海  │ │ 专业的│ │ AI搜索优化 │ │ 平台        │ │ 怎么选│                 │
│ │ 华东  │ │ 靠谱的│ │            │ │ 服务商      │ │ 推荐  │                 │
│ └───────┘ └───────┘ └────────────┘ └────────────┘ └───────┘                 │
│                                                                              │
│ 每行一个词；缺位列会被跳过；核心词与行业词不能为空。                           │
│                                                                              │
│ 预计生成：162 条，最多预览 500 条                                               │
│                                                                              │
│                                                            [生成候选]          │
└──────────────────────────────────────────────────────────────────────────────┘
```

**生成规则**：

- 每列按换行分词；空行不参与组合。
- 空的可选列按“默认词”处理，即跳过该列。
- 核心词和行业词必填。
- 可选列为空时跳过，不拼接空字符串。
- 结果必须经过后端去重、长度校验、自动补元数据。
- 超过 500 条时后端截断，前端展示截断提示。

### 7.4 AI 扩展状态

```
生成中：
┌─ AI 扩展 ─────────────────────────────────────────────────────────────── × ─┐
│ 正在为「省心推」生成用户真实会问的问题，预计 15-25 秒。                      │
│                                                                              │
│ [取消任务]                                                                    │
└──────────────────────────────────────────────────────────────────────────────┘

失败：
┌─ AI 扩展失败 ─────────────────────────────────────────────────────────── × ─┐
│ 大模型暂不可用或输出无法解析。                                                │
│ AI 点已退还。                                                                 │
│                                                                              │
│ [重试] [切换为手动批量] [关闭]                                                │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## 8. Data Model

### 8.1 Migration

项目当前未发布生产、无真实租户数据。本次 migration 不需要 `CONCURRENTLY` 和历史去重脚本；若未来在线上数据上做同类变更，必须改成预扫描 + 并发建索引方案。

```sql
-- migrations/2026-05-12T14:00:00_add_question_expansion_metadata.up.sql
ALTER TABLE brand_keywords
    ADD COLUMN layer     VARCHAR(8)  NOT NULL DEFAULT 'L2',
    ADD COLUMN seed_word VARCHAR(200),
    ADD COLUMN source    VARCHAR(32) NOT NULL DEFAULT 'manual';

ALTER TABLE brand_keywords
    ADD CONSTRAINT ck_brand_keywords_layer
        CHECK (layer IN ('L1','L2','L3','L4','L5')),
    ADD CONSTRAINT ck_brand_keywords_source
        CHECK (source IN ('manual','combination','ai_distill','auto'));

CREATE INDEX idx_brand_keywords_internal_source
    ON brand_keywords (brand_id, source)
    WHERE deleted_at IS NULL;

ALTER TABLE brand_questions
    ADD COLUMN layer  VARCHAR(8)  NOT NULL DEFAULT 'L2',
    ADD COLUMN intent VARCHAR(16) NOT NULL DEFAULT 'informational',
    ADD COLUMN source VARCHAR(32) NOT NULL DEFAULT 'manual';

ALTER TABLE brand_questions
    ADD CONSTRAINT ck_brand_questions_layer
        CHECK (layer IN ('L1','L2','L3','L4','L5')),
    ADD CONSTRAINT ck_brand_questions_intent
        CHECK (intent IN ('informational','evaluative','decisional')),
    ADD CONSTRAINT ck_brand_questions_source
        CHECK (source IN ('manual','combination','ai_distill'));

CREATE INDEX idx_brand_questions_intent
    ON brand_questions (brand_id, intent)
    WHERE deleted_at IS NULL;

CREATE UNIQUE INDEX uk_brand_question_text_active
    ON brand_questions (brand_id, lower(btrim(question_text)))
    WHERE deleted_at IS NULL;
```

### 8.2 字段语义

| 表 | 字段 | 语义 | 用户是否可见 |
| --- | --- | --- | --- |
| `brand_keywords` | `layer` | 内部默认问题桶的系统标签；兼容旧结构 | 否 |
| `brand_keywords` | `seed_word` | 内部默认问题桶创建时的品牌名快照 | 否 |
| `brand_keywords` | `source` | `auto` 表示系统内部默认问题桶 | 否 |
| `brand_questions` | `layer` | 系统推断的问题层级，用于下游分析 | V1 默认不展示 |
| `brand_questions` | `intent` | 系统推断的问题意图 | V1 默认不展示 |
| `brand_questions` | `source` | 问题来源：手动、拓词工具、AI 扩展 | 可在后续筛选中展示 |

### 8.3 唯一性策略

同一品牌下，归一化后的问题文本只能存在一条 active 记录：

```sql
(brand_id, lower(btrim(question_text))) WHERE deleted_at IS NULL
```

V1 只做 `trim + lower`，不剥离标点。原因是带问号和不带问号可能影响实际 AI 平台回答，先保留文本差异。

---

## 9. Backend Architecture

### 9.1 文件布局

```
server/internal/tenant/app/
  question_expansion_service.go    ← NEW · 问题生成与物化核心服务
  question_metadata_classify.go    ← NEW · layer + intent 规则分类器
  question_distill_prompt.go       ← NEW · AI 扩展提示词模板
  brand_service.go                 ← 扩展 QuestionResponse metadata；创建品牌时创建默认问题桶
  cache_support.go                 ← 复用现有 brand:* 缓存键

server/internal/tenant/transport/
  question_expansion_handler.go    ← NEW · Gin handler
  router.go                        ← brands group 下挂问题生成路由
  brand_handler.go                 ← 旧问题 CRUD 增加唯一冲突映射

server/internal/bootstrap/
  bootstrap.go                     ← 注入 llmClient + brandService → questionExpansion service
```

### 9.2 `QuestionExpansionService`

```go
type QuestionExpansionService struct {
    pool  *pgxpool.Pool
    llm   llm.Client
    brand *BrandService
    cache sharedcache.Cache
    audit *auditlog.AsyncWriter
}

func (s *QuestionExpansionService) GenerateByCombination(
    ctx context.Context,
    brandID int64,
    req QuestionCombinationRequest,
) (*QuestionCandidateResult, error)

func (s *QuestionExpansionService) GenerateByAIDistill(
    ctx context.Context,
    brandID int64,
    req QuestionDistillRequest,
) (*QuestionCandidateResult, error)

func (s *QuestionExpansionService) MaterializeQuestions(
    ctx context.Context,
    brandID int64,
    req MaterializeQuestionsRequest,
) (*MaterializeQuestionsResult, error)

func (s *QuestionExpansionService) ClassifyMetadata(
    ctx context.Context,
    brandID int64,
    texts []string,
) ([]ClassifiedQuestion, error)
```

### 9.3 关键类型

```go
type QuestionCombinationRequest struct {
    Region   []string `json:"region"`
    Prefix   []string `json:"prefix"`
    Core     []string `json:"core" binding:"required"`
    Industry []string `json:"industry" binding:"required"`
    Suffix   []string `json:"suffix"`
    MaxItems int      `json:"max_items"` // default 500, hard cap 500
}

type QuestionDistillRequest struct {
    SeedTopic string `json:"seed_topic" binding:"required,min=2"`
}

type QuestionCandidate struct {
    Text          string `json:"text"`
    Layer         string `json:"layer"`
    Intent        string `json:"intent"`
    Source        string `json:"source"` // manual / combination / ai_distill
    MissingSuffix bool   `json:"missing_suffix"`
    TooShort      bool   `json:"too_short"`
    Duplicate     bool   `json:"duplicate"` // brand-level duplicate
    SuggestSkip   bool   `json:"suggest_skip"`
}

type QuestionCandidateResult struct {
    Candidates      []QuestionCandidate `json:"candidates"`
    AIPointsCharged int                 `json:"ai_points_charged,omitempty"`
    CacheHit        bool                `json:"cache_hit,omitempty"`
    Truncated       bool                `json:"truncated,omitempty"`
}

type MaterializeQuestionsRequest struct {
    Source    string                `json:"source"` // manual / combination / ai_distill
    Questions []MaterializeQuestion `json:"questions" binding:"required,min=1"`
}

type MaterializeQuestion struct {
    Text   string `json:"text" binding:"required"`
    Layer  string `json:"layer"`
    Intent string `json:"intent"`
    Source string `json:"source"`
}

type MaterializeQuestionsResult struct {
    CreatedQuestions int          `json:"created_questions"`
    SkippedQuestions []SkipReason `json:"skipped_questions"`
}

type SkipReason struct {
    Text   string `json:"text"`
    Reason string `json:"reason"`
}
```

`SkipReason.Reason` 取值：

- `too_short`
- `invalid_text`
- `duplicate`
- `duplicate_in_batch`
- `quota_exceeded`
- `duplicate_concurrent`
- `quota_exceeded_concurrent`

### 9.4 自动元数据分类

系统自动为问题补充两个标签：

| 字段 | 用途 | 是否主表展示 |
| --- | --- | --- |
| `intent` | 区分了解、评估、决策类问题 | 否 |
| `layer` | 区分品牌、业务、痛点、长尾、对比等问题层级 | 否 |

#### Intent 规则

| 类别 | 触发词 | 默认 |
| --- | --- | --- |
| `decisional` | 哪家好、哪个好、怎么选、推荐、哪里买、适合谁 | - |
| `evaluative` | 对比、区别、哪个更、优劣、测评、排名、值不值 | - |
| `informational` | 是什么、怎么做、如何、为什么、介绍、原理 | 默认 |

优先级：`decisional > evaluative > informational`。

#### Layer 规则

| 优先级 | 层级 | 触发条件 |
| --- | --- | --- |
| 1 | `L5` | 出现两个及以上已知品牌名，或出现对比类词 |
| 2 | `L1` | 只出现当前品牌名 |
| 3 | `L4` | 出现地域、人群、价格、场景修饰 |
| 4 | `L3` | 出现痛点、问题、踩坑、解决等表达 |
| 5 | `L2` | 兜底 |

品牌上下文由 service 根据 `brandID` 从 `brands` 和 `competitors` 读取，前端不传品牌名数组，避免 body/path 不一致造成边界问题。

### 9.5 AI 扩展提示词

```
你是一个 GEO（Generative Engine Optimization）资深策略师。
请围绕当前品牌和输入主题，生成中国用户在 AI 搜索里真实会问的问题。

【输入】
- 当前品牌: {{brand_name}}
- 竞品列表: {{competitor_names}}
- 主题: {{seed_topic}}

【输出 JSON Schema】
{
  "candidates": [
    {
      "text": "string, 完整中文问句, ≤40 字",
      "intent": "informational|evaluative|decisional",
      "layer": "L1|L2|L3|L4|L5"
    }
  ]
}

【约束】
1. candidates 长度 ≤ 20
2. 至少覆盖 3 类 intent
3. 问题必须是自然口语问句
4. 至少 4 条包含地域、价位、人群或场景修饰
5. 严格输出 JSON，不要 Markdown，不要解释
```

LLM 返回后仍由本地规则复核标签；规则结果优先。

### 9.6 API Endpoints

挂在既有 `tenantProtected.Group("/brands")` 下：

| Method | Path | 说明 |
| --- | --- | --- |
| `POST` | `/brands/:id/questions/combination-preview` | 拓词工具候选预览 |
| `POST` | `/brands/:id/questions/ai-distill` | AI 扩展候选预览 |
| `POST` | `/brands/:id/questions/materialize` | 保存候选到当前品牌问题集 |
| `POST` | `/brands/:id/questions/classify-metadata` | 批量补充 `layer` / `intent` |

所有接口继承现有认证、租户、工作区和订阅校验中间件。

### 9.7 配额与 AI 点

| 操作 | 问题配额 | AI 点 | 失败处理 |
| --- | --- | --- | --- |
| 单条新增 | 保存时检查 | 0 | 返回表单错误 |
| 拓词工具预览 | 不消耗 | 0 | 参数错误直接返回 |
| AI 扩展预览（缓存命中） | 不消耗 | 0 | - |
| AI 扩展预览（缓存未命中） | 不消耗 | 1 点 | 失败 refund |
| 保存问题 | Phase 1 + Phase 2 检查 | 0 | 见物化算法 |

AI 扩展缓存：

- Key：`question_distill:{tenant_id}:{brand_id}:{sha1(seed_topic)}`
- Value：只存 `[]QuestionCandidate`
- TTL：300 秒
- 命中时跳过 AI 点预留，返回 `cache_hit=true`

**问题上限配置**：

新问题驱动页面使用**账号级问题上限**，同一账号下所有品牌共享 `question_limit`，不再使用旧的 `max_keywords * max_questions_per_keyword` 模型。配置放在 `server/configs/config.yaml` 与 `deploy/config.yaml` 的 `brand_library` 下：

```yaml
brand_library:
  free_brand_limit: 1
  paid_brand_limit: 2

  # 问题驱动页面使用：当前账号最多保存多少个问题，所有品牌共用。
  # key 必须匹配 membership.plans[].code；新增套餐只加一行配置，不改代码。
  question_limits_by_plan:
    default: 25
    free: 5
    plus: 25
    pro: 50

  # Deprecated：旧模型参数。问题驱动页面不再读取这两个字段。
  # 若旧关键词 CRUD 仍保留，可在过渡期继续使用；下线旧 CRUD 后删除。
  max_keywords: 5
  max_questions_per_keyword: 5
```

解析规则：

- 读取当前租户订阅套餐的 `plan_code`。
- 优先取 `question_limits_by_plan[plan_code]`。
- 未命中或配置值小于等于 0 时，取 `question_limits_by_plan.default`。
- `default` 缺失或小于等于 0 时兜底为 25。
- 初始配置建议：`free=5`、`plus=25`、`pro=50`，但这些值必须可通过 YAML 修改。
- `BrandLibrarySummaryResponse` 新增 `max_questions`、`used_questions`、`remaining_questions`，前端配额提示和保存前置判断都读账号级字段。
- `max_questions_per_brand` 仅作为过渡期兼容别名返回，不再表达产品语义。

### 9.8 物化两阶段算法

#### Phase 1：事务外预校验

```
input:
  MaterializeQuestionsRequest{Source, Questions}
  brandID

load:
  current_q_count := SELECT COUNT(*) FROM brand_questions
                     WHERE tenant_id = $tenantID AND deleted_at IS NULL

  existing_norm_set := SELECT lower(btrim(question_text))
                       FROM brand_questions
                       WHERE brand_id = $brandID AND deleted_at IS NULL

process:
  maxQuestions := limits.QuestionLimitForPlan(currentPlanCode) // from question_limits_by_plan
  remaining := maxQuestions - current_q_count
  if remaining < 0: remaining = 0

  in_batch_norm_set := {}
  accepted := []
  skipped := []

  for q in req.Questions:
    text := trim(q.Text)
    norm := lower(text)

    if text == "" or len(norm) < 4:
      skipped += {text, "too_short"}
      continue

    if norm in existing_norm_set:
      skipped += {text, "duplicate"}
      continue

    if norm in in_batch_norm_set:
      skipped += {text, "duplicate_in_batch"}
      continue

    if remaining <= 0:
      skipped += {text, "quota_exceeded"}
      continue

    q.Text = text
    q.Layer = coalesceValid(q.Layer, InferLayer(text, knownBrands))
    q.Intent = coalesceValid(q.Intent, ClassifyIntent(text))
    q.Source = coalesceValid(q.Source, req.Source, "manual")

    accepted += q
    in_batch_norm_set += norm
    remaining--

  if len(accepted) == 0:
    return 400 no_valid_questions + skipped
```

#### Phase 2：事务内写入

```go
tx, _ := pool.Begin(ctx)
defer tx.Rollback(ctx)

// 1. 序列化同一品牌的问题写入
_, err := tx.Exec(ctx, `
    SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))
`, fmt.Sprintf("brand:%d", brandID), "questions")
if err != nil { return err }

// 2. 确保内部默认问题桶存在
bucketID, err := ensureDefaultQuestionBucket(ctx, tx, tenantID, brandID)
if err != nil { return err }

_, _ = tx.Exec(ctx, `
    SELECT 1 FROM brand_keywords WHERE id = $1 FOR UPDATE
`, bucketID)

// 3. 锁内重算问题配额
var currentCount int
_ = tx.QueryRow(ctx, `
    SELECT COUNT(*)::INT
    FROM brand_questions
    WHERE tenant_id = $1 AND deleted_at IS NULL
`, tenantID).Scan(&currentCount)

maxQuestions := limits.QuestionLimitForPlan(currentPlanCode) // from question_limits_by_plan
remaining := maxQuestions - currentCount
if remaining < 0 { remaining = 0 }

if remaining < len(accepted) {
    overflow := accepted[remaining:]
    accepted = accepted[:remaining]
    for _, q := range overflow {
        skipped = append(skipped, SkipReason{Text: q.Text, Reason: "quota_exceeded_concurrent"})
    }
}

if len(accepted) == 0 {
    return ErrBadRequest("no_valid_questions", skipped)
}

// 4. 批量写入，品牌级唯一索引兜底防并发重复
payload, _ := json.Marshal(accepted)
rows, err := tx.Query(ctx, `
    INSERT INTO brand_questions (
        tenant_id, brand_id, keyword_id, question_text,
        layer, intent, source, status
    )
    SELECT $1, $2, $3, q.text, q.layer, q.intent, q.source, 'active'
    FROM jsonb_to_recordset($4::jsonb)
         AS q(text TEXT, layer TEXT, intent TEXT, source TEXT)
    ON CONFLICT (brand_id, lower(btrim(question_text)))
              WHERE deleted_at IS NULL
    DO NOTHING
    RETURNING question_text
`, tenantID, brandID, bucketID, payload)
if err != nil { return err }

inserted := map[string]struct{}{}
for rows.Next() {
    var text string
    _ = rows.Scan(&text)
    inserted[normalizeQuestion(text)] = struct{}{}
}

for _, q := range accepted {
    if _, ok := inserted[normalizeQuestion(q.Text)]; !ok {
        skipped = append(skipped, SkipReason{Text: q.Text, Reason: "duplicate_concurrent"})
    }
}

if err := tx.Commit(ctx); err != nil {
    return ErrInternal("materialize_failed")
}

return MaterializeQuestionsResult{
    CreatedQuestions: len(inserted),
    SkippedQuestions: skipped,
}
```

### 9.9 内部默认问题桶

`brand_questions.keyword_id` 当前仍是必填字段，因此每个品牌需要一条内部默认问题桶记录。

| 场景 | 行为 |
| --- | --- |
| 品牌已有 `source=auto` 的 active 桶 | 复用并锁行 |
| 品牌没有默认桶 | 在同一事务内创建 |
| 品牌改名 | V1 不同步桶名；桶不展示给用户 |
| 老数据缺桶 | 首次保存问题时 lazy-create |
| 系统桶创建失败 | 当前事务失败，不写入问题 |

创建规则：

```sql
-- 先查系统桶，避免误复用历史上用户创建的同名记录。
SELECT id
FROM brand_keywords
WHERE tenant_id = $1
  AND brand_id = $2
  AND source = 'auto'
  AND deleted_at IS NULL
ORDER BY id ASC
LIMIT 1
FOR UPDATE;

-- 未命中时创建。name 使用稳定内部名，避免与用户历史数据重名。
INSERT INTO brand_keywords (
    tenant_id, brand_id, name, status,
    layer, seed_word, source
) VALUES (
    $1, $2, '__default_questions__', 'active',
    'L1', $brand_name, 'auto'
)
ON CONFLICT (brand_id, name) WHERE deleted_at IS NULL
DO UPDATE
   SET source = 'auto',
       layer = 'L1',
       seed_word = COALESCE(brand_keywords.seed_word, EXCLUDED.seed_word),
       updated_at = brand_keywords.updated_at
RETURNING id;
```

说明：

- `name='__default_questions__'` 是稳定内部名，只用于满足旧唯一约束和外键。
- 查询优先按 `source=auto` 找系统桶；只有缺失时才创建。
- `seed_word` 保存创建时的 `brand.name` 快照，用于排查，不参与用户语义。
- 该记录不进入用户可见配额提示，不在图二页面展示。
- `ListKeywords` / 旧列表接口在图二页面的数据源里必须过滤 `source=auto`，避免内部桶渗出到 UI。
- 若未来移除内部层，可先把 `brand_questions.keyword_id` 改为 nullable，再迁移掉该依赖。

### 9.10 创建品牌时的默认桶

`BrandService.Create` 成功插入 brand 后，在同一事务内创建默认问题桶。

不变量：

| 项 | 决策 |
| --- | --- |
| 失败回退 | 默认桶创建异常时回滚 brand 创建 |
| 审计 | `brand.create` + `brand.create_default_question_bucket`，after-commit best-effort |
| 缓存 | 复用现有 `invalidateBrandCaches` |
| 返回值 | `BrandResponse` 不暴露内部桶 |
| lazy-create | 保留，用于修复历史或测试数据缺桶场景 |

---

## 10. Frontend Architecture

### 10.1 文件布局

```
apps/admin-web/src/
  views/
    BrandsView.vue                     ← 改造为图二的问题驱动品牌管理页
    BrandQuestionCreateView.vue        ← 新建问题向导页
  components/
    brand-management/
      BrandCardList.vue                ← 可后续拆分的品牌卡片列表
      BrandGuidePanel.vue              ← 可后续拆分的品牌管理说明折叠条
      BrandQuestionTable.vue           ← 可后续拆分的问题集全宽表格
      QuestionExpansionToolPanel.vue   ← 可后续拆分的拓词工具面板
      QuestionCandidatePreview.vue     ← 可后续拆分的候选预览
      QuestionSourceBadge.vue          ← 可选来源徽标；V1 主表不展示
  lib/api.ts                           ← 加 brandQuestionsApi
  i18n/messages/zh-CN.ts               ← 加 brandManagement.questions.*
  i18n/messages/en-US.ts               ← 同上

packages/shared-types/src/index.ts     ← 加 QuestionCandidate / MaterializeQuestions 类型
```

### 10.2 状态管理

V1 不引入 Pinia store：

- 当前品牌选择存在 `BrandsView.vue` 本地状态。
- 品牌列表、问题列表、竞品列表使用既有查询能力和缓存策略。
- 候选预览只在新建问题向导页内存在，离开即丢弃。
- 可选：向导页未保存草稿写入 localStorage，TTL 24h。

### 10.3 关键交互流

```dot
digraph flow {
    rankdir=LR;
    "进入品牌管理" -> "加载品牌卡片";
    "加载品牌卡片" -> "选择品牌";
    "选择品牌" -> "问题集 Tab";
    "问题集 Tab" -> "点击 新增单条问题";
    "问题集 Tab" -> "点击 批量扩展问题";
    "点击 新增单条问题" -> "当前页轻量表单";
    "点击 批量扩展问题" -> "新建问题向导页";

    "新建问题向导页" -> "拓词工具";
    "新建问题向导页" -> "AI 扩展";
    "新建问题向导页" -> "手动批量";

    "拓词工具" -> "POST /brands/:id/questions/combination-preview";
    "AI 扩展" -> "POST /brands/:id/questions/ai-distill";
    "手动批量" -> "POST /brands/:id/questions/classify-metadata";
    "当前页轻量表单" -> "POST /brands/:id/questions/materialize";

    "POST /brands/:id/questions/combination-preview" -> "候选预览";
    "POST /brands/:id/questions/ai-distill" -> "候选预览";
    "POST /brands/:id/questions/classify-metadata" -> "候选预览";

    "候选预览" -> "勾选/编辑/删除";
    "勾选/编辑/删除" -> "POST /brands/:id/questions/materialize";
    "POST /brands/:id/questions/materialize" -> "刷新问题表";
}
```

---

## 11. Error Handling

| 失败场景 | 后端响应 | 前端处理 |
| --- | --- | --- |
| 拓词工具核心为空 | `400 invalid_params: core_required` | 字段内联错误 |
| 拓词工具行业为空 | `400 invalid_params: industry_required` | 字段内联错误 |
| AI provider 未配置 | `503 llm_unavailable` | Toast + 切换手动批量 |
| AI 超时 | `503 llm_timeout`，AI 点 refund | Toast + “AI 点已退还” |
| AI 输出无法解析 | `502 llm_invalid_output`，AI 点 refund | Toast + 重试 |
| 枚举非法 | `400 invalid_enum` | 向导页内联错误 |
| 没有可保存问题 | `400 no_valid_questions` + skipped | 保留候选预览，黄色提示 |
| 部分问题被跳过 | `200 OK` + skipped | 顶部提示已保存 N 条、跳过 M 条 |
| 并发重复 | `200 OK` + `duplicate_concurrent` | 合并进跳过明细 |
| 并发配额不足 | `200 OK` + `quota_exceeded_concurrent` | 合并进跳过明细 |
| 旧问题 CRUD 撞唯一索引 | `409 question_exists` | 表单提示“该品牌下已存在相同问题” |
| 数据库异常 | `500 materialize_failed` | Toast，提示稍后重试 |

---

## 12. Testing Strategy

| 层 | 类型 | 覆盖 |
| --- | --- | --- |
| `question_metadata_classify.go` | Go 表驱动单测 | intent/layer 规则、优先级、兜底 |
| `question_expansion_service.go` 组合生成 | Go 单测 | 空输入、极大组合、截断、重复、metadata 默认值 |
| `question_expansion_service.go` AI 扩展 | Go 单测 | 成功、超时、JSON 解析失败、缓存命中、AI 点退款 |
| `MaterializeQuestions` | Go 集成测试 | 品牌级重复、批内重复、配额截断、并发写入、无有效问题、事务回滚 |
| `BrandLibraryConfig` | Go 单测 | `question_limits_by_plan` 解析、`free=5`、`plus=25`、`pro=50`、未知套餐 fallback 到 `default` |
| `ensureDefaultQuestionBucket` | Go 集成测试 | 已存在复用、缺失创建、创建失败回滚 |
| `BrandService.Create` | Go 集成测试 | 创建品牌时生成默认问题桶、审计 best-effort、缓存失效 |
| handler/router | Go 测试 | 4 个新路由注册、枚举校验、tenant middleware |
| 旧问题 CRUD | Go 集成测试 | 重复问题返回 `409 question_exists` |
| 前端 | 手动 QA + dev-server smoke | 图二布局、Tab、向导页、候选预览、保存刷新 |

后端命令：

```bash
cd server
gofmt -l ./internal/...
go vet ./internal/...
go test ./internal/tenant/app/...
TEST_DATABASE_URL=postgres://... go test -tags=integration ./internal/...
go build ./cmd/tenant-api
```

前端命令：

```bash
pnpm --filter admin-web typecheck
pnpm --filter admin-web build
pnpm --filter admin-web lint
```

---

## 13. Rollout Plan

当前项目未上线生产，V1 可全量发布：

1. 跑 migration：新增元数据列、品牌级问题唯一索引。
2. 上线 server：新增问题生成路由，旧问题 CRUD 增加唯一冲突映射。
3. 上线 admin-web：改造 `BrandsView.vue` 为图二布局。
4. 打开品牌管理入口。

未来若已经有生产数据，再做类似唯一索引变更时必须：

- 先预扫描重复数据。
- 线上使用 `CREATE UNIQUE INDEX CONCURRENTLY`。
- 分阶段发布服务与索引。

---

## 14. Compatibility

| 方面 | 决策 |
| --- | --- |
| 数据库 | 只加列、加索引，不删表不删字段 |
| 旧 `brand_questions.keyword_id` | 继续写内部默认问题桶 id |
| 旧问题 CRUD | payload 基本不变，但重复问题返回 `409 question_exists` |
| 旧品牌创建 | 增加内部默认问题桶副作用，响应不变 |
| 旧列表接口 | 若继续服务旧页面，可保留原始响应；图二品牌管理页必须调用过滤后的数据聚合或在前端过滤 `source=auto` |
| 旧配置字段 | `max_keywords` / `max_questions_per_keyword` 不再作为问题驱动页面额度来源；新页面只读 `question_limits_by_plan` 解析出的账号级 `max_questions` |
| 缓存 | 复用现有 brand cache key，写入后失效 |
| 下游监测 | 继续从 `brand_questions` 读取问题 |
| 前端路由 | 新增 `brands/:brandId/questions/create` page 向导；单条新增保留在品牌管理页 |

---

## 15. Effort Estimation

| 任务 | 人天 |
| --- | --- |
| 后端 migration + 唯一索引 | 0.3 |
| 后端问题组合生成 + 元数据分类 | 0.8 |
| 后端 AI 扩展 + JSON Schema + AI 点退款 + 缓存 | 0.8 |
| 后端物化两阶段算法 + 默认问题桶 | 0.9 |
| 后端 BrandService.Create 扩展 + 旧 CRUD 冲突映射 | 0.4 |
| 后端 handler/router/bootstrap | 0.4 |
| 前端 BrandsView 图二布局 | 0.8 |
| 前端新建问题向导页 + 四种方式 | 1.0 |
| 前端候选预览 + 保存刷新 + skipped 提示 | 0.7 |
| shared-types + api.ts + i18n | 0.4 |
| 联调 + QA + bugfix | 0.9 |
| **合计** | **≈ 7.4 人天** |

---

## 16. Open Questions

| # | 问题 | 当前决策 |
| --- | --- | --- |
| Q1 | 主表是否展示 intent/layer 标签 | V1 不展示，避免破坏图二的简洁表格 |
| Q2 | AI 扩展扣点 | 1 点/次，5 分钟缓存命中不扣点 |
| Q3 | 候选草稿是否服务端保存 | V1 不保存，向导页临时态 + 可选 localStorage |
| Q4 | 默认问题桶是否计入用户可见配额 | 不计入用户可见文案，只做系统兼容 |
| Q5 | 品牌改名是否同步默认问题桶 | V1 不同步 |
| Q6 | 组合生成 500 上限 | 保留，超过时截断并提示 |
| Q7 | 后续是否彻底移除内部桶 | 单独立迁移设计，不放入 V1 |
| Q8 | 配额是否按套餐固定字段配置 | 不用固定字段；使用 `question_limits_by_plan` map，新增套餐不改代码 |

---

## 17. Appendix A — 完整流程图

```
┌──────────────────────┐
│      品牌管理         │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   品牌管理说明        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   品牌卡片列表        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  问题集 / 竞品库 Tab  │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   问题集全宽表格      │
└──────────┬───────────┘
           │
           ▼
┌────────────────────────────────────┐
│ 新增单条问题 / 批量扩展问题         │
└──────────┬─────────────────────────┘
           │
           ▼
┌────────────────────────────────────────┐
│ 新建问题向导页                         │
│ 拓词工具 / AI 扩展 / 手动批量           │
└──────────┬─────────────────────────────┘
           │
           ▼
┌──────────────────────┐
│      候选预览         │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│      保存问题         │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│    刷新问题集表格     │
└──────────────────────┘
```

---

## 18. Appendix B — i18n keys

```yaml
brandManagement:
  title: 品牌管理
  createBrand: 创建新品牌
  guide:
    title: 品牌管理说明
    body: 管理品牌、问题集和竞品库，用于后续 AI 平台监测与 GEO 分析。
  tabs:
    questions: 问题集
    competitors: 竞品库
  questions:
    create: 新建问题
    table:
      question: 问题集
      createdAt: 创建时间
      actions: 操作
    modal:
      title: 新建问题
      currentBrand: 当前品牌
      methods:
        combination: 拓词工具
        aiDistill: AI 扩展
        manualBatch: 手动批量
      preview: 候选预览
      summary: 共 {total} 条候选 · 已选择 {selected} 条 · 过短 {tooShort} 条 · 重复 {duplicate} 条
      save: 保存问题 ({count})
    combination:
      title: 拓词工具生成
      region: 1.地域词
      prefix: 2.前缀词
      core: 3.核心词（必填）
      industry: 4.行业词（必填）
      suffix: 5.后缀词
      coreRequired: 核心不能为空
      industryRequired: 行业不能为空
      generate: 生成候选 ({count})
    errors:
      questionExists: 该品牌下已存在相同问题
      noValidQuestions: 没有可保存的问题，请调整候选后重试
      aiUnavailable: 大模型暂不可用
      aiRefunded: AI 点已退还
      partialSaved: 已保存 {created} 条，跳过 {skipped} 条
```

---

## 19. Appendix C — Acceptance Criteria

### 19.1 文档自查

- [x] 页面心智改为品牌 → 问题集 → 新建问题。
- [x] 图二关键结构已覆盖：品牌管理标题、品牌卡片、`问题集 / 竞品库` Tab、全宽表格、右侧 `批量扩展问题` 与 `新增单条问题`。
- [x] 用户可见流程不要求选择内部中间层实体。
- [x] 后端仍兼容 `brand_questions.keyword_id`。
- [x] 品牌级问题唯一索引已改为 `(brand_id, lower(btrim(question_text)))`。
- [x] 物化返回只包含 created/skipped 问题结果。
- [x] 错误表不再包含旧页面的重名复用或中间层配额错误。

### 19.2 手动 QA

| # | 操作 | 期望 |
| --- | --- | --- |
| 1 | 进入品牌管理 | 看到图二风格布局 |
| 2 | 选中品牌卡 | 下方默认打开问题集 Tab |
| 3 | 查看问题集表格 | 列为问题集、创建时间、操作 |
| 4 | 点击 `新增单条问题` | 当前页打开单条问题表单 |
| 5 | 单条新增并保存 | 表格刷新，新问题出现 |
| 5.1 | 点击 `批量扩展问题` | 进入新建问题 page 向导 |
| 6 | 拓词工具缺核心 | 字段内联错误 |
| 7 | 拓词工具生成 500+ | 候选截断并提示 |
| 7.1 | 拓词工具每列换行输入 | 当前列词数与预计候选数实时更新 |
| 8 | 保存重复问题 | 跳过明细显示 duplicate |
| 9 | AI 扩展成功 | 候选出现，未保存前表格不变 |
| 10 | AI 扩展失败 | Toast 提示，AI 点退还 |
| 11 | 配额不足 | 部分保存或无有效问题提示 |
| 12 | 编辑已入库问题文本为重复文本 | 返回 `409 question_exists` 并内联提示 |
| 13 | 新建品牌 | 响应不暴露内部默认桶，但后端存在兼容记录 |
| 14 | 分别切换 free / plus / pro 套餐配置 | 问题保存上限分别为 5 / 25 / 50，修改 YAML 后 reload 生效 |

---

## Changelog

### v9 — 2026-05-12

| Severity | Finding | 修复 |
| --- | --- | --- |
| P0 | 页面仍按旧中间层组织，和图二的问题集表格不一致 | 全文改为品牌管理页的问题驱动信息架构 |
| P0 | 创建入口仍要求用户先填写中间层名称 | 改为 `新增单条问题` / `批量扩展问题`，API 不再接收用户选择的 `keyword_id` / `keyword_name` |
| P1 | 问题唯一性仍绑定旧中间层，跨同品牌会重复 | 唯一索引改为品牌级 `(brand_id, lower(btrim(question_text)))` |
| P1 | 物化响应暴露内部实现字段 | 返回值改为 `created_questions` + `skipped_questions` |
| P1 | 新建品牌自动创建旧可见记录的设计会污染 UI | 改为内部默认问题桶，响应和页面均不展示 |
| P2 | 前端架构新增独立页面，与用户要求图二不符 | 改造 `BrandsView.vue`，不新增独立入口 |

**Next step:** 基于本文输出实施计划到 `docs/superpowers/plans/2026-05-12-question-expansion-plan.md`。