GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

1
Some checks failed
CI / verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
高物
2026-04-20 21:06:48 +08:00
parent 1c72066bab
commit 75944b1f1f
102 changed files with 9648 additions and 1540 deletions
Download Patch File Download Diff File Expand all files Collapse all files

369
docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md Normal file
View File

@@ -0,0 +1,369 @@
# 当前工程优化点盘点（2026-04-20）
更新时间：`2026-04-20`
## 0. 盘点目标
这份文档用于回答一个更直接的问题：
**基于当前仓库状态，接下来最值得投入工程时间的优化点是什么。**
本轮只做文档盘点，不直接修改业务代码；结论同时参考了当前工作区现状。
需要注意，仓库当前存在一批未提交改动，尤其集中在 `custom world`、`assets`、`platform shell` 相关模块，所以本文更强调“优先级与切入方式”，而不是要求做大范围整仓改写。
---
## 1. 当前快照
## 1.1 本轮复核方式
本轮主要复核了以下内容：
1. 现有工程优化审计文档与目录索引
2. `package.json`、`vite.config.ts`、`.eslintrc.cjs` 等门禁脚本
3. 当前前端、后端、脚本目录的大文件热点
4. 运行时、鉴权、自定义世界、资产链路的边界实现
5. 当前 `typecheck / lint / build` 状态
---
## 1.2 当前门禁结果
| 项目 | 结果 | 当前判断 |
| --- | --- | --- |
| `npm run typecheck` | 失败 | 当前第一优先级问题，类型基线已失真 |
| `npm run lint:eslint` | 失败 | `136` 个 error、`4` 个 warning，且 `95` 个可自动修复 |
| `npm run build` | 通过 | 发布链路未红，但体积压力仍明显存在 |
### 关键说明
当前状态和 `2026-04-10` 那轮“build warning 直接拦截”的状态不同：
1. **构建现在可以通过。**
2. **真正变成第一阻塞项的是 `typecheck` 与 `lint`。**
3. **构建虽然通过，但主包、功能包、CSS 体积依然偏重，说明性能类优化仍然值得做。**
---
## 1.3 当前热点文件快照
本轮按源码目录统计的大文件热点如下：
| 文件 | 当前行数 | 判断 |
| --- | --- | --- |
| `src/components/CustomWorldEntityEditorModal.tsx` | `6122` | 当前前端最大热点 |
| `server-node/src/app.test.ts` | `3568` | 后端测试聚合度过高 |
| `server-node/src/modules/assets/characterAssetRoutes.ts` | `2802` | 资产路由职责过重 |
| `src/services/ai.ts` | `2432` | 浏览器侧 AI 编排仍然偏重 |
| `server-node/src/modules/story/storyActionRoutes.test.ts` | `2402` | 运行时路由测试聚合度过高 |
| `src/data/npcInteractions.ts` | `2274` | NPC 规则数据仍然集中 |
| `src/prompts/storyPromptBuilders.ts` | `1728` | prompt 构造成为新的复杂度中心 |
| `server-node/src/modules/custom-world/runtimeProfile.ts` | `1623` | custom world runtime 编译热点 |
| `src/hooks/story/npcEncounterActions.ts` | `1582` | NPC 行动流仍然偏重 |
| `src/components/game-shell/PlatformHomeView.tsx` | `1474` | 平台首页壳层继续膨胀 |
| `src/components/game-shell/PreGameSelectionFlow.tsx` | `1418` | 前置选择流程职责过多 |
| `src/services/customWorld.ts` | `1383` | 自定义世界服务虽然收缩，但仍偏大 |
---
## 2. 结论先行
当前仓库的优化重点，已经不是“继续清旧 Vite 插件链路”或者“继续讨论前后端是否要分离”。
更准确地说，当前最值得做的优化点已经收敛成四类：
1. **先恢复可信的工程基线。**
`typecheck` 与 `lint` 当前都是红线，继续扩功能会放大返工成本。
2. **拆掉正在持续膨胀的新热点。**
热点已经从早期运行时主链，迁移到 `custom world`、`asset routes`、`platform shell`、`prompt builders`。
3. **继续把前端退出“运行时真相”和“鉴权真相”。**
当前前端仍保留本地快照镜像与自动登录凭证持久化。
4. **补一轮入口归档，减少疑似孤岛模块和大测试聚合文件。**
这部分不一定最急，但会持续拉低仓库可维护性。
一句话判断：
**当前最值得投入的不是横向加功能，而是把质量门禁重新拉绿，再把 custom world / asset / platform 这批新复杂度中心拆开。**
---
## 3. 优化点清单
## 3.1 P0：先恢复类型基线
这是当前最优先的工程优化点。
### 证据
`npm run typecheck` 当前失败，主要问题集中在两类：
1. `CustomWorldCampScene` 结构漂移
- `src/components/CustomWorldEntityEditorModal.test.tsx`
- `src/data/customWorldLibrary.ts`
- `src/services/customWorld.ts`
- `src/services/customWorldCamp.ts`
2. 局部实现与类型定义不同步
- `src/components/auth/AccountModal.test.tsx` 的测试数据缺少新增字段
- `src/components/game-canvas/GameCanvasShared.tsx` 引用了未定义的 `DEFAULT_IMAGE_STYLE`
### 影响
1. 类型系统已经不能提供可信回归信号。
2. 自定义世界链路当前正在迭代，如果继续在红线状态叠加修改，后续会反复出现“改 A 崩 B”的情况。
3. 测试 fixture 与正式类型脱节，会让测试文件逐渐失去文档价值。
### 建议
1. 先补一个统一的 `CustomWorldCampScene` 构造/归一化入口，禁止在多个文件里手写不完整字面量。
2. 把 `auth`、`custom world` 的测试 fixture 改成工厂函数，避免字段新增后多处漏改。
3. 单独清掉 `GameCanvasShared.tsx` 这类“编译即失败”的确定性问题，优先恢复 `typecheck` 绿色基线。
---
## 3.2 P0：恢复 lint 可信度，区分机械问题和真实问题
这项和类型基线同级。
### 证据
`npm run lint:eslint` 当前结果是：
- `136` 个 error
- `4` 个 warning
- 其中 `95` 个问题可自动修复
当前 lint 问题明显分成两层：
1. 机械问题
- import 排序
- export 排序
- 未使用导入
2. 真实问题
- `server-node/src/modules/inventory/inventoryStoryActionService.ts` 出现 React Hook 规则错误
- `server-node/src/migrate.ts` 仍触发 `no-console`
- `packages/shared/src/http.ts` 触发 `@typescript-eslint/ban-types`
- 若干文件存在真正未使用变量、转义和规则误配问题
### 影响
1. 当前 lint 信号噪音仍然较高，不利于 review。
2. 真实问题会被大量机械问题掩盖。
3. 团队会更倾向于跳过 lint，而不是信任 lint。
### 建议
1. 先跑一轮仅机械修复的清理批次，优先吃掉 import sort、unused imports 这类低风险项。
2. 再单独处理 Hook 误用、共享契约类型、脚本规则豁免这类语义问题。
3. 之后把“自动可修复问题”与“必须人工处理的问题”拆成两个门禁视角，减少下次再次堆积。
---
## 3.3 P1：拆 custom world / asset / platform 新热点
这是当前最有性价比的结构性优化点。
### 证据
当前复杂度最高的业务热点，已经集中在这些模块：
1. `src/components/CustomWorldEntityEditorModal.tsx`
2. `server-node/src/modules/assets/characterAssetRoutes.ts`
3. `src/services/ai.ts`
4. `src/prompts/storyPromptBuilders.ts`
5. `server-node/src/modules/custom-world/runtimeProfile.ts`
6. `src/components/game-shell/PlatformHomeView.tsx`
7. `src/components/game-shell/PreGameSelectionFlow.tsx`
8. `src/hooks/story/npcEncounterActions.ts`
### 问题本质
这些文件并不是单纯“代码多”，而是同时承载了多类职责：
1. UI 状态
2. 领域规则
3. 请求编排
4. 文本构造
5. 运行时映射
6. 面板切换与流程控制
### 建议
1. `CustomWorldEntityEditorModal.tsx`
- 先按“实体列表/表单区/资源区/高级设置/预览区”拆组件
- 再把数据准备与提交编排抽成 hook
2. `characterAssetRoutes.ts`
- 拆成 route、prompt payload、job orchestration、产物发布、错误响应五层
3. `PlatformHomeView.tsx` 与 `PreGameSelectionFlow.tsx`
- 把页面壳层、数据加载、卡片渲染、弹层控制拆开
4. `storyPromptBuilders.ts` 与 `runtimeProfile.ts`
- 把“模板片段”“上下文归一化”“规则裁剪”“最终拼接”分层
---
## 3.4 P1：继续控制构建产物体积
构建虽通过，但体积已经给出明显信号。
### 当前证据
本轮 `npm run build` 输出里，几个值得关注的点是：
1. `dist/assets/AuthenticatedApp-*.js`：`794.77 kB`
2. `dist/assets/index-*.js`：`197.44 kB`
3. `dist/assets/CustomWorldResultView-*.js`：`163.38 kB`
4. `dist/assets/ai-*.js`：`131.73 kB`
5. `dist/assets/PreGameSelectionFlow-*.js`：`96.39 kB`
6. `dist/assets/index-*.css`：`201.44 kB`
### 影响
1. 虽然还没触发新的 build gate 红线，但首屏、缓存和移动端体验会继续承压。
2. `AuthenticatedApp` 主包偏大，说明平台壳层仍然装入了过多首屏不必需能力。
3. CSS 体积继续上涨，说明样式正在跨模块相互堆叠。
### 建议
1. 继续把 custom world、asset studio、平台详情页、角色资产工具从主壳层路径中抽离。
2. 审查 `ai.ts`、`custom world result view`、`pregame selection` 是否还能再延迟加载。
3. 对全局样式做一次按模块归属清理，减少公共样式无限增长。
---
## 3.5 P1：继续收紧前端与后端边界
这项已经不是“要不要做”的问题，而是“还剩多少尾巴没收完”。
### 当前证据
1. `src/services/apiClient.ts`
- 当前仍把 `access token`
- 自动登录用户名
- 自动登录密码
写入 `window.localStorage`
2. `src/hooks/story/runtimeStoryCoordinator.ts`
- 当前仍会在调用后端运行时前先 `putSaveSnapshot(...)`
- 响应后继续 `rehydrateSavedSnapshot(...)`
3. `src/hooks/story/npcEncounterActions.ts`
- 当前仍从前端动作流触发 `generateQuestForNpcEncounter(...)`
- 说明 NPC 任务“换单/重抽”分支尚未完全后端化
### 影响
1. 前端仍保留了一部分运行时真相与鉴权真相。
2. 自动登录凭证持久化在边界和安全上都不理想。
3. 运行时快照前置写入，会让“前端镜像状态”和“后端会话状态”继续纠缠。
### 建议
1. 优先移除自动登录用户名/密码本地持久化，收敛到服务端 session / refresh 机制。
2. 把运行时快照改为“展示缓存”而不是“提交前真相源”。
3. 把 NPC 任务更换动作补齐到后端 runtime/session 边界，不再由前端直接发起生成决策。
---
## 3.6 P2：做一次疑似孤岛模块与旧入口归档
这项不一定最紧急，但现在做会明显降低后续维护噪音。
### 当前现象
从当前入口关系看，以下模块值得做一次正式复核：
1. `src/components/GameShell.tsx`
2. `src/components/custom-world-home/CustomWorldCreationHub.tsx`
3. `src/components/custom-world-home/CustomWorldCreationLauncherModal.tsx`
4. `src/components/custom-world-agent/CustomWorldAgentLauncherModal.tsx`
5. `src/components/custom-world-agent/CustomWorldAgentDraftDrawer.tsx`
6. `src/hooks/story/storyBootstrap.ts`
7. `src/hooks/useEquipmentFlow.ts`
8. `src/hooks/useForgeFlow.ts`
9. `src/hooks/useInventoryFlow.ts`
10. `src/services/typewriter.ts`
### 当前判断
这批模块不一定全部是垃圾代码，但至少说明一件事：
**仓库里仍然存在一批“不是正式入口、也没有清晰归档标签”的过渡实现。**
### 建议
把这类模块统一分成三类：
1. 正式保留并接回入口
2. 明确标记为实验稿
3. 直接归档或删除
这样可以减少后续开发时的误判成本。
---
## 3.7 P2：拆测试聚合文件，恢复测试的定位能力
当前测试文件也已经出现“大一统热点”。
### 证据
1. `server-node/src/app.test.ts`：`3568` 行
2. `server-node/src/modules/story/storyActionRoutes.test.ts`：`2402` 行
3. `server-node/src/modules/assets/characterAssetRoutes.test.ts`：`1235` 行
4. `src/hooks/story/npcEncounterActions.test.ts`：`1199` 行
### 影响
1. 失败定位成本高。
2. fixture 复用差，字段一变容易整片测试跟着漂移。
3. 测试文件本身开始变成新的维护热点。
### 建议
1. 按领域动作拆测试文件，而不是继续堆到单一总测文件中。
2. 补 fixture builder / factory，减少字面量散落。
3. 对 `runtime / auth / custom world / assets` 这几条链路增加更明确的契约测试分层。
---
## 4. 推荐执行顺序
如果只按工程收益排序，建议按下面的顺序推进：
1. 先修 `typecheck`
2. 再把 `lint` 分成机械修复和语义修复两轮
3. 然后拆 `custom world / asset / platform` 热点
4. 再继续收前端运行时与鉴权边界
5. 最后处理孤岛模块归档和测试拆分
---
## 5. 当前不建议优先做的事
1. 不建议在 `typecheck` 和 `lint` 仍为红线时继续横向扩功能。
2. 不建议直接在 `CustomWorldEntityEditorModal.tsx`、`characterAssetRoutes.ts`、`PlatformHomeView.tsx` 里继续堆新逻辑。
3. 不建议把 bundle 体积问题简单理解为“先放宽阈值”，当前更适合继续拆职责和延迟加载。
4. 不建议在未确认入口关系前随手删除可疑旧模块，先做归档分类更稳。
---
## 6. 本文依据
文档依据：
1. `docs/audits/engineering/README.md`
2. `docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.md`
3. `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md`
4. `docs/experience/PROJECT_WORK_EXPERIENCE_PLAYBOOK.md`
当前仓库复核依据：
1. `package.json`
2. `.eslintrc.cjs`
3. `vite.config.ts`
4. `scripts/build-gate.mjs`
5. `src/App.tsx`
6. `src/services/apiClient.ts`
7. `src/hooks/story/runtimeStoryCoordinator.ts`
8. `src/hooks/story/npcEncounterActions.ts`
9. 当前源码大文件体量扫描结果
10. `npm run typecheck`
11. `npm run lint:eslint`
12. `npm run build`

