# 联通云细颗粒度 Pricing Importer 设计计划

> For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

**Goal:** 在不伪造价格事实的前提下，把联通云从目录级 `import_cucloud_catalog.go` 升级为可验证的细颗粒度 pricing importer。

**Architecture:** 采用“两层事实源”设计：第一层抓取帮助中心公开文档中已明确结构化披露的 Token Plan 模型价格与区域支持信息并真实落库；第二层对 AISP 按量计费公开文档仅做“计费模式已验证、具体 per-model payg 单价未公开”的 blocker 标注，不把未公开的销售价伪造成 `region_pricing`。实现上优先复用 `official_pricing_import_common.go`，新增 `import_cucloud_pricing.go`，并保留 `import_cucloud_catalog.go` 作为目录入口校验。

**Tech Stack:** Go llm_script importer、联通云帮助中心 SSR HTML、正则/HTML 表格解析、现有 `officialPricingRecord` / `catalogVerificationRecord`。

---

## 已验证事实

1. 目录入口仍有效：
   - `https://www.cucloud.cn/act/CloudAI.html`
   - 已由现有 `import_cucloud_catalog.go` 校验 AICP / AI 应用开发平台存在。

2. AISP 帮助中心公开页面可直接 `GET`，无需登录，且页面源码内内嵌完整文档内容：
   - `https://support.cucloud.cn/document/127/591/2357.html?id=2357&folderid=2973`（购买计费）
   - `https://support.cucloud.cn/document/127/591/2357.html?id=2357&folderid=3237`（Coding Plan）
   - `https://support.cucloud.cn/document/127/591/2357.html?id=2357&folderid=3236`（Token Plan）

3. 已从公开源码中确认的结构化价格事实：
   - Token Plan 个人版：
     - Lite 15元/月，600万 tokens
     - Pro 30元/月，1200万 tokens
     - Max 45元/月，1800万 tokens
   - Token Plan 团队版：
     - Lite 198元/月，25,000 credits
     - Pro 698元/月，100,000 credits
     - Max 1398元/月，250,000 credits
   - 团队版 credits 对三种模型公开披露了折算综合单价：
     - `DeepSeek-V4-Pro`：9.30 元/百万tokens
     - `DeepSeek-V4-Flash`：0.70 元/百万tokens
     - `MiniMax-M2.5`：1.10 元/百万tokens

4. 已从公开源码中确认的结构化区域支持事实：
   - 区域列：`呼和浩特二区 / 上海二十二区 / 武汉四区 / 济南五区 / 贵阳基地二区`
   - 可从 `Token Plan概述` 或 `AI服务平台API介绍` 表格中解析模型-区域支持矩阵。

5. 已确认但不能伪造的边界：
   - AISP `购买计费/计费项及计费方式`、`按量计费模式` 文档明确说明“按量计费”为官方公开模式，单位为 `元/千 Tokens`，且按所选模型销售价实时累加。
   - 但当前公开帮助中心页面未披露具体每个模型的按量销售价表。
   - 因此现阶段不能把 AISP payg 的 per-model 单价写入 `region_pricing`。

## 设计决策

### 决策 A：拆成“可落库价格”与“已验证 blocker”两部分

1. 可直接落库到 `region_pricing` 的只有：
   - Token Plan 团队版中公开给出的三个模型综合单价。
2. 只能记录 blocker、不能写价格的部分：
   - AISP 按量计费 per-model 销售价。

理由：
- 公开文档对 payg 的计费机制有描述，但没有模型价格表。
- 用户明确要求“找不到就标 blocker，不伪造 importer”。
- Token Plan 团队版三模型综合单价属于公开结构化价格，足够支撑一个“真实 importer v1”。

### 决策 B：新增 pricing importer，不覆盖 catalog importer

保留：
- `scripts/import_cucloud_catalog.go`：继续负责 `cucloud-aicp-platform` / `cucloud-ai-app-platform` 目录存在性校验。

新增：
- `scripts/import_cucloud_pricing.go`：负责 AISP Token Plan 公开价格与模型区域支持的结构化导入。

理由：
- catalog importer 与 pricing importer 的事实层级不同。
- 后续若官方公开 payg 模型价表，可在 `import_cucloud_pricing.go` 内扩展，不影响目录校验链路。

### 决策 C：v1 只导入三个模型，价格视为 blended price

v1 导入模型：
- `DeepSeek-V4-Pro`
- `DeepSeek-V4-Flash`
- `MiniMax-M2.5`

价格写法：
- 因公开文档给的是“综合单价 X 元/百万tokens”，不是 input/output 分拆价；
- v1 写入 `officialPricingRecord` 时采用：
  - `InputPrice = blendedPrice`
  - `OutputPrice = blendedPrice`
