create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//345/267/245/345/205/267/fixtures.mjs

@@ -0,0 +1,132 @@
+/** 虚构数据，仅供视觉验证的独立浏览器上下文使用。 */
+export const user = { id: 'qa-user', name: '林间', account: 'qa.visual@example.invalid' }
+export const companyScope = { type: 'company', companyId: 'qa-company' }
+export const projectScope = { ...companyScope, type: 'project', projectId: 'qa-project' }
+export const workspaces = [
+  { scope: { type: 'platform' }, name: '平台管理', administrator: 'platform' },
+  { scope: companyScope, name: '星屿科技', administrator: 'company' },
+  { scope: projectScope, name: '月光计划', companyName: '星屿科技', administrator: 'project' },
+]
+
+const pageDefinitions = {
+  platform: [
+    ['home', '平台工作台', 'dashboard'],
+    ['companies', '企业管理', 'companies'],
+    ['accounts', '全局账号', 'accounts'],
+    ['roles', '平台角色', 'roles'],
+    ['menus', '菜单管理', 'menus'],
+    ['audit', '平台操作日志', 'audit-log'],
+  ],
+  company: [
+    ['home', '企业工作台', 'home'],
+    ['profile', '企业资料', 'profile'],
+    ['members', '企业成员', 'members'],
+    ['roles', '企业角色', 'roles'],
+    ['projects', '项目管理', 'projects'],
+    ['audit', '企业操作日志', 'audit-log'],
+  ],
+  project: [
+    ['home', '项目工作台', 'home'],
+    ['profile', '项目资料', 'profile'],
+    ['members', '项目成员', 'members'],
+    ['roles', '项目角色', 'roles'],
+    ['audit', '项目操作日志', 'audit-log'],
+  ],
+}
+
+function access(scope) {
+  const menus = pageDefinitions[scope.type].map(([page, name, icon], sort) => ({
+    id: `qa-${scope.type}-${page}`,
+    scopeType: scope.type,
+    parentId: null,
+    type: 'page',
+    name,
+    icon,
+    sort,
+    hidden: false,
+    status: 'active',
+    routeKey: `${scope.type}.${page}`,
+    permissionKey: `${scope.type}.${page}.read`,
+    protected: false,
+    children: [],
+  }))
+  return {
+    user,
+    scope,
+    administrator: scope.type,
+    permissionKeys: menus.flatMap(({ routeKey }) =>
+      ['read', 'create', 'update', 'status', 'administrator', 'add', 'roles'].map(
+        (operation) => `${routeKey}.${operation}`,
+      ),
+    ),
+    menus,
+    menuVersion: 1,
+    catalogVersion: '2026-09-19.1',
+  }
+}
+
+const date = '2026-09-10T02:20:00.000Z'
+const company = {
+  id: 'qa-company',
+  name: '星屿科技',
+  code: 'STARISLE',
+  description: '连接灵感，创造日常中的新可能。',
+  status: 'active',
+  version: 1,
+  createdAt: date,
+  updatedAt: date,
+}
+const project = {
+  ...company,
+  id: 'qa-project',
+  companyId: 'qa-company',
+  name: '月光计划',
+  code: 'MOONLIGHT',
+}
+const companies = [
+  company,
+  {
+    ...company,
+    id: 'qa-company-2',
+    name: '云间设计',
+    code: 'CLOUD',
+    description: '让想象拥有形状。',
+  },
+  { ...company, id: 'qa-company-3', name: '远山工作室', code: 'FARHILL', status: 'disabled' },
+]
+
+function page(items, url) {
+  const query = url.searchParams.get('query') ?? ''
+  const status = url.searchParams.get('status')
+  const filtered = items.filter(
+    (item) =>
+      (!query || `${item.name} ${item.code ?? ''}`.includes(query)) &&
+      (!status || item.status === status),
+  )
+  return { items: filtered, total: filtered.length, page: 1, pageSize: 20 }
+}
+
+export function fixtureResponse(url, scenario) {
+  const path = url.pathname.replace(/^\/api/, '')
+  if (path === '/workspaces') {
+    return { user, workspaces: scenario === 'empty-workspaces' ? [] : workspaces }
+  }
+  if (path === '/platform/access') return access({ type: 'platform' })
+  if (path === '/companies/qa-company/access') return access(companyScope)
+  if (path === '/companies/qa-company/projects/qa-project/access') return access(projectScope)
+  if (path === '/platform/companies') return page(scenario === 'empty' ? [] : companies, url)
+  if (path === '/companies/qa-company/projects') return page([project], url)
+  if (path === '/companies/qa-company') return { ...company, administrators: [] }
+  if (path === '/companies/qa-company/projects/qa-project')
+    return { ...project, administrators: [] }
+  if (path === '/platform/accounts') {
+    return page(
+      [{ ...user, status: 'active', createdAt: date, updatedAt: date, platformRoleIds: [] }],
+      url,
+    )
+  }
+  if (path.endsWith('/roles') || path.endsWith('/members') || path.endsWith('/audit-logs')) {
+    return page([], url)
+  }
+  return undefined
+}

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//345/267/245/345/205/267/visual-check.mjs

