@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/blank/docs/errors/README.md

@@ -0,0 +1,357 @@
+# 错误码册
+
+这是本业务项目自带的离线诊断手册。先使用错误码、声明位置、reason/fix 定位；不需要克隆框架仓库。
+
+- [HTTP 运行时错误与业务码](runtime.md)：401/403/404、状态冲突、约束拒绝、DOMAIN_ERROR 等。
+- [业务排错顺序](../ai/troubleshooting.md)：启动、权限、审批人、worker、死信与导入导出。
+- CAGE-* 是声明、工具链或内部运行诊断；HTTP code 与业务 domainCode 是另一层，不要混为一谈。
+
+每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
+
+## 智能运行时
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AI-001](CAGE-AI-001.md) | 智能运行时声明无效 |
+
+## 文件字段与上传
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-FILE-001](CAGE-FILE-001.md) | 文件字段或上传配置无效 |
+
+## 可靠读取审计
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AUDIT-001](CAGE-AUDIT-001.md) | 可靠读取审计失败 |
+
+## 运行状态诊断
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DIAG-001](CAGE-DIAG-001.md) | 运行诊断输入或连接失败 |
+
+## 后台执行与就绪
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-WORKER-001](CAGE-WORKER-001.md) | 缺少必要后台引擎 |
+| [CAGE-WORKER-002](CAGE-WORKER-002.md) | 事件与消费者清单不匹配 |
+| [CAGE-WORKER-003](CAGE-WORKER-003.md) | 后台任务未在停机时限内结束 |
+
+## 审批
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-APPR-001](CAGE-APPR-001.md) | 可路由字段不存在 |
+| [CAGE-APPR-002](CAGE-APPR-002.md) | 审批结论落到其他聚合 |
+| [CAGE-APPR-003](CAGE-APPR-003.md) | 审批结论未允许流程调用 |
+| [CAGE-APPR-004](CAGE-APPR-004.md) | 路由没有对应审批绑定 |
+| [CAGE-APPR-005](CAGE-APPR-005.md) | 流程名称格式错误 |
+| [CAGE-APPR-006](CAGE-APPR-006.md) | 流程没有步骤 |
+| [CAGE-APPR-007](CAGE-APPR-007.md) | 找不到审批人 |
+| [CAGE-APPR-010](CAGE-APPR-010.md) | 流程专用命令没有调用者 |
+
+## 登录认证
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AUTH-001](CAGE-AUTH-001.md) | OIDC 发现文档获取失败 |
+
+## 业务流程阅读规格
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-BIZ-001](CAGE-BIZ-001.md) | 业务流程声明无效 |
+| [CAGE-BIZ-002](CAGE-BIZ-002.md) | 业务流程与真实声明不一致 |
+
+## 体积与逃生口预算
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-BUDGET-001](CAGE-BUDGET-001.md) | 内核超出体积预算 |
+| [CAGE-BUDGET-002](CAGE-BUDGET-002.md) | 公共原语超过词汇预算 |
+| [CAGE-BUDGET-003](CAGE-BUDGET-003.md) | 新增未经基线认可的 unsafe |
+
+## 命令
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CMD-002](CAGE-CMD-002.md) | 已有记录命令缺少 id |
+| [CAGE-CMD-003](CAGE-CMD-003.md) | 新建命令没有目标状态 |
+
+## 第三方连接器
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CONN-001](CAGE-CONN-001.md) | 连接器名称格式错误 |
+| [CAGE-CONN-002](CAGE-CONN-002.md) | 外部操作路径格式错误 |
+| [CAGE-CONN-003](CAGE-CONN-003.md) | 地址白名单包含协议或路径 |
+| [CAGE-CONN-004](CAGE-CONN-004.md) | 只读操作被用作出站写映射 |
+| [CAGE-CONN-005](CAGE-CONN-005.md) | 入站事件名称格式错误 |
+| [CAGE-CONN-006](CAGE-CONN-006.md) | 回调命令未允许 external |
+| [CAGE-CONN-007](CAGE-CONN-007.md) | 当前环境没有连接器地址 |
+| [CAGE-CONN-008](CAGE-CONN-008.md) | 外部请求发生网络错误或超时 |
+| [CAGE-CONN-009](CAGE-CONN-009.md) | 外部服务返回非成功状态 |
+| [CAGE-CONN-010](CAGE-CONN-010.md) | 外部响应不符合 schema |
+| [CAGE-CONN-011](CAGE-CONN-011.md) | 出站永久失败进入死信 |
+| [CAGE-CONN-012](CAGE-CONN-012.md) | 外部专用命令没有声明调用者 |
+| [CAGE-CONN-013](CAGE-CONN-013.md) | 出站幂等键无效或请求冲突 |
+| [CAGE-CONN-014](CAGE-CONN-014.md) | 不可重试外部写入结果未知 |
+| [CAGE-CONN-015](CAGE-CONN-015.md) | 连接器超时或限流参数无效 |
+
+## 创建应用
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CREATE-001](CAGE-CREATE-001.md) | 项目创建参数或模板资源有误 |
+
+## 可抽取声明
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DECL-001](CAGE-DECL-001.md) | 声明不在可抽取的顶层常量 |
+| [CAGE-DECL-002](CAGE-DECL-002.md) | 声明没有从 domain 入口导出 |
+| [CAGE-DECL-003](CAGE-DECL-003.md) | 声明不是 export const |
+| [CAGE-DECL-004](CAGE-DECL-004.md) | 跨文件导出名冲突 |
+
+## 依赖边界
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DEP-001](CAGE-DEP-001.md) | 领域声明直接依赖 IO |
+| [CAGE-DEP-002](CAGE-DEP-002.md) | 适配器绕过命令写库 |
+| [CAGE-DEP-003](CAGE-DEP-003.md) | 前端依赖服务端实现 |
+| [CAGE-DEP-004](CAGE-DEP-004.md) | 声明或 handler 直接发请求/动态导入 |
+| [CAGE-DEP-005](CAGE-DEP-005.md) | domain 反向依赖生成物 |
+
+## 工程目录与模块依赖
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-STRUCT-001](CAGE-STRUCT-001.md) | 业务源码目录不符合模块约定 |
+| [CAGE-STRUCT-002](CAGE-STRUCT-002.md) | 源码依赖越过模块边界 |
+
+## 死信操作
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DLQ-001](CAGE-DLQ-001.md) | 死信不存在或已经处理 |
+
+## 运行配置
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ENV-001](CAGE-ENV-001.md) | 缺少数据库连接配置 |
+| [CAGE-ENV-002](CAGE-ENV-002.md) | 运行配置不满足安全边界 |
+| [CAGE-ENV-003](CAGE-ENV-003.md) | 服务启动不能隐式初始化组织 |
+
+## 事件载荷与兼容性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-EVENT-001](CAGE-EVENT-001.md) | 事件载荷不满足声明 |
+| [CAGE-EVENT-002](CAGE-EVENT-002.md) | 事件变更不向后兼容 |
+
+## 字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-FIELD-001](CAGE-FIELD-001.md) | 敏感字段种类不存在 |
+| [CAGE-FIELD-002](CAGE-FIELD-002.md) | 引用目标为空 |
+| [CAGE-FIELD-003](CAGE-FIELD-003.md) | 字段不是字段原语 |
+| [CAGE-FIELD-004](CAGE-FIELD-004.md) | 覆盖系统保留列 |
+
+## 关系字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REL-001](CAGE-REL-001.md) | 关系字段声明无效 |
+
+## 生成一致性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-GEN-001](CAGE-GEN-001.md) | 契约等生成结果过期 |
+| [CAGE-GEN-002](CAGE-GEN-002.md) | 声明结构没有对应迁移 |
+| [CAGE-GEN-003](CAGE-GEN-003.md) | 输入校验需要服务端执行 |
+
+## 角色授权与防提权
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或额度 |
+| [CAGE-GRANT-002](CAGE-GRANT-002.md) | 授予超出自己的数据范围 |
+| [CAGE-GRANT-003](CAGE-GRANT-003.md) | 能力不在代码目录中 |
+
+## 影响分析
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-IMPACT-001](CAGE-IMPACT-001.md) | 影响分析没有可用基线 |
+| [CAGE-IMPACT-002](CAGE-IMPACT-002.md) | 命名本体快照无效 |
+
+## 账号初始化
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-INIT-001](CAGE-INIT-001.md) | 管理员 URL 没有数据库名 |
+| [CAGE-INIT-002](CAGE-INIT-002.md) | 集群已有账号但缺少原凭证 |
+| [CAGE-INIT-003](CAGE-INIT-003.md) | 三种连接身份或目标不一致 |
+| [CAGE-INIT-004](CAGE-INIT-004.md) | 账号已创建但 .env 替换失败 |
+| [CAGE-INIT-005](CAGE-INIT-005.md) | 显式组织初始化或凭据交付失败 |
+
+## 定时任务
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-JOB-001](CAGE-JOB-001.md) | 定时表达式不合法 |
+| [CAGE-JOB-002](CAGE-JOB-002.md) | 任务调用了未声明的命令 |
+| [CAGE-JOB-003](CAGE-JOB-003.md) | 任务读取了未声明的聚合 |
+
+## 通用 lint
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-LINT-001](CAGE-LINT-001.md) | lint 语法或规则错误 |
+
+## 结构迁移与安全层
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-MIG-001](CAGE-MIG-001.md) | 迁移事务执行失败 |
+| [CAGE-MIG-002](CAGE-MIG-002.md) | 安全层重建失败 |
+| [CAGE-MIG-005](CAGE-MIG-005.md) | 已执行迁移内容被修改 |
+
+## 名称
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-NAME-001](CAGE-NAME-001.md) | 聚合名必须大驼峰 |
+| [CAGE-NAME-002](CAGE-NAME-002.md) | 字段名必须小驼峰 |
+| [CAGE-NAME-003](CAGE-NAME-003.md) | 事件名必须大驼峰 |
+| [CAGE-NAME-004](CAGE-NAME-004.md) | 命令名必须小驼峰 |
+| [CAGE-NAME-005](CAGE-NAME-005.md) | 查询名必须小驼峰 |
+| [CAGE-NAME-006](CAGE-NAME-006.md) | 任务名必须小驼峰 |
+
+## 组织模型
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ORG-001](CAGE-ORG-001.md) | 业务入口遗漏组织模型 |
+
+## 资源配对
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-PAIR-002](CAGE-PAIR-002.md) | 离开持有资源状态却没有释放 |
+
+## 安全查询
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-QUERY-001](CAGE-QUERY-001.md) | 查询必须选择一种实现 |
+| [CAGE-QUERY-002](CAGE-QUERY-002.md) | 自定义查询直接访问基表 |
+| [CAGE-QUERY-003](CAGE-QUERY-003.md) | 查询读取范围与声明不一致 |
+
+## 跨聚合反应
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REACT-001](CAGE-REACT-001.md) | 反应目标与命令聚合不一致 |
+| [CAGE-REACT-002](CAGE-REACT-002.md) | 同事务反应链嵌套过深 |
+| [CAGE-REACT-003](CAGE-REACT-003.md) | 集合或步骤顺序声明无效 |
+
+## 显式读依赖
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-READS-001](CAGE-READS-001.md) | handler 使用了未声明读依赖 |
+
+## 运行时注册表
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REG-001](CAGE-REG-001.md) | 注册表缺少被引用声明 |
+| [CAGE-REG-002](CAGE-REG-002.md) | 聚合或查询注册重名 |
+| [CAGE-REG-003](CAGE-REG-003.md) | 命令能力点重复 |
+
+## 自动路由
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ROUTE-001](CAGE-ROUTE-001.md) | 业务项目手写 HTTP 路由 |
+
+## 数据范围
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SCOPE-001](CAGE-SCOPE-001.md) | 范围组合子未知 |
+| [CAGE-SCOPE-002](CAGE-SCOPE-002.md) | 范围字段没有声明 |
+
+## 密钥边界
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SECRET-001](CAGE-SECRET-001.md) | 运行环境缺少密钥 |
+| [CAGE-SECRET-002](CAGE-SECRET-002.md) | 源码疑似包含密钥字面量 |
+
+## 敏感字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SENS-001](CAGE-SENS-001.md) | 敏感字段未标注就进入事件 |
+
+## SQL 参数化
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SQL-001](CAGE-SQL-001.md) | SQL 拼接用户值 |
+| [CAGE-SQL-002](CAGE-SQL-002.md) | sql.raw 接收动态表达式 |
+
+## 状态与可达性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-STATE-001](CAGE-STATE-001.md) | 引用了未声明状态 |
+| [CAGE-STATE-002](CAGE-STATE-002.md) | 状态集合为空 |
+| [CAGE-STATE-003](CAGE-STATE-003.md) | 状态名称格式错误 |
+| [CAGE-STATE-004](CAGE-STATE-004.md) | 状态名称重复 |
+| [CAGE-STATE-005](CAGE-STATE-005.md) | 状态声明位置冲突 |
+| [CAGE-STATE-010](CAGE-STATE-010.md) | 状态不可达 |
+| [CAGE-STATE-011](CAGE-STATE-011.md) | 非终态没有后续操作 |
+
+## AI 托管区
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SYNC-001](CAGE-SYNC-001.md) | AGENTS 托管区过期或标记损坏 |
+
+## 测试报告
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-TEST-001](CAGE-TEST-001.md) | 测试进程没有生成结果报告 |
+| [CAGE-TEST-002](CAGE-TEST-002.md) | 派生测试准备或初始夹具失败 |
+| [CAGE-TEST-003](CAGE-TEST-003.md) | 测试数据库目录归属不匹配 |
+
+## 逃生口
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-UNSAFE-001](CAGE-UNSAFE-001.md) | 逃生口缺少原因或负责人 |
+
+## 升级
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-UPGRADE-001](CAGE-UPGRADE-001.md) | 升级版本或 codemod 有歧义 |
+
+## 历史流程
+
+[CAGE-MIG-003](CAGE-MIG-003.md)、[CAGE-MIG-004](CAGE-MIG-004.md) 属于旧版初始化流程，当前使用 init + migrate；保留页面供历史诊断。
+
+手册随创建项目时的 CLI 版本分发。cage sync 仅更新 AGENTS 托管区；升级后需要按该版本的资料核对差异。
+
+框架维护者：修改 scripts/error-catalog.ts 后运行 pnpm docs:errors；不要只手改生成的逐码页面。

