zfc/guzhi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
guzhi/.trae/documents/估值计算步骤 API 设计与落实方案.md
邹方成 cc352d3184 feat: 重构后端服务并添加新功能 
refactor: 优化API路由和响应模型
feat(admin): 添加App用户管理接口
feat(sms): 实现阿里云短信服务集成
feat(email): 添加SMTP邮件发送功能
feat(upload): 支持文件上传接口
feat(rate-limiter): 实现手机号限流器
fix: 修复计算步骤入库问题
docs: 更新API文档和测试计划
chore: 更新依赖和配置
2025-11-19 19:36:03 +08:00

7.8 KiB
Raw Blame History

目标

  • 完整设计并落实“估值计算步骤”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.113.14 市场价值子项：分别写入 C1C4

    • 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() 修复）。

交付

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