docs: in-app manuals batch 2 — getting started, activities, metrics, assistant skills, go-live and import (#2329)

.changeset/2329-in-app-docs-batch-2.md

@@ -0,0 +1,15 @@
+---
+"hotcrm": minor
+---
+
+Clause-②: no
+Metadata-protocol: none
+
+**Six more manual pages, each with a Chinese version.** The in-app manuals under **Help** gain the pages a new member and a new administrator reach for first:
+
+- User Manual, Getting Started: **Getting Started — Your First Day** (where HotCRM opens for each role, My Work, the approval inbox, notifications, search, Help) and **Using the Assistant** (what each HotCRM skill of the platform assistant does on ObjectOS Cloud and Enterprise, and which buttons it may press).
+- User Manual, Sales: **Activities** (logging calls and meetings, the activity clock held meetings keep, Schedule Follow-up, tasks, reminders, Do Not Call). The Tasks section of the Opportunities page moves here.
+- User Manual, new **Analytics** group: **Metrics** (what each dashboard measure, tile and report counts, from win rate to quiet accounts).
+- Admin Manual: **Go-Live Checklist** (demo data, people, positions, permission sets, scheduled work, import, checking as a user), which the Admin Manual now opens on, and **Importing Data** (order, the key each row is matched on, suspected duplicate leads, owners, common refusals).
+
+The Automation page's list of AI skills is replaced by a link to Using the Assistant. The metrics, skills and import-matching statements are each checked against the compiled app, so a renamed measure, skill action or import key fails the build until the page follows.

.github/markdown-link-check-config.json

@@ -34,6 +34,18 @@
     {
       "pattern": "^\\./(crm_admin_[a-z_]+\\.md)$",
       "replacement": "{{BASEURL}}/src/docs/$1"
+    },
+    {
+      "pattern": "^\\./(crm_getting_[a-z_]+\\.md)$",
+      "replacement": "{{BASEURL}}/src/docs/$1"
+    },
+    {
+      "pattern": "^\\./(crm_analytics_[a-z_]+\\.md)$",
+      "replacement": "{{BASEURL}}/src/docs/$1"
+    },
+    {
+      "pattern": "^\\./(crm_ai_[a-z_]+\\.md)$",
+      "replacement": "{{BASEURL}}/src/docs/$1"
     }
   ]
 }

src/docs/crm_admin_automation.md

@@ -63,11 +63,9 @@ renewal reminder goes out. The times above are what runs once the switch is on.
 HotCRM ships **skills**, not assistants of its own. The platform provides the
 assistant (ObjectStack ADR-0063: the runtime owns exactly two agents and the
 surface you are in binds one); an app extends it by authoring skills that
-attach by surface affinity. HotCRM's six — live data, lead qualification, case
-triage, email drafting, revenue forecasting, customer 360 — operate over live
-CRM data and reach anything that *changes* state through the same Actions the
-UI buttons use, so permissions and audit are identical. The end user simply
-asks — no agent selection required.
+attach by surface affinity. There is nothing to switch on per skill: which
+skills exist is decided by the app. What each one does, and the buttons it may
+press, is in [Using the Assistant](./crm_ai_skills.md).
 
 ---
 

src/docs/crm_admin_automation.zh.md

@@ -34,7 +34,7 @@ description: 每个自动化门槛和计划时间、定义它的流程、计划
 
 ## AI 技能
 
-HotCRM 提供的是**技能**，而不是自己的助手。助手由平台提供（ObjectStack ADR-0063：运行时只拥有两个智能体，你所在的界面绑定其中一个）；应用通过编写按界面亲和性挂载的技能来扩展它。HotCRM 的六个技能——实时数据、线索资格评估、工单分诊、邮件起草、收入预测、客户 360——在实时 CRM 数据上运行，任何*改变*状态的操作都通过与界面按钮相同的操作完成，所以权限和审计完全一致。最终用户只需直接提问——无需选择智能体。
+HotCRM 提供的是**技能**，而不是自己的助手。助手由平台提供（ObjectStack ADR-0063：运行时只拥有两个智能体，你所在的界面绑定其中一个）；应用通过编写按界面亲和性挂载的技能来扩展它。技能不需要逐个开启：有哪些技能由应用决定。每项技能做什么、可以按哪些按钮，见[使用助手](./crm_ai_skills.md)。
 
 ---
 

