openxiangda 2.0.0-alpha.110 → 2.0.0-alpha.113

package/skills/openxiangda-v2/references/field-components.md

@@ -16,7 +16,7 @@ PostgreSQL 物理列、索引、查询运算符、权限路径和桌面/移动
 | `text.rich` | 富文本 | 清洗后的 HTML `string` | `text` |
 | `number.integer` | 整数 | `number` | `bigint` |
 | `number.decimal` | 小数、金额、百分比 | `number` | `numeric(p,s)` |
-| `boolean` | 开关 | `boolean` | `boolean` |
+| `boolean` | 是/否选择 | `boolean` | `boolean` |
 | `date` | 日期 | `YYYY-MM-DD` | `date` |
 | `time` | 时间，可声明分钟或秒精度 | `HH:mm:ss` | `time(0)` |
 | `datetime` | 日期时间 | RFC3339 instant | `timestamptz` |
@@ -45,6 +45,33 @@ PostgreSQL 物理列、索引、查询运算符、权限路径和桌面/移动
 单值空值统一使用 `null`；多值、附件和图片统一使用 `[]`。`subtable` 不在父表保存
 JSON，而是通过标准 Data API 事务维护普通子资源。
 
+布尔字段没有默认值时显示“未选择”，不会把未填写当成“否”。PC 和移动端可以直接选择“否”并提交 `false`；`false` 是有效值，不是必填校验中的空值。只有明确声明默认值时才初始化对应布尔值。
+
+## 图片、缩略图和附件读取
+
+文件本体保存于平台对象存储，业务字段保存 `DataFileRef[]` 或 `DataImageRef[]`，不把 Base64 图片、文件字节、浏览器 `blob:` 地址写入业务字段。`previewUrl` 和 `thumbnailUrl` 是平台按当前应用、环境和文件权限生成的读取地址，不是永久公开 OSS 地址；不要自行替换域名、删除环境参数或拼接对象存储路径。
+
+图片上传完成后，平台保留原文件，并生成最长边 480 像素、保持比例、不放大小图的 WebP 缩略图，编码质量参数为 82。列表、活动卡片、小封面和头像优先用缩略图；大图预览和下载按需读取原文件。当前原生文件端点只支持原文件和 `variant=thumbnail`，不能自行拼接 `width`、`quality` 等未声明参数。附件字段中的图片不保证具有缩略图，需要缩略图能力时声明 `image` 字段。
+
+标准图片/附件展示可以直接使用 Field Kit：
+
+```tsx
+import { AttachmentFileList } from 'openxiangda/field-kit';
+
+<AttachmentFileList
+  files={record.cover ?? []}
+  resourceCode="activities"
+  imageTiles
+  mobile={isMobile}
+/>
+```
+
+组件按文件引用选择缩略图，预览和下载经过平台接口。自定义活动封面同样先选择 `cover.thumbnailUrl`；只有平台引用没有缩略图时才回退 `cover.previewUrl`。不要写 `previewUrl || thumbnailUrl`，否则小卡片也会下载完整原图。保留真实宽高或稳定的封面比例，非首屏图片使用懒加载；不得在列表渲染时预取所有原图。
+
+受限文件的缓存必须保留权限核验。配套平台支持私有条件缓存时，浏览器可以保存文件响应，再次访问由平台先核对当前权限，内容未变化返回 304，从本地复用字节；`no-cache` 表示复用前校验，和 `no-store` 禁止保存不同。缺少可靠实体标识或请求失败时仍禁止缓存。不应由应用添加长期免校验缓存、公开 CDN 缓存或跨账号 Blob 缓存来绕过该规则。公开长期缓存需要独立、明确的公开发布契约，不能仅因字段名叫封面就视为公开。
+
+验收时同时记录原图/缩略图字节、列表实际请求的变体、重复访问传输量和权限撤销结果。仅看到 `blob:` 地址不能判断用了 Base64，HTTP 200 也不能证明命中了缓存。
+
 ## 声明示例
 
 ```ts
@@ -92,7 +119,12 @@ JSON，而是通过标准 Data API 事务维护普通子资源。
 }
 ```
 