16
docs/audits/engineering/README.md
View File

@@ -4,25 +4,29 @@
## 当前推荐入口
1. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)
1. [CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md](./CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md)
这一版是面向当前仓库状态的优化点盘点，适合直接拿来排优先级和拆执行批次。
2. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)
这一版是对 `2026-04-19` 基线的当前仓库复核，明确哪些问题已经处理、哪些表述需要纠正、热点又迁移到了哪里。
2. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)
3. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)
这一版保留原始问题快照和执行回填，适合回看“为什么会有这轮清理与边界收口”。
3. [ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md)
4. [ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md)
这一版最适合作为当前工程基线，重点从“是否真正绿色”“门禁有没有覆盖真实风险”来判断仓库状态。
4. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md)
5. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md)
适合回看运行时主链路、Story/Combat 边界、分层过渡期问题。
5. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md)
6. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md)
适合看第一轮系统性工程扫描，了解最早的问题基线。
## 融合结论
- 当前仓库已经完成“旧 dev 插件链路删除、根目录噪音清理、`server-node -> src/**` 反向依赖切断”这批第一阶段任务。
- 当前如果想直接判断“今天先优化什么”，优先看 `CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md`。
- 当前的新重点已经进一步收敛到三类：未接线孤岛模块、前端残留的运行时/鉴权真相、热点向 prompt/runtime profile/平台入口壳层迁移。
- 三轮结论是一致收敛的：问题不在“有没有开始工程化”，而在“工程化是否真正覆盖了最危险的主链路”。
- 最新一轮已经把关注点集中到质量门禁、真实绿色基线、关键模块豁免和 build warning 上。
- `2026-04-19` 这一轮把问题压实到了四类：仓库噪音、旧 dev 入口残留、前端越界运行时逻辑、巨型热点文件。
- `2026-04-20` 这一轮进一步确认：前两类已经阶段性完成，当前真正剩下的是边界尾巴和新热点迁移。
- 如果只是为了判断现在先做什么，直接从 `2026-04-01` 开始即可。
- 如果是要看当前清理和边界收口的最新状态，优先看 `2026-04-20`。
- 如果是要看当前清理和边界收口的最新状态，优先看 `ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md`。
- 如果是要看“当前可执行的优化点清单”，优先看 `CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md`。
- 如果是要做长期重构方案，再按 `2026-03-29 -> 2026-03-30 -> 2026-04-01 -> 2026-04-19 -> 2026-04-20` 的顺序回看演进。