- 同时在 `SourceURL` / `notes` / 文档中明确这是 `Token Plan blended price`，不是 AISP payg 的 input/output 拆分价。

风险：
- 这不适合作为严格意义上的 OpenAI-style in/out token 定价比较。
- 但比继续停留在目录级“无细颗粒度价格”更真实，且不会伪造不可得的 input/output 拆分。

### 决策 D：区域粒度以“支持矩阵交集”写入

建议落库策略：
- 仅对公开支持该模型的区域写入 region_pricing 记录。
- 例如：
  - `DeepSeek-V4-Pro` -> `贵阳基地二区`
  - `DeepSeek-V4-Flash` -> `贵阳基地二区`（团队版表明确）以及个人版支持区域若文档已写明，可谨慎扩展，但 v1 优先用矩阵表而不是 prose。
  - `MiniMax-M2.5` -> 从矩阵表取支持区域。

理由：
- 同一模型在联通云并非全区域可用。
- 使用支持矩阵可避免写出不存在的区域价格。

## 文件设计

### 1. 新增 importer

**Create:** `scripts/import_cucloud_pricing.go`

职责：
1. 获取公开帮助中心页面 HTML
2. 修复页面源码中的 UTF-8 / Latin1 混杂问题
3. 从页面源码中定位目标文档 `content` 块：
   - `Token Plan概述`
   - `AI服务平台API介绍` 或 `各云区域模型支持情况`
   - `计费项及计费方式`
   - `按量计费模式`
4. 解析：
   - Token Plan 团队版三模型综合单价表
   - 模型-区域支持矩阵表
5. 生成 `officialPricingRecord`
6. dry-run 输出：
   - 记录数
   - 模型数
   - 区域数
   - 是否检测到 `payg_mode_confirmed=true`
   - `payg_price_table_public=false`

建议 CLI 参数：
- `-url`：默认购买计费页或 Token Plan 页
- `-fixture`：本地样例 HTML
- `-dry-run`
- `-timeout`

### 2. 新增测试

**Create:** `scripts/import_cucloud_pricing_test.go`

测试覆盖：
1. 能从 fixture 中解析三模型 blended 价格
2. 能解析区域支持矩阵
3. 仅为支持区域生成记录
4. dry-run 摘要包含：
   - `source=cucloud-pricing-import`
   - `models=3`
   - `payg_mode_confirmed=true`
   - `payg_price_table_public=false`
5. 若 fixture 缺少三模型价格表，测试应 fail

### 3. 新增 fixture

**Create:** `scripts/testdata/cucloud_pricing_sample.html`

内容最少应覆盖：
- Token Plan 团队版价格表
- 三模型 `综合单价X元/百万tokens`
- 区域支持矩阵表
- `按量计费` 文本（用于 blocker 语义断言）

### 4. runtime 接入

**Modify:**
- `scripts/run_intel_pipeline.sh`
- `scripts/run_real_pipeline.sh`
- `scripts/run_daily.sh`
- `scripts/verify_importer_smoke.sh`
- `scripts/importer_smoke_gate_test.sh`
- `scripts/pipeline_runtime_alignment_test.sh`

接入方式：
- 保留 `cucloud_catalog`
- 新增 `cucloud_pricing`
- 失败消息区分：
  - 目录失败：`联通云目录校验失败`
  - 价格失败：`联通云 Token Plan 价格导入失败`

### 5. seed / docs 同步

**Modify:**
- `seeds/plan_catalog_inventory_seed_cn_relays_top20plus.json`
- `docs/PLAN_CATALOG_COVERAGE_MATRIX.md`
- `docs/NEXT_IMPORTER_RUNTIME_PRIORITY.md`
- `docs/PLAN_CATALOG_INVENTORY.md`
- `scripts/import_plan_catalog_test.go`

同步原则：
- `cucloud-aicp-platform` / `cucloud-ai-app-platform` 仍指向 `import_cucloud_catalog.go`
- 如新增联通云价格型 catalogCode，则新建 seed 项；否则仅在 docs 中注明：
  - `目录入口已导入`
  - `Token Plan 三模型 blended price 已导入`
  - `AISP payg per-model price table 仍未公开`

## 推荐实现顺序

### Task 1: 固化 discovery 结果到 fixture 与计划文档

**Objective:** 把已验证的公开证据固化为可重复测试输入。

**Files:**
- Create: `scripts/testdata/cucloud_pricing_sample.html`
- Create: `docs/plans/2026-05-22-cucloud-pricing-importer-plan.md`

**Step 1: 写 fixture**
- 从公开页面中裁剪最小必要 HTML 片段：
  - Token Plan 三模型价格表
  - 区域支持矩阵表
  - 按量计费说明段落

**Step 2: 验证 fixture 可读**
Run:
- `python3 - <<'PY' ...` 或 importer 单测读取 fixture
Expected:
- 能定位三张关键表 / 段落

