openxiangda-skill-kit 2.0.0-alpha.39 → 2.0.0-alpha.47

package/docs/field-components.md

@@ -1,93 +0,0 @@
-# 平台字段组件使用指南
-
-OpenXiangda 2.0 应用的持久化表单字段统一使用 `openxiangda-field-kit`。桌面端从
-`openxiangda-field-kit/desktop` 导入，移动端从 `openxiangda-field-kit/mobile` 导入；列表、
-详情和只读状态使用对应的 `FieldValue`。应用可以自由组合页面，但不要在业务页面重新实现字段值、
-文件上传、人员部门目录、地址、定位或签名协议。
-
-## 基本用法
-
-```tsx
-import { DesktopFieldControl, DesktopFieldValue } from 'openxiangda-field-kit/desktop';
-
-<DesktopFieldControl
-  definition={{ code: 'amount', label: '预算金额', kind: 'money', precision: 2 }}
-  value={values.amount}
-  onChange={amount => setValues(current => ({ ...current, amount }))}
-/>
-
-<DesktopFieldValue
-  definition={{ code: 'amount', label: '预算金额', kind: 'money', precision: 2 }}
-  value={values.amount}
-/>
-```
-
-移动端替换为 `MobileFieldControl` 与 `MobileFieldValue`。平台目录、地址、定位和文件字段还需要传入
-当前应用的 `FieldPlatformContext`；标准 Admin/User 页面已经自动提供。
-
-常用体验配置继续沿用 1.0 的语义：文本支持 `maxLength`、`showCount`、前后缀和清空；数值支持
-`min`、`max`、`step`、`precision`、单位位置和千分位；日期支持今天之前、今天之后或自定义区间；
-多选支持 `maxCount`，子表支持 `minRows` / `maxRows`。这些都是页面行为，不改变 2.0 稳定值协议。
-标准模板锁定 Ant Design 的尺寸、圆角和密度，不开放会造成三端样式分裂的任意 `variant` / `size` 覆盖。
-
-## 什么时候使用哪个组件
-
-| 需求 | 使用 | 不应使用 |
-| --- | --- | --- |
-| 标题、名称、编号 | `text` | 不用富文本 |
-| 多行纯文本说明 | `textarea` | 不需要格式时不用 `richtext` |
-| 表格、链接、图片和带格式正文 | `richtext` | 简单备注不用它 |
-| 数量、金额、比例 | `number` / `money` / `percent` | 不用文本保存可计算数值 |
-| 少量互斥选项 | `radio` | 选项很多时用 `option` |
-| 少量并列多选 | `checkbox` | 选项很多时用 `options` |
-| 平台成员与组织 | `user(s)` / `department(s)` | 不用自由文本或复制组织树 |
-| 邮寄或行政区地址 | `address` | 需要经纬度时用 `location` |
-| 现场打点、签到 | `location` | 普通地址填写不用定位 |
-| 任意类型文件 | `attachments` | 只收图片时使用 `images` |
-| 照片、截图、凭证 | `images` | 不要直接使用 Ant Upload |
-| 同一表单的多行明细 | `subtable` | 独立生命周期的大量记录应建资源页面 |
-| 现场手写确认 | `signature` | 法律电子签章接专业签署服务 |
-| 流程状态展示 | `workflowStatus` | 不允许页面直接编辑流程状态 |
-
-完整机器可读清单由 `fieldCatalog` 导出，包含每个 `FieldKind` 的值协议、适用和不适用场景。
-
-关联表单组件已经弃用。普通关联选择使用 `option`、`radio` 或文本；需要分页检索、复杂权限和业务
-联动时，由应用通过 NestJS App API 实现独立页面，不把业务查询重新塞进通用字段组件。
-
-## 附件和图片
-
-DataResource 中对应字段必须声明为 `type: 'file'`。组件保留 1.0 已验证的上传、进度、取消、失败
-重试、预览、下载和删除交互；底层由一个 `fileService` 调用 2.0 Native Files API。应用不接触
-`initiate → PUT → complete → delete-unbound` 细节，也不要拼接对象存储地址。
-
-```ts
-{ code: 'attachments', type: 'file', nullable: true,
-  file: { multiple: true, maxCount: 10, maxSizeMb: 50 } }
-```
-
-同名文件不会合并；只按平台 `fileId` 或稳定 URL 去重。图片字段可以配置 `imageCompression`，但页面
-不能放宽 DataResource 已声明的数量、类型和大小限制。
-
-## 富文本图片
-
-富文本本身仍保存清洗后的 HTML 字符串。需要上传内嵌图片时，把 `richTextImageFieldCode` 指向同一
-资源中真实的 `file` 字段；标准表单会把上传结果追加到该文件字段，确保记录保存时完成文件绑定。
-
-```ts
-{
-  code: 'description',
-  label: '详细说明',
-  kind: 'richtext',
-  richTextToolbar: 'full',
-  richTextImageFieldCode: 'images',
-}
-```
-
-没有配置伴随文件字段时，桌面编辑器仍支持图片 URL，但不会开放本地图片上传。
-
-## 验收要求
-
-- 编辑、禁用、只读和空值均可用。
-- 必填标识紧邻标签；提交失败定位到第一个错误字段。
-- Desktop 与 Mobile 使用独立 renderer，移动入口不加载桌面 Ant Design 录入控件。
-- 附件、图片、富文本、人员、部门、地址、定位和签名必须在标准模板真实保存后回显。