package/templates/blank/docs/errors/runtime.md

@@ -0,0 +1,50 @@
+# HTTP 运行时错误与业务码
+
+[返回错误码册](README.md) · [排错方法](../ai/troubleshooting.md)
+
+框架诊断分三层：`CAGE-APPR-007` 等内部/工具码、HTTP 响应的通用 `code`、业务拒绝的 `domainCode`。同一次失败可以同时涉及几层；例如审批人配置问题出现在 worker 死信，前端提交此前可能已成功。
+
+## 接口错误
+
+| code | HTTP | 含义 | 业务前端/AI 应怎么做 |
+| --- | --- | --- | --- |
+| UNAUTHENTICATED | 401 | 会话不存在/失效或认证未通过 | 重新登录；回调先核对验签，不跳过认证 |
+| FORBIDDEN | 403 | 无能力、身份不允许，或 CSRF 拒绝等 | 看 detail 与当前授权；不能只因有按钮就认为有权。客户端会刷新过期 CSRF 令牌重试 |
+| NOT_FOUND | 404 | 记录不存在或超出范围 | 用当前用户检查 id/租户/范围，不泄漏范围外数据 |
+| INVALID_INPUT | 400 | Zod/协议输入错误、外键或检查约束等 | 按输入 schema 修正字段和格式，不直接扩大 schema |
+| INVALID_TRANSITION | 409 | 当前状态不允许该命令 | 刷新记录，按真实生命周期显示允许操作 |
+| CONSTRAINT_VIOLATED | 403 | 职责分离、额度、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
+| INVARIANT_VIOLATED | 409 | 命令结果不满足聚合不变量 | 修正输入或 handler，保持合法结果 |
+| CONFLICT | 409 | 版本、唯一性、数据库串行化/死锁等冲突 | 看 detail、重新读取再决定是否重试；不要盲目重复创建 |
+| DOMAIN_ERROR | 422 | handler 返回 fail | 读取 domainCode，展示业务文案和必要 detail |
+| RATE_LIMITED | 429 | 请求超过限流 | 按提示等待，避免页面无限重试 |
+| INTERNAL | 500 | 未分类内部错误 | 用 requestId 查服务端日志，向用户显示通用失败；不返回堆栈/密钥 |
+| NETWORK（仅客户端） | 0 | 请求未取得可用网络响应 | 检查连接与服务状态；保留同次操作幂等键，避免误认为服务端一定未执行 |
+
+网络失败和超时不证明服务端事务未提交。通用重试与人工重试都需考虑幂等与当前状态，不能先写 SQL 回滚业务再重发。
+
+## 业务码用法
+
+领域 handler 返回：
+
+```ts
+return fail('STOCK_SHORT', ['A-01']);
+```
+
+HTTP 响应形状为：
+
+```json
+{ "code": "DOMAIN_ERROR", "domainCode": "STOCK_SHORT", "detail": ["A-01"] }
+```
+
+客户端方法返回可区分结果，先判断 `result.ok`；失败时看 `result.code`，业务错误再看 `result.domainCode`。不要假设 code 直接等于 STOCK_SHORT，也不要把所有 403 当作“请重新登录”。
+
+业务码由项目定义并在页面翻译；字段 schema、不变量、硬约束和业务 fail 各有职责。正常业务拒绝不要伪装成普通异常导致 INTERNAL。
+
+## 异步任务与死信
+
+导入/导出 HTTP 202 只表示任务已接受，任务详情另有 queued/processing/retrying/completed/failed/expired。检查 task.errorCode/result 和导入报告，完成后才提供成功提示或下载。
+
+outbox 消费失败可能重试或进死信；修复内层错误后重放，查看同一聚合后续消息是否继续。使用管理接口处理，不直接更新 sys.outbox 或业务状态。
+
+当前实现定义位于框架源码 `packages/kernel/src/errors.ts` 与客户端包；实际 API 响应为准。生成契约会列出命令可能的通用错误与能抽取到的业务码，但不代表任何错误都已被实际测试覆盖。

