8.5 KiB
前端展示配置与业务职责分离
2026-10-21,基于已部署提交 3221ac65。用户选择同一仓库分层,先完成可定制布局基础。
本轮实现
React 已经通过 src/services/api 调用 Go HTTP;当前发布仍将 dist 与 API 放在同一镜像。本轮不搬仓库、不拆生产镜像,首先拆开看板查询流程和展示配置。
src/features/annotation-output/useAnnotationOutputData.ts集中筛选、查询竞态、统计快照、分页、供应商/人员下钻和导出。通过操作函数暴露业务意图,展示不直接维护快照或请求参数。src/components/AnnotationOutputDashboard.tsx组装已有业务内容和交互,按当前账号身份提供内容。默认顺序和统计口径保持一致。src/features/annotation-output/DashboardPresentation.tsx仅接受已授权的内容槽,负责顺序、密度、强调色以及预览/取消/保存/恢复默认。它不导入请求客户端、不获取任务数据,不根据配置生成业务按钮。presentation.ts是展示文档唯一校验入口。复用已有 Zod,无新增依赖。读取不合法、未知版本或损坏文档时使用默认;保存失败明确报错,不伪称已保存。- Go 的权限、统计快照和任务规则继续保持权威;业务请求和响应结构未更改。JSON v4 与标注保存/恢复不在本次范围。
这是第一条完整分层路径,不代表八千行标注页已经完成拆分。
展示文档 v1
{
"version": 1,
"page": "annotation-output",
"order": ["metrics", "suppliers", "tasks"],
"density": "comfortable",
"accent": "orange"
}
三个区块必须各出现一次;个人看板没有供应商内容时不会因排序配置而生成该区块。density 仅 comfortable/compact;accent 仅 orange/blue/teal。固定的查询入口、加载和错误反馈不参与排序。节点使用稳定身份,布局调整不重建查询控制器、不清空分页或筛选;相同源下账号/组织/角色变化重建看板,清除上一身份的内存结果。
首版是此浏览器的个人偏好,按组织 ID、账号 ID、角色组成键隔离。无服务端保存、跨设备同步或组织统一模板;既有深浅主题及标注专注布局设置继续独立工作。配置不存客户数据。可用的本地存储不构成授权边界,所有业务访问仍由服务器检查。
后续 agent 如何接入
agent 将来生成上述受限展示文档,走同一校验、预览和显式保存路径;本轮没有创建或接入 agent。拒绝未知字段、JavaScript、HTML、任意 CSS、URL、请求端点、权限字段和统计口径,不用生成代码替换业务 UI。
未来若增加共享模板,应另外定义组织/角色作用域、服务端授权与严格校验、版本竞争、发布和回退;客户端校验不能代替服务器校验。当前只实现实际需要的浏览器存储,不预建插件系统或通用 agent 执行器。
后续重构顺序
- 保留本轮展示 seam,扩展具体页面前先确定该页允许改变的内容与必须保留的业务控件。
- 深化标注保存/恢复 module:统一 autosave 等待、版本检查、丢响应回读及本地状态采纳。保留草稿/正式工作区、ADR0007 的原子归档和撤销、ADR0010 的旧任务恢复。
- 在该基础上统一拖拽与 E 面板的编辑会话,保持不同交互方式。
- 需要独立发布时,再拆 Web 与 Go 构建产物;保留同源入口优先,并测试认证 cookie、CSRF、媒体地址、滚动升级和前后端契约兼容。无需先拆成两个仓库。
本地验证
发布门禁已接入 npm run test:browser:dashboard:自动启动独立端口的内存 API 与 Vite、运行下列回归、关闭自己启动的进程,证据保留在 local-data/test-results/。不依赖既有本地 Mongo。
配置校验测试:node --test tests/frontend/dashboard-presentation.test.mjs。
已有真实 HTTP 看板回归扩展了布局预览、取消、保存、刷新恢复、重置、零额外统计请求,以及原有分页、快照一致性、下钻和 CSV 导出。本轮使用内存隔离样本,既没有连接快照 Mongo,也没有连接生产:
go run ./tests/browser/support/annotation-output-replica -memory -web-port 5201 -api-port 3031
VITE_DEV_API_BASE_URL=http://127.0.0.1:3031 npm run dev:web -- --host 127.0.0.1 --port 5201 --strictPort
BROWSER_EXECUTABLE="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" npm run test:browser:annotation-output
本地测试账号随机生成于忽略目录 local-data/verification/customer-dashboard-20261020/accounts.json,不得提交。未传 -memory 时仍保留原有本地 Mongo 测试模式;须先确认该端口实际目标。本轮内存验证不宣称覆盖 Mongo 重启持久化。
相关依据:React 状态保持与重置、Zod 严格对象校验。
本轮验证结果(2026-10-21)
- TypeScript、格式、生产构建与生产 dist 浏览器启动通过。
- 展示文档校验 4 组测试通过,包括未知字段、缺失/重复区块、错误版本、账号作用域与存储失败。
- 三角色真实 HTTP + 内存样本共 33 项检查通过;同浏览器账号切换、损坏配置回退、保存失败、窄屏与 Escape 共 4 项补充检查通过,页面无运行时错误。
- 全量前端正式基线门禁通过:13 项历史失败,均在已有 14 项基线中,没有新增失败,未修改基线。首次受限运行在既有 devboot 本机监听测试停滞,中止后允许本机端口重跑通过。
- 发布工具 37 项测试通过;新的自动启动/清理测试命令完整运行通过,已列入发布策略。
- 独立应用代码复核未发现阻断问题。没有执行公司部署、客户任务写入或 PR 提交。
第二阶段实施
2026-10-21 已继续完成保存协调与共享切片编辑会话的本地改造,见实现与兼容性记录。第一阶段看板配置不扩展到任务写入。
2026-10-21 分层依赖自动检查
保存协调、切片编辑会话、任务池、正式决定和审核草稿的分层已经分别落地,见同目录的 annotation-persistence.md、annotation-pool-loading.md、review-decision-coordination.md 和 review-draft-persistence.md。本轮把已拆出的部分职责约束加入 npm run lint:architecture,并由 lint:web 执行;现有本地提交钩子与发布流程调用 lint:web,因此无需另设发布入口。
检查复用项目已安装的 TypeScript AST,不新增依赖:
- 看板展示层只允许现有展示文件与 React、图标、Zod 依赖;业务数据 hook、HTTP 客户端、其他页面、别名导入与其他包不在允许范围内。
- 五个已拆出的协议入口(标注保存、切片会话、审核草稿、正式决定、决定完成协调)递归检查本地
src/lib帮助模块,拒绝 React、业务 HTTP、页面等依赖,避免通过间接帮助模块重新耦合。 - 检查静态 import、export-from、类型导入、动态 import、require 及 module.require;Vite glob 加载因无法逐一静态确认而阻断。协议模块内 JSX 的隐式 React 依赖也阻断。无法静态确定的模块加载、同名不同扩展造成的解析歧义、缺失文件、未解析依赖和语法错误阻断;报告具体文件、行号与依赖链。循环依赖遍历会终止,不因循环漏掉其他分支。
这是当前已分层模块的导入规则,不是整个仓库已完成分层,也不是恶意代码检测或运行时沙箱。直接使用浏览器全局、CSS 内容、回调中夹带业务行为等仍须代码审阅和行为回归;agent 继续只能提交受严格 schema 校验的展示文档。添加新依赖或扩大保护范围时,应根据实际职责调整规则和测试,不加通用豁免。
本轮无应用运行时代码、接口、Mongo、工作流、分类或交付格式变化,不涉及在途任务迁移。10 组回归覆盖正常依赖图以及违规直接/间接导入、动态加载、类型导入、循环、缺失文件、解析失败、扩展名歧义、glob 与隐式 JSX 依赖。独立复核指出的三处漏检已经修正并补用例。三角色看板真实 HTTP 与内存夹具的 33 项检查、4 项布局补充检查通过;全量前端仍为 13 项历史失败,零新增,14 项基线未改。发布工具、类型与格式检查通过。
本轮证据保存于工作树忽略目录 local-data/verification/architecture-dependencies-20261021/。未推送、未提交 PR、未部署。