f

resources/dev-report/BUILT_REPORT_FIELDS.md

@@ -0,0 +1,330 @@
+# 企业全景报告 · Build 后 JSON 字段说明
+
+本文描述 **`BuildReportFromRawSources` / `buildReport` 产出的报告对象**（与 `cmd/qygl_report_build`、QYGLJ1U9 聚合逻辑一致）。  
+数值在 JSON 中可能为 **number**（`json.Unmarshal` 后常见 `float64`）或 **string**，以实际序列化结果为准。
+
+## 数据来源概览
+
+| 报告一级字段 | 主要来源（原始接口 / 表） |
+|-------------|---------------------------|
+| `basic`、`branches`、`guarantees`、`management`、`assets`、`activities`（部分）等 | 企业全量信息核验 V2（QYGLUY3S，`jiguang`） |
+| 存在 `annualReports` 且非空时 | 上述块中与公示年报重复的 `YEARREPORT*` 表会在构建前剔除，改由年报接口数据支撑展示逻辑 |
+| `shareholding`、`controller`、`beneficiaries`、`investments`（`list`） | 优先股权全景（QYGLJ0Q1，`equity`），否则回退全量 |
+| `risks` 中司法部分 | 司法涉诉（QYGL5S1I，`judicial`）等 |
+| `annualReports` | 企业年报（QYGLDJ12，`annualRaw`），键名统一转小驼峰 |
+| `taxViolations` | 税收违法（QYGL8848），`items[]` 为驼峰化对象 |
+| `ownTaxNotices` | 欠税公告（QYGL7D9A），`items[]` 为固定映射字段 |
+
+## 线上接口额外字段
+
+经 **QYGLJ1U9** 返回时，在 Build 结果上还会增加（不参与 `BuildReportFromRawSources` 纯构建）：
+
+| 字段 | 说明 |
+|------|------|
+| `reportId` | 报告编号，用于查看页 |
+| `reportUrl` | 报告查看链接 |
+
+## 根对象字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `reportTime` | string | 报告生成时间，`2006-01-02 15:04:05` |
+| `entName` | string | 企业名称（与 `basic.entName` 一致，便于顶层取用） |
+| `creditCode` | string | 统一社会信用代码 |
+| `basic` | object | 主体登记信息，见下节 |
+| `basicList` | array | **可选**。全量 `BASICLIST` 原始数组，有数据时存在 |
+| `branches` | array | 分支机构列表 |
+| `shareholding` | object | 股权与控制 |
+| `controller` | object \| null | 实际控制人 |
+| `beneficiaries` | array | 最终受益人 |
+| `investments` | object | 对外投资汇总 |
+| `guarantees` | array | 对外担保（年报披露摘要） |
+| `management` | object | 人员与组织、从业与社保 |
+| `assets` | object | 资产与经营（按年度摘要） |
+| `licenses` | object | 行政许可、变更、知产出质等 |
+| `activities` | object | 招投标、网站网店等 |
+| `inspections` | array | 抽查检查 |
+| `risks` | object | 风险与合规（含司法、处罚、抵押等） |
+| `timeline` | array | 工商变更时间线 |
+| `listed` | object \| null | 上市信息，无则 `null` |
+| `riskOverview` | object | 综合风险评分与标签（由报告聚合结果计算） |
+| `annualReports` | array | 企业年报（公示）列表，按 `reportYear` 降序 |
+| `taxViolations` | object | `{ total, items[] }` 税收违法 |
+| `ownTaxNotices` | object | `{ total, items[] }` 欠税公告 |
+
+---
+
+## `basic`（主体概览）
+
+由全量 `BASIC` 映射，常见字段：
+
+| 字段 | 说明 |
+|------|------|
+| `entName`、`creditCode`、`regNo`、`orgCode` | 名称、统一码、注册号、组织机构代码 |
+| `entType`、`entTypeCode`、`entityTypeCode` | 企业类型及编码 |
+| `establishDate` | 成立日期 |
+| `registeredCapital`、`regCapCurrency`、`regCapCurrencyCode` | 注册资本及币种 |
+| `regOrg`、`regOrgCode`、`regProvince`、`provinceCode`、`regCity`、`regCityCode`、`regDistrict`、`districtCode` | 登记机关及行政区划 |
+| `address`、`postalCode` | 住所、邮编 |
+| `legalRepresentative` | 法定代表人 |
+| `compositionForm` | 组成形式 |
+| `approvedBusinessItem` | 许可经营项目 |
+| `status`、`statusCode` | 经营状态（中文 / 代码） |
+| `operationPeriodFrom`、`operationPeriodTo` | 营业期限 |
+| `approveDate`、`cancelDate`、`revokeDate`、`cancelReason`、`revokeReason` | 核准、注销、吊销等 |
+| `businessScope` | 经营范围 |
+| `lastAnnuReportYear` | 最后年报年度 |
+| `oldNames` | string[]，曾用名；无则为 `[]` |
+
+---
+
+## `branches[]`
+
+| 字段 | 说明 |
+|------|------|
+| `name`、`regNo`、`creditCode`、`regOrg` | 分支机构名称、注册号、统一码、登记机关 |
+
+---
+
+## `shareholding`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `shareholders` | array | 股东及出资明细 |
+| `shareholderCount` | int | 股东人数 |
+| `registeredCapital`、`currency` | number / string | 注册资本与币种（来自 BASIC） |
+| `topHolderName`、`topHolderPercent` | string / number | 第一大股东及持股比例 |
+| `top5TotalPercent` | number | 前五大股东持股比例合计 |
+| `equityChanges` | array | 股权变更记录 |
+| `equityPledges` | array | 股权出质 |
+| `paidInDetails` | array | 实缴出资明细（年报表） |
+| `subscribedCapitalDetails` | array | 认缴出资明细（年报表） |
+| `hasEquityPledges` | bool | 是否存在股权出质 |
+
+### `shareholders[]` 常见子字段
+
+| 字段 | 说明 |
+|------|------|
+| `name`、`type`、`typeCode` | 股东名称、类型 |
+| `ownershipPercent` | 持股比例 |
+| `subscribedAmount`、`paidAmount` | 认缴额、实缴额 |
+| `subscribedCurrency`、`subscribedCurrencyCode`、`paidCurrency` | 币种 |
+| `subscribedDate`、`paidDate` | 认缴/实缴日期 |
+| `subscribedMethod`、`subscribedMethodCode`、`paidMethod` | 出资方式 |
+| `creditCode`、`regNo` | 股东证件侧代码/注册号 |
+| `isHistory` | 是否历史股东 |
+| `source` | 数据来源说明，如「股权全景」 |
+
+### `equityChanges[]`
+
+| 字段 | 说明 |
+|------|------|
+| `changeDate`、`shareholderName`、`percentBefore`、`percentAfter`、`source` | 变更日期、股东、变更前后比例、来源 |
+
+### `equityPledges[]` / `paidInDetails[]` / `subscribedCapitalDetails[]`
+
+结构与 `qyglj1u9_processor_build.go` 中 `mapEquityPledges`、`mapPaidInDetails`、`mapSubscribedCapitalDetails` 一致（含 `yearReportId`、`investor`、金额日期方式等字段）。
+
+---
+
+## `controller`（可为 `null`）
+
+| 字段 | 说明 |
+|------|------|
+| `id`、`name`、`type`、`percent` | 实控人标识、名称、类型、比例 |
+| `path` | object \| null，`nodes` / `links`，节点上可能含 `entityId`（由 `uid` 复制） |
+| `reason`、`source` | 说明、数据来源 |
+
+---
+
+## `beneficiaries[]`
+
+| 字段 | 说明 |
+|------|------|
+| `id`、`name`、`type`、`typeCode`、`percent`、`path`、`reason`、`source` | 受益人标识、名称、类型、比例、路径、理由、来源 |
+
+---
+
+## `investments`
+
+| 字段 | 说明 |
+|------|------|
+| `totalCount`、`totalAmount` | 对外投资户数、认缴合计（全量路径下） |
+| `list` | 对外投资企业列表 |
+| `legalRepresentativeInvestments` | 法定代表人对外投资（FRINV） |
+
+### `list[]` 常见子字段
+
+`entName`、`creditCode`、`regNo`、`entType`、`regCap`、`regCapCurrency`、`entStatus`、`regOrg`、`establishDate`、`investAmount`、`investCurrency`、`investPercent`、`investMethod`、`isListed`、`source`。
+
+---
+
+## `guarantees[]`
+
+| 字段 | 说明 |
+|------|------|
+| `yearReportId`、`mortgagor`、`creditor`、`principalAmount`、`principalKind`、`guaranteeType`、`periodFrom`、`periodTo`、`guaranteePeriod` | 年报担保摘要 |
+
+---
+
+## `management`
+
+| 字段 | 说明 |
+|------|------|
+| `executives` | array，`name`、`position` |
+| `legalRepresentativeOtherPositions` | array，法人对外任职：`entName`、`position`、`name`、`regNo`、`creditCode`、`entStatus` |
+| `employeeCount`、`femaleEmployeeCount` | 从业人数、女性从业人数（来自最新年报 BASIC 摘要） |
+| `socialSecurity` | object | 社会保险分项参保人数等，**一般为全量 `YEARREPORTSOCSEC` 首条原始对象**（键名多为大写，与数据源一致）；无数据时可能为空对象 `{}` |
+
+---
+
+## `assets`
+
+| 字段 | 说明 |
+|------|------|
+| `years` | array，按年度的资产经营摘要 |
+
+### `assets.years[]`
+
+| 字段 | 说明 |
+|------|------|
+| `year`、`reportDate` | 年度、关联年报标识（实现上取自 `ANCHEID`） |
+| `assetTotal`、`revenueTotal`、`mainBusinessRevenue`、`taxTotal`、`equityTotal`、`profitTotal`、`netProfit`、`liabilityTotal` | 资产、收入、税费、权益、利润、负债等 |
+| `businessStatus`、`mainBusiness` | 经营状态、主营业务 |
+
+---
+
+## `licenses`
+
+| 字段 | 说明 |
+|------|------|
+| `permits` | array，`name`、`valFrom`、`valTo`、`licAnth`、`licItem` |
+| `permitChanges` | array，`changeDate`、`detailBefore`、`detailAfter`、`changeType` |
+| `ipPledges` | array，原始知产出质结构（与全量一致） |
+| `otherLicenses` | array，当前固定为空数组 |
+
+---
+
+## `activities`
+
+| 字段 | 说明 |
+|------|------|
+| `bids` | array，招投标原始项 |
+| `websites` | array，网站或网店（年报表 `YEARREPORTWEBSITEINFO`） |
+
+---
+
+## `inspections[]`
+
+| 字段 | 说明 |
+|------|------|
+| `dataType`、`regOrg`、`inspectDate`、`result` | 抽查类型、机关、日期、结果 |
+
+---
+
+## `risks`
+
+### 标量与汇总
+
+| 字段 | 说明 |
+|------|------|
+| `riskLevel`、`riskScore` | 内部粗算风险等级/分数（与 `riskOverview` 计算方式不同，以 `riskOverview` 为准做展示） |
+| `hasCourtJudgments`、`hasJudicialAssists`、`hasDishonestDebtors`、`hasLimitHighDebtors` | 布尔标志 |
+| `hasAdminPenalty`、`hasException`、`hasSeriousIllegal` | 行政处罚、经营异常、严重违法 |
+| `hasTaxOwing`、`hasSeriousTaxIllegal`、`hasMortgage`、`hasEquityPledges` | 欠税、重大税收违法、动产抵押、股权出质 |
+| `hasQuickCancel` | 简易注销公告 |
+| `dishonestDebtorCount`、`limitHighDebtorCount` | 失信、限高条数 |
+
+### 主要数组 / 对象
+
+| 字段 | 说明 |
+|------|------|
+| `dishonestDebtors` | 失信被执行人（映射后子字段含 `id`、`obligation`、`caseNo`、`execCourt` 等） |
+| `limitHighDebtors` | 限高名单（原始结构数组） |
+| `litigation` | 涉诉汇总，`administrative` / `civil` / … 各类下为 `{ count, cases[] }`，`cases[]` 含 `caseNo`、`court`、`filingDate` 等 |
+| `adminPenalties`、`adminPenaltyUpdates` | 行政处罚及变更 |
+| `exceptions` | 经营异常原始列表 |
+| `seriousIllegals` | 严重违法原始列表 |
+| `mortgages` | 动产抵押（含子数组 `mortgagees`、`collaterals` 等） |
+| `quickCancel`、`liquidation` | 简易注销、清算信息，无则 `null` |
+| `taxRecords` | `{ taxLevelAYears[], seriousTaxIllegal[], taxOwings[] }`（全量税务相关原始切片） |
+| `courtJudgments`、`judicialAssists` | 裁判文书、司法协助（原始结构） |
+
+---
+
+## `timeline[]`
+
+| 字段 | 说明 |
+|------|------|
+| `date`、`type`、`title`、`detailBefore`、`detailAfter`、`source` | 变更日期、事项类型、标题、变更前后、来源 |
+
+---
+
+## `listed`（可为 `null`）
+
+| 字段 | 说明 |
+|------|------|
+| `isListed` | bool |
+| `company` | object，上市主体工商摘要片段 |
+| `stock`、`topShareholders`、`listedManagers` | 股票信息、十大股东、高管（多为原始结构） |
+
+---
+
+## `riskOverview`（综合风险，供页眉/总览）
+
+| 字段 | 说明 |
+|------|------|
+| `riskLevel` | string，`低` / `中` / `高` |
+| `riskScore` | int，0–100 |
+| `tags` | string[]，命中风险点的简短标签 |
+| `items` | array，`{ name, hit }`，各维度是否命中 |
+
+---
+
+## `annualReports[]`
+
+- 每条为 **QYGLDJ12 单条年报**经 **`convertReportKeysToCamel` 递归转小驼峰** 后的对象。
+- 除汇总字段外，常见还包含（名称以驼峰为准）：网站 `reportWebsiteInfo`、股东 `reportShareholderInfo`、对外投资 `reportInvestInfo` 与 `investInfo`、社保 `reportSocialSecurityInfo`、担保 `reportGuaranteeInfo`、股权变更 `reportEquityChangeInfo`、变更 `reportChangeInfo` 等，**具体键集合以接口返回为准**。
+- 页面汇总网格展示的字段集合与 `qyglj1u9_processor_build.go` 中 `mapAnnualReports` 之后、`qiye.html` 内 `sumKeys` 对齐（`investInfo` 仅在详情列表展示，不在顶层网格重复）。
+
+---
+
+## `taxViolations`
+
+```json
+{ "total": 0, "items": [] }
+```
+
+- `total`：条数，缺省时与 `items.length` 一致。
+- `items[]`：**QYGL8848 每条记录键名转驼峰后的对象**。展示层常用字段包括（以实际数据为准）：`entityName`、`taxpayerCode`、`caseType`、`entityCategory`、`illegalFact`、`punishBasis`、`illegalStartDate`、`illegalEndDate`、`illegalTime`、`publishDepartment`、`checkDepartment`、`belongDepartment`、`police`、`agencyPersonInfo` 等。
+
+---
+
+## `ownTaxNotices`
+
+```json
+{ "total": 0, "items": [] }
+```
+
+### `items[]` 固定映射字段
+
+| 字段 | 说明 |
+|------|------|
+| `taxIdNumber` | 纳税人识别号 |
+| `taxpayerName` | 纳税人名称 |
+| `taxCategory` | 欠税税种 |
+| `ownTaxBalance`、`ownTaxAmount`、`newOwnTaxBalance` | 欠税余额、欠税金额、当前新发生欠税余额 |
+| `taxType` | 税务类型（来自原始 `type`） |
+| `publishDate` | 发布日期 |
+| `department` | 主管税务机关 |
+| `location` | 地点 |
+| `legalPersonName` | 法定代表人 |
+| `personIdNumber`、`personIdName` | 证件号码及证件名称字段名 |
+| `taxpayerType`、`regType` | 纳税人类型、登记类型 |
+
+---
+
+## 维护说明
+
+- **字段增删**以 `internal/domains/api/services/processors/qygl/qyglj1u9_processor_build.go` 为准；年报、税收违法条目的细键若接口升级，可能随 `convertReportKeysToCamel` 自动变为新驼峰键。
+- 前端展示标签中文名见 `resources/qiye.html` 中 `keyLabels`（与 Build 字段名对应）。