package/docs/frontend.md

@@ -1,78 +0,0 @@
-# 前端架构
-
-状态：2026-08-16 桌面 Admin 已发布；独立移动用户端标准页面包和生成模板双入口已经实现，移动 Chromium 已覆盖身份、数据与流程提交主链路。旧自研 Shell 与 Vite 模板已经删除，企业采购参考应用已通过类型检查、测试、Umi production build 与桌面/移动 Chromium 验收。完整决策见[Ant Design Pro v6 Admin 全量切换](/architecture/ant-design-pro-v6-admin-foundation)、[移动用户端标准页面](/architecture/mobile-user-standard-pages-v2)，状态证据见[实施路线图](/architecture/implementation-roadmap)。
-
-## 默认技术栈
-
-OpenXiangda 2.0 桌面管理端采用 React 19、Ant Design 6、Umi Max 4、ProComponents 3 与 utoopack。`openxiangda-admin` 是平台集成层，不重复实现一套后台组件库：
-
-- ProLayout：应用壳、菜单、页头与桌面导航；
-- PageContainer：统一页面层级和主操作；
-- ProTable：服务端搜索、排序、分页和列配置；
-- ProForm：数据表单和流程业务表单；
-- Descriptions / ProCard：详情、审计与流程摘要；
-- ECharts：当前角色权限内的聚合指标与趋势。
-
-应用不得建立第二套身份存储、权限判断、查询 DSL 或业务数据缓存。前端 capability 只负责界面裁剪，Data API、App API 与 Workflow API 始终在服务端授权。
-
-## 路由、菜单与标签
-
-应用页面路径、组件、标题、菜单、capability 与标签属性来自一份 `applicationRoutes`。Umi route 与 ProLayout metadata 从它派生；重复路径和 fallback 漂移在 check/build 阶段失败。未来由 `openxiangda generate` 生成时也只能替换这个单一事实源。
-
-`AdminLayout` 提供最多 12 个会话标签。标签只保存路径、标题和打开顺序，并按平台 `identityScope` 隔离；不保存 Token、授权结论、表单草稿或业务响应。切换稳定角色会更新 identity epoch 并重新建立页面上下文。当前版本没有伪装成缓存的隐藏 keep-alive 实例池；需要真实保活时必须另行设计资源上限和失效协议。
-
-## 身份与平台访问
-
-- `OpenXiangdaAdminProvider` 从平台读取 Principal、RoleSession、角色绑定和 capability。
-- 多角色用户每次只使用一个稳定角色，不隐式合并权限。
-- 应用管理员由平台授予最高能力，前端不按角色名称硬编码绕过。
-- `useOpenXiangdaAdmin().appApi()` 通过平台同源网关调用当前环境 NestJS 后端；浏览器不保存集群 Service 地址和 Token。
-- Data API 客户端始终携带当前 RoleSession，并使用服务端分页、筛选、排序与 revision/CAS。
-
-## 标准页面
-
-### 工作台
-
-`WorkbenchPage` 按“关键指标、趋势、快捷入口”组织中低密度首页。生产指标必须来自当前 RoleSession 下的服务端受限聚合；参考应用的本地种子统计仅用于开发验收。
-
-### 数据管理
-
-`ResourceTablePage` 使用 ProTable 提供页面标题、新建主操作、显式搜索、服务端列表、分页、排序、列设置和权限化操作。`ResourcePageDefinition` 只描述页面字段与交互；DataResource 继续只描述数据库字段、类型、索引、文件约束与 Data API 能力。
-
-`ResourceFormPage` 提供独立新建/编辑页面，使用 revision/CAS 保存。`ResourceDetailPage` 展示平台字段渲染、附件和审计时间线。列表也可默认使用轻量 Modal/Drawer；业务拥有独立流程入口时可以关闭通用 create/update/delete，避免绕过业务后端。
-
-### 流程提交
-
-`WorkflowSubmissionPage` 默认只展示业务表单和“提交”。点击后先经 Data API/App API 保存业务记录，再调用 Kernel prepare，并在 Modal 中显示真实审批路径和必要的主部门/审批人选择。用户确认后才消费 preparation token 发起流程；审批预览不常驻页面，Workflow Kernel 不保存业务字段。
-
-### 工作中心、任务与实例
-
-`WorkflowWorkCenterPage` 显示当前稳定角色的待办、已处理与我发起。`WorkflowTaskPage` / `WorkflowInstancePage` 解释后端 Surface 的流程信息、业务数据、审计时间线与允许操作；同意、拒绝、退回、转交、代理和加签仍由 Kernel 做并发与权限判定。
-
-应用领域动作使用 `loadAppActions` 加载 `app_action`，使用 `executeAppAction` 调用 NestJS App API。自定义动作不能覆盖 Kernel 同名操作；加载失败只关闭业务动作，不阻断标准审批。
-
-## Field Kit 与移动用户端
-
-所有平台字段使用 `openxiangda-field-kit` 的稳定值协议。人员、部门、单选、多选、单选框、复选框、日期、日期区间、地址、图片、附件、富文本和数值等都由统一定义驱动存储与显示。组件选型见[平台字段组件使用指南](./field-components.md)。
-
-- 桌面 Admin 从 `openxiangda-field-kit/desktop` 使用 Ant Design 控件。
-- 移动用户端由 `openxiangda-user/mobile` 提供工作台、数据列表/表单/详情和流程提交/任务/实例页面，并从 `openxiangda-field-kit/mobile` 使用 Ant Design Mobile 的独立字段交互；不把桌面 Select、DatePicker 或 Cascader 缩小后复用。
-- 人员、部门、行政区、上传、下载和预览都通过平台 API；应用不自行复制平台目录或文件协议。关联表单平台组件已弃用，复杂关联查询由应用页面和 App API 实现。
-- UI 必填、默认值、显隐、布局和帮助文本属于页面层；后端业务不应假设自定义页面一定执行了前端校验。
-
-生成模板将桌面 Admin 与移动用户端放在同一个 AppPackage 的两个独立懒加载路由树中；`/admin` 只加载 Pro 页面，`/m` 只加载 `openxiangda-user/mobile`，根入口按设备能力一次性选择。移动 Chromium 已验证两棵树不混用 DOM，并覆盖稳定角色切换、列表/详情、流程发起与平台特殊字段。
-
-## 本地开发与门禁
-
-```bash
-openxiangda dev
-openxiangda generate
-openxiangda check
-openxiangda test
-pnpm --filter @app/web test:e2e
-pnpm --filter @app/web build
-```
-
-CLI 同时监督 Umi、NestJS、本地平台与工作区 PostgreSQL。UI-only 只用于非持久化界面预览。桌面 Chromium 链路覆盖工作台、菜单、标签、角色切换、数据列表/详情、供应商标准表单、流程工作中心、单按钮流程提交与个人中心；移动 Chromium 链路覆盖自动入口、独立 UI 树、角色切换、数据列表/详情、流程发起和平台字段。两条链路都断言没有浏览器运行时错误。
-
-生产构建分别约束首屏脚本、异步 chunk 的 gzip/原始体积与开发标记；不得包含模板假用户、Umi Mock、开发 Secret、Vite 或旧 AdminShell。

