## 目标

* 完整设计并落实“估值计算步骤”API与落库机制，保证：

  1. 用户提交估值后，所有中间计算步骤按规范写入数据库；
  2. 管理端在详情中查看完整步骤链条与中间结果；
  3. 统一数学公式、变量来源、步骤编号与展示结构。

## 现有能力与锚点

* 步骤模型：`ValuationCalculationStep`（app/models/valuation.py:88-107）

* 步骤写入：控制器提供创建/查询（app/controllers/valuation.py:24-53, 37-53）

* 管理端步骤查询：`GET /api/v1/valuations/{id}/steps`（app/api/v1/valuations/valuations.py:50-56）

* 已有示例记录：风险调整B3模块内已演示步骤写入（app/utils/calculation\_engine/risk\_adjustment\_b3/sub\_formulas/risk\_adjustment\_b3.py:195-237）

* 用户端计算入口：后台任务执行统一计算（app/api/v1/app\_valuations/app\_valuations.py:210-299）

## 公式总览与数学表达

1. 经济价值 B1（economic\_value\_b1）

* 基础价值 B11：依据财务与法律/创新、普及度

  * 示例表达：`B11 = w_f * f(three_year_income) + w_i * innovation_ratio + w_p * popularity_score + w_l * infringement_factor + w_pat * patent_score`

* 流量因子 B12：`S = α * S1 + β * S2 + γ * S3`；其中 S1 搜索指数（百度/微信/微博），S2 行业均值，S3 社交传播（点赞/评论/分享）

* 政策乘数 B13：`P = p_impl * implementation_stage_score + p_fund * funding_support_score`

* 汇总：`B1 = B11 * (1 + θ * S) * (1 + λ * P)`

1. 文化价值 B2（cultural\_value\_b2）

* 活态传承 B21：`B21 = κ1 * inheritor_level_coefficient + κ2 * offline_sessions + κ3 * social_views`

* 纹样基因 B22：`B22 = μ1 * historical_inheritance + μ2 * structure_complexity + μ3 * normalized_entropy`

* 汇总：`B2 = B21 + B22`

1. 风险调整 B3（risk\_adjustment\_b3）

* 风险评分总和：`R = 0.3 * market_risk + 0.4 * legal_risk + 0.3 * inheritance_risk`

* 风险调整系数：`B3 = 0.8 + 0.4 * R`（app/utils/.../risk\_adjustment\_b3.py:33-45, 47-66）

1. 市场价值 C（market\_value\_c）

* 竞价 C1：`C1 = weighted_average_price(transaction_data, manual_bids, expert_valuations)`

* 热度系数 C2：`C2 = ψ1 * daily_browse_volume + ψ2 * collection_count`

* 稀缺性乘数 C3：`C3 = φ(circulation)`（限量>稀缺性高）

* 时效性衰减 C4：`C4 = decay(recent_market_activity)`

* 汇总：`C = C1 * (1 + C2) * C3 * C4`

1. 最终估值 AB（final\_value\_ab）

* 模型估值 B：`B = B1 + B2`；再叠加风险调整：`B_adj = B * B3`

* 市场估值：`C`

* 最终：`Final = f(B_adj, C)`（例如加权平均或规则合成）

## 变量定义与来源映射

* 用户输入（UserValuationCreate，app/schemas/valuation.py:144-147）：

  * `three_year_income`、`annual_revenue`、`rd_investment`、`application_coverage`、`offline_activities`、`platform_accounts`、`sales_volume`、`link_views`、`circulation`、`last_market_activity`、`price_fluctuation`、`funding_status`、`implementation_stage`、`patent_application_no`、`historical_evidence`、`pattern_images`、`inheritor_level`、`inheritor_age_count`

* 系统/API来源：

  * 搜索指数S1、行业均值S2、社交传播S3（app/api/v1/app\_valuations/app\_valuations.py:328-347, 333-343）

  * ESG分、行业系数、政策匹配度（app/api/v1/app\_valuations/app\_valuations.py:47-80）

  * 侵权/专利校验（app/api/v1/app\_valuations/app\_valuations.py:81-118）

## 计算步骤落库设计

* 统一步骤结构（app/schemas/valuation.py:239-259）：

  * `step_order`：序号（含小数层级，如 1.11, 2.31）

  * `step_name`：中文名称（如“基础价值B11计算”）

  * `step_description`：公式与解释

  * `input_params`：输入参数 JSON（含变量与其来源）

  * `output_result`：中间结果（如每项得分，最终值）

  * `status`：`in_progress|completed|failed`

  * `error_message`：失败描述

