> 本文整理自平台文档 docs/wujies/5.x/platform/architecture/design-docs.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-f49b1b074790-cover.svg)
这些是设计与方案文档:它们解释"为什么这么设计",以及有哪些备选方案被否掉了。 和文档站的其它页面不同,它们更接近工程日志 —— 包含实测记录、被推翻的假设、 以及踩过的坑。
它们不在本站正文(wujies-site 的 content/)里,而是随代码放在各仓库自己的 docs/ 下: 应用 / 插件开发类在 wujies-plugins/docs/,平台与部署类在 wujies-platform/docs/ (1Panel 那几份在 wujies-platform/docs/1panel/)。下面的路径都是仓库内路径,不是本站链接。
这些 docs/ 跟着各自的仓库进版本管理;要长期保留的内容请写在这里, 而不是散落在工作区根(工作区根已不再有游离的 docs/)。
什么时候看哪份
| 文档 | 什么时候看 |
|---|---|
wujies-plugins/docs/开发指南.md | 想搞懂"这东西是什么、怎么跑、改哪里"。本站大量内容的第一手来源 |
wujies-plugins/docs/应用市场-插件打包与部署教程.md | 要打包 / 上架 / 安装 / 签名,照着手敲命令 |
wujies-platform/AGENTS.md | 改代码前扫一遍"不变量"和"已知坑"。人也能当速查表。权威来源,优先级最高 |
wujies-plugins/docs/应用市场改造方案.md | 想知道为什么这么设计、有哪些备选方案被否了 |
wujies-plugins/docs/应用市场-插件运行时探针报告.md | 想动插件加载机制(类加载器 / 子上下文),先看这份实测记录 |
wujies-plugins/docs/应用市场-竞品调研与差距分析.md | 想对齐 Halo 等系统的能力边界 |
wujies-platform/docs/1panel/1Panel打包手册.md | 要把平台打成 1Panel 应用包 |
wujies-platform/docs/1panel/1Panel部署与上架.md | 怎么装、怎么上架到官方商店、排障速查 |
wujies-platform/docs/开发问题与解决方案.md | 本项目的踩坑总记录(2026-10):类加载器 / MyBatis 映射注册 / 序列化 / 前端远程产物 / 安装生命周期 / Windows 编码。想知道"这个坑怎么来的、怎么修的"看它 |
wujies-plugins/docs/插件开发详细教程.md | 从零到能做出来的详细版教程(16 章),以 wujies-quote 为骨架;★ 章节覆盖跨插件调用 / 开放接口 / Job / 系统服务 |
wujies-plugins/docs/AI-插件开发-SKILL.md | 给 AI 编码助手看的操作手册(不是教程):不变量、SOP、错误对照表、AI 特有的纪律 |
wujies-platform/docs/1panel/1Panel手册-待改清单.md + 1Panel手册-改动diff.txt | 那次改名后对 1Panel 手册做的逐处改动与依据(含"哪些不该改"的判断) |
wujies-platform/docs/app-market/app.schema.json | 应用清单的 JSON Schema |
几个"为什么"的答案
改造方案文档里有推导过程,这里给出结论:
### 为什么不给 sys_menu 加 app_code 列
归属从 app_version_menu 反查即可,「不需要改表」。 加列要动框架的实体 / VO / Mapper XML / 菜单页面,代价大得多, 而且会和 app_version_menu 形成两份真相。
### 为什么迁移不做 down
MySQL 的 DDL 是隐式提交的,包在一个事务里是假的安全感。 所以设计上要求脚本幂等,把"能重跑"当作回滚能力的替代品。
### 为什么进程内隔离而不是进程外
决策是进程内(性能优先):绝大多数插件需要与宿主深度交互, 进程内是主流选择。不可信页面用 iframe 降级沙箱。
### 为什么目录读取不做缓存
频率很低(只在安装/升级时几次),而加缓存会遇到 "刚上架却装到旧版本"这种难以解释的问题。
刻意不做的事(部分)
| 不做 | 理由 |
|---|---|
| 不往宿主那个 HandlerMapping 里注册插件路由 | 那是别人正在用的表,注销时键算错会连宿主接口一起摘掉 |
| 不让插件的 HandlerMapping 自动扫描上下文 | 父类默认实现会把宿主控制器重复注册一遍,排查时极具误导性 |
| 不让插件类加载器"子优先" | 平台类必须由父加载器提供,否则出现"双 Class 世界" |
| 不删任务历史 | 它是审计线索 |
| 不删对象存储里的文件 | 平台不知道它们属于谁,也不该替用户删文件 |
| 不做"上传即部署" | 上传只登记(解包读清单 + 落 OSS + 记校验和),产物释放是另一个动作 |
| 状态过滤放在前端 | 状态 tab 的计数必须来自"不带状态过滤"的整份列表 |
相关阅读
- [开发指南(贡献者)](/docs/wujies/5.x/platform/plugin/advanced/contributing)
- [必须遵守的不变量](/docs/wujies/5.x/platform/plugin/basics/invariants)
- [文档站维护说明](/docs/wujies/5.x/platform/reference/website)
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-f49b1b074790-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。