package/docs/getting-started.md

@@ -1,148 +0,0 @@
-# 开始开发
-
-## 创建应用
-
-```bash
-openxiangda app create my-app --app-code my-app --name "My App" --install
-cd my-app
-openxiangda skill install
-openxiangda auth login --base-url https://platform.example.com
-openxiangda app link --base-url https://platform.example.com
-openxiangda app provision
-openxiangda app info
-```
-
-开发 2.0 工具链本身时，不需要先发布 alpha 包。创建一个独立验收应用并把依赖链接到本地源码：
-
-```bash
-openxiangda app create ../my-local-validation \
-  --app-code my-local-validation \
-  --name "Local Validation" \
-  --local-sdk /absolute/path/to/openxiangda-v2 \
-  --install
-```
-
-带 `--install` 时，创建器先写依赖映射并安装，再执行确定性契约生成；新应用第一次执行 `generate --check` 就应通过。省略 `--install` 时结果会标记 `generationDeferred: true`，需要先运行 `pnpm install`，再运行 `openxiangda generate`。`--local-sdk` 会先把本地 2.0 SDK 构建为 `.openxiangda/local-sdk-artifacts/` 下的 npm tarball，再写入机器相关的 pnpm `file:` overrides；它只用于可丢弃的本地验收应用。tarball 与正式发包采用同一依赖归一化规则，避免源码符号链接把第二份 React/NestJS 运行时带入应用进程。
-
-应用始终调用工作区本地 `openxiangda-cli`；本地依赖未安装时直接失败，不存在 1.x 回退。`skill install` 会同时安装领域 Skills 与其引用的 2.0 参考文档。
-
-创建结果是普通 pnpm workspace：
-
-```text
-apps/web                 React + Ant Design
-apps/server              NestJS
-packages/domain          业务类型与规则
-packages/contracts       平台生成契约
-openxiangda.config.ts    应用级平台声明
-```
-
-## 日常循环
-
-```bash
-openxiangda dev
-openxiangda dev status
-openxiangda generate
-openxiangda check
-openxiangda test
-pnpm test:e2e
-```
-
-需要使用钉钉家校监护关系的应用，应先阅读[家校通讯录关系](./school-contact-relations.md)。2.0 尚未正式投产，当前生产应用继续使用 1.0 SDK；2.0 应用必须通过 NestJS App API 和当前 RoleSession 读取，不能复制 1.0 页面 SDK 代码。
-
-`openxiangda dev` 是唯一受监督的日常入口：它启动完整 Ant Design Pro Admin、相互隔离的 React/Umi Max 与 NestJS 进程、独立 loopback 本地平台，以及工作区隔离的 PostgreSQL。开发者**不需要安装 PostgreSQL**，只需要 Docker Desktop 或兼容容器运行时；CLI 自动下载摘要固定的镜像、创建数据库、选择端口并限制容器资源。2.0 模板已经删除 Vite/旧自研 Shell，不保留兼容档位。关闭前台命令或执行 `openxiangda dev stop` 时只停止进程和容器并保留项目专属 volume，因此数据在重启后仍存在；受管进程组带工作区身份记录，监督进程意外中断后也可由下一次启动或 stop 安全回收。`openxiangda dev status` 查看当前/上次会话；只有显式执行 `openxiangda dev reset --data` 才会在校验工作区、容器、数据卷和凭据归属后删除本地数据库与凭据。`openxiangda dev --reset` 是“安全重置后立即启动”的快捷形式。工作区内部 `pnpm dev` 只供 CLI 编排，不负责平台进程、数据库、会话锁和清理，不作为公开开发命令。local 不是远程环境，不要求 provision 或远程 OAuth/Secret。`generate` 根据配置生成 Data、AuthZ、Event 与 Workflow 类型。`check` 必须是确定性的：同一提交、同一依赖锁、同一配置产生同一结果。完整本地模型见 [本地开发内核](./architecture/local-development-v2.md)。
-
-默认 `pnpm test:e2e` 会自行启动隔离的 UI-only 快速回归。需要把同一套 Chromium 场景作为完整本地集成证据时，先保持 `openxiangda dev --no-open` 运行，再执行 `OPENXIANGDA_E2E_BASE_URL=http://127.0.0.1:<web-port> pnpm test:e2e`。此时 Playwright 不创建第二个服务器，而是验证浏览器、独立本地平台、NestJS 与项目专属 PostgreSQL 的同一受监督会话；`<web-port>` 以 `openxiangda dev status` 为准。外部会话模式不会隐式重置开发数据，针对确定性种子数据的整套回归只能指向一次性验收应用，或由开发者先明确停止并执行 `openxiangda dev --reset`；不得在测试配置中绕过 CLI 所有权校验直接清理容器或 volume。
-
-完整模式下，浏览器对 App API 的请求先进入本地平台网关：网关验证当前稳定 RoleSession，丢弃浏览器自带的 Authorization，再用仅限 loopback 的短期平台身份转发给 NestJS。CLI 另外创建一个 workspace runtime OAuth client，只把原始 Secret 注入 `dev:server`，供 Worker/Scheduler/后台业务调用 Data API；前端开发进程拿不到该 Secret。数据库连接、OAuth 凭据和其他本地状态位于 Git 忽略的 `.openxiangda/local/state/`，权限为仅当前用户可读写，并且不会进入 AppPackage。
-
-开发 2.0 工具链本身时，每一轮可用一个命令完成发布前同等级的本地验收：
-
-```bash
-pnpm verify:local
-```
-
-它会用本地 tarball 创建并销毁一个独立新应用，覆盖脚手架、安装、生成、单测、生产构建、Skill 和文档；Chromium 只运行一次，并在该临时应用经过显式安全重置后的完整受监督会话中同时验证 React、独立本地平台、NestJS 与真实 PostgreSQL。相同生命周期还验证工作区隔离、资源限制、重启持久化、事务幂等回放和显式重置。它不会执行 npm 发布、Git 提交或平台部署。
-
-准备发包时，先从干净且已同步远端的 `master` 物化已经评审的 Changesets，
-检查生成的包版本、内部依赖与模板 BOM，提交并推送该版本提交，然后查看机器生成的影响计划：
-
-```bash
-pnpm release:version
-# review, commit and push the generated version diff
-pnpm release:plan
-pnpm verify:release
-pnpm release:publish
-```
-
-`release:version` 不提交、不发包，只把 Changesets 确定的候选版本写入 Git 工作树；未完成这一步时，后续所有发布命令会在构建前失败。`release:plan` 会完成 npm 不可变性检查并比较候选包与上一发布版本的真实 tarball。`verify:release` 冻结一批带摘要的候选 tarball，只针对这批工件执行一次正式增量门禁，并留下不可变验证凭据；`release:publish` 必须消费该凭据，只复查并发与摘要后发布同一批字节，不会重复测试。真实 PostgreSQL 生命周期门禁也只在本地平台、开发生命周期或相关模板发生变化时运行。无法分类的新包或变化自动升级为全量验证，周期审计使用配对的 `pnpm verify:release:full` 和 `pnpm release:publish:full`。发布后需要更新独立 reference 仓库时，再显式执行 `pnpm release:sync-reference`。
-
-## OAuth2 应用身份
-
-外部系统或后台任务通过平台托管的 OAuth2 client credentials 获取短期 token，不使用用户 RoleSession。客户端 Secret 只在创建或轮换时返回一次：
-
-```bash
-openxiangda oauth client create --name erp-sync \
-  --environment preproduction \
-  --scope app:invoke \
-  --scope data:read
-openxiangda oauth client list
-openxiangda oauth client rotate <client-id> --grace-period-seconds 600
-openxiangda oauth audit list --limit 100
-```
-
-NestJS App API 使用 `@RequireCapability` 验证服务身份 scope；Workflow 操作仍强制用户 RoleSession，不允许服务身份代替审批人。
-
-应用后端自己的 workload client 由平台托管，不向开发者显示 Secret。查询状态或主动轮换时使用专门命令：
-
-```bash
-openxiangda oauth runtime status --environment preproduction
-openxiangda oauth runtime rotate --environment preproduction \
-  --grace-period-seconds 600 \
-  --idempotency-key runtime-rotation-20260812
-```
-
-`runtime rotate` 先以当前 credential version 做 CAS 暂存，再对该环境当前激活的同一个 AppVersion 创建滚动 DeploymentRun。新 Secret 只在平台内部写入 Kubernetes Secret；新 Pod 就绪后使用新凭据，旧 Pod 在宽限期内仍可换 token。命令重试必须复用同一个幂等键，不重建或篡改应用版本。
-
-## 环境 Secret 与运行维护
-
-`openxiangda.config.ts` 只声明后端需要的 Secret 名称和注入环境变量，值不会进入源码或 AppPackage。可先在本地/测试环境配置，再部署应用：
-
-```bash
-APP_SECRET='preproduction-only-value' \
-  openxiangda secret create dingtalk-client-secret \
-  --environment preproduction \
-  --from-env APP_SECRET
-
-openxiangda event subscription list
-openxiangda event delivery list
-openxiangda workflow provider list --environment preproduction
-```
-
-事件死信通过 `event delivery replay` 显式重放；Workflow Provider 密钥轮换要在下一次成功部署后才激活。
-
-## 构建与发布
-
-应用 CI 先构建并推送后端镜像，再将不可变镜像摘要交给 CLI：
-
-```bash
-openxiangda build --backend-image registry.example.com/apps/my-app@sha256:...
-openxiangda deploy preproduction --backend-image registry.example.com/apps/my-app@sha256:...
-openxiangda status <deployment-id>
-openxiangda environment status
-```
-
-CLI 上传应用包并创建 DeploymentRun；部署、重试、健康检查和激活都由平台执行。CLI 退出不影响发布继续进行。生产只晋级预发已验证的同一不可变 AppVersion，不重新构建。
-
-`app provision` 只用于首次创建平台中的稳定 2.0 应用身份和默认 `preproduction` 环境；命令可安全重试，且需要平台管理员身份。首次执行 `openxiangda promote <preproduction-deployment-id> production` 时，平台才惰性创建唯一的 `production` 环境并发布相同 AppVersion。
-
-测试应用不使用时可执行 `openxiangda environment stop preproduction` 把当前工作负载缩容为零；环境、业务数据、Secret 元数据、Head 和发布历史都会保留。需要继续测试时执行 `openxiangda environment start preproduction`。正式环境使用相同命令，但不会由平台自动停止。
-
-## AI 入口
-
-AI 先读取 `openxiangda://workspace/context` 和 `openxiangda://environments`，再使用 MCP 的 `check_app`、`run_tests`、`build_app` 等结构化工具。`start_environment`、`stop_environment` 等会改变环境的工具必须在用户明确授权后调用。
-CI 或非交互环境不写用户会话文件，必须成对提供短期凭据：
-
-```bash
-OPENXIANGDA_BASE_URL=https://platform.example.com/service \
-OPENXIANGDA_TOKEN="$TOKEN" openxiangda check
-```