@@ -0,0 +1,274 @@
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { fixtureResponse } from './fixtures.mjs'
+
+// 运行：node .spaces/04.界面与主题/万物梦幻/工具/visual-check.mjs --base-url http://127.0.0.1:9999
+// 仅检查浏览器可启动：node .spaces/04.界面与主题/万物梦幻/工具/visual-check.mjs --check-launch
+const require = createRequire(import.meta.url)
+const bundled =
+  'C:/Users/Administrator/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright'
+const { chromium } = require(process.env.PLAYWRIGHT_MODULE || bundled)
+const args = process.argv.slice(2)
+const baseUrl = args.includes('--base-url')
+  ? args[args.indexOf('--base-url') + 1]
+  : 'http://127.0.0.1:9999'
+const only = args.includes('--only') ? args[args.indexOf('--only') + 1] : undefined
+const featureRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const uiOutput = resolve(featureRoot, 'ui')
+const reportOutput = resolve(featureRoot, '测试证据')
+const browserPaths = [
+  process.env.PLAYWRIGHT_EXECUTABLE_PATH,
+  chromium.executablePath(),
+  'C:/Users/Administrator/AppData/Local/ms-playwright/chromium-1208/chrome-win64/chrome.exe',
+  'C:/Users/Administrator/AppData/Local/ms-playwright/chromium-1187/chrome-win/chrome.exe',
+].filter(Boolean)
+const executablePath = browserPaths.find(existsSync)
+assert(executablePath, '未找到 Chromium，请通过 PLAYWRIGHT_EXECUTABLE_PATH 指定已安装浏览器。')
+const browser = await chromium.launch({ executablePath, headless: true })
+if (args.includes('--check-launch')) {
+  console.log(JSON.stringify({ executablePath, version: browser.version(), baseUrl }, null, 2))
+  await browser.close()
+  process.exit(0)
+}
+
+const report = { baseUrl, browser: browser.version(), mockData: true, checks: [], failures: [] }
+await mkdir(uiOutput, { recursive: true })
+await mkdir(reportOutput, { recursive: true })
+const selected = (name) => !only || name === only || name.startsWith(`${only}-`)
+if (only && existsSync(resolve(reportOutput, 'visual-report.json'))) {
+  const previous = JSON.parse(
+    await readFile(resolve(reportOutput, 'visual-report.json'), 'utf8'),
+  )
+  if (previous.baseUrl === baseUrl) {
+    report.checks = previous.checks.filter(({ name }) => !selected(name))
+    report.failures = previous.failures.filter(({ name }) => !selected(name))
+  }
+}
+
+async function scenario({ name, viewport, data = 'filled', check }) {
+  if (!selected(name)) return
+  const context = await browser.newContext({
+    viewport,
+    deviceScaleFactor: 1,
+    reducedMotion: 'reduce',
+  })
+  await context.addCookies([{ name: 'token', value: 'qa-only-noncredential', url: baseUrl }])
+  const unexpected = []
+  const pageErrors = []
+  await context.route('**/*', async (route) => {
+    const request = route.request()
+    const url = new URL(request.url())
+    if (!url.pathname.startsWith('/api/')) return route.continue()
+    if (request.method() !== 'GET') {
+      unexpected.push(`禁止真实写入：${request.method()} ${url.pathname}`)
+      return route.fulfill({ status: 405, json: { message: '视觉验证不提交写入请求。' } })
+    }
+    const body = fixtureResponse(url, data)
+    if (body === undefined) {
+      unexpected.push(`未配置 fixture：${url.pathname}`)
+      return route.fulfill({ status: 501, json: { message: '视觉验证 fixture 未配置。' } })
+    }
+    return route.fulfill({ status: 200, json: body })
+  })
+  const page = await context.newPage()
+  page.on('pageerror', (error) => pageErrors.push(error.message))
+  try {
+    await check(page)
+    assert.deepEqual(unexpected, [], '存在未 mock 的 API 请求')
+    assert.deepEqual(pageErrors, [], '存在未处理的页面错误')
+    report.checks.push({ name, viewport, passed: true })
+    console.log(`PASS ${name}`)
+  } catch (error) {
+    const failure = { name, viewport, error: error.message, unexpected, pageErrors }
+    report.failures.push(failure)
+    console.error(`FAIL ${name}: ${error.message}`)
+    await page.screenshot({ path: resolve(uiOutput, `${name}-failure.png`), fullPage: true })
+  } finally {
+    await context.close()
+  }
+}
+
+async function settle(page, path) {
+  await page.goto(`${baseUrl}${path}`, { waitUntil: 'networkidle' })
+  await page.locator('.workspace-brand:visible').first().waitFor({ state: 'visible' })
+  assert.match(await page.locator('.workspace-brand:visible').first().innerText(), /万物/)
+  assert.equal(await page.locator('.scope-strip').count(), 0, '原作用域横条应移除')
+  await page.evaluate(() => document.fonts.ready)
+}
+
+async function noPageOverflow(page) {
+  const dimensions = await page.evaluate(() => ({
+    viewport: innerWidth,
+    document: document.documentElement.scrollWidth,
+    body: document.body.scrollWidth,
+  }))
+  assert(
+    dimensions.document <= dimensions.viewport + 1,
+    `文档横向溢出：${JSON.stringify(dimensions)}`,
+  )
+  assert(dimensions.body <= dimensions.viewport + 1, `页面横向溢出：${JSON.stringify(dimensions)}`)
+}
+
+async function visibleWorkspace(page, text) {
+  const matches = page.locator('.workspace-context strong').filter({ hasText: text })
+  await matches.first().waitFor({ state: 'visible' })
+  const visible = await matches.evaluateAll((elements) =>
+    elements.some((element) => {
+      const rect = element.getBoundingClientRect()
+      const style = getComputedStyle(element)
+      return (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        rect.right > 0 &&
+        rect.left < innerWidth &&
+        rect.bottom > 0 &&
+        rect.top < innerHeight &&
+        style.visibility !== 'hidden' &&
+        style.display !== 'none'
+      )
+    }),
+  )
+  assert(visible, `当前工作空间“${text}”应在视口内可见`)
+}
+
+async function capture(page, name) {
+  await noPageOverflow(page)
+  await page.screenshot({
+    path: resolve(uiOutput, `${name}.png`),
+    fullPage: true,
+    animations: 'disabled',
+  })
+}
+
+try {
+  await scenario({
+    name: 'companies-desktop-empty',
+    viewport: { width: 1440, height: 960 },
+    data: 'empty',
+    check: async (page) => {
+      await settle(page, '/platform/companies')
+      await page.locator('.workspace-table-empty').waitFor()
+      await visibleWorkspace(page, '平台管理')
+      await capture(page, 'companies-desktop-empty')
+    },
+  })
+  await scenario({
+    name: 'companies-desktop-data',
+    viewport: { width: 1440, height: 960 },
+    check: async (page) => {
+      await settle(page, '/platform/companies')
+      await page.getByText('星屿科技', { exact: true }).waitFor()
+      assert.equal(await page.locator('tr.ant-table-row').count(), 3)
+      await capture(page, 'companies-desktop-data')
+      await page.getByPlaceholder('搜索企业名称或编码').fill('云间')
+      await page.getByRole('button', { name: /查\s*询/ }).click()
+      await page.waitForFunction(() => document.querySelectorAll('tr.ant-table-row').length === 1)
+      await page.getByRole('button', { name: /重\s*置/ }).click()
+      await page.waitForFunction(() => document.querySelectorAll('tr.ant-table-row').length === 3)
+      await page.getByRole('button', { name: '开通企业' }).click()
+      await page.getByRole('dialog').waitFor()
+      await capture(page, 'company-create-dialog')
+      await page
+        .getByRole('dialog')
+        .getByRole('button', { name: /取\s*消/ })
+        .click()
+    },
+  })
+  for (const width of [390, 360, 320]) {
+    await scenario({
+      name: `companies-mobile-${width}`,
+      viewport: { width, height: 844 },
+      check: async (page) => {
+        await settle(page, '/platform/companies')
+        await page.getByText('星屿科技', { exact: true }).waitFor()
+        await visibleWorkspace(page, '平台管理')
+        await page.locator('.workspace-switch .anticon').waitFor({ state: 'visible' })
+        await page.locator('.workspace-logout .anticon').waitFor({ state: 'visible' })
+        await capture(page, `companies-mobile-${width}`)
+        const menu = page
+          .locator('.ant-pro-global-header-collapsed-button, .ant-pro-layout-collapsed-button')
+          .first()
+        await menu.click()
+        const accountLink = page.locator('a[href="/platform/accounts"]:visible')
+        await accountLink.click()
+        await page.waitForURL('**/platform/accounts')
+        await page.locator('td').filter({ hasText: 'qa.visual@example.invalid' }).waitFor()
+        await capture(page, `accounts-mobile-${width}`)
+      },
+    })
+  }
+  for (const width of [1440, 390]) {
+    await scenario({
+      name: `workspaces-${width}`,
+      viewport: { width, height: 960 },
+      check: async (page) => {
+        await settle(page, '/workspaces')
+        await page.locator('.workspace-card').first().waitFor()
+        assert.equal(await page.locator('.workspace-card').count(), 3)
+        await capture(page, `workspaces-${width}`)
+        await page.getByLabel('搜索工作空间').fill('月光')
+        assert.equal(await page.locator('.workspace-card').count(), 1)
+        await page.locator('.workspace-card').getByRole('link').click()
+        await page.waitForURL('**/companies/qa-company/projects/qa-project')
+        await page.getByRole('heading', { name: '项目工作台' }).waitFor({ state: 'visible' })
+        await visibleWorkspace(page, '月光计划')
+        await capture(page, `project-home-${width}`)
+        await settle(page, '/companies/qa-company/projects')
+        await visibleWorkspace(page, '星屿科技')
+        await page.getByText('月光计划', { exact: true }).waitFor()
+        await capture(page, `company-projects-${width}`)
+      },
+    })
+  }
+  await scenario({
+    name: 'workspaces-empty',
+    viewport: { width: 390, height: 844 },
+    data: 'empty-workspaces',
+    check: async (page) => {
+      await settle(page, '/workspaces')
+      await page.getByText('暂未加入企业，请联系管理员添加', { exact: true }).waitFor()
+      await capture(page, 'workspaces-empty')
+    },
+  })
+  for (const width of [1440, 390]) {
+    for (const authPage of ['login', 'register']) {
+      await scenario({
+        name: `${authPage}-${width}`,
+        viewport: { width, height: 960 },
+        check: async (page) => {
+          await page.goto(`${baseUrl}/${authPage}`, { waitUntil: 'networkidle' })
+          await page.locator('.login-brand').waitFor({ state: 'visible' })
+          assert.match(await page.locator('.login-brand').innerText(), /万物/)
+          const fields =
+            authPage === 'login' ? ['账号', '密码'] : ['姓名', '账号', '密码', '确认密码']
+          for (const label of fields) {
+            const field = page.getByLabel(label, { exact: true })
+            await field.waitFor({ state: 'visible' })
+            await field.scrollIntoViewIfNeeded()
+            const rect = await field.boundingBox()
+            assert(
+              rect && rect.width > 100 && rect.x >= 0 && rect.x + rect.width <= width + 1,
+              `字段“${label}”应完整显示`,
+            )
+          }
+          await page.evaluate(() => scrollTo(0, 0))
+          await capture(page, `${authPage}-${width}`)
+        },
+      })
+    }
+  }
+} finally {
+  await writeFile(
+    resolve(reportOutput, 'visual-report.json'),
+    `${JSON.stringify(report, null, 2)}\n`,
+  )
+  await browser.close()
+}
+console.log(
+  `完成：${report.checks.length} 通过，${report.failures.length} 失败；截图：${uiOutput}；报告：${reportOutput}`,
+)
+process.exitCode = report.failures.length ? 1 : 0

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//346/265/213/350/257/225/350/257/201/346/215/256/visual-report.json

