crm-backend-matt/.scratch/gen_opp_3b.py

# -*- coding: utf-8 -*-
"""详情子域 - 勘察 + 附件 (6 个接口)."""
import io, sys
sys.path.insert(0, 'D:/code/crm-backend-matt/.scratch')
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
from bru_lib import (
    write_bru, bru_form, build_docs, env_json,
    req_form_example, req_query_example,
)

# ---------- 勘察 Tab ----------
print('== 详情子域 / 勘察 ==')

SURVEY_ROWS = [
    ('id','string','勘察记录ID'),
    ('createTime','string','创建时间'),
    ('updateTime','string','更新时间'),
    ('oppId','string','所属商机ID'),
    ('surveyDate','string','现场勘察日期 yyyy-MM-dd'),
    ('engineerUserId','string','主要工程师用户ID（引用 crm-auth SysUser）'),
    ('applyWay','string','申请方式字典 code（工单申请/线下申请等）'),
    ('surveySeq','string','勘察次数字典 code（第一次/第二次/第三次/三次以上）'),
    ('applyNo','string','申请单号（可空）'),
    ('surveyDesc','string','勘察补充说明（可空，长文本）'),
]
SURVEY_ONE = (
    '{\n'
    '        "id": "1",\n'
    '        "createTime": "2024-01-01 12:00:00",\n'
    '        "updateTime": "2024-01-01 12:00:00",\n'
    '        "oppId": "1",\n'
    '        "surveyDate": "2024-01-15",\n'
    '        "engineerUserId": "1",\n'
    '        "applyWay": "apply_01",\n'
    '        "surveySeq": "seq_01",\n'
    '        "applyNo": "SS20240115001",\n'
    '        "surveyDesc": "现场环境符合安装要求；客户需要三期设备"\n'
    '      }'
)
SURVEY_PAGE_JSON = (
    '{\n'
    f'    "content": [\n{SURVEY_ONE}\n    ],\n'
    '    "total": 1,\n'
    '    "size": 10,\n'
    '    "current": 1,\n'
    '    "pages": 1,\n'
    '    "empty": false\n'
    '  }'
)
docs = build_docs(
    '勘察分页', 'POST', '/api/opportunity/site-survey/page',
    '商机详情「勘察」Tab：分页拉取该商机的现场勘察记录（多次勘察保留历史不覆盖）。列表「联系方式」由 `engineerUserId` 反查 SysUser 电话脱敏展示，不冗余存。',
    [('oppId','string','是','-','商机ID'),
     ('pageNum','number','否','1','页码'),
     ('pageSize','number','否','10','每页条数')],
    req_form_example('POST','/api/opportunity/site-survey/page',
        [('oppId','1'),('pageNum','1'),('pageSize','10')]),
    [('content','array<object>','勘察记录数组')] + [('content[].'+r[0],r[1],r[2]) for r in SURVEY_ROWS] + [
        ('total','number','总条数'),
        ('size','number','每页条数'),
        ('current','number','当前页码'),
        ('pages','number','总页数'),
        ('empty','boolean','是否为空结果'),
    ],
    env_json(SURVEY_PAGE_JSON),
)
write_bru('商机管理/详情子域', '勘察分页.bru',
    bru_form(5, '勘察分页', 'post', '/api/opportunity/site-survey/page',
        [('oppId','1'),('pageNum','1'),('pageSize','10')], docs))

add_survey_params = [
    ('oppId','string','是','-','商机ID'),
    ('surveyDate','string','是','-','现场勘察日期 yyyy-MM-dd'),
    ('engineerUserId','string','是','-','主要工程师用户ID（引用 crm-auth SysUser，可跨部门选人）'),
    ('applyWay','string','是','-','申请方式字典 code'),
    ('surveySeq','string','是','-','勘察次数字典 code'),
    ('applyNo','string','否','-','申请单号（人工录入，线下拿到后补录）'),
    ('surveyDesc','string','否','-','勘察补充说明（长文本）'),
]
add_survey_kv = [
    ('oppId','1'),('surveyDate','2024-01-15'),('engineerUserId','1'),
    ('applyWay','apply_01'),('surveySeq','seq_01'),
    ('applyNo','SS20240115001'),('surveyDesc','现场环境符合安装要求'),
]
docs = build_docs(
    '新增勘察', 'POST', '/api/opportunity/site-survey/add',
    '新建现场勘察记录（无状态机，填完即完整记录，不联动阶段轴 2）。附件走统一附件表 `opportunity_attachment`（`bizType=SITE_SURVEY`，`bizId`=本记录 id）。',
    add_survey_params,
    req_form_example('POST','/api/opportunity/site-survey/add', add_survey_kv),
    '新增勘察记录ID（Long，序列化为 string）',
    env_json('"1"'),
)
write_bru('商机管理/详情子域', '新增勘察.bru',
    bru_form(6, '新增勘察', 'post', '/api/opportunity/site-survey/add', add_survey_kv, docs))