-来源端点只接受当前表单绑定值、关键字和游标；页大小由 `source.pageSize` 固定。
+来源端点接受当前表单绑定值、关键字和游标；页大小由 `source.pageSize` 固定。
+标准流程的具名动作发起表单由 `WorkflowSubmissionPage` 自动传递 `launch: { workflowCode, operationCode }`。
+平台核对当前环境已部署的流程、动作、输入字段映射和当前用户动作权限；不要求额外授予宿主表单 CRUD 权限。
+普通 CRUD 表单不传此绑定，继续检查对应创建/修改权限。自定义选择器可通过 `searchResource` 的同名选项传递
+已声明的发起绑定，不能用它扩大目标资源的读取范围或执行动作。
+使用此功能的编译包自动要求平台能力 `workflow.named-input-sources` 的 `1.0.0` 版本；先检查目标平台能力，配套升级后再发布。
 平台按来源资源的字段权限和 PostgreSQL RLS 查询并返回完整资源快照。来源记录改名或删除后，
 已经保存的 `{label,value,resourceCode,snapshot}` 仍可直接展示，不需要再次查询。
 

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

@@ -11,9 +11,10 @@ OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.0.0-alpha.110 skill install --force
-pnpm dlx openxiangda@2.0.0-alpha.110 login --base-url https://platform.example.com
-pnpm dlx openxiangda@2.0.0-alpha.110 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.0.0-alpha.113 skill install --force
+pnpm dlx openxiangda@2.0.0-alpha.113 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.0.0-alpha.113 login --base-url https://platform.example.com
+pnpm dlx openxiangda@2.0.0-alpha.113 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -38,7 +39,7 @@ AGENTS.md                平台约定与项目自有说明
 
 以实际模板输出为准。资源与页面通过模块声明组合，不创建 `platform/data`。`apps/server` 仅在启用后端时初始化；后续保留用户业务代码。
 
-AppSpec 随开发持续维护：测试发布前补齐总纲、关联变更与验收计划，部署后记录真实业务结果，生产晋级核对该测试版本的验收报告。普通开发和检查可用于逐步补齐资料。具体步骤见[全流程记录](appspec.md)。
+AppSpec 随开发持续维护：测试发布前补齐总纲、关联变更与验收计划，部署后记录真实业务结果，生产晋级核对该测试版本的验收报告。新应用业务实现前先完成[产品设计与确认基线](product-design.md)；研究、示例原型和技术检查可用于逐步完善设计。具体步骤见[全流程记录](appspec.md)。
 
 ## 连接开发 {#connected-development}
 
@@ -61,3 +62,5 @@ 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、截图数量或检查表填满均不代替真实业务验收。

package/skills/openxiangda-v2/references/mcp.md

@@ -31,6 +31,34 @@ MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，
 
 工具返回相同内容的 structuredContent 与文本结果，包含 ok、operation、data 和适用的 diagnostics/nextActions。业务失败设置 isError=true；按错误码、定位和平台 recovery 决定下一步。工具协议错误同样停止当前操作。check_app 会生成文件并运行检查、测试、构建；失败后未执行的阶段标记 skipped。deploy_app 已包含完整检查，生产晋级必须传入成功的测试 DeploymentRun ID，不重新构建。详见 [校验](testing.md)与[部署](delivery.md)。
 