package/docs/index.md

@@ -1,27 +0,0 @@
----
-layout: home
-hero:
-  name: OpenXiangda 2.0
-  text: 把平台应用当作真正的软件工程
-  tagline: 标准 React 前端、NestJS 后端、统一 Data API、上下文权限、Workflow Kernel v2、事件订阅与应用级交付
-  actions:
-    - theme: brand
-      text: 开始开发
-      link: /getting-started
-    - theme: alt
-      text: 阅读架构
-      link: /concepts
-features:
-  - title: 一个应用，一个版本
-    details: 前端、后端、配置契约和生成类型共同构成不可变 AppVersion。
-  - title: 平台托管后端
-    details: 每应用独立容器，共享 Kubernetes 集群资源，由平台完成部署与身份注入。
-  - title: AI 可用但不依赖 AI 发布
-    details: CLI、MCP 和 Skills 共用确定性服务；平台持久化执行部署，不让会话承担状态机。
----
-
-OpenXiangda 2.0 保留平台统一数据与治理能力，同时把应用开发恢复成成熟的前后端工程。本工具链只面向 2.0 应用；旧应用由独立的 1.x 产品线维护。
-
-当前能力的完成证据、真实缺口和实施顺序见[实施路线图与证据矩阵](/architecture/implementation-roadmap)。Admin 已确认[全量切换到 Ant Design Pro v6](/architecture/ant-design-pro-v6-admin-foundation)，不再维护自研 Shell/Vite 双轨。实现前先阅读[环境配置内核](/architecture/environment-configuration-kernel-v2)、[Alpha 退役与 Native 切换前置审计](/architecture/native-kernel-inventory-v2)、[原生配置投影蓝图](/architecture/native-configuration-projection-v2)与[授权一致性内核](/architecture/authorization-consistency-v2)，Admin 页面协议建立在这些可验证的运行时事实之上。
-
-开发表单、列表或详情前阅读[平台字段组件使用指南](/field-components)，按场景选择桌面、移动和只读组件。

