feat(contact): one structured mailing_address replaces five flat mailing_* fields (#1836)

.changeset/contact-mailing-address-one-field.md

@@ -0,0 +1,29 @@
+---
+'hotcrm': minor
+---
+
+**A contact's mailing address is now one structured field.** `crm_contact` stored its
+address as five separate text fields — `mailing_street`, `mailing_city`, `mailing_state`,
+`mailing_postal_code`, `mailing_country`. It now carries one `mailing_address`
+(`Field.address()`), the same shape as an account's Billing Address and a lead's Address.
+FROM five fields TO one: the contact detail page shows the address as one unit, the
+contact form's Mailing Address tab edits it as one field, and each locale pack carries one
+label instead of five. A report, list view, integration or API client that read or wrote
+`mailing_street` … `mailing_country` must read and write `mailing_address` and its parts
+(`street`, `city`, `state`, `postalCode`, `country`) instead.
+
+**The contact import template does not change.** `assets/import-templates/contacts.csv`
+keeps its five `Mailing …` columns. The `crm_contact_import` mapping now sends each column
+to one part of `mailing_address` (`mailing_address.street` … `mailing_address.country`), so
+a customer's existing file imports exactly as before; a row with all five cells blank
+leaves the address empty.
+
+**Existing deployments: run the one-time conversion after upgrading.** Upgrading does not
+move the old values; the five old columns stay in the database, unused. Run
+`pnpm exec tsx scripts/backfill-contact-mailing-address.ts --url https://<your-org> --email
+<admin> --password <pw>` to see what it will write, then again with `--apply`. It composes
+each contact's `mailing_address` from the non-blank old columns, writes only an empty
+`mailing_address` (an address someone entered after the upgrade is kept and listed), never
+changes or deletes the old columns, and is safe to re-run — a converted org reports nothing
+to do. Run it **before** `os migrate apply --allow-destructive`: that command drops unused
+columns, and with them the only copy of the old addresses.

content/docs/guides/import-and-export.mdx

@@ -38,7 +38,7 @@ A job takes up to **50,000 rows**; split a bigger file. Undo has a tighter ceili
 - **Picklists** — matched against the field's option labels *and* values, case-insensitively, so *Technology* and *technology* both land. The shipped mappings additionally translate the vocabulary other systems export — *SaaS*, *Trade Show*, *Client*. Anything still unrecognised fails its row with `invalid_option` rather than being dropped quietly.
 - **Dates** — `YYYY-MM-DD` is safest.
 - **Numbers** — plain digits (`1500000`, not `1.5M`).
-- **Addresses** — contacts have real mailing-address columns; accounts and leads store an address as one structured field that cannot be assembled out of separate spreadsheet columns. The known limits are listed in [Import your own data](/docs/guides/importing-your-data).
+- **Addresses** — the contact template's five mailing columns fill the parts of the contact's one structured mailing address; the account and lead templates carry no address columns. The known limits are listed in [Import your own data](/docs/guides/importing-your-data).
 
 ### Matching keys — not external IDs
 

content/docs/guides/import-and-export.zh-Hans.mdx

@@ -38,7 +38,7 @@ description: 数据进出 HotCRM 真正落地的那部分——列表视图上
 - **选项列表**——按字段选项的标签*和*值做匹配，不区分大小写，所以 *Technology* 和 *technology* 都能落地。随附的映射还额外翻译其他系统导出时使用的词汇——*SaaS*、*Trade Show*、*Client*。仍然认不出来的值会让该行以 `invalid_option` 失败，而不是被悄悄丢掉。
 - **日期**——`YYYY-MM-DD` 最稳妥。
 - **数字**——纯数字（`1500000`，不是 `1.5M`）。
-- **地址**——联系人有真实的通讯地址列；客户和潜在客户把地址存为一个结构化字段，无法由分散的表格列拼装出来。已知限制列在[导入你自己的数据](/zh-Hans/docs/guides/importing-your-data)。
+- **地址**——联系人模板的五个邮寄地址列分别填入联系人那一个结构化邮寄地址的各个部分；客户和潜在客户的模板不带地址列。已知限制列在[导入你自己的数据](/zh-Hans/docs/guides/importing-your-data)。
 
 ### 匹配键——而不是外部 ID
 

content/docs/guides/import-and-export.zh-Hant.mdx

@@ -40,7 +40,7 @@ description: 資料進出 HotCRM 真正落地的那部分——清單檢視上
 - **選項清單**——按欄位選項的標籤*和*值做比對，不區分大小寫，所以 *Technology* 和 *technology* 都能落地。隨附的對應還額外翻譯其他系統匯出時使用的詞彙——*SaaS*、*Trade Show*、*Client*。仍然認不出來的值會讓該列以 `invalid_option` 失敗，而不是被悄悄丟掉。
 - **日期**——`YYYY-MM-DD` 最穩妥。
 - **數字**——純數字（`1500000`，不是 `1.5M`）。
-- **地址**——聯絡人有真實的通訊地址欄；客戶和潛在客戶把地址存為一個結構化欄位，無法由分散的表格欄拼裝出來。已知限制列在[匯入你自己的資料](/zh-Hant/docs/guides/importing-your-data)。
+- **地址**——聯絡人範本的五個郵寄地址欄分別填入聯絡人那一個結構化郵寄地址的各個部分；客戶和潛在客戶的範本不含地址欄。已知限制列在[匯入你自己的資料](/zh-Hant/docs/guides/importing-your-data)。
 
 ### 比對鍵——而不是外部 ID
 

content/docs/guides/importing-your-data.mdx

@@ -233,14 +233,14 @@ blank and the lead lands as **New**.
 
 ## Known limits
 
-- **Addresses import for contacts only.** Contacts have separate mailing-address
-  fields, so their address columns land. Accounts and leads store their address as
-  one structured field that cannot be assembled from separate spreadsheet columns,
-  and a single joined address string is rejected row by row (*"Billing Address has
-  an invalid address value"*). Those two templates therefore carry no address
-  columns, and adding one to the sheet changes nothing — the mapping only reads the
-  headers it declares. Fill those addresses in after the import, in the record or
-  via the API.
+- **Addresses import for contacts only.** The contact template's five `Mailing …`
+  columns each fill one part — street, city, state/province, postal code, country —
+  of the contact's single structured Mailing Address; a row with all five blank
+  leaves it empty. The account and lead templates carry no address columns, and
+  adding one to the sheet changes nothing — the mapping only reads the headers it
+  declares. A single joined address string is not a way in either: it is rejected
+  row by row (*"Billing Address has an invalid address value"*). Fill those
+  addresses in after the import, in the record or via the API.
 - **50,000 rows per job.** Split a bigger file.
 - **Undo covers 5,000 rows.** Larger imports finish but cannot be rolled back —
   import big data sets in chunks if you want that safety net.

content/docs/guides/importing-your-data.zh-Hans.mdx

@@ -211,11 +211,11 @@ curl -X POST "$HOTCRM/api/v1/data/import/jobs/$JOB_ID/undo" -H "Authorization: B
 
 ## 已知限制
 
-- **地址只对联系人生效。** 联系人有独立的邮寄地址字段，因此地址列可以落库；客户和潜在
-  客户把地址存为一个结构化字段，无法由分散的表格列拼装出来，而拼成一整串地址会被逐行
-  拒绝（*"Billing Address has an invalid address value"*）。所以这两份模板不带地址列，
-  自行往表里加一列也不会有任何效果 —— 映射只读它声明过的表头。请在导入后在记录页或
-  通过 API 补录。
+- **地址只对联系人生效。** 联系人模板的五个 `Mailing …` 列分别填入联系人那一个结构化
+  邮寄地址的一部分（街道、城市、省份、邮政编码、国家）；五列全空的行则不写地址。客户和
+  潜在客户的模板不带地址列，自行往表里加一列也不会有任何效果 —— 映射只读它声明过的表头；
+  拼成一整串地址同样行不通，会被逐行拒绝（*"Billing Address has an invalid address
+  value"*）。请在导入后在记录页或通过 API 补录。
 - **单个作业上限 50,000 行。** 更大的文件请拆分。
 - **撤销上限 5,000 行。** 超过这个规模的导入仍会完成，但无法回滚 —— 想保留这份保险，
   就分批导入。

content/docs/guides/importing-your-data.zh-Hant.mdx

@@ -216,11 +216,11 @@ curl -X POST "$HOTCRM/api/v1/data/import/jobs/$JOB_ID/undo" -H "Authorization: B
 
 ## 已知限制
 
-- **地址僅對聯絡人生效。** 聯絡人有獨立的郵寄地址欄位，因此其地址欄可以匯入；客戶與
-  潛在客戶將地址存為單一結構化欄位，無法由分散的試算表欄位組裝而成，而拼成一整串地址
-  會被逐列拒絕（*"Billing Address has an invalid address value"*）。因此這兩份範本不含
-  地址欄，自行在表中加上也不會有任何效果 —— 對應只讀取它宣告過的標題。請於匯入後在
-  記錄頁或以 API 補登。
+- **地址僅對聯絡人生效。** 聯絡人範本的五個 `Mailing …` 欄分別填入聯絡人那一個結構化
+  郵寄地址的一部分（街道、城市、省份、郵政編碼、國家）；五欄全空的列則不寫入地址。客戶
+  與潛在客戶的範本不含地址欄，自行在表中加上也不會有任何效果 —— 對應只讀取它宣告過的
+  標題；拼成一整串地址同樣行不通，會被逐列拒絕（*"Billing Address has an invalid
+  address value"*）。請於匯入後在記錄頁或以 API 補登。
 - **每個作業上限 50,000 列。** 更大的檔案請拆分。
 - **復原上限 5,000 列。** 超過此規模的匯入仍會完成，但無法回復 —— 若想保留這道保險，
   請分批匯入。

content/docs/sales/contacts.mdx

@@ -17,7 +17,7 @@ The contact detail screen has 7 collapsible sections:
 | **Account & Title** | Contact owner, account, job title, department |
 | **Buying Centre** | Buying function, attitude to us, relationship strength — see [The Buying Centre](./buying-centre) |
 | **Contact Information** | Email, phone, mobile |
-| **Mailing Address** | Mailing street, city, state/province, postal code and country — five separate fields |
+| **Mailing Address** | One structured mailing address — street, city, state/province, postal code and country kept together as a single field |
 | **Additional Info** | Lead source, description, last contacted |
 | **Communication Preferences** | Primary contact flag, do-not-call, email opt-out |
 

content/docs/sales/contacts.zh-Hans.mdx

@@ -17,7 +17,7 @@ description: 你向其销售并为其提供服务的客户处的人——决策
 | **客户与职务** | 联系人负责人、所属客户、职位、部门 |
 | **采购决策圈** | 采购角色、对我司态度、与销售关系强度——见[采购决策圈](./buying-centre) |
 | **联系方式** | 邮箱、电话、手机 |
-| **邮寄地址** | 邮寄地址、邮寄城市、邮寄省份、邮政编码、邮寄国家（五个独立字段） |
+| **邮寄地址** | 一个结构化的邮寄地址字段——街道、城市、省份、邮政编码、国家作为一个整体保存 |
 | **附加信息** | 线索来源、描述、最近联系时间 |
 | **沟通偏好** | 主要联系人、禁止致电、拒绝邮件 |
 

content/docs/sales/contacts.zh-Hant.mdx

@@ -19,7 +19,7 @@ description: 你向其銷售並為其提供服務的客戶處的人——決策
 | **客戶與職務** | 聯絡人負責人、所屬客戶、職位、部門 |
 | **採購決策圈** | 採購角色、對我司態度、與銷售關係強度——見[採購決策圈](./buying-centre) |
 | **聯絡方式** | 郵箱、電話、手機 |
-| **郵寄地址** | 郵寄地址、郵寄城市、郵寄省份、郵政編碼、郵寄國家（五個獨立欄位） |
+| **郵寄地址** | 一個結構化的郵寄地址欄位——街道、城市、省份、郵政編碼、國家作為一個整體儲存 |
 | **附加資訊** | 線索來源、描述、最近聯絡時間 |
 | **溝通偏好** | 主要聯絡人、禁止致電、拒絕郵件 |
 

docs/STATUS.md

@@ -19,7 +19,7 @@ loader registers:
 
 ```text
 HotCRM v3.1.0
-Data: 18 Objects  363 Fields
+Data: 18 Objects  359 Fields
 UI: 1 Apps  14 Views  8 Pages  5 Dashboards  10 Reports  31 Actions
 Logic: 32 Flows
 Security: 12 Positions  7 Permissions

docs/requirements/0004-contact-buying-centre-map.md

@@ -30,7 +30,7 @@ Read the step's noun list against the object and it splits cleanly in two.
 
 **Already there.** 姓名 — `salutation` + `first_name` + `last_name`, with the `full_name`
 formula as the record title. 部门 — `department`, a select. 职务 — `title`. 联系方式 — `email`,
-`phone`, `mobile` and the structured `mailing_*` block. The record also already carries
+`phone`, `mobile` and the mailing address (one `mailing_address` field since #1836). The record also already carries
 `crm_account` as a master-detail parent, so every contact is anchored to the account whose
 buying centre it belongs to, plus `is_primary`, `do_not_call` / `email_opt_out` and
 `last_contacted_date`.