docs(xingbang): 适配项目开发流程并建立经验驱动预审新版文档

docs/project-process/04-ui-spec.md

@@ -5,7 +5,7 @@
 > **输出**：表面规格 + DESIGN.md（含 token）+ i18n 约束。
 > **进入下一阶段（⑤ 实现）**：状态机、动作权限、设计 token、i18n 全部定案。
 
-> 适用判定：本阶段仅当改动拥有用户可见 UI（web 界面、Electron 窗口、设置面板、硬件设备界面）时强制；纯后端/网关/CLI 改动标记 `not applicable`。
+> 适用判定：本阶段仅当改动拥有用户可见 UI（项目工作台、评审页面、材料与配置界面、证据/模拟面板）时强制；纯后端/网关/CLI 改动标记 `not applicable`。
 
 ---
 
@@ -19,7 +19,7 @@
 - [ ] 每个交付面有：页面骨架 + 组件粒度边界 + 完整状态机 + 动作×权限表
 - [ ] 每个 UI 提交/展示的字段能在规格 §2 找到（契约门）
 - [ ] 视觉 token（颜色/字号/间距/圆角/组件）有语义化来源，不出现临时发明的 `blue500` 类裸色
-- [ ] 全部 UI 文案走 i18n（本仓：`packages/web-ui/src/i18n/messages.ts`，zh-CN/en-US 双语），无硬编码用户可见字符串
+- [ ] 新版文案有统一维护方式、错误码映射和语言范围；当前主要中文组件内文案，统一key化方案待建设，不声称已有双语语言包
 - [ ] 可访问性约束写明：对比度（WCAG AA）、focus-visible、颜色不单独承载状态、reduced-motion
 - [ ] 异常态（加载/空/错误/禁用/提交中）有明确视觉与文案定义（对应规格 `E-*`）
 
@@ -42,9 +42,9 @@
 
 | 编号 | 规则 |
 |---|---|
-| R-4.7 | **视觉事实源唯一**：有 UI 的项目维护唯一的视觉 token 事实源（本仓现状：`packages/web-ui/src/theme/tokens.css`，语义 token + CSS 变量，经 `styles.css` `@import` 消费；若将来建根级 `DESIGN.md` 则与之对齐）；禁止在组件里临时发明颜色/间距/字号。 |
+| R-4.7 | **视觉来源明确**：先检查src/app/globals.css、src/components/xingbang/navigation.css和当前页面CSS；v2视觉契约在docs/v2/DESIGN.md，统一token实现待建设。避免新增互相冲突的裸色/间距，不顺手重构无关旧页。 |
 | R-4.8 | **语义 token 优先**：token 用语义角色（`primary`/`surface`/`danger`），不用调色板名（`teal-500`）；组件 token 带状态（如 `button-primary-hover`、`text-input-focused`）。 |
-| R-4.9 | **token 可导出可防漂移**：token 能导出为 CSS 变量/主题，并用 lint/diff/单测检查漂移（本仓：`tokens.css` 变量 + `styles.test.ts` 等单测守卫；`useAppearance.ts` 归一化主题 id）；"文件存在"不等于"被使用"（G-3）。 |
+| R-4.9 | **防漂移须执行**：新token统一来源需有实际消费和可运行检查。当前scripts/test_ui_readability.cjs是源码守卫，不是完整token导出检查；缺少机制列待办。 |
 | R-4.10 | **可访问性硬约束**：正文与 focus 态满足 WCAG AA 对比度；错误/成功/选中状态不得只靠颜色表达；支持 reduced-motion；表单与错误态有明确指引。 |
 | R-4.11 | **不强推框架外规范**：后端/CLI/纯数据项目标记 `not applicable`，不套用视觉契约。 |
 
@@ -52,9 +52,9 @@
 
 | 编号 | 规则 |
 |---|---|
-| R-4.12 | 所有用户可见文案走 key 化翻译（本仓：`packages/web-ui/src/i18n/messages.ts`，扁平 key + `t(key, params?)`，key 按命名空间组织：`common.*`/`task.*`/`settings.*`/`shell.*`/`inspector.*`/`mode.*`）；禁止硬编码中文/英文串。 |
-| R-4.13 | 多语言文案与 UI 状态同步维护；新增文案必须同时补齐既有语言包。 |
-| R-4.14 | 设备端/子窗口界面不做 i18n 决策，文案由宿主统一注入（避免每窗口维护语言状态）。 |
+| R-4.12 | 新版文案按业务域规划key并绑定错误码；实际文件位置和调用方法在UI设计阶段明确。当前仅有中文文案，不能凭空引用语言包；旧页面修复遵循最小范围。 |
+| R-4.13 | 已支持的语言与UI状态同步维护；增加语言需明确范围和验收，不因来源模板写有双语就扩充产品需求。 |
+| R-4.14 | API返回稳定错误码，前端统一映射业务文案；同源代理转发错误语义，不自行生成另一套判断或吞错。 |
 
 ---
 
@@ -72,7 +72,7 @@ Interaction         交互约束：URL 状态、选择集规则、确认对话
 Constraints
 ```
 
-> 模板参考：`vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md` 的 §3（复用结构，内容必须基于本仓事实）。
+> 兴邦表面规格示例见 [v2 UI Spec](../v2/04-ui-spec.md)，需求编号仍回链至对应规格。
 
 ### 3.2 DESIGN.md 结构
 
@@ -85,11 +85,11 @@ Markdown（人读）            Overview / Colors / Typography / Layout / Elevat
                             + 每个 token 的"何时用 / 何时不用 / 防止什么 agent 错误"
 ```
 
-> 完整示例：`vendor/better-harness/case-studies/project-harness/design-md-complete-example.md`（结构性回退模板，数值必须替换为本仓已核实的来源）。若项目尚无 DESIGN.md：从现有代码/主题推断并标注"推断"，未决品牌决策标记 `needs-design-decision`，禁止编造。
+> 参考 [v2 DESIGN.md](../v2/DESIGN.md)。已观察值注明CSS来源，推断标“推断”，未定品牌决策标needs-design-decision；候选契约未被CSS消费不能宣称视觉系统已统一。
 
 ### 3.3 交付物清单
 - 每个交付面的表面规格
-- `DESIGN.md`（若建）或其缺失项清单；本仓现状：视觉 token 事实源为 `packages/web-ui/src/theme/tokens.css`（含证据分级：Present / Structured / Token-ready / Agent-ready / Aligned / Backstopped）
+- `DESIGN.md`或缺失清单；现有来源为src/app/globals.css和业务CSS。记录Present/Structured/Token-ready/Aligned/Backstopped证据等级，不能跳级。
 - i18n key 清单（新增/变更）
 - UI 验收映射：表面规格的每条交互约束 ↔ 规格 `AC-xx` ↔ [06-validation.md](06-validation.md) 的测试点（组件/E2E）
 
@@ -114,3 +114,5 @@ Markdown（人读）            Overview / Colors / Typography / Layout / Elevat
 
 - 输入：阶段 ① [01-requirement.md](01-requirement.md) §3、阶段 ③ [03-detailed-design.md](03-detailed-design.md)
 - 验证：阶段 ⑥ [06-validation.md](06-validation.md)（UI 驱动平面与裁判分离约束）
+
+变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。