### Task 2: 先写失败测试

**Objective:** 先锁定 importer 的真实合同。

**Files:**
- Create: `scripts/import_cucloud_pricing_test.go`

**Step 1: 写 failing tests**
至少包括：
- `TestParseCUCloudPricingBuildsBlendedRecords`
- `TestParseCUCloudPricingBuildsRegionMatrix`
- `TestRunCUCloudPricingImportDryRunPrintsSummary`

**Step 2: 运行测试确认失败**
Run:
- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go ./scripts/import_cucloud_pricing_test.go`
Expected:
- FAIL，因为 importer 尚不存在或解析逻辑未实现

### Task 3: 实现最小 importer

**Objective:** 只实现三模型 blended price + 区域支持矩阵。

**Files:**
- Create: `scripts/import_cucloud_pricing.go`

**实现要点：**
1. 获取 HTML
2. `latin1 -> utf8` 修正
3. 通过最近的 `"content":"...","createBy"` 边界提取目标内容块，而不是依赖简单 title-first regex
4. 表格解析：
   - Table A：团队版三模型综合单价
   - Table B：模型区域支持矩阵
5. 产出 `officialPricingRecord`
   - `OperatorName`: `Unicom AISP`
   - `OperatorNameCn`: `联通云 AI服务平台AISP`
   - `OperatorWebsite`: `https://www.cucloud.cn`
   - `SourceURL`: 购买计费 / Token Plan 页面
   - `Currency`: `CNY`
   - `InputPrice == OutputPrice == blendedPrice`
   - `Region`: 匹配支持矩阵中的具体云区域
6. dry-run 摘要要显式输出：
   - `payg_mode_confirmed=true`
   - `payg_price_table_public=false`

### Task 4: 运行 focused tests

**Objective:** 验证 importer 合同成立。

Run:
- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go ./scripts/import_cucloud_pricing_test.go`
Expected:
- PASS

### Task 5: 接入 smoke / pipeline

**Objective:** 让新 importer 进入日跑链路，但不移除 catalog importer。

**Files:**
- Modify: `scripts/verify_importer_smoke.sh`
- Modify: `scripts/importer_smoke_gate_test.sh`
- Modify: `scripts/pipeline_runtime_alignment_test.sh`
- Modify: `scripts/run_intel_pipeline.sh`
- Modify: `scripts/run_real_pipeline.sh`
- Modify: `scripts/run_daily.sh`

**Step 1: 增加 `cucloud-pricing-fixture` / `cucloud-pricing-live` smoke**
**Step 2: 增加 runtime source key `cucloud_pricing`**
**Step 3: 保留 `cucloud_catalog`**

### Task 6: 文档 truth-sync

**Objective:** 把联通云状态从“只有目录级”升级为“目录+部分结构化价格”。

**Files:**
- Modify: `docs/PLAN_CATALOG_COVERAGE_MATRIX.md`
- Modify: `docs/NEXT_IMPORTER_RUNTIME_PRIORITY.md`
- Modify: `docs/PLAN_CATALOG_INVENTORY.md`
- Modify: `seeds/plan_catalog_inventory_seed_cn_relays_top20plus.json`（如需要）

**文案要求：**
- 明确写：
  - Token Plan 三模型 blended price 已真实导入
  - AISP payg per-model 单价未公开，仍属 blocker
- 禁止写成“联通云 payg 已完整打通”

## 验证命令

### Focused unit tests
- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go ./scripts/import_cucloud_pricing_test.go`

### Plan catalog mapping tests
- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/import_plan_catalog.go ./scripts/import_plan_catalog_test.go`

### Shell gates
- `bash scripts/pipeline_runtime_alignment_test.sh`
- `bash scripts/importer_smoke_gate_test.sh`

### Live dry-run
- `go run -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go -dry-run`

**Expected live dry-run truth:**
- 只宣称 Token Plan 三模型 blended price 已导入
- 同时输出 / 记录 `payg_mode_confirmed=true`
- 同时输出 / 记录 `payg_price_table_public=false`

## 非目标

1. 不伪造 AISP payg per-model input/output 单价
2. 不把 Token Plan blended price 冒充为 OpenAI 风格 input/output split price
3. 不删除现有 `import_cucloud_catalog.go`
4. 不在未发现公开价表前宣称“联通云细颗粒度价格已完整闭环”

## 当前最短闭环路径

1. 先实现 `import_cucloud_pricing.go` v1
2. 只导入三模型 Token Plan blended price + 区域支持矩阵
3. runtime/smoke 接入
4. docs 标明 payg per-model price 仍是 verified blocker

这条路径能把联通云从“纯目录级”提升到“部分结构化价格已真实落库”，同时保持事实边界清晰。