package/templates/blank/docs/examples/purchase-admin/README.md

@@ -0,0 +1,5 @@
+# 采购范例参考源码
+
+本目录只供阅读，不参与应用编译、注册、运行或迁移。当前应用的真实领域入口是项目根目录 packages/domain/src/index.ts。
+
+按 [采购范例导读](../../ai/purchase-example.md) 阅读；导读中的范例路径在本目录下查找。需要可运行的完整采购项目时，重新使用 create-cage-app --template purchase 创建新目录，不要直接把整套业务导入空白项目。

package/templates/blank/docs/examples/purchase-admin/apps/api/src/main.ts

@@ -0,0 +1,14 @@
+// 启动入口只装配框架：认证、业务路由和 /admin 都由 createServer 提供。
+// WEB_DIR 在部署镜像中指向 Vite 构建产物；本地由 Vite 独立提供前端。
+// 进程启动只建立服务，不迁移结构、不初始化账号；这些操作由受控 CLI 流程提前完成。
+// 声明中启用的 AI、审批与文件接口由框架挂载，后台事件消费仍需要独立 worker 进程。
+import { createServer } from '@yss123/cage-http';
+import * as domain from '@app/domain';
+
+// 默认不接受转发头；部署在代理后时，仅在这里填写实际可信代理的地址或网段。
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台', trustProxy: false });
+// listen 先等待路由、扩展与授权通知初始化；失败直接拒绝顶层启动，不伪装为已就绪。
+await server.listen();
+// 退出时释放数据库池及 LISTEN 连接，部署滚动替换时不会留下旧连接。
+process.once('SIGINT', () => void server.close());
+process.once('SIGTERM', () => void server.close());

