Skip to content

docs(guides): email-and-calendar 按实测改写——Log a Call 的三写路径、活动指标所在仪表盘、连接器段落标注未落地 (#738) - #755

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-738-email-calendar-log-call
Aug 5, 2026
Merged

docs(guides): email-and-calendar 按实测改写——Log a Call 的三写路径、活动指标所在仪表盘、连接器段落标注未落地 (#738)#755
yinlianghui merged 1 commit into
mainfrom
claude/issue-738-email-calendar-log-call

Conversation

@yinlianghui

@yinlianghui yinlianghui commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Fixes #738

前提核实（对 origin/main 实测）

issue 的前提成立。src/actions/global.actions.ts 的 log_call 一次提交写三样东西，页面上写的还是 #592 之前的行为：

  • crm_event 插入（第 281-299 行）：subject / type / status='held' / start_datetime / owner_id / related_to_type + related_to_* 关联，duration_minutes / location / description 按填写补上；
  • crm_event_attendee 逐行插入（第 311-341 行）：发起人 is_organizer: true, response: 'accepted'；从联系人/线索记录触发时目标记录自身入列；表单选中的 attendee_contacts / attendee_users 各成一行，按 type:id 去重；
  • sys_activity 只作 ADR-0052 指针（第 348-365 行）：source_object: 'crm_event' / source_id，metadata 里只剩 attendee_count，不再塞参会人名单。

改写后的段落只讲这三条并把完整模型交给 content/docs/sales/meetings-and-calls.mdx（#737 落地），不复制它的表格。

两处待核实项：都不成立，同 PR 修掉

1）「counted in the rep's activity metrics on the Sales / Service dashboards」——错。

按 src/dashboards/*.dashboard.ts 逐个数据集清点：

仪表盘 绑定的数据集
sales_dashboard opportunity_metrics、forecast_metrics
service_dashboard case_metrics
sales_activity_dashboard（label Sales Activity） event_metrics、task_metrics、account_metrics、opportunity_metrics

event_metrics（src/datasets/event.dataset.ts，object: 'crm_event'）只被 activity.dashboard.ts 消费，销售/服务两个仪表盘上没有任何活动磁贴。页面改为指向 Sales Activity 上真实存在的磁贴：Interactions Logged、Customer Minutes、Activity by Rep、Activity Mix。（同类问题在 activities.mdx 上已有 #747 在排队，那页不在本 PR 文件面内。）

2）连接器段落——同样不成立，且不止「Calendar sync / Email tracking / Inbound case email」三段。

src/ 里没有任何连接器元数据：grep gmail|outlook|connector 只命中线索评分里的免费邮箱正则、产品目录种子里的 "Integration Connector Pack" 商品，以及 flow 注释。平台侧 @objectstack/plugin-email@17.0.0-rc.2 自述是 "transport-pluggable outbound delivery with sys_email persistence"，sys_email 的 status 只有 queued | sent | failed（没有页面写的「已退信」），未配置 provider 时 resolveTransport 回落到 LogTransport 并打印 "no transport configured — using LogTransport (mail will NOT be sent)"。入站、双向同步、追踪像素、定时发送在平台和应用两侧都不存在。

因此把「连接收件箱 / 邮件记录的工作原理 / 邮件追踪 / 日历同步 / 入站工单邮件 / 邮件模板」六段的标题统一标注 (not shipped yet)，段内保留设计意图并明说今天没有，链到 whats-new 的 roadmap。这是仓库既有的处理方式，不是我新发明的：guides/mobile.mdx:10 用同一形态的 callout 处理原生 App，whats-new.mdx 的 "Wow #3 — Honest about what's in the box" 把「设计了、在路线图上、v1 不发」明确写成产品文档的标准姿势。若维护者更希望直接删段而不是标注，请在 review 里说一声，这是一次 sed 的事。

顺带按实测校正的、同一页上的其它断言

  • Send Email：只注册在 crm_contact（src/actions/contact.actions.ts:46，objectName: 'crm_contact'），页面原文说「联系人、工单、商机上都有」；visible: record.email_opt_out == false；写 sys_email（status queued）+ 指向它的 sys_activity 指针（summary 为 Email: 加主题），并顺手盖 crm_contact.last_contacted_date 与父客户的 crm_account.last_activity_date。原文的「回复经双向同步串回同一条记录」「投递状态含已退信」「Settings → System Email Queue」均无依据，已改写/删除。
  • AI 段：src/skills/email-drafting.skill.ts 明确只起草不发送（无 ai 块 ⇒ 不物化 action_send_email 工具），页面原文「点击发送，邮件通过你已连接的收件箱发出」与之相反。同时按 Docs drift (round 2 leftovers): ~39 product pages still name "Sales/Service Copilot" as a persona; config comment and RELEASE_STRATEGY.md still stale #612 去掉 "AI Copilot" 人格化称谓，统一为 AI 助手。
  • 孤儿段落：「Save reusable email templates…」这一块在三语页面里都没有标题（夹在 Log a Call 段尾），读起来像 Log a Call 的一部分；本 PR 给了它标题并标注未落地。
  • 隐私段：Delete Personal Data 操作在 src/ 中不存在，地址/域名排除也不存在，已按实际可做的路径改写。

关于反向验证

这一页的散文断言没有门禁覆盖（test/docs-object-coverage.test.ts 只保证每个 crm_* 对象有一页文档），所以不存在「改前红、改后绿」的检查可展示，这里不编造一个。能拿到的真实反向验证是三语一致性那条：临时删掉 zh-Hans 页的一个 callout 后 test/docs-drift.test.ts 按预期变红并点名本页（email-and-calendar.zh-Hans.mdx: 1 callout(s), but ... has 2），恢复后 31 passed——说明本次三语同改确实被现有门禁盯着。

验证

  • pnpm hygiene && pnpm test：62 files / 1475 passed, 1 skipped
  • pnpm typecheck：clean
  • npx vitest run test/docs-drift.test.ts test/docs-object-coverage.test.ts：2 files / 53 passed
  • 控制字符自查：grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 三页均干净

文件面

content/docs/guides/email-and-calendar.mdx + zh-Hans / zh-Hant + 一个 changeset。没有碰 content/docs/sales/**、src/**、测试与 content/docs/releases/。

越界发现另行记录（见下方 issue 链接）：content/docs/guides/index.mdx 的本页描述行仍写「Connect Gmail / Outlook, two-way sync, email tracking」，content/docs/guides/integrations.mdx 的连接器表把 Gmail/Outlook 及另外九类连接器都列为「Built-in」——与本页同一类问题，均不在本 PR 文件面内。

🤖 Generated with Claude Code

https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa

Generated by Claude Code

@claude
docs(guides): restate email-and-calendar against the shipped write pa…
34040b3 
…th (#738)

"Log a Call" still described the pre-event behaviour: one `sys_activity` row
of kind *call*. The action writes three things — a `crm_event`, one
`crm_event_attendee` row per person, and an ADR-0052 activity pointer at the
event — so the section now says that and hands the full model to
sales/meetings-and-calls instead of restating its tables.

Two further claims on the page, measured against src/:

- activity metrics live on `sales_activity_dashboard` (event_metrics over
  crm_event), not on sales_dashboard / service_dashboard, which bind only
  opportunity_metrics / forecast_metrics and case_metrics;
- the inbox and calendar connector sections (Gmail/Outlook connect, two-way
  email and calendar sync, open/click tracking, scheduled send, inbound case
  email, email templates) have no metadata behind them, and the platform ships
  outbound delivery only (@objectstack/plugin-email, sys_email statuses
  queued/sent/failed, default LogTransport). Each such section is marked
  "(not shipped yet)" and points at the roadmap, per the mobile.mdx and
  whats-new "honest about what's in the box" precedent.

Send Email, AI drafting, call logging and the privacy section are restated
from the metadata: the action is registered on crm_contact only, the timeline
entry is a pointer at the sys_email row, and the drafting skill has no send
tool. zh-Hans / zh-Hant carry the same content.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa
@vercel

vercel Bot commented Aug 5, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
hotcrm Ignored Ignored Aug 5, 2026 5:50pm

Request Review

This was referenced Aug 5, 2026
Closed
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 5, 2026 17:53
@yinlianghui yinlianghui mentioned this pull request Aug 5, 2026
Closed
@yinlianghui
yinlianghui added this pull request to the merge queue Aug 5, 2026
Merged via the queue into main with commit 3388d2c Aug 5, 2026
9 checks passed
This was referenced Aug 5, 2026
Merged
Closed
Closed
Closed
Merged
Merged
Closed
Merged
Closed
Closed
Closed
Merged
github-merge-queue Bot pushed a commit that referenced this pull request Aug 6, 2026
@yinlianghui @claude
docs: fix two dangling in-page anchors (#749, #764) (#868)
9e151de 
sla-and-escalation linked /docs/administration/automation#case-escalation in
all three locales, but the automation page has no "Case Escalation" heading —
"Case Escalation Process" is a row in the table under "## Flows (multi-step)".
English now links #flows-multi-step; the Chinese pages drop the anchor because
their heading is 流程（多步骤）/ 流程（多步驟）, whose slug differs.

guides/mobile in Chinese linked whats-new#roadmap while the translated heading
is 路线图 / 路線圖 — heading translated, anchor not. Both drop the anchor,
matching PR #755 / #762. English keeps #roadmap, which resolves.

Co-authored-by: Claude <noreply@anthropic.com>
This was referenced Aug 6, 2026
Merged
Closed
Closed
Merged
Merged
Merged
yinlianghui added a commit to yinlianghui/hotcrm that referenced this pull request Aug 10, 2026
@yinlianghui @claude
docs(guides): 按实际落地能力重述 integrations 页，并校正指南索引描述行 (objectstack-ai#756) (
0683288 
objectstack-ai#762)

`guides/integrations.mdx` 把 10 类连接器列为「Built-in」，每行还给了一个
`Setup → Integrations → X` 的菜单路径。对着源码实测：`src/` 里没有任何连接器
元数据，平台包里也没有任何一家厂商的连接器插件，应用里更没有
`Setup → Integrations` 菜单——这些设置路径把读者指向了一个不存在的界面，是本页
最具误导性的部分。

按 objectstack-ai#755 确立的姿态处理：整表作为设计意图保留并标注「尚未落地」、链到路线图
（路线图上本来就写着「更多连接器」），同时给表格加第三列，逐行写明今天最接近的
落地能力。

其余各节同样逐条实测：

- **Webhooks** 是本页唯一真实的能力，而且原文错在另一个方向：
  `@objectstack/plugin-webhooks` 确实提供出站 webhook 服务，但 HotCRM 从未启用它
  —— `objectstack.config.ts` 的 `requires` 里没有 `webhooks`，它也不属于平台对每个
  应用都会加载的那一批能力，本应用也没有声明任何 webhook。现在改述为一个部署侧的
  决定，重试次数 / 载荷结构 / 投递日志这些细节交还给平台自己的文档。
- **GraphQL** 删除：它不在产品规划内，平台已把 `/graphql` 从服务表移除。杜撰的
  `POST /api/v1/leads` 示例一并删除——对象名是 `crm_lead`，路由形态取决于运行时版本。
- **事件总线**（Kafka / EventBridge / Pub-Sub）、**密钥存储**（Vault / AWS Secrets
  Manager / GCP Secret Manager、90 天 OAuth 轮换）与原生 **`*.connector.ts` 插件**
  形态在平台能力清单里都没有对应词条，各自标注「尚未落地」，并点明真正相邻的机制
  （记录变更流程、`secret` 字段失败关闭地加密写入 `sys_secret`、钩子 / 流程 / 操作体）。
- 新增 **今天已落地的能力** 一节：HTTP 数据 API、客户 / 联系人 / 线索 / 商机列表视图
  的 CSV / XLSX 导出、电子表格导入、出站发送邮件，以及 `notify` 节点的应用内通知。

指南索引里 **邮件与日历** 和 **集成** 两行随之改写：邮件行原先仍写着
「连接 Gmail / Outlook、双向同步、邮件追踪」，而该页自己已经把这些标为尚未落地。

zh-Hans / zh-Hant 同步。


Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa

Co-authored-by: Claude <noreply@anthropic.com>
yinlianghui added a commit to yinlianghui/hotcrm that referenced this pull request Aug 10, 2026
@yinlianghui @claude
docs(guides): import-and-export 按实测改写——导入向导在列表视图而非 Setup → Data，Sales…
131daf9 
…force 迁移标注未落地 (objectstack-ai#763) (objectstack-ai#797)

* docs(guides): import-and-export 按实测改写——导入向导在列表视图而非 Setup → Data，Salesforce 迁移标注未落地 (objectstack-ai#763)

`Setup → Data` 分组根本不存在(Setup 应用只有 Overview/Apps/People &
Organization/Access Control/Approvals/Configuration/Diagnostics/Integrations/
Advanced 九组),因此本页几乎每一步指向的都是不存在的界面。

但 issue「Import Wizard 不存在」这一条不成立:Console 的 object grid 确实
随附导入向导,入口在对象列表视图工具栏的 Import,并通过
`listImportMappings` → `meta.getItems('mapping')` 按 targetObject 列出本应用
自己的三个具名映射——与 importing-your-data.mdx 的 API 路线是同一条服务端
通路的两端。已按此改写,两页互链。

未落地的部分(Salesforce 迁移向导、OAuth、定时导出、数据主体请求)按
objectstack-ai#755/objectstack-ai#756 先例标注「尚未落地」并保留设计意图;能落地的部分对着
exportOptions、allowExport 授权与真实向导步骤重写。三语同改。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa

* docs: 把 changeset 里的站内路径从 markdown 链接改为纯文本 (objectstack-ai#763)

CI 的 link-check(gaurav-nelson/github-action-markdown-link-check)扫描面是
`.md`,`.changeset/*.md` 在内;它把 `[...](...)` 里的路径当 URL 校验,而
`/docs/guides/importing-your-data` 这样的站内根相对路径无法解析 →
Status: 400 / ERROR: 1 dead links found!。config 的 ignorePatterns 也没有
覆盖根相对路径。

本地首轮只核了 .mdx 页,因此没撞上这条。改为反引号纯文本;三个 mdx 页里的
站内链接不受影响(那些是 .mdx,不在该 action 的扫描面内)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

content/docs/guides/email-and-calendar.mdx 的 "Log a Call" 段仍描述 #592 之前的写入行为（只写 sys_activity，没有 event/参会人）

2 participants

@yinlianghui @claude