package/docs/llms.txt

@@ -1,20 +0,0 @@
-# OpenXiangda 2.0 documentation
-
-- /getting-started.md: standard workspace and development loop
-- /concepts.md: application, platform, data, runtime, and version boundaries
-- /frontend.md: React admin shell, role session, CRUD, workflow UI
-- /field-components.md: platform field catalog, usage, selection rules, file and rich-text examples
-- /backend.md: NestJS modules, identity, Data API, health, secrets
-- /data-authz.md: RBAC plus contextual data and field authorization
-- /workflow-events.md: Workflow Kernel v2, providers, actions, durable events
-- /delivery.md: immutable AppPackage and platform-owned DeploymentRun
-- /architecture/implementation-roadmap.md: evidence-backed capability status, dependencies, and delivery order
-- /architecture/environment-configuration-kernel-v2.md: native environment registry, immutable projections, Head activation, gateway delegation, and runtime gates
-- /architecture/native-kernel-inventory-v2.md: read-only database, data-volume, and Kubernetes evidence; redaction, ambiguity classification, deterministic digests, and migration-plan validation
-- /architecture/authorization-consistency-v2.md: environment-native RBAC, role subjects, contextual scope, concurrency, cache, and cutover invariants
-- /architecture/admin-shell-v2.md: complete Admin framework contracts and staged implementation gates
-- /architecture/repository-and-release.md: standalone 2.0 repository and release boundaries
-- /architecture/tenant-public-origin-v2.md: canonical tenant origin registry, migration, cookie boundary, and gateway contract
-- /architecture/tenant-public-origin-implementation-blueprint.md: file-level B0-O schema, API, CLI, deployment, and verification contract
-- /reference/cli.md: generated CLI commands
-- /reference/mcp.md: generated MCP resources and tools

