natlan-web 文档

按读者要做的事分四层（Diátaxis）。先想清楚现在要做什么，再选层。

层	目录	回答的问题	形态
教程	tutorials/	第一次接触，怎么从零跑起来？	手把手、可照做
操作手册	guides/	要完成某个具体任务，步骤是什么？	任务导向、面向目标
参考	reference/	这个接口、配置、字段、表到底是什么？	查得到、求精确
内部原理	internals/	系统为什么这样设计、怎么运转？	解释、给出取舍

教程

文档	内容
从零把四个站跑起来	装依赖、起各站 dev、连后端、构建与检查
走一遍共享组件的改动闭环	改 `ui/` → 文案 → 检查 → 四站波及面

四个站

接口契约

共享组件库 ui/

文档	内容
库总览	定位、目录约定、导入路径、横切模块、样式
组件库契约	宿主契约 + 五条设计准则（为什么组件长这样）
基础件目录	`primitives` / `forms` / `layout` / `feedback` / `data` 的逐组件 props
图表层	`ChartCanvas` 架构、9 个图表组件、4 个自绘插件
复合块	看板、抖动可视化、机群地图

横切

文档	解释什么
单体仓架构	为什么合仓、为什么不用 workspaces、边界与波及面
交互契约	URL 即状态、SWR 轮询、表格基线、确认分级、错误分层
国际化与主题	字典归库/语言归宿主、完整性检查、暗色的两条投递路径
人机验证：自建 Cap 产物	为什么自建、界面与解题器的分界、对 CSP 的要求
授权页为何独立托管	OIDC issuer 的约束、跨源实测、迁移路上验证出的事实

刚加入项目 → 从零跑起来 → 单体仓架构 → 组件库契约

要改一个页面 → 交互契约 → 对应站的参考

要用某个共享组件 → 基础件目录 / 图表层 / 复合块查它的 props

要改共享组件 → 走一遍改动闭环 → 组件库契约 → 加组件检查清单

要发布 → 部署 Worker 站；若改动碰到 ui/ 或授权页 → 再走投放授权界面

线上出问题 → 验证码/CSP 相关看排查手册；接口字段对不上看对应的接口契约

要对接后端 / 改接口 → 控制台接口（含错误 detail 是稳定接口这一条约定）→ 抖动接口

要动视觉 → 品牌与视觉设定（口径）→ 设计令牌（取值）