docs = build_docs(
    '删除勘察', 'POST', '/api/opportunity/site-survey/delete',
    '逻辑删除勘察记录（走 BaseEntity 逻辑删）。',
    [('id','string','是','-','勘察记录ID')],
    req_form_example('POST','/api/opportunity/site-survey/delete',[('id','1')]),
    None, env_json('null'),
)
write_bru('商机管理/详情子域', '删除勘察.bru',
    bru_form(7, '删除勘察', 'post', '/api/opportunity/site-survey/delete',
        [('id','1')], docs))

# ---------- 附件 Tab ----------
print('== 详情子域 / 附件 ==')

ATT_ROWS = [
    ('id','string','附件行ID'),
    ('createTime','string','创建时间（上传时间）'),
    ('updateTime','string','更新时间'),
    ('oppId','string','所属商机ID'),
    ('bizType','string','业务归属类型：OPP/FOLLOW_UP/SITE_SURVEY/SCHEME_CARD'),
    ('bizId','string','业务对象ID（跟进/勘察/方案卡 id；bizType=OPP 时=opp_id 或空）'),
    ('materialType','string','资料类型字典 code（现场资料/设计清单-图纸/客户需求资料等）'),
    ('fileId','string','文件ID（引用 crm-file 文件本体）'),
    ('remark','string','附件说明（可空）'),
]
ATT_ONE = (
    '{\n'
    '      "id": "1",\n'
    '      "createTime": "2024-01-01 12:00:00",\n'
    '      "updateTime": "2024-01-01 12:00:00",\n'
    '      "oppId": "1",\n'
    '      "bizType": "OPP",\n'
    '      "bizId": "1",\n'
    '      "materialType": "material_01",\n'
    '      "fileId": "1",\n'
    '      "remark": "客户需求文档"\n'
    '    }'
)
docs = build_docs(
    '附件列表', 'GET', '/api/opportunity/attachment/list',
    '商机详情「附件」Tab：按 `bizType` 过滤附件列表；不传 `bizType` 返回该商机全部附件。文件本体走 crm-file 单独拉取。',
    [('oppId','string','是','-','商机ID'),
     ('bizType','string','否','-','业务归属类型过滤：OPP/FOLLOW_UP/SITE_SURVEY/SCHEME_CARD')],
    req_query_example('GET','/api/opportunity/attachment/list',
        [('oppId','1'),('bizType','OPP')]),
    ATT_ROWS,
    env_json(f'[\n{ATT_ONE}\n  ]'),
)
write_bru('商机管理/详情子域', '附件列表.bru',
    bru_form(8, '附件列表', 'get', '/api/opportunity/attachment/list',
        [('oppId','1'),('bizType','OPP')], docs))

add_att_params = [
    ('oppId','string','是','-','商机ID'),
    ('fileId','string','是','-','文件ID（先调 crm-file 上传拿到）'),
    ('bizType','string','否','-','业务归属类型：OPP/FOLLOW_UP/SITE_SURVEY/SCHEME_CARD'),
    ('bizId','string','否','-','业务对象ID'),
    ('materialType','string','否','-','资料类型字典 code'),
    ('remark','string','否','-','附件说明'),
]
add_att_kv = [
    ('oppId','1'),('fileId','1'),('bizType','OPP'),('bizId','1'),
    ('materialType','material_01'),('remark','客户需求文档'),
]
docs = build_docs(
    '新增附件', 'POST', '/api/opportunity/attachment/add',
    '将已上传到 crm-file 的文件挂到商机某业务对象下。跟进附件（bizType=FOLLOW_UP）应用层限 10 个/条（原型明画）。',
    add_att_params,
    req_form_example('POST','/api/opportunity/attachment/add', add_att_kv),
    '新增附件行ID（Long，序列化为 string）',
    env_json('"1"'),
)
write_bru('商机管理/详情子域', '新增附件.bru',
    bru_form(9, '新增附件', 'post', '/api/opportunity/attachment/add', add_att_kv, docs))

docs = build_docs(
    '删除附件', 'POST', '/api/opportunity/attachment/delete',
    '逻辑删除附件行；文件本体不动，由 crm-file 侧独立管理生命周期。',
    [('id','string','是','-','附件行ID')],
    req_form_example('POST','/api/opportunity/attachment/delete',[('id','1')]),
    None, env_json('null'),
)
write_bru('商机管理/详情子域', '删除附件.bru',
    bru_form(10, '删除附件', 'post', '/api/opportunity/attachment/delete',
        [('id','1')], docs))

print('part3b done — 勘察 + 附件 6 个接口完成')