package/docs/reference/cli.md

@@ -1,69 +0,0 @@
-# CLI Reference
-
-> Generated from `DEVKIT_COMMANDS`. Do not edit manually.
-
-| Command | Risk | Purpose |
-| --- | --- | --- |
-| `auth login` | write-local | 通过平台浏览器授权登录 2.0 |
-| `auth status` | read | 查看当前登录会话 |
-| `auth logout` | write-local | 删除当前登录会话 |
-| `app create` | write-local | 从官方模板创建 2.0 应用 |
-| `app link` | write-local | 绑定平台地址和应用环境 |
-| `app provision` | deploy | 在平台幂等创建 2.0 应用身份和默认预发环境 |
-| `app info` | read | 读取应用工作区上下文 |
-| `authz membership list` | read | 查询 Native 应用角色成员 |
-| `authz membership grant` | deploy | 授予 Native 应用业务角色 |
-| `authz membership update` | deploy | 更新 Native 角色成员范围 |
-| `authz membership revoke` | deploy | 撤销 Native 应用角色成员 |
-| `authz relationship list` | read | 查询 Native 资源关系授权 |
-| `authz relationship grant` | deploy | 创建 Native 资源关系授权 |
-| `authz relationship update` | deploy | 更新 Native 资源关系授权 |
-| `authz relationship revoke` | deploy | 撤销 Native 资源关系授权 |
-| `authz super-admin list` | read | 查询 Native 应用超级管理员 |
-| `authz super-admin grant` | deploy | 授予 Native 应用超级管理员 |
-| `authz super-admin revoke` | deploy | 撤销 Native 应用超级管理员 |
-| `oauth client list` | read | 查询应用 OAuth2 客户端 |
-| `oauth client create` | deploy | 创建环境绑定的 OAuth2 客户端 |
-| `oauth client update` | deploy | 更新 OAuth2 客户端 |
-| `oauth client rotate` | deploy | 双密钥轮换 OAuth2 客户端 |
-| `oauth client revoke` | deploy | 吊销 OAuth2 客户端 |
-| `oauth runtime status` | read | 查询平台托管运行凭据状态 |
-| `oauth runtime rotate` | deploy | 暂存运行凭据并创建同版本滚动部署 |
-| `oauth audit list` | read | 查询 OAuth2 审计事件 |
-| `secret list` | read | 查询环境隔离的应用 Secret 元数据 |
-| `secret create` | deploy | 从本机安全来源创建应用 Secret |
-| `secret update` | deploy | 更新应用 Secret 元数据和状态 |
-| `secret rotate` | deploy | 追加不可变版本并轮换应用 Secret |
-| `secret delete` | deploy | 删除未被当前配置引用的应用 Secret |
-| `secret audit list` | read | 查询应用 Secret 审计事件 |
-| `event subscription list` | read | 查询应用事件订阅 |
-| `event subscription status` | deploy | 暂停或恢复事件订阅 |
-| `event subscription rotate-secret` | deploy | 暂存下一版本事件签名密钥并随下次部署激活 |
-| `event delivery list` | read | 查询事件投递与死信 |
-| `event delivery replay` | deploy | 幂等回放历史事件投递 |
-| `event timer list` | read | 查询定时事件 |
-| `event timer status` | deploy | 暂停或恢复定时事件 |
-| `event timer fire` | write-local | 在完整本地开发会话中触发下一次定时事件 |
-| `workflow provider list` | read | 查询 Workflow Assignee Provider |
-| `workflow provider rotate` | deploy | 轮换 Workflow Provider 签名密钥 |
-| `skill install` | write-local | 安装 OpenXiangda 2.0 AI Skills |
-| `skill validate` | read | 验证 OpenXiangda 2.0 AI Skills |
-| `dev` | write-local | 启动受监督的完整本地应用 |
-| `dev status` | read | 查看当前工作区本地开发会话 |
-| `dev stop` | write-local | 停止当前工作区本地开发会话并保留数据 |
-| `dev reset` | write-local | 删除当前工作区本地数据库和开发状态 |
-| `generate` | write-local | 生成 Data/App/Workflow/Event 类型契约 |
-| `check` | read | 确定性检查完整应用 |
-| `test` | read | 运行应用测试 |
-| `build` | write-local | 构建并密封一个 AppPackage |
-| `deploy` | deploy | 创建平台持久执行的 DeploymentRun |
-| `promote` | deploy | 以同一 AppVersion 晋级目标环境 |
-| `environment status` | read | 查询应用环境、运行状态和活动版本 |
-| `environment start` | deploy | 从活动版本启动应用环境 |
-| `environment stop` | deploy | 停止应用环境并保留数据与配置 |
-| `status` | read | 查询 DeploymentRun 状态 |
-| `logs` | read | 查询部署检查点和关联日志 |
-| `retry` | deploy | 重试可恢复的 DeploymentRun |
-| `cancel` | deploy | 幂等取消 DeploymentRun |
-| `rollback` | deploy | 以历史 AppVersion 创建回滚部署 |
-| `doctor` | read | 诊断本地工具链和平台兼容性 |