src/docs/crm_admin_data_import.md

@@ -0,0 +1,95 @@
+---
+title: Importing Data — Order, Matching & Refusals
+description: The order to import accounts, contacts and leads in, how a row is matched to a record that already exists, and the refusals an import can meet.
+order: 3
+# sources: the import mappings and integrity rules this doc describes. Build
+# ignores unknown frontmatter keys.
+sources:
+  - mapping:crm_account_import
+  - mapping:crm_contact_import
+  - mapping:crm_lead_import
+  - object:crm_account
+  - object:crm_contact
+  - object:crm_lead
+---
+
+# Importing Data — Order, Matching & Refusals
+
+For the administrator loading an existing customer base into HotCRM. This page
+covers what HotCRM does with your rows; the file templates and the step-by-step
+import screens are in the product documentation's import guide.
+
+## Import in this order
+
+1. **Accounts** first.
+2. **Contacts** next: every contact names its account, and the account must
+   already exist.
+3. **Leads** last.
+
+Open **Import** on the **Accounts**, **Contacts** or **Leads** list and upload
+your file. When its columns are the ones HotCRM's template uses, the wizard
+picks the saved mapping HotCRM ships for that object, such as
+**Account Import (CSV)**: it knows the column headings and translates the
+values other systems use, so there is nothing to map by hand. On the last step,
+**Validate data** checks every row and writes nothing; import only once it is
+clean.
+
+An import can be undone from **History** in the same dialog. Undo in the
+reverse order (leads, then contacts, then accounts), so no contact is left
+pointing at an account that is gone.
+
+## A row updates the record it matches
+
+Each saved mapping matches a row to an existing record by a business key:
+
+| Object | Matched on | What that means |
+|---|---|---|
+| **Account** | **Account Name** | A row naming an account that already exists updates it. Account names are unique within your organization. |
+| **Contact** | **Email** | A row whose email already belongs to a contact updates that contact, including the account it sits under. One email address belongs to one contact in your organization. |
+| **Lead** | **Email** | A row whose email already belongs to a lead updates that lead. |
+
+So re-running a corrected file updates rather than duplicates. It also means
+a row is matched to a record you did not mean: if the demo company is still
+in place, a real account that shares a demo account's name updates the demo
+record. Clear the demo records first; see the
+[Go-Live Checklist](./crm_admin_setup.md).
+
+## Leads that repeat someone you know
+
+A lead is never refused for repeating an email address. An import row whose
+email matches an existing lead updates that lead, as above. When a new lead's
+email belongs to a contact instead (or, for a lead created by hand or by a web
+form, to an older lead), the lead is still created, and HotCRM sets its
+**Duplicate Status** to **Suspected** and links it to that record: a contact
+wins over a lead, and the oldest lead over newer ones. Review them in the **Suspected Duplicates** tab on **Leads**. A person
+sets **Confirmed** after checking that the two are the same; nothing is merged
+or deleted on its own.
+
+## Owners
+
+Each file can carry an owner column holding a user's email address.
+
+- An address that matches a user makes that user the owner.
+- An address that matches no user fails the row. Nothing is guessed: invite
+  the user first, or clear the cell.
+- A blank owner makes **you**, the person running the import, the owner. This
+  holds for leads too: imported leads are not spread across the sales reps the
+  way a web-form lead is. Reassign them after the import if they should be.
+
+## Common refusals
+
+A refused row names its row number and the field, so you can fix the file
+and run it again. The ones you will meet most:
+
+- **A required value is missing** — for example a contact without its first
+  name, last name, email or account.
+- **A value is not one of the options** — picklists take HotCRM's own labels or
+  codes, in any letter case, plus the common words other systems use. Anything
+  still unknown fails the row rather than being dropped.
+- **A reference matches nothing** — an account name on a contact, or an owner
+  email, that names no existing record.
+- **A website is not a full address** — write it with `https://`.
+
+Business rules run during an import exactly as they do on a save: a new lead
+gets its follow-up deadline, and a row that breaks a rule the app enforces is
+refused with that rule's own message.