* 步骤编号建议：

  * 经济价值 B1：2.1x（B11=2.11，B12=2.12，B13=2.13，汇总B1=2.19）

  * 文化价值 B2：2.2x（B21=2.21，B22=2.22，汇总B2=2.29）

  * 风险调整 B3：2.3x（总评R=2.30，B3=2.31）

  * 市场价值 C：3.1x（C1=3.11，C2=3.12，C3=3.13，C4=3.14，汇总C=3.19）

  * 最终估值 AB：4.1x（B组合=4.11，B×B3=4.12，Final=4.19）

* 落库时机：统一在后台任务中分模块记录（app/api/v1/app\_valuations/app\_valuations.py:38-41, 142-171）

* 写入方式：通过控制器 `create_calculation_step`（app/controllers/valuation.py:24-36）

* 已有范例：风险调整B3模块先 `in_progress` 再 `completed`（app/utils/.../risk\_adjustment\_b3.py:195-237）

## 完整流程说明

1. 原始数据输入：`POST /api/v1/app-valuations/`（app/api/v1/app\_valuations/app\_valuations.py:210-299）
2. 后台任务提取参数：B1/B2/B3/C（app/api/v1/app\_valuations/app\_valuations.py:302-567）
3. 模块计算与步骤记录：按编号分别执行，逐步写入 `ValuationCalculationStep`
4. 汇总合成：计算 `model_value_b`、`market_value_c`、`final_value_ab` 与 `dynamic_pledge_rate` 并存入 `ValuationAssessment`
5. 管理端查看：

* 详情：`GET /api/v1/valuations/{id}`（返回序列化后的详情）

* 步骤：`GET /api/v1/valuations/{id}/steps`（返回序列化后的步骤数组）

## 示例计算过程（模拟数据）

* 输入（节选）：

  * `three_year_income=[400,450,500]`，`annual_revenue=500`，`rd_investment=50`（创新投入比=10%）

  * `application_coverage=全国覆盖`（popularity\_score→由B11计算器给分）、`offline_activities=12`

  * `platform_accounts.douyin.likes=1200`（S3参数），`price_fluctuation=[95,105]`（波动率）

  * `inheritor_level=市级传承人`（转换为系数）、`inheritor_age_count=[45,60,75]`

  * `historical_evidence={历史文献:3, 考古发现:2, 传承谱系:5}`

* 步骤样例：

  * 2.11 基础价值B11：`input_params={three_year_income, innovation_ratio, popularity_score, infringement_score, patent_score}` → `output_result={B11: 123.45}`

  * 2.12 流量因子B12：`input_params={S1,S2,S3}` → `output_result={S: 0.32}`

  * 2.13 政策乘数B13：`input_params={implementation_stage,funding_support}` → `output_result={P: 0.15}`

  * 2.19 B1汇总：`output_result={B1: 156.78}`

  * 2.21 活态传承B21：`input_params={inheritor_level_coefficient,offline_sessions, social_views}` → `output_result={B21: 10.2}`

  * 2.22 纹样基因B22：`input_params={historical_inheritance,structure_complexity,normalized_entropy}` → `output_result={B22: 8.9}`

  * 2.30 风险总评R：`input_params={market_risk,legal_risk,inheritance_risk}` → `output_result={R: 0.42}`

  * 2.31 风险调整B3：`output_result={B3: 0.97}`

  * 3.11~~3.14 市场价值子项：分别写入 C1~~C4

  * 3.19 市场价值C：`output_result={C: 118.0}`

  * 4.11/4.12/4.19 最终汇总：`output_result={B: 175.88, B_adj: 170.6, Final: 122.0}`

## 后台展示规范

* 列表返回序列化后的 Pydantic 对象，避免 JSONResponse 序列化错误（已在管理端端点处理）

* 步骤展示：按照 `step_order` 升序，逐条显示 `step_name`、`step_description`、`input_params`、`output_result`、`status`；失败步骤显示 `error_message`

## 实施项

1. 将 B1、B2、C 模块对齐 B3 的“步骤写入”模式：每个子公式在计算前记录 `in_progress`，完成后记录 `completed` 并带结果；异常时标记 `failed`。
2. 在 `FinalValueACalculator` 合成阶段补充步骤记录（B组合、B×B3、Final）。
3. 确保管理端详情与步骤返回统一进行 JSON 序列化（管理端端点已按 `model_dump_json()` 修复）。

## 交付

* 我将按上述规范逐步在计算引擎各子模块与统一计算入口中补充“步骤写入”，并确保管理端端点返回可序列化的数据结构；完成后会提供一份面向管理员的“估值步骤查看”前后端对接说明（端点与字段）。