邹方成
cc352d3184
refactor: 优化API路由和响应模型 feat(admin): 添加App用户管理接口 feat(sms): 实现阿里云短信服务集成 feat(email): 添加SMTP邮件发送功能 feat(upload): 支持文件上传接口 feat(rate-limiter): 实现手机号限流器 fix: 修复计算步骤入库问题 docs: 更新API文档和测试计划 chore: 更新依赖和配置
185 lines
7.8 KiB
Markdown
185 lines
7.8 KiB
Markdown
## 目标
|
||
|
||
* 完整设计并落实“估值计算步骤”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()` 修复）。
|
||
|
||
## 交付
|
||
|
||
* 我将按上述规范逐步在计算引擎各子模块与统一计算入口中补充“步骤写入”，并确保管理端端点返回可序列化的数据结构；完成后会提供一份面向管理员的“估值步骤查看”前后端对接说明（端点与字段）。
|
||
|