package/docs/reference/mcp.md

@@ -1,31 +0,0 @@
-# MCP Reference
-
-> Generated from the MCP server registry. Do not edit manually.
-
-## Resources
-
-- `openxiangda://workspace/context`
-- `openxiangda://workspace/contracts`
-- `openxiangda://platform/capabilities`
-- `openxiangda://deployments/latest`
-- `openxiangda://environments`
-- `openxiangda://docs/index`
-
-## Tools
-
-- `workspace_context`
-- `contract_describe`
-- `generate_contracts`
-- `check_app`
-- `run_tests`
-- `fire_local_timer`
-- `build_app`
-- `deployment_plan`
-- `environment_status`
-- `start_environment`
-- `stop_environment`
-- `deploy_app`
-- `deployment_status`
-- `deployment_logs`
-- `retry_deployment`
-- `rollback_app`

package/docs/school-contact-relations.md

@@ -1,136 +0,0 @@
-# 家校通讯录关系
-
-状态：2.0 尚未正式投产。本页定义已经实现的后端读取合同和应用接入方式；当前生产应用仍按 1.0 文档接入，不能混用两代 SDK。
-
-## 数据合同
-
-### 平台内置身份角色
-
-成功的家校全量同步会维护平台层身份角色（不属于应用 `RoleSession` 的可切换角色）：
-
-| 展示名 | 稳定编码 | 来源 |
-| --- | --- | --- |
-| 家长 | `SCHOOL_GUARDIAN` | 家校成员 `guardian` |
-| 学生 | `SCHOOL_STUDENT` | 家校成员 `student` |
-| 老师 | `SCHOOL_TEACHER` | 家校成员 `teacher` |
-
-身份可组合，同一用户可以同时拥有多个编码。2.0 的 `NativePrincipal` / `Principal` 和 `RoleSessionContext` 以可选的 `platformRoleCodes` 暴露这些编码；它们只用于业务身份判断，不能替代当前应用角色、不能参与 `roleCodes` 的切换，也不能由浏览器提交。权限默认不限制，应用若需要按身份限制页面或 App API，应在服务端使用这些可信编码显式校验。
-
-```ts
-const isTeacher =
-  request.openxiangda?.principal.platformRoleCodes?.includes('SCHOOL_TEACHER')
-```
-
-应用开发者不直接写 `roles` 绑定，也不在本地复制同步结果；下一次完整同步会自动增删平台身份绑定。
-
-平台同步钉钉家校通讯录后，以只读关系返回监护人、学生和班级。关系两端都包含：
-
-- `userId`：平台用户 ID，业务数据应保存这个稳定标识；
-- `dingtalkUserId`：钉钉 `userid`，用于钉钉侧联动和排查；
-- `name`：平台用户姓名；
-- `mobile`：平台已有手机号，可能为 `null`。
-
-关系还包含 `relationCode`、`relationName`、班级信息、同步时间和同步状态。未能安全绑定到平台用户、或角色方向不一致的数据不会出现在应用查询结果中。
-
-## 权限与默认范围
-
-通过既有认证和 `RoleSession` 校验的非游客用户，在没有声明任何 `school-contact:*` 范围能力时，平台默认使用 `all`，可以查看当前租户全部已同步关系。应用自己的 App API 仍按正常方式声明业务操作能力，例如：
-
-```ts
-authz: {
-  capabilities: [
-    {
-      code: 'app:school-service:family:read',
-      kind: 'backend',
-      name: '使用家庭关系功能',
-    },
-    {
-      code: 'app:school-service:school-contact:self:read',
-      kind: 'backend',
-      name: '读取本人家校关系',
-    },
-    {
-      code: 'app:school-service:school-contact:class:read',
-      kind: 'backend',
-      name: '读取任教班级家校关系',
-    },
-  ],
-  roles: [
-    {
-      code: 'user',
-      name: '普通用户',
-      capabilities: ['app:school-service:family:read'],
-    },
-  ],
-}
-```
-
-应用自己的查询接口进入不可变 App API 合同并使用业务操作能力：
-
-```ts
-backend: {
-  operations: [
-    {
-      code: 'family.mine',
-      method: 'GET',
-      path: '/api/family/mine',
-      capability: 'app:school-service:family:read',
-      requestSchema: { type: 'object', additionalProperties: false },
-      responseSchema: { type: 'object' },
-    },
-  ],
-}
-```
-
-未给活动角色授予任何 `school-contact:*` 范围能力时，数据范围就是 `all`，不限制，可以查看全部已同步关系。只有业务明确需要最小化可见范围时，才给角色增加 `self:read` 或 `class:read`；可选的 `school-contact:read` 表示显式保持 `all`。同一角色同时获得多个范围能力时按 `all > class > self` 取最宽范围，避免前后端对范围产生不同解释。无有效 Principal/RoleSession、游客和跨租户请求仍然拒绝。
-
-## NestJS App API
-
-浏览器不能直接调用平台关系接口。应用后端使用 `OpenXiangdaPlatformClient`，透传 SDK 已验证的 authorization 和当前 RoleSession，再通过应用自己的 App API 返回业务需要的字段：
-
-```ts
-import {
-  OpenXiangdaHttpRequest,
-  OpenXiangdaOperation,
-  OpenXiangdaPlatformClient,
-} from 'openxiangda-nest';
-import { Controller, Get, Req } from '@nestjs/common';
-import { appOperations } from '@app/contracts';
-
-@Controller('/api/family')
-export class FamilyController {
-  constructor(private readonly platform: OpenXiangdaPlatformClient) {}
-
-  @Get('/mine')
-  @OpenXiangdaOperation(appOperations.familyMine)
-  async mine(@Req() request: OpenXiangdaHttpRequest) {
-    const context = request.openxiangda!;
-    return await this.platform.mySchoolContactFamily(
-      context.authorization,
-      context.roleSessionId!,
-      { page: 1, pageSize: 50 }
-    );
-  }
-}
-```
-
-可用方法：
-
-- `querySchoolContactRelations(authorization, roleSessionId, query)`：按平台用户 ID、手机号、钉钉 userid、姓名、班级或关系类型分页检索；
-- `schoolContactChildren(..., userId, query)`：查询指定监护人的学生；
-- `schoolContactGuardians(..., userId, query)`：查询指定学生的监护人；
-- `mySchoolContactFamily(...)`：同时查询当前用户作为监护人和学生的两个方向。
-
-应用前端用 `useOpenXiangdaAdmin().appApi()` 调用上面的 App API。不要把登录 token、RoleSession ID、平台 URL 或完整关系快照放入浏览器缓存；手机号只展示给确有业务需要的页面，日志不得记录手机号和完整返回体。
-
-## 失效与降级
-
-- `sync.state = disabled`：租户未开启后续同步，历史关系仍可能存在；
-- `sync.state = not_synced`：已开启但尚无成功快照；
-- `sync.state = current`：至少有一次成功快照，`lastSuccessfulSyncAt` 给出时间。
-
-应用应显示同步状态，不要把“查不到关系”等同于“该用户没有家校关系”。平台只有在完整快照成功后才替换关系；钉钉分页失败时保留上次成功数据。
-
-## 验证
-
-至少覆盖：默认 `all`、`self`、任教班级 `class`、无权限 403、RoleSession 切换、手机号为空、同步关闭和空关系。完成后运行 `openxiangda generate --check`、`openxiangda check` 和 `openxiangda test`。