openxiangda-skill-kit 2.0.0-alpha.98 → 2.0.0

package/skills/openxiangda-v2/references/getting-started.md

@@ -0,0 +1,66 @@
+# 安装与开始开发
+
+OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准审批和通知使用远端平台能力；只有真实服务端业务动作才按需增加 NestJS。本地无需启动平台、Docker 或 PostgreSQL。
+
+## 准备 {#prerequisites}
+
+准备平台地址、具有应用开发权限的账号、Node.js 24 和 pnpm 10.15.1。向平台维护者取得已验证的 OpenXiangda 2.0 精确版本，并核对平台能力是否支持。`openxiangda@latest` 可能属于 1.x；不能用它选择 2.0。
+
+## 安装与创建 {#create}
+
+以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
+
+```bash
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ login --base-url https://platform.example.com
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ create my-app --base-url https://platform.example.com
+cd my-app
+pnpm openxiangda context --json
+pnpm openxiangda dev
+```
+
+将两处示例平台地址替换为同一个目标地址。`create` 先核对目标与当前登录平台，再创建本地目录、安装依赖并初始化远端应用；新应用不会自动沿用文件中最后登录的站点。CI 使用原有成对的 `OPENXIANGDA_BASE_URL` 和 `OPENXIANGDA_TOKEN` 时，可以由该显式地址指定目标。
+
+初始化中断后重试同一命令；已有目录会核对原平台绑定，不能通过 `create` 改绑到其他站点。地址不一致时先检查目标并登录正确的平台，不修改 link 文件绕过检查，也不要使用内部 provision 接口另建应用。创建操作应在用户要求创建应用的范围内执行。
+
+进入项目后使用 `pnpm openxiangda`，由项目依赖和锁文件决定版本。查看使用资料运行 `pnpm openxiangda docs`；查看单一主题运行 `pnpm openxiangda docs frontend`。安装到其他 AI 工具时使用 `skill install --destination <Skill根目录>`。
+
+## 项目结构 {#workspace}
+
+```text
+apps/web                 页面与应用入口
+packages/contracts       平台编译器生成的契约
+modules                  业务模型、页面选择和模块声明
+openxiangda.config.ts    应用装配、导航、权限和按需能力
+appspec                  需求、架构、变更和验收记录
+AGENTS.md                平台约定与项目自有说明
+```
+
+以实际模板输出为准。资源与页面通过模块声明组合，不创建 `platform/data`。`apps/server` 仅在启用后端时初始化；后续保留用户业务代码。
+
+AppSpec 随开发持续维护：测试发布前补齐总纲、关联变更与验收计划，部署后记录真实业务结果，生产晋级核对该测试版本的验收报告。新应用业务实现前先完成[产品设计与确认基线](product-design.md)；研究、示例原型和技术检查可用于逐步完善设计。具体步骤见[全流程记录](appspec.md)。
+
+## 连接开发 {#connected-development}
+
+`dev` 监听本机回环地址，页面通过同源代理访问平台测试数据。浏览器不持久化平台凭据。终端和页面显示当前环境；只有生产环境时会持续提示生产数据风险。开发数据写入仍是远端真实写入，按任务范围操作。
+
+纯 CRUD 修改优先使用标准模型、字段和页面；跨模型事务或外部副作用再选择后端。角色、行和字段权限在平台执行。详见[开发流程](development.md)、[模型与标准 CRUD](application-foundation.md)和[按需后端](backend.md)。
+
+## 检查与交付 {#delivery}
+
+只检查时运行 `pnpm openxiangda check`。需要部署测试环境时直接运行 `pnpm openxiangda deploy`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。
+
+生产必须复用成功测试运行。部署状态、真实角色验收和回滚步骤见[应用交付](delivery.md)。纯前端发布不要求 Docker；启用后端后才需要官方镜像构建条件。
+
+## 接入 MCP {#mcp}
+
+MCP 使用相同的项目 CLI：
+
+```bash
+pnpm exec openxiangda --mcp-stdio --cwd <应用绝对路径>
+```
+
+先调用 `workspace_context`，再按任务读取 `docs_read` 和当前契约。配置示例与工具参数见[MCP 参考](mcp.md)。登录、创建和长期 dev 进程继续由 CLI/终端管理。
+
+指定站点授权可用 `auth status --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验，无需工作区。状态为 `authorized` 才证明当前 access 被平台接受；`missing`/`platform_mismatch`/`refresh_required` 需处理会话，`unauthorized` 表示平台拒绝，`unavailable` 表示暂时无法核验，不能当成过期。查询不刷新、不打开浏览器、不修改绑定；应用管理权限需另行核验。

package/skills/openxiangda-v2/references/interaction-patterns.md

@@ -0,0 +1,56 @@
+# 页面交互模式与体验评审
+
+按实际角色和任务选择下面的标准起点，并在 AppSpec 页面设计中记录适用范围、差异和验收。模式是设计建议，不是额外运行库；控件、导航、权限和数据继续消费[平台前端](frontend.md)、[字段组件](field-components.md)和[数据权限](data-authz.md)。
+
+## 标准管理页面 {#admin}
+
+适用于管理员维护独立业务对象。显式选择 CRUD 视图，沿用 Field Kit、Ant Design 与组件默认外观。页面优先呈现标题、主要新建入口、常用筛选、列表与行操作；复杂筛选按需展开。列按办理任务选择，记录默认排序、分页上限、空值/长文显示与操作条件。辅助模型无需独立导航。
+
+列表进入详情再返回时明确关键词、筛选、页码、选择范围与位置是否保留；批量操作说明当前页/已选记录范围，确认内容包含实际对象及影响。新建和编辑复用字段规则，失败定位到字段并保留其他输入。删除只在业务明确需要时提供，由服务端权限和业务约束最终裁定。
+
+标准 CRUD 自带的状态可引用共用设计；页面仍需说明角色、数据范围、可见字段、业务校验及差异。AC 至少按实际维护任务验证列表到详情返回、成功写入、禁止写入和适用校验。
+
+## PC 用户任务页面 {#pc-task}
+
+适用于申请、办理和跨模型任务。先给当前任务与下一步，按使用频率和决策顺序安排信息，不把所有底表铺成菜单。列表、详情和办理页按任务分开；同页编辑/提交/成功等状态在同一 PageSpec 中记录。
+
+为每个入口写清直接链接、前置条件、返回位置与成功出口。可编辑区域和只读依据区分，主操作有具体业务动词；确认步骤仅用于需要复核的信息和后果。页面动作对应一个明确的业务契约，提交结果未知时查询原结果，不以新随机幂等键重提。
+
+## 移动用户页面 {#mobile-task}
+
+使用有作用域的 `openxiangda/mobile` 与平台字段组件。根据现场任务独立组织首页、列表、详情和填写顺序；不把宽表格缩小后当作移动设计。确定常用入口、任务卡片上的必要信息、主动作、导航返回与输入退出规则。
+
+逐页检查触摸目标、键盘遮挡、焦点、滚动、安全区和长标题；筛选抽屉的应用/取消含义明确。网络慢时保留输入并阻止误操作，失败后给恢复入口。图片先缩略图、原图按需，附件展示大小限制、进度和失败原因。设计写明目标尺寸和渠道，真实验收在目标端走完主要任务。
+
+## 匿名表单与本人记录 {#public-form}
+
+外部无平台账号的人使用[匿名公开访问](public-access.md)，不建 guest 角色或开放普通 Data API。设计说明公开入口、收集目的、必填/可选信息、附件规则、提交后结果和本人记录的能力范围。
+
+明确同浏览器续填/本人访问的边界与凭证丢失后的实际行为，不承诺跨设备找回能力。所有权由平台填写；前端不接受用户指定其他人的身份。公开页面状态、校验、结果未知与安全提示按所消费契约设计，不虚构额外隐私同意或注册步骤。
+
+## 审批与办理详情 {#workflow}
+
+复用[标准流程、待办和通知](workflow-events.md)。详情优先显示当前状态、业务摘要、当前任务及历史；只提供当前用户被授权的操作。区分申请人、办理人和旁观者看到的字段、意见与动作，写清退回可编辑范围、撤回条件、转交等已启用能力。
+
+快速重复点击、任务已被他人处理和响应中断要有具体结果与恢复方式。通知详情跳转回标准目标，不复制流程状态或另做审批授权。AC 用真实角色覆盖主流程、退回/拒绝及越权反例。
+
+## 每页交互规格检查 {#page-review}
+
+把下表应用到每个实际页面。共用行为引用一个权威设计，页面写差异；不适用时说明业务理由，不为凑表增加功能。
+
+| 维度 | 编码前的具体决定 |
+| --- | --- |
+| 任务与入口 | 稳定页面 ID，REQ/旅程、角色和目标；入口、直链、返回及成功出口 |
+| 信息与字段 | 区域优先级、默认排序/筛选；标签、帮助、默认值、必填、联动、可编辑条件、校验时机和提示位置 |
+| 操作与反馈 | 主次操作、触发条件、文案、隐藏/禁用依据、复核内容、成功反馈和后续动作 |
+| 页面状态 | 初次加载/刷新、正常、首次空数据、筛选无结果、无权限、请求错误和重试 |
+| 写入与恢复 | 未保存、提交中、成功、明确失败、结果未知、他人修改冲突；输入保留与草稿边界 |
+| 数据边界 | 空值、长文本、最大条目、分页、批量选择范围；附件类型/大小/失败及重试 |
+| 权限与多端 | 页面/动作/行/字段、多角色并集；PC 批量与移动任务差异、键盘焦点、触摸和返回 |
+| 原型与验收 | 所选标准模式或原型位置、适用状态；对应 AC、角色、输入条件、操作和可观察结果 |
+
+## 评审与验证尺度 {#evaluation}
+
+先用用户能理解的方式走一遍“从哪里进来、看到什么、怎样完成、出错怎么恢复”，再核对规则、数据与权限的一致性。原型允许样例数据，必须标注；只有效果图不能证明任务可完成。选定标准模式也需完成本应用的逐页差异设计。
+
+实现后用实际界面验证任务成功率和明显阻碍，至少覆盖已纳入范围的角色、入口、重要状态和目标端。记录结果未知、重复操作和并发冲突的服务端读回，不只看 toast；性能记录数据量和请求链路。构建通过、HTTP 200、截图数量或检查表填满均不代替真实业务验收。