+## authorization_status
+
+核验平台授权。只读核验明确指定站点的当前授权；不依赖工作区，不启动登录、刷新凭据或修改绑定。authorized 不代表应用管理权限。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "baseUrl": {
+      "type": "string",
+      "minLength": 1,
+      "description": "明确指定目标平台地址"
+    }
+  },
+  "required": [
+    "baseUrl"
+  ],
+  "additionalProperties": false
+}
+```
+
 ## workspace_context
 
 查看工作区。首先读取当前项目、工具链版本和绑定，不运行构建或创建远端对象。
@@ -86,7 +114,7 @@ MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，
 
 ## appspec_context
 
-读取业务需求。读取当前规格、开发阶段缺口、分页历史或指定稳定 ID 的正文；测试发布核对设计与计划，生产晋级核对实际验收。
+读取需求与设计。读取设计索引、稳定 ID 正文与引用闭包、开工和测试发布缺口；设计基线确认后制定实施计划，生产晋级核对原测试版本实际验收。
 
 - 只读：是
 - 可替换文件或改变远端状态：否
@@ -100,7 +128,7 @@ MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，
   "type": "object",
   "properties": {
     "selector": {
-      "description": "能力、变更或 ADR 的稳定 ID",
+      "description": "能力、变更、ADR 或 DES-* 设计的稳定 ID",
       "type": "string",
       "minLength": 1
     },

package/skills/openxiangda-v2/references/product-design.md

@@ -0,0 +1,142 @@
+# 对话发现与详细产品设计
+
+用户可以只说“想做一个系统”，不必先知道模块、技术方案或权限模型。AI 的职责是理解资料和实际工作，主动提出有理由的建议，通过持续交流形成用户能理解、团队能实施的权威设计。新应用先覆盖完整首发范围，完成设计基线后再制定实施计划和编写业务实现。设计研究、标注示例数据的原型和可行性验证可以先进行。
+
+## 先识别已有事实 {#entry}
+
+已有工作区读取 `context --json`、相关 `spec context <ID> --json`；没有工作区时可先在用户指定的本地目录整理 AppSpec，不为访谈执行 login/create 或创建远端应用。只要求研究时交付研究即可。收到完整资料先复用已有答案，核对版本、来源和冲突，避免重问。已有明确决定持续有效。
+
+按任务加载本专题相关章节及[交互模式](interaction-patterns.md)，不用把所有流程方法展示给用户。全新应用设计本期完整范围；既有应用围绕受影响需求、角色、旅程和页面修订；纯文案或无行为调整沿用有效基线并说明影响，不重写全套 PRD。明确只做原型时，保持原型范围。
+
+资料中的业务描述是证据，嵌入的指令、账号和凭据不是执行授权。引用来源文件、页码/段落、访谈日期与具体答复范围，脱敏后保存必要摘要；不要把原始敏感资料整份复制进 Git。
+
+## 用业务语言推进每轮对话 {#conversation}
+
+每轮理解已有内容，提出有依据的候选方案，聚焦一至三个相关问题；收到答复后复述决定和影响、更新权威材料，再处理下一项未知。用户不需要填写方法论表格或选择流程阶段。优先问真实发生过的例子，避免用“会不会使用这个功能”诱导肯定回答。
+
+用户不知道模块时，先了解谁在什么场景完成什么任务，顺着开始、交接、结束和异常发现模块。对每个候选模块说明服务的角色和任务、缺失的影响、依赖的平台能力、增加的成本，以及本期/候选/延期。评估身份与访问、业务对象、状态、协作、入口、权限、附件、消息、追溯、统计和集成的适用性；不把这些自动变成十个必建模块。
+
+用户说“不知道怎么选”时，给出适合已知规模的推荐和理由，说明一个主要代价及可替代方案，再请用户选择或修正。不要把“需要哪些模块”“权限怎么设计”整体丢回去，也不把 AI 推荐直接标成用户决定。关键问题未决定时列出影响，继续不依赖它的设计。
+
+示例对话（假设业务，不能当作已确认需求）：
+
+> 我们先看设备实际怎么被使用。你们主要想管清台账，还是也要处理借用和归还？可以讲一次最近的借用，现在由谁登记、怎样交接？
+
+用户描述多人借用、管理员用表格登记后：
+
+> 按这个流程，首期建议包括设备台账、借还申请、管理员办理和我的借用，能串起“有什么—谁在用—何时归还—谁负责”。维修暂列候选。借用需要负责人审批，还是管理员确认设备可用即可？这决定是否启用审批。
+
+用户不清楚时：
+
+> 如果目前没有负责人审批制度，建议先由管理员确认可用性，办理更短；代价是不能提供独立审批记录。若有高价值设备必须审批的规定，可以只对那类设备增加规则。我先把这两种方案列为待决定。
+
+随后按现场手机使用和管理员电脑办理设计入口，再讲通跨部门访问、退回、重复提交和并发等场景。确认总结只包含实际答复，不突然加入收费、采购、绩效等未经讨论的模块。
+
+## 权威记录与持续确认 {#authority}
+
+AppSpec 是唯一设计记录位置。`app.md` 是总纲与目录，详细规则各有归属：PRD 管业务规则，权限设计管业务访问含义，页面规格管交互，架构/ADR 管实现边界。其他文件引用稳定 ID，避免复制一套规则后各自修改。模型字段和可执行权限仍由应用声明与编译器生成，不把 AppSpec 变成第二套 Schema。
+
+在产品来源或 PRD 中维护一张按需增长的事实表：
+
+| ID | 内容与范围 | 状态 | 来源/答复 | 影响文档 |
+| --- | --- | --- | --- | --- |
+| 本项目稳定条目 ID | 具体事实、建议或决定 | 资料事实 / AI 建议待确认 / 用户已确认 / 否决 / 延期 / 冲突 | 文件段落或实际答复时间及摘要 | 相关 REQ、DES、ADR |
+
+这些是人读的记录语义，不是另一套运行时状态机。冲突先展示两处差异和影响，由有权决定业务的人澄清。用户改变决定时记录原因，更新受影响 PRD、权限、旅程、页面、架构与 AC；旧确认不覆盖新的业务含义。技术命名、受支持组件的局部布局等在已定要求内自行处理。
+
+确认围绕有业务意义的决定和可审阅成果，不逐文件机械索要“同意”。实际答复需要能说明确认了哪一版的哪些范围；已有明确批准直接沿用。沉默、超时、AI 自查或虚构签字不是确认。用户暂时无法决定时，将阻断项写在相应文档 `## 未确认问题` 的 `- [ ]` 中；不影响本期的假设和延期另列，不伪装成已解决。
+
+## 从业务到详细设计 {#deliverables}
+
+先理解实际流程和目标，再建议模块和范围；角色、任务、入口、权限、异常和架构可随着资料交错展开。设计工作安排可以提前说明，业务实施任务必须等基线就绪。
+
+| 材料 | 完成标准 | 常见遗漏 |
+| --- | --- | --- |
+| 来源与 PRD | 现状、目标和可观察结果；角色；首发/非目标；模块理由；术语；业务规则、输入输出、状态与边界；可证伪 REQ/AC | 用功能名称代替规则；建议未获确认 |
+| 旅程与信息架构 | 每类角色主任务从入口到完成的步骤、交接、异常恢复；导航和跨页面关系；管理端/PC/移动/公开入口适用性 | 有菜单但实际任务无法完成 |
+| 逐页规格 | 任务入口与返回，信息优先级和字段规则，动作与反馈，全部适用状态，权限、多端差异和 AC | 只有页面标题、截图或成功状态 |
+| 视觉与原型 | 采用的标准模式、布局与控件边界、阅读顺序、响应与移动差异；关键任务和异常可走查 | 只有漂亮图片，点击后没有任务出口 |
+| 权限设计 | 角色目标；页面、操作、行、字段；多角色并集；自己/本部门/跨部门；正反场景 | 隐藏按钮冒充服务端授权 |
+| 应用架构 | 所有者、领域与模型关系、状态不变量、平台能力映射、事务/并发/结果未知、资源预算、外部依赖和回滚 | 普通 CRUD 重写 Nest；复制身份或权限状态 |
+| 设计评审 | 完整范围走查、引用一致、遗漏与冲突关闭、实际用户确认、内容摘要 | 只写一个 passed 或把技术检查当验收 |
+
+架构技术细节由 AI 结合实时平台能力处理；新增业务限制和权限变化回到用户。性能先记录规模假设、分页/索引、请求次数、批量/并发上限、延迟目标与测量方法，目标和实测分开。标准 CRUD、审批、待办、消息、匿名访问优先复用平台，Nest 只用于真实业务事务或集成。
+
+页面必须记录初始加载、刷新、首次空数据、筛选无结果、错误、无权限、提交中、成功、明确失败、结果未知及并发冲突的适用性。公共状态可引用共用设计，逐页写差异；不适用时写具体理由。详细逐页检查与标准方案见[交互模式](interaction-patterns.md)。
+
+## AppSpec 材料模板 {#templates}
+
+应用资料放在 `product/`（来源与 PRD）、`experience/`（旅程和逐页规格）、`design/`（视觉、权限和架构）、`reviews/`（评审）下。它们都是 `appspec/` 内单层 Markdown；不要使用嵌套页面目录。只为实际需要的材料建文件，不复制一批“已确认”示例。
+
+设计文件采用下面的受限 YAML；按实际类型和稳定 ID 修改。`documents` 引用本文件依赖的其他设计、总纲、CAP 或 ADR，不能引用 ChangeSpec 形成计划与基线循环。正文保存详细设计；来源可在正文引用脱敏文件或 HTTPS 链接。
+
+```yaml
+---
+schema: openxiangda.appspec/design/v1
+id: DES-PRODUCT
+title: 本期产品需求
+status: draft
+type: product
+documents: []
+---
+```
+
+`status` 为 `draft / confirmed / superseded / rejected`。确认一组设计后按实际答复更新，不靠命令自动批准。稳定规则仍使用 `### REQ-*`，场景使用 `#### AC-*`，跨文档引用 ID 而不重复定义。可用 `requirements`、`capabilities`、`resources`、`actions`、`decisions` 关联已有实现；设计阶段不凭空编造平台字段或代码。
+
+各类型的正文模板如下。按这些二级章节展开真实内容，允许继续拆三级标题；内容相同可以引用共用设计，并写明适用理由。
+
+| type | 目录建议 | 二级章节 |
+| --- | --- | --- |
+| sources | product | 来源与事实；建议与问题 |
+| product | product | 目标与范围；角色与任务；模块与取舍；业务规则；验收标准 |
+| journey | experience | 角色与场景；主流程与交接；异常与恢复；页面与入口 |
+| page | experience | 任务与入口；信息与字段；操作与反馈；页面状态；写入与恢复；权限与多端；原型与验收 |
+| visual | design | 界面模式；布局与多端；原型与状态；可访问性 |
+| permissions | design | 角色与范围；页面与操作；行与字段；多角色与反例 |
+| architecture | design，或复用 decisions 中的 ADR | 所有者与边界；模型与状态；契约与能力；失败与并发；容量与回滚 |
+| review | reviews | 范围与覆盖；一致性评审；用户确认 |
+
+每个复杂页面独立一份 `page`；同页状态合并描述，不同任务页面分别记录。标准 CRUD 可共享模式，但仍说明本应用字段、权限、筛选和任务差异。架构可复用已有 accepted ADR，不再复制架构文档。
+
+## 开工评审与实施计划 {#readiness}
+
+本轮 ChangeSpec 的 front matter 用 `documents: [DES-REVIEW-INITIAL]` 引用一份评审。评审引用本轮受评设计，其依赖也纳入基线；摘要只绑定这些文档，不绑定随后变化的任务、源码或运行验收。初稿格式：
+
+```yaml
+---
+schema: openxiangda.appspec/design/v1
+id: DES-REVIEW-INITIAL
+title: 首发设计评审
+status: draft
+type: review
+scope: initial
+documents: [DES-PRODUCT, DES-JOURNEY, DES-PAGE-HOME, DES-VISUAL, DES-PERMISSIONS, DES-ARCHITECTURE]
+---
+```
+
+`scope: initial` 自动将应用总纲纳入基线并覆盖完整首发，至少包含产品、旅程、页面、视觉、权限、架构六类；某类入口不适用仍说明范围。`scope: change` 只评审受影响范围，在“范围与覆盖”列出复用基线、变化、受影响文档和未受影响理由，不能用它缩小尚未设计的新应用范围。
+
+先按真实角色走通每个主要任务，检查规则、权限、页面状态、原型和架构相互一致；AC 包括授权成功、禁止角色拒绝和适用的异常。标准模式能充分说明的页面不强求另画图片；自定义关键任务做可走查原型，用户意见回写权威规格。原型数据标明为示例，不导入业务数据。
+
+`spec context <变更ID> --json` 返回 `lifecycle.design.baselineDigest` 以及具体缺口；没有完整设计时仍可读取摘要，摘要本身不是批准。完成语义评审并获得实际确认后，在评审中记录 `confirmedBy`、ISO 时间 `confirmedAt`、包含具体答复定位和范围的 `confirmationSource`，保存所评设计的 `baselineDigest`，并把已确认设计和评审状态设为 `confirmed`。这些字段只能从实际过程填写，不能使用示例人名或当前时间冒充确认。文档最终状态变化后重新读取摘要并核对其仍对应获批范围。
+
+context 的 `readyForImplementation` 为真时才制定具体实现任务，把 REQ、页面/旅程、权限和 ADR 映射到源码、测试及 AC。`readyForTest` 还要求本轮任务、验收计划及原有交付章节完整。普通 `check` 可以发现技术问题；正式测试部署缺设计时失败关闭。工具检查结构和摘要，不能证明用户确认真实或体验合格，也不能拦截任意编辑器中的写操作；Skill 必须遵守开工顺序。
+
+设计改变导致摘要失配时先分析差异：只影响局部就修订对应设计和确认范围，未改决定继续有效；不要只复制新摘要让错误消失。纯文案变化不必修改无关设计，实际实施记录说明原因。生产晋级继续读取原测试提交的设计与计划，复用成功测试包并核对实际验收，见[全流程记录](appspec.md)。
+
+## 体验验收与后续恢复 {#handoff}
+
+新任务先看总纲和设计索引，再按 DES/CAP/ADR/变更 ID 加载正文，恢复已知事实、候选模块、已确认范围、阻断问题与下一步。不要把旧会话中未记录的猜测当决定。大型资料按任务加载，单次有界；原型资源只引用，工具不自动打开外部内容或执行脚本。原型引用需记录内容摘要、固定版本或不可变地址；当前设计摘要覆盖 Markdown 正文，图片、HTML 和外部资源的实际版本仍需走查核对，不能把可变的同名链接当作不变的设计。
+
+实现后按相同角色和任务走查真实页面，核对筛选返回、输入保留、权限拒绝、慢请求、重复点击、冲突恢复、附件与目标端可用性。记录实际环境、角色、样本、失败与证据；技术测试、原型评审和业务验收分别报告。将反馈合回其权威材料，再归档变更。
+
+## 方法来源与平台适配 {#sources}
+
+以下仅借鉴方法，本文为面向 OpenXiangda 的原创适配，不安装或复制上游工作流。BMAD 用于持续澄清和 PRD/UX/架构衔接，PM Skills 用于访谈、假设和主动建议，Design OS 用于逐页规格与原型交接，Spec Kit 用于可验证需求和跨文档检查。主动建议仍需实际确认，任何方法都不能替代平台能力归属。
+
+- [BMAD PRD，固定提交](https://github.com/bmad-code-org/BMAD-METHOD/blob/abe4eb1bce919c9d22cd18b3519353d5824c4b75/skills/bmad-prd/SKILL.md)（MIT，另含商标说明）。
+- [PM Skills，固定提交](https://github.com/phuryn/pm-skills/tree/18468a95b427e70e258b51389796367c6f684e7d)（MIT）。
+- [Design OS，固定提交](https://github.com/buildermethods/design-os/tree/529dedb43bfec24b2cbb128f26dd8cbc6143f754)（MIT）。
+- [Spec Kit，固定提交](https://github.com/github/spec-kit/tree/4a7341a93d944d6efe153b71da4a1adb9c2b578c)（MIT）。
+
+视觉收敛与体验检查可参考 [Impeccable](https://github.com/pbakaus/impeccable/tree/831cabee8b4bc1a2b66e5ae22003e9a19b57d464) 与 [DESIGN.md](https://github.com/google-labs-code/design.md/tree/9bf8eae67128b6cc55ad9bf86665767deb4c11cd) 的方法（Apache-2.0）。本专题不承诺这些项目的当前版本或排名，也不因案例要求增加平台功能。

package/skills/openxiangda-v2/references/testing.md

@@ -22,6 +22,10 @@ CI、离线开发或尚未发布的候选包使用 `pnpm openxiangda check --loc
 
 ## 按变化范围验收 {#acceptance}
 
+应用测试归当前项目维护。模板不限制页面数量、源文件数、总行数、业务类名或登录布局；初始模板与通用组件的模拟响应回归由工具链发行门禁维护。类型、声明、构建制品和实际运行性能仍需按各自规则验证，源码行数不能替代性能测量。
+
+Web 默认保留开发服务回环访问检查。按需 Nest 使用 `tsx --test` 发现项目中的业务测试；没有用例时只有零项测试，不能当成业务已验收。浏览器目录 `apps/web/e2e/` 起初只有编写说明，添加本应用的 `*.spec.ts` 后运行 `pnpm test:e2e`；真实角色验收绑定 AppSpec 和指定测试版本。
+
 修改资源时验证声明、PC/移动字段语义及受影响的新增、详情、修改、删除、筛选、导出和版本冲突。用允许角色验证成功，用禁止角色验证页面、操作、行和字段边界；存储值及审计应符合声明。平台内部的数据库和性能回归由平台维护者负责，应用不重复搭建平台数据库测试。
 
 只改文案时验证受影响页面。复杂事务、并发和值转换使用聚焦测试。浏览器验收实际操作并检查错误，不能用模拟响应或空页面加载代替真实角色验收。

package/skills/openxiangda-v2/references/upgrading.md

@@ -2,7 +2,11 @@
 
 ## 升级前核对 {#before}
 
-先运行 `pnpm openxiangda context --json`，确认项目锁定的根包版本、平台绑定和启用能力。取得目标精确版本和变更说明，核对平台能力要求。应用只直接管理 openxiangda 根包，内部物理包组合由该发行确定。
+先运行 `pnpm list openxiangda --depth 0` 核对项目实际安装的根包版本，再运行 `pnpm openxiangda context --json` 核对平台绑定和启用能力。取得目标精确版本和变更说明，核对平台能力要求。应用只直接管理 openxiangda 根包，内部物理包组合由该发行确定。
+
+上下文的 `toolchain.packageName` 标明版本来源，当前 `toolchain.version` 是 `openxiangda-devkit-core` 的物理包版本，不能当作 openxiangda 根包版本。根包与 CLI、Devkit、MCP、contracts 等独立版本化，由根包精确依赖组成同一发行；数字不同不代表版本漂移。
+
+协议版本说明数据格式，能力版本说明某项平台契约，校验实现摘要说明实际执行的规则；不能只比较名称里的数字判断是否配套。旧工具读不懂新协议时升级项目根包及 Skill/MCP；平台缺少新能力时由维护者升级或启用平台能力；规则摘要不同则按发布组合核对两端。诊断无法确定哪端落后时，不应无条件升级平台或反复改业务代码。
 
 共享校验使用 `configuration-compatibility/v2` 描述，包含校验实现摘要。切换到这一契约时，平台和项目工具链需按同一发布说明配套升级。随后每次发布在构建前核对实现摘要；不要反复修改业务代码来处理工具版本不配套。
 
@@ -16,6 +20,12 @@
 
 持续运行的 MCP 进程仍可能加载旧代码，升级后重启该连接并重新读取 workspace_context、资料版本和当前契约。全局 Skill 的版本不代表所有项目版本；进入项目后以项目锁定的 CLI 和随包资料为准。
 
+## 整理旧模板测试 {#tests}
+
+旧模板的测试与源码预算属于项目自有文件，升级包不会静默删除。若新增页面或合理重构触发样例限制，先提交当前源码，检查 `apps/web/test/contracts.test.ts`、`apps/web/scripts/check.mjs` 和 `apps/server/test/smoke.test.ts`：把项目实际业务断言保留，仅移除固定初始页数、样例文件名、普通业务词和总行数限制；Web 的 check 保留 `tsc -p tsconfig.json --noEmit`，后端可用 `tsx --test` 自动发现用例。
+
+旧 `apps/web/e2e/` 中的通用模拟平台夹具及 `*.e2e.html` 不代表本应用验收。确认没有项目用例依赖后，可连同 Vite 中对应的预热入口整理；保留项目自行编写的用例与配置。使用实际业务记录重建验收覆盖，并执行完整 check；不要把整理样例当成修复真实契约、类型或权限错误的方法。
+
 ## 失败与回退 {#rollback}
 
 保留失败指针和变更差异。资料缺失或摘要不符时重新安装该精确版本，不能复制其他版本的文档掩盖问题。应用版本回滚、依赖降级和数据/迁移恢复分别处理；降级 npm 包不等于撤回已经发生的业务写入。