@@ -0,0 +1,104 @@
+{
+  "baseUrl": "http://127.0.0.1:9999",
+  "browser": "145.0.7632.6",
+  "mockData": true,
+  "checks": [
+    {
+      "name": "companies-desktop-empty",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-desktop-data",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "workspaces-1440",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "workspaces-390",
+      "viewport": {
+        "width": 390,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "workspaces-empty",
+      "viewport": {
+        "width": 390,
+        "height": 844
+      },
+      "passed": true
+    },
+    {
+      "name": "login-1440",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "register-1440",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "login-390",
+      "viewport": {
+        "width": 390,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "register-390",
+      "viewport": {
+        "width": 390,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-mobile-390",
+      "viewport": {
+        "width": 390,
+        "height": 844
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-mobile-360",
+      "viewport": {
+        "width": 360,
+        "height": 844
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-mobile-320",
+      "viewport": {
+        "width": 320,
+        "height": 844
+      },
+      "passed": true
+    }
+  ],
+  "failures": []
+}

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//351/252/214/350/257/201/350/257/264/346/230/216.md

@@ -0,0 +1,25 @@
+# 万物梦幻主题视觉验证
+
+使用当前本地 React 页面，通过独立 Playwright 浏览器上下文提供虚构数据。不会读取浏览器个人资料、真实凭据或现有登录态，不会写入后端数据。
+
+```powershell
+node ".spaces/04.界面与主题/万物梦幻/工具/visual-check.mjs" --base-url http://127.0.0.1:9999
+```
+
+- `--check-launch`：只验证本机 Chromium 可启动，不打开页面、不截图。
+- `--only companies-mobile-390`：只运行指定场景；`--only companies-mobile` 复验全部手机企业场景。定向运行会更新同一服务地址的已有报告，保留其他场景验证结果。
+- `PLAYWRIGHT_MODULE`：覆盖 Playwright 模块位置。
+- `PLAYWRIGHT_EXECUTABLE_PATH`：覆盖已有 Chromium 可执行文件位置。
+- 若受限沙箱阻止启动 Chromium（`spawn EPERM`），需使用获准的沙箱外执行权限运行同一脚本。
+
+`fixtures.mjs` 定义平台、企业、项目身份以及企业列表空/有数据状态。全部 `/api/` 请求由浏览器路由拦截：只允许已知 GET fixture，写入请求返回 405，未知请求返回 501 并导致验证失败。
+
+输出的 PNG 使用虚构名称“星屿科技”“月光计划”和 `example.invalid` 测试账号。`visual-report.json` 记录通过项和失败项。它们是本地 UI 验证证据，不能作为真实业务数据或服务端集成验证结果。
+
+## 验证记录（2026-09-10）
+
+- 本次前端修改文件的定向 `vp check` 通过；QA 脚本与 fixture 的定向检查通过。
+- 前端 6 个测试文件、43 个测试通过；最终前端构建通过。
+- 全仓 `vp check` 因已有的 164 个格式问题未通过，本次未扩大格式修改范围。
+- `vp install --frozen-lockfile` 因 pnpm 非 TTY 重建 modules 保护退出，验证沿用本地已安装依赖。
+- 视觉验证 12 个场景全部通过，0 失败。使用真实本地前端和独立浏览器的网络 mock，覆盖桌面 1440px、手机 320/360/390px，检查品牌、当前工作空间、表格、导航、空态及登录/注册字段。最终 PNG 已通过解码验证，主要交付截图已进行目视复核。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//344/272/244/344/273/230/350/256/260/345/275/225.md

@@ -0,0 +1,12 @@
+# 前端国际化交付记录
+
+## 交付内容
+
+- 在 `apps/web/src/i18n/config.ts` 集中声明应用 locale 到组件库和日期库的标识映射。
+- 新增 `apps/web/src/i18n/ui-locale.ts`，统一返回 antd Locale、Pro Components `IntlType`、Day.js 和 `<html lang>` 配置。
+- `apps/web/src/App.tsx` 根据同一 locale 状态驱动 `ConfigProvider`、`ProConfigProvider` 和 Day.js。
+- 更新 Web README 与 `.spaces` 正式需求、设计、测试和索引文档。
+
+## 状态
+
+已实现并完成构建、测试和 i18n 词条检查。当前语言范围仍为 `zh_CN` 与 `en_US`。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -0,0 +1,19 @@
+# 前端国际化测试报告
+
+## 验证范围
+
+- 应用 locale 到 antd `ConfigProvider` 的映射。
+- 应用 locale 到 Pro Components `IntlType` 的映射。
+- 应用 locale 到 Day.js 和 `<html lang>` 的同步。
+- 词条完整性、TypeScript 编译和 React Web 测试回归。
+
+## 验证结果（2026-09-19）
+
+| 命令 | 结果 |
+| --- | --- |
+| `pnpm --filter web build` | 通过，TypeScript 与 Vite 构建成功 |
+| `pnpm --filter web test --run` | 通过，17 个测试文件、112 个测试 |
+| `pnpm i18n:check` | 通过，1254 个词条无新增、废弃或未使用 |
+| `git diff --check` | 通过 |
+
+本次未改动后端接口、权限契约或 UI 截图；浏览器视觉回归仍沿用主题验证说明中的既有流程。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,18 @@
+# 前端国际化设计方案
+
+## 统一状态
+
+`@bubblesjs/i18n-core` store 是唯一语言状态源。`apps/web/src/i18n/config.ts` 集中维护应用 locale 及其适配标识，`ui-locale.ts` 将应用 locale 映射为：
+
+- antd 的 `Locale` 对象；
+- Pro Components 的 `IntlType`（`zhCNIntl` / `enUSIntl`）；
+- Day.js locale 标识（`zh-cn` / `en`）；
+- `<html lang>` 标识。
+
+## 渲染与副作用
+
+`App.tsx` 在渲染时将 antd locale 和 Pro `intl` 传入 Provider；在 locale 变化后的 effect 中设置 Day.js 全局 locale 和 `<html lang>`。这样静态组件配置会随 React 重新渲染，日期库的全局副作用也只在语言变化时执行。
+
+## 扩展约束
+
+新增语言时必须同时补充词条加载器、`APP_LOCALE_ADAPTERS`、antd locale 包、Pro Components intl 以及 Day.js locale 导入，并执行 `pnpm i18n:check` 与前端构建。