src/docs/crm_admin_data_import.zh.md

@@ -0,0 +1,53 @@
+---
+title: 导入数据——顺序、匹配与拒绝
+description: 客户、联系人和线索按什么顺序导入，一行数据如何匹配到已有记录，以及导入可能遇到的拒绝。
+---
+
+# 导入数据——顺序、匹配与拒绝
+
+写给要把现有客户数据导入 HotCRM 的管理员。本页讲 HotCRM 如何处理你的每一行数据；文件模板和导入界面的逐步操作，见产品文档里的导入指南。
+
+## 按这个顺序导入
+
+1. 先导入**客户**。
+2. 再导入**联系人**：每个联系人都要写明所属客户，而这个客户必须已经存在。
+3. 最后导入**线索**。
+
+在**客户**、**联系人**或**线索**列表上打开**导入**并上传文件。如果文件的列就是 HotCRM 模板里的列，向导会自动选用 HotCRM 为这个对象提供的已保存映射，例如 **Account Import (CSV)**：它认得这些列标题，也会翻译其他系统使用的取值，所以不需要手动映射。在最后一步，**校验数据**会逐行检查且不写入任何内容；校验通过后再导入。
+
+导入可以在同一个对话框的**历史记录**里撤销。请按相反的顺序撤销（先线索、再联系人、最后客户），这样就不会留下指向已删除客户的联系人。
+
+## 一行数据会更新它匹配到的记录
+
+每个已保存映射都按一个业务键把一行数据匹配到已有记录：
+
+| 对象 | 匹配依据 | 含义 |
+|---|---|---|
+| **客户** | **客户名称** | 一行写着已存在客户的名称，就会更新那个客户。客户名称在你的组织内唯一。 |
+| **联系人** | **邮箱** | 一行的邮箱已经属于某个联系人，就会更新那个联系人，包括它所属的客户。一个邮箱地址在你的组织内只属于一个联系人。 |
+| **线索** | **邮箱** | 一行的邮箱已经属于某条线索，就会更新那条线索。 |
+
+所以重新运行一份改正过的文件，会更新而不是重复创建。这也意味着一行可能匹配到你并不想动的记录：如果演示公司还在，一个与演示客户同名的真实客户会更新那条演示记录。请先清理演示记录，见[上线清单](./crm_admin_setup.md)。
+
+## 重复已知人员的线索
+
+线索从来不会因为邮箱重复而被拒绝。导入的一行如果邮箱匹配到已有线索，会像上面说的那样更新那条线索。如果新线索的邮箱属于某个联系人（或者，对于手工或网页表单创建的线索，属于一条更早的线索），线索仍会被创建，HotCRM 会把它的**重复状态**设为**疑似重复**，并关联到那条记录：联系人优先于线索，最早的线索优先于较新的线索。在**线索**的**疑似重复线索**标签页里复核它们。有人核对两条记录确是同一个人之后，再设为**已确认重复**；系统不会自动合并或删除任何记录。
+
+## 负责人
+
+每个文件都可以有一列负责人，填的是用户的邮箱地址。
+
+- 邮箱匹配到某个用户，这个用户就是负责人。
+- 邮箱匹配不到任何用户，这一行会失败。系统不做猜测：先邀请这个用户，或者清空这个单元格。
+- 负责人留空，负责人就是**你**，也就是执行导入的人。线索也是如此：导入的线索不会像网页表单来的线索那样分给各位销售代表。如果需要，导入之后再重新分配。
+
+## 常见的拒绝
+
+被拒绝的行会写明行号和字段，方便你改好文件再运行一次。最常见的几种：
+
+- **缺少必填值**——例如联系人缺少名、姓、邮箱或所属客户。
+- **取值不在选项内**——选项列表接受 HotCRM 自己的标签或代码（不区分大小写），以及其他系统常用的说法。仍然无法识别的取值会让这一行失败，而不是被悄悄丢掉。
+- **引用匹配不到记录**——联系人上的客户名称，或负责人邮箱，找不到对应的已有记录。
+- **网址不完整**——请带上 `https://`。
+
+导入时，业务规则与手工保存时完全一样地运行：新线索会拿到跟进期限；违反应用强制规则的行，会以那条规则自己的提示被拒绝。