package/templates/blank/docs/examples/purchase-admin/apps/api/src/worker.ts

@@ -0,0 +1,17 @@
+// API 与 worker 使用相同声明。worker 专门处理审批启动、异步反应和 ERP 推送。
+// 两个进程部署同一版本，消费者依据声明发现工作；事件提交成功不等于这些后台动作已经完成。
+import { startWorker } from '@yss123/cage-http/worker';
+import { fakeConnector, stage } from '@yss123/cage-connectors';
+import * as domain from '@app/domain';
+
+// 本地和测试的 ERP 返回确定的单号，便于查看同步记录；生产环境走真实出口。
+if (stage() === 'fake') {
+  fakeConnector(domain.erp, {
+    pushOrder: (request) => ({ erpNo: `DEMO-${request.externalId.slice(0, 8)}` }),
+  });
+}
+// 框架拥有轮询、重试、调度和连接生命周期；应用只注册本地 fake，不另建数据库池或业务重试循环。
+const worker = await startWorker({ domain });
+// 停止句柄等待框架在途工作收尾并释放连接，避免进程退出时留下仍在续租的消费者。
+process.once('SIGINT', () => void worker.stop());
+process.once('SIGTERM', () => void worker.stop());

package/templates/blank/docs/examples/purchase-admin/apps/web/src/app/app.tsx

@@ -0,0 +1,128 @@
+/**
+ * 采购应用的路由组合层，集中连接认证、工作台、采购、库存和审批模块的公开入口。
+ * 会话先恢复，再决定展示页面、跳转登录或保留原地址提示网络故障。
+ * 页面身份来自 URL，模块间导航通过 app 注入；前端能力守卫不能代替服务端授权。
+ */
+// URL 是页面身份；应用壳只组合路由、会话与模块，不用组件状态模拟多页面导航。
+import { BrowserRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom';
+import { LoginPage } from '../modules/auth';
+import { HomePage } from '../modules/workspace';
+import { PurchaseOrdersPage, PurchaseOrderDetailPage } from '../modules/purchase';
+import { InventoryPage } from '../modules/inventory';
+import { ApprovalTasksPage, useApprovalTasks } from '../modules/approval';
+import { PageState } from '../shared/ui/page-state';
+import { RequireCapability } from '../shared/ui/require-capability';
+import { loginReturnTo } from '../shared/lib/navigation';
+import { useSession } from './use-session';
+import { WorkspaceLayout } from './workspace-layout';
+
+const home = '/workspace';
+
+/**
+ * 安装 BrowserRouter 并渲染路由树。部署方需为业务深链接提供 SPA 回退，/api 和 /admin 由各自服务处理。
+ */
+export function App() {
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  );
+}
+
+/**
+ * 在组合层读取审批待办数量并传给采购列表，使采购模块不依赖审批页面的内部实现。
+ * 待办尚未加载或失败时允许数量缺省，页面显示未知而不伪造零。
+ */
+function OrdersRoute() {
+  const tasks = useApprovalTasks();
+  return <PurchaseOrdersPage pendingTasks={tasks.data?.length} />;
+}
+
+/**
+ * 根据 useSession 的 loading/guest/ready/error 状态组装路由。
+ * guest 使用完整路径、查询参数和 hash 构造 returnTo；ready 经 loginReturnTo 校验后回跳。
+ * 网络错误保持当前地址以便重试；未知业务地址展示 404 页面，记录读取错误由各页面处理。
+ */
+function AppRoutes() {
+  const { session, restore, onLogin, onLogout } = useSession();
+  const location = useLocation();
+  if (session === 'loading')
+    return (
+      <div className="loading" role="status">
+        正在连接工作台…
+      </div>
+    );
+  if (session === 'error')
+    return (
+      <PageState
+        title="暂时无法连接工作台"
+        description="请检查网络和 API 服务，重试后继续访问当前地址。"
+        to={home}
+        label="返回工作台"
+      >
+        <button onClick={restore}>重新连接</button>
+      </PageState>
+    );
+  const login = `/login?returnTo=${encodeURIComponent(location.pathname + location.search + location.hash)}`;
+  return (
+    <Routes>
+      <Route
+        path="/login"
+        element={
+          session === 'ready' ? (
+            <Navigate to={loginReturnTo(location.search, home)} replace />
+          ) : (
+            <LoginPage onLogin={onLogin} />
+          )
+        }
+      />
+      <Route
+        element={
+          session === 'ready' ? <WorkspaceLayout onLogout={onLogout} /> : <Navigate to={login} replace />
+        }
+      >
+        <Route index element={<Navigate to={home} replace />} />
+        <Route path="workspace" element={<HomePage />} />
+        <Route
+          path="procurement/orders"
+          element={
+            <RequireCapability capability="PurchaseOrder.read" home={home}>
+              <OrdersRoute />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="procurement/orders/:id"
+          element={
+            <RequireCapability capability="PurchaseOrder.read" home={home}>
+              <PurchaseOrderDetailPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="inventory"
+          element={
+            <RequireCapability capability="Inventory.read" home={home}>
+              <InventoryPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="approvals"
+          element={<ApprovalTasksPage orderUrl={(id) => `/procurement/orders/${encodeURIComponent(id)}`} />}
+        />
+        <Route
+          path="*"
+          element={
+            <PageState
+              title="页面不存在"
+              description="请检查地址，或从工作台导航进入已有页面。"
+              to={home}
+              label="返回工作台"
+            />
+          }
+        />
+      </Route>
+    </Routes>
+  );
+}