--- name: microi-system-delivery description: Microi 吾码从自然语言交付完整系统的总控规范。用于通过 MCP、VS Code 插件、V8 引擎、低代码元数据、UniApp/H5、PC 后台和 Playwright E2E 设计、生成、升级、测试、同步或交付完整 Microi 系统。 --- > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。 # Microi 全系统交付复盘与总控规范 本 Skill 来自一次完整业务系统交付复盘。目标是让下一套 OA、ERP、MES、CRM、商城、预约、互联网项目等 Microi 系统少走返工路：先固定事实源，再用 MCP 正确建模，最后用可视化和业务闭环测试证明可交付。 每张由 AI/MCP 创建的业务表都必须同时设计默认表单 Banner，不能只建字段和菜单。完整 Manifest 使用 `tables[].formBanner`；未显式配置时仍按字段类型选择业务编号/名称标题、 客户/项目副标题、首个 `ImgUpload`、状态/类型标签和真实数值指标，并写入 `diy_table` 语义字段。跨表统计由接口引擎批量返回，禁止随机数、固定演示值和 N+1；Banner 不属于 模块引擎或 `sys_menu`。逐步建模在字段完成后调用 `microi_configure_form_banner` 回读验收。 ## 交付总原则 1. **先事实源，后建模**：先读需求文档、截图、现有蓝图、数据库结构和菜单结构，形成业务蓝图；不要边猜边建表、边猜边写接口。 2. **先平台能力，后临时绕路**：能用 MCP/平台 API 修改元数据、字段、菜单、事件、接口引擎、数据源、任务调度，就不要新建临时 `_fix_*`、`_mcp_*` 接口引擎绕过平台能力。MCP 缺能力时优先补 MCP/后端，再补 Skill。 3. **平台通用层禁止项目定制**：Microi.Server、Microi.Client、MCP、VS Code 插件、microi.skills 中不得写某个项目专属文案、专属上传限制、专属业务规则。项目规则应在租户表、接口引擎、业务配置、前端项目或业务蓝图中。 4. **本地改完必须远端验收**：V8 文件、表单事件、菜单按钮、数据源、工作流、页面配置等不能只改本地文件。必须写入远端数据库，并通过 HTTP 或平台工具回读确认。 5. **测试不等于接口能通**：交付前必须跑构建、接口契约、真实登录、核心写流程、截图、人眼复核、网络 404/5xx 守卫、远端同步状态。 6. **生产数据谨慎优先**：涉及真实会员、余额、积分、订单、库存、卡券、收益、佣金、分润等资金/资产数据时，先确认服务器、租户、目标表、筛选条件和影响范围，再执行 MCP、接口引擎或 SQL 写操作。除用户明确要求清理/重置或必须修复错误数据外，不得擅自批量改真实数据。 7. **默认按分布式交付**：任何后端能力都假设会有至少两个节点连接同一数据库和 Redis，并经历滚动升级、重复投递与节点硬重启。定时任务/消费者使用分布式租约且业务本身幂等；会话、票据和任务状态使用共享存储；新旧版本并存时采用“先扩展、后迁移、再收缩”。只在单节点验证通过不能视为完整交付。 8. **业务逻辑默认接口引擎、元数据升级默认应用商城**：先用低代码 CRUD/事件，再用接口引擎；只缺底层原子能力时先扩展 V8，只有协议/鉴权/密钥隔离/运行时内核才进入 C#。表、字段、Tab、菜单、权限、引擎、页面和任务等可打包资源不得新增 `Microi.Upgrade` 定制类；官方开发者通过 `microi_itdos` 发布官方应用后再由目标租户 MCP 更新，无官方权限时只升级自己的租户。 9. **平台能力四项同步**：按 `workspace-conventions/SKILL.md` 首部识别创始人源码工作区；每项平台新增、增强或修复都逐项判断应用商城、官方中文文档、Skills、MCP 是否需要完善，交付时列出证据或无需修改的依据。复用已有 MCP 能力，不机械新增工具；镜像发布不等于客户部署，客户手动更新边界必须保留。 ## 用户问题编号跟踪（强制） 用户一次提出多个问题时，必须先拆成 `1、2、3、4...` 的问题清单，并在交付过程中保持同一编号，不得合并吞掉或用笼统“已优化”代替。 每个编号都要记录： - 需求原文或等价复述。 - 实现状态：已实现 / 部分实现 / 未实现 / 阻塞。 - 修改位置：前端文件、接口引擎、低代码表字段、菜单、数据、Skill 或测试。 - 验收方式：构建、接口回读、数据库回读、Playwright 自动化、截图、人眼复核。 - 剩余风险：未覆盖的端、未验证账号、需要用户确认的数据口径。 最终回复必须按原始编号逐项汇总：哪些已实现、哪些未实现、是否通过全自动化测试、是否通过截图验证。不能只给总括性“都完成了”。如果某项没有测试或没有截图，必须明说“未覆盖/未截图”，并说明原因。 ## 平台安全与存量兼容验收（强制） AI 零代码交付不能只验证管理员帐号和页面能打开。任何涉及 FormEngine、菜单、角色、子表、文件、SaaS 或登录协议的交付，都必须按以下服务端边界设计和验收： ### FormEngine 混合授权 - Token 只完成身份认证，不是任意表的访问凭证。浏览器、UniApp、SDK 等外部请求必须继续校验表、菜单、角色、操作权限和数据范围。 - 显式 `_SysMenuId` / `ModuleEngineKey` 进入精确菜单校验；伪造、传错或借用其它表菜单时失败关闭，不能退回兼容推断。 - 为兼容存量前端 V8，无菜单请求由后端从当前用户真正拥有的菜单授权快照中推断目标表权限。没有候选菜单、范围无法安全合并或解析失败时失败关闭；不要要求所有历史项目一次性补 `_SysMenuId`。 - 标准 PC facade 只给当前菜单绑定的当前表注入菜单 Id，跨表调用不借用主表菜单。没有菜单入口的 SDK/定制页才使用最小【高级表权限】。 - 后端接口引擎、后端表单 V8 和平台内部调用由服务端建立可信上下文，不要求 `_SysMenuId`；客户端伪造 `_TrustedServerInvocation` 或 `_InvokeType:'Server'` 不能获得信任。 - `TableChild` 使用父记录范围内委托：验证父菜单、父表字段配置、子菜单、父记录数据范围和外键，并由服务端强制注入外键。隐藏子菜单不要求存量角色逐个补权限。 - 菜单 `SqlWhere` / `SqlJoin` 只约束列表、计数、导出等集合查询；单行详情只校验同表菜单访问权。主表写入由 `Add` / `Edit` / `Del` / `Import` 专项权限控制，不把查询范围追加到写入 SQL，也不因查询 Join 拒绝。行级写业务限制放在后端表单 V8 或专用接口引擎。 ### 保护表、控制面与缓存 - SaaS、接口引擎、表/字段、菜单角色、用户、任务、数据源、MQ/MQTT、页面、打印、工作流、数据库、应用商城、AI 与安全审计等保护表，普通客户端 `Level < 9999` 硬拒绝；菜单或表权限不能覆盖。 - 创建 V8、接口引擎、任务、数据源和 Redis 管理等控制面 API 继续要求 `Level >= 9999`。不能只靠前端隐藏菜单。 - 权限缓存使用按 `OsClient` 隔离的共享 Redis `epoch`、用户快照、短 TTL L1/L2。用户/角色/菜单/权限变化后提升 `epoch`；验收至少使用两个节点确认无需清 Redis或重启即可生效。 - Upgrade15 只清理普通角色的保护表直接授权，不能删除正常业务菜单权限。 ### 上传、私有文件与 SaaS - 上传业务默认值为 100 MB/文件、200 MB/次、10 文件、2 GB/帐号/日、20 GB/租户/日。有效值只按当前租户 `sys_osclients` → 代码安全默认值解析，租户可以提高或降低业务默认值；不得为上传开关、额度或硬上限新增 API 环境变量或 `appsettings` 节点。最终仍受代码内不可突破的灾难保护、HTTP/Multipart/Form 和反向代理上限约束。共享 Redis 原子预留，Redis 故障失败关闭。 - 无字段上下文的普通交互式上传默认私有桶，一级安全目录为 `file`、`img`、`avatar`、`editor`；可由管理员在普通 `sys_config.HdfsUploadRules` 按真实角色授权业务目录与公有权限。通配符必须有界并先校验实际路径，保留目录与跨租户不能放行。标准表单仍按权威字段配置执行。可信后端 V8 仍受全局文件大小硬上限。 - 普通客户端私有文件签名必须提交 `FormEngineKey`、`FormDataId`、`FieldId`、`SysMenuId` 并验证记录字段真实引用；不能把后端 `V8.Method.GetPrivateFileUrl({FilePathName})` 的可信调用方式照搬到浏览器。 - Upgrade16 六个上传字段全部可空，空值保持老租户兼容；升级后回读字段元数据、租户值并刷新 SaaS 缓存。 - `V8.OsClientModel` / `V8.SysConfig` 只使用脱敏副本，不返回整个对象。新租户不能复制主租户整条 `sys_osclients`；数据库、认证、Redis、存储、MQ/MQTT、搜索凭据必须独立创建或由服务端托管。 - Redis 管理器只允许超级管理员使用当前租户或已保存连接；匿名/temporary 任意 Host 连接必须拒绝，MCP 写操作必须 `confirmExecution`，禁止传递 Redis 密码。 ### 网络、登录和发布兼容 - `CorsAllowOrigins` 和全局 CORS 来源都为空时默认允许任意来源；配置后才按精确来源/通配符收紧。CORS 不是鉴权边界。 - 严格 SSRF 默认关闭，未配置时不得拒绝存量非 HTTP(S)、URL 凭据、私网、云元数据和重定向调用；显式启用后才执行严格拦截与精确主机白名单。 - 登录 RSA 仅避免密码在请求体直接显示，HTTPS 才是安全边界。必须保留历史 RSA fallback，专属公私钥成对切换，不能因删除旧常量造成所有客户无法登录。 - 登录传 `_ClientType`，请求携带稳定 `did`，每次响应接收 `authorization`。多标签续签 single-flight；`TokenReplaced` 先检查新 Token，旧响应不能清掉新登录态。 - 安全升级不得删除私有子 Git 的 `Microi.Server/Microi.net/License/keys/`。授权签名资产与登录 RSA 用途不同，禁止以安全清理为由混删。 - 不得修改默认 CORS/SSRF/RSA 行为后只用新装环境验收；必须覆盖旧前端、历史 V8、滚动升级和至少两个节点。 ### 安全自动化最低断言 1. 普通角色保护表读写、伪造菜单、伪造可信标记均失败。 2. 真实菜单、历史无菜单推断和父记录范围内 TableChild 均成功，跨父记录失败。 3. 查询范围在列表、计数、导出中生效；详情按同表菜单访问权成功；有写权限的单表/Join 模块写入成功，无写权限失败，后端 V8 行级业务校验可回滚。 4. 节点 A 改权限后节点 B 无需重启生效。 5. 上传大小/数量/双日额度、多节点并发和 Redis 故障行为正确。 6. 私有文件跨菜单/记录/字段失败，授权访问成功，匿名失败。 7. CORS 空配置兼容、配置后收紧；SSRF 默认兼容、严格模式拦截。 8. 历史 RSA fallback 和专属匹配密钥均可登录；并发续签不反复退出。 9. SaaS 脱敏投影不包含基础设施密钥，Redis anonymous/temporary/非管理员管理失败。 ## 前端交付检查清单 - 底部 tabBar 图标不 404。 - 首页、分类、详情、Banner、头像、订单凭证图全部真实加载。 - 主题切换是全局生效，不是只对一个页面生效。 - 列表页和详情页显示同一主体名称、头像、状态，不能列表对、详情错。 - 关联人名不得退化成“卖家BMB9”“匿名卖家”等可推断 Id 的兜底，除非确实无数据。 - 关键业务资产不得默认选中第一条，必须用户手动选择。 - 自己不能抢自己的单，不能约自己的单，必须给明确提示。 - 消息/待办/约单/审核类提醒必须有未读角标，已读后消失。 - 订单状态角标只给需要处理的状态，不给“全部/已完成/已取消”等静态分类堆数字。 ## 交付完成定义 一次 Microi 全系统交付只有同时满足以下条件才算完成： 1. 蓝图/方案文档已更新到最新业务口径。 2. MCP 真实写入并通过平台验收工具验证。 3. V8 接口引擎/事件/菜单按钮本地与远端同步干净。 4. VS Code 插件同步状态无异常差异或冲突。 5. 前端构建通过。 6. 后端和前端服务可自动启动。 7. Playwright 账号登录、接口契约、网络守卫、业务闭环、截图复核均通过。 8. 生成或修改的通用经验已写回 microi.skills，且不能包含项目专属措辞；不能只写本地 memory、聊天记录或项目临时文档。 ## 详细参考路由（渐进披露） 仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。 - [references/progressive-01-标准工作流.md](references/progressive-01-标准工作流.md)：标准工作流 - [references/progressive-02-自动化测试必须覆盖的坑.md](references/progressive-02-自动化测试必须覆盖的坑.md)：自动化测试必须覆盖的坑；复盘记录格式