src/docs/crm_admin_setup.md

@@ -0,0 +1,99 @@
+---
+title: Go-Live Checklist — Setting HotCRM Up
+description: The order to take HotCRM live in — demo data, people, positions, permission sets, scheduled work and your own data — and what each step changes.
+order: 0
+# sources: the setup surface this doc walks through. Build ignores unknown
+# frontmatter keys.
+sources:
+  - position:crm_positions
+  - permission_set:crm_user
+  - permission_set:system_admin
+---
+
+# Go-Live Checklist — Setting HotCRM Up
+
+For the administrator taking HotCRM live. Work through the steps in order: each
+one relies on the one before it. The rules behind each step (who sees what,
+where each threshold lives) are on the other pages of this manual; this page is
+the order to apply them in.
+
+## 1. Decide about the demo data
+
+A new HotCRM organization is filled with a demo company on its first start:
+accounts, contacts, leads, deals, cases, quotes and the rest, so the dashboards
+have something to show. The demo records are handed to the first
+administrator. There is no switch in Setup for this; the build decides:
+
+- the standard build seeds the demo company into the organization;
+- the multi-organization build gives each new organization the product
+  catalogue and nothing else.
+
+On the standard build, clear out the demo records you do not want **before**
+you import your own: an import matches rows to the records already there, so
+a real account that shares a demo account's name would update the demo record
+instead of creating yours. See [Importing Data](./crm_admin_data_import.md).
+
+## 2. Bring people in
+
+Create your colleagues under **Setup → People & Organization → Users**, or
+invite them under **Invitations**. A new user holds no HotCRM access until the
+next two steps give them some; until then, HotCRM sends them to the platform's
+access page instead of an empty app.
+
+## 3. Give each person a position
+
+Positions decide most of what a person can do, and they drive the automation
+too. Open **Setup → Access Control → Positions**, open a position, and add its
+holders. A person may hold more than one. Holding a position gives its
+permission sets to the holder; a position with no permission set only widens
+which records a holder can see.
+
+Three positions are routing pools, and the automation does nothing useful
+until they are staffed:
+
+- **Sales Representative** — a new lead that arrives with no owner, such as
+  one from a web form, goes to the holder with the fewest open leads.
+- **Service Agent** — new cases with no owner go to the holder with the fewest
+  open cases. While nobody holds it, new cases stay unassigned.
+- **Service Manager** — an escalated case goes to the holder with the fewest
+  open cases.
+
+Two more carry approvals: a **Sales Manager** approves new accounts, lead
+conversions and large deals, and a **Sales Director** also signs off the
+largest deals. Put your regional reps in **NA Sales Team** or **EU Sales Team**
+as well, so they can edit the accounts in their territory.
+What each position opens up is in [Access](./crm_admin_access.md).
+
+## 4. Check the permission sets
+
+Positions hand out the everyday sets. Two sets are worth checking by hand under
+**Setup → Access Control → Permission Sets**:
+
+- **System Administrator** — give it to the people who run HotCRM. It opens
+  this manual and grants list export, which the platform's own administrator
+  access does not.
+- **CRM User** — HotCRM's floor for every member: their own leads, accounts,
+  deals, tasks and events, and read access to products, campaigns and
+  knowledge. Someone who holds no position needs at least this set to work in
+  HotCRM.
+
+## 5. Switch on scheduled work
+
+The daily and hourly sweeps (stalled deals, expiring quotes and contracts, SLA
+breaches, renewal and task reminders) do not run until the deployment switches
+scheduled work on. Until then nothing expires and no reminder goes out. How to
+switch it on, and every schedule it starts, is in
+[Automation](./crm_admin_automation.md).
+
+## 6. Bring in your data
+
+Import accounts first, then contacts, then leads. The order, the matching rules
+and the refusals you may meet are in [Importing Data](./crm_admin_data_import.md).
+
+## 7. Check it as your users
+
+**Setup → People & Organization → Users** lets you impersonate a user from the
+row menu. Sign in as one person of each job and check that HotCRM opens where
+the [Getting Started](./crm_getting_started.md) page says it does for them, and
+that the sidebar shows what they need. An entry missing for someone is almost
+always a position or permission set missing from step 3 or 4.