192 lines
12 KiB
Markdown
192 lines
12 KiB
Markdown
# Phase 1 设计系统与官网骨架报告
|
||
|
||
日期：2026-09-08
|
||
范围：P1-01 至 P1-06
|
||
状态：官网骨架完成；真实认证、TTS、CMS 和管理业务未实现。
|
||
|
||
## 1. 交付摘要
|
||
|
||
- 建立 Next.js App Router + TypeScript + Tailwind CSS 4 本地应用。
|
||
- 建立 KAOTINGS 深色设计系统：`#0D0F12` 背景、橙 `#FF6A00`、蓝 `#1677FF`、青 `#00D1E6`、近白文字及灰阶变量。
|
||
- 使用正式 Logo 的网页公开副本 `public/brand/logo_bt.png`；AI/PDF 原档仍不直接公开。
|
||
- 完成响应式导航、移动导航、页脚、跳过导航链接、键盘焦点样式和减少动效处理。
|
||
- 首页以蓝牙、音频、嵌入式和硬件产品为主体，AI Lab/TTS 保持轻量入口。
|
||
- 完成产品列表、产品详情模板、关于、联系、TTS、登录、注册、账户和管理页面布局。
|
||
- 所有缺少真实资料的产品内容集中在 `lib/content.ts`，并使用“开发占位”标识；没有虚构规格、联系方式、资质或操作成功。
|
||
|
||
## 2. P1 工作包
|
||
|
||
| 编号 | 状态 | 实现位置 | 验证 |
|
||
| --- | --- | --- | --- |
|
||
| P1-01 | 已完成 | `app/globals.css`、`components/ui.tsx` | 设计令牌、按钮、输入、焦点、间距和响应式规则已集中定义 |
|
||
| P1-02 | 已完成 | `components/site-header.tsx`、`components/site-footer.tsx`、`app/layout.tsx` | 桌面导航、移动菜单、账户入口、页脚和跳过导航已实现 |
|
||
| P1-03 | 已完成 | `app/page.tsx` | Hero、硬件产品、技术能力、AI Lab、联系入口已实现 |
|
||
| P1-04 | 已完成 | `app/products/`、`app/about/`、`app/contact/`、`lib/content.ts` | 列表和详情模板由集中式占位数据驱动 |
|
||
| P1-05 | 已完成（布局） | `app/tts/`、`app/login/`、`app/register/`、`app/account/`、`app/admin/` | 加载/空/待接入/禁用/错误语义已展示；真实业务未接入 |
|
||
| P1-06 | 功能实现与构建检查完成；真实视觉验收待完成 | `app/layout.tsx`、`app/not-found.tsx`、全局样式 | typecheck、build、路由冒烟和响应式源码检查通过；真实浏览器桌面/移动验收未完成 |
|
||
|
||
## 3. 页面清单
|
||
|
||
| 路由 | 当前能力 |
|
||
| --- | --- |
|
||
| `/` | 品牌首页，产品为主，AI Lab 为入口 |
|
||
| `/products` | 开发占位产品列表和分类视觉 |
|
||
| `/products/product-placeholder-a` | 产品详情模板 |
|
||
| `/products/product-placeholder-b` | 产品详情模板 |
|
||
| `/about` | 公司定位和原则，未虚构公司履历 |
|
||
| `/contact` | 联系信息边界和待确认状态 |
|
||
| `/tts` | TTS 工作台布局，控件禁用，不调用服务 |
|
||
| `/login`、`/register` | 认证表单布局，提交禁用 |
|
||
| `/account` | 账户、权益、额度和历史空状态 |
|
||
| `/admin`、`/admin/users`、`/admin/tts` | 管理后台布局和禁用状态 |
|
||
| `404` | 友好 Not Found 页面 |
|
||
|
||
## 4. 占位数据规则
|
||
|
||
所有开发占位内容集中在 `lib/content.ts`。当前只使用：
|
||
|
||
- `产品资料待补充 A/B` 作为模板标识，不作为正式产品名称。
|
||
- `无线音频`、`蓝牙配件` 作为待确认分类示意，不包含规格和性能承诺。
|
||
- CSS 抽象产品视觉只用于检查版式，不冒充真实产品图片。
|
||
- 联系页、页脚和关于页明确说明正式联系方式和公司资料待确认。
|
||
|
||
后续替换时只需先替换内容适配器；Phase 4 接入 CMS 时不应重写页面模板。
|
||
|
||
## 5. 本地验证
|
||
|
||
已执行：
|
||
|
||
- `npm install`：安装 46 个依赖包，审计结果为 0 vulnerabilities。
|
||
- `npm run typecheck`：通过。
|
||
- `npm run build`：通过，全部静态页面生成成功。
|
||
- 本地 `next start` 动态端口启动：成功，无启动错误。
|
||
- HTTP 冒烟：首页、产品列表、两个产品详情、关于、联系、TTS、登录、注册、账户、管理首页、用户管理、TTS 管理和 Logo 静态资源均返回 `200`。
|
||
- 响应式源码检查：容器、断点、移动导航、移动端排列、键盘焦点和 `prefers-reduced-motion` 已覆盖。此项是源码检查，不等同于实际设备视觉验收。
|
||
|
||
当前执行环境对固定本地端口 `3000`、`3100`、`3210` 返回 Windows `EACCES`；动态端口可启动，因此没有修改系统端口策略。当前环境没有可用的 Chrome、Edge、Firefox 或既有 Playwright，尚未完成真实桌面/移动浏览器视觉验收，也未生成截图。该项明确交由测试站浏览器或用户电脑/手机验收，不将源码检查写成设备验收通过。
|
||
|
||
## 6. 最小测试部署方案
|
||
|
||
### 6.1 本阶段部署范围
|
||
|
||
只部署官网骨架，不部署数据库、Redis、TTS、Worker、CMS 或认证服务。页面中的真实业务入口保持禁用或预览说明。
|
||
|
||
### 6.2 服务器所需软件
|
||
|
||
- Ubuntu 24.04 已有，建议安装 Node.js `20.9+`，当前项目本地使用 Node.js `24.11.1` 验证。
|
||
- npm 随 Node.js 提供。
|
||
- 不需要 PostgreSQL、Redis、对象存储、TTS 或 CMS。
|
||
- 可先不安装 Nginx/Caddy，直接由 `next start` 提供局域网 HTTP 验证。
|
||
|
||
### 6.3 部署目录和命令建议
|
||
|
||
在权限未落实前不执行。为避免第一阶段申请 root 部署目录，可优先评估用户目录：
|
||
|
||
```text
|
||
/home/flym/kaotings-www
|
||
```
|
||
|
||
建议流程：
|
||
|
||
```bash
|
||
npm ci
|
||
npm run build
|
||
npm run start -- -H 0.0.0.0 -p 3000
|
||
```
|
||
|
||
访问地址：`http://192.168.199.22:3000/`
|
||
|
||
### 6.4 权限和端口
|
||
|
||
- 文件复制到 `/home/flym/kaotings-www` 可由 `flym` 用户完成，前提是目录由该用户拥有。
|
||
- 安装 Node.js、配置系统级进程、开放防火墙端口或绑定受控服务可能需要 sudo/管理员权限。
|
||
- 当前 `flym` 属于 sudo 组，但非交互 sudo 仍需要额外认证；本次未安装或修改服务器服务。
|
||
- 最小访问端口：SSH `22` 用于运维，应用 TCP `3000` 仅允许局域网测试来源。
|
||
- 本阶段不开放 80/443，不配置正式域名或 HTTPS；认证和生产发布前仍必须完成可信 HTTPS。
|
||
|
||
### 6.5 测试部署退出条件
|
||
|
||
- 局域网浏览器能打开首页、产品模板、关于、联系和所有预览入口。
|
||
- 仅显示开发占位内容，不显示虚构联系方式、产品规格或成功状态。
|
||
- 服务器重启或进程重启后的启动方式已记录；正式部署前再替换为受控进程管理和反向代理。
|
||
|
||
## 7. 部署前核实状态
|
||
|
||
本方案已复核：本轮只部署 Next.js 官网骨架，所需新增软件为 Node.js 20.9+ 与 npm；不安装 PostgreSQL、Redis、TTS、Worker、CMS 或对象存储。服务器变更前需要确认 Node.js 安装权限、`/home/flym/kaotings-www` 写权限、TCP/3000 局域网访问权限，以及后续进程保持方式。当前尚未执行服务器安装或部署。
|
||
|
||
## 8. 测试站部署前实测
|
||
|
||
本次通过已确认的 SSH 主机执行只读核实：
|
||
|
||
- `/home/flym` 可写，适合作为用户级部署目录；`/home/flym/kaotings-www` 尚未创建。
|
||
- 未安装 Node.js 和 npm，无法执行 `npm ci`、`npm run build` 或 `next start`。
|
||
- `flym` 在 `sudo` 组，但 `sudo -n -l` 返回需要密码，当前没有可供自动部署使用的非交互 sudo 权限。
|
||
- 从开发机访问 TCP/3000 失败，当前没有应用监听或放行该端口。
|
||
- 本次未安装软件、创建服务、开放端口或启动测试站。
|
||
|
||
因此当前部署阻断项是：管理员需要安装 Node.js 20.9+ 和 npm，或提供用户目录可用的 Node.js；同时需要允许 `192.168.199.0/24`（或实际测试网段）访问 TCP/3000。若要求系统级服务或防火墙变更，还需要 sudo/管理员权限。权限落实后再执行最小部署，并提供 `http://192.168.199.22:3000/` 实际访问结果和真实浏览器视觉验收记录。
|
||
|
||
## 9. 最小测试部署结果
|
||
|
||
服务器变更权限已落实，本次已完成官网骨架部署：
|
||
|
||
- 安装 Node.js `v24.11.1` 和 npm `11.6.2`；未安装数据库、Redis、TTS、Worker、CMS 或对象存储。
|
||
- Node.js 官方压缩包已在服务器端完成 SHA-256 校验后安装到 `/opt`，命令链接位于 `/usr/local/bin`。
|
||
- 应用目录：`/home/flym/kaotings-www`。
|
||
- 执行 `npm ci` 和 `npm run build`，构建通过，全部静态路由生成成功。
|
||
- 以 `flym` 用户启动 `next start`，监听 `0.0.0.0:3000`；本次未创建 systemd 服务，重启后不会自动拉起。
|
||
- 开发机访问 TCP/3000 成功。
|
||
- 首页、产品列表、两个产品详情、关于、联系、TTS、登录、注册、账户、管理首页、用户管理、TTS 管理和 Logo 静态资源均从测试机返回 HTTP `200`。
|
||
- 当前访问地址：[`http://192.168.199.22:3000/`](http://192.168.199.22:3000/)。
|
||
|
||
## 10. 真实浏览器视觉验收
|
||
|
||
本执行环境没有可用的 Chrome、Edge、Firefox、Playwright 或截图工具，因此本轮没有生成桌面/移动截图，也不将 HTTP `200` 或源码响应式检查写成视觉验收通过。
|
||
|
||
请在桌面浏览器和手机浏览器访问上方地址，重点检查：
|
||
|
||
- 深色背景、橙蓝青配色、正式 KAOTINGS Logo 和导航布局。
|
||
- 桌面导航与移动端折叠菜单、首页产品主体和 AI Lab 轻量入口。
|
||
- 产品列表、两个产品详情模板和开发占位标识。
|
||
- `/tts`、`/login`、`/register`、`/account`、`/admin` 的空状态、禁用状态和预览提示。
|
||
- 移动端是否有横向溢出、文字截断、焦点不可见或触控区域过小。
|
||
|
||
上述人工检查完成前，Phase 1 的真实视觉验收保持“待完成”。
|
||
|
||
## 11. 本轮首页视觉修正
|
||
|
||
依据 `docs/design/references/kaotings-homepage-approved-reference.png` 和用户提供的测试截图完成以下调整：
|
||
|
||
- 内容容器最大宽度从 `1180px` 调整为 `1320px`，宽屏保留左右边界，减少主体过窄问题。
|
||
- 导航 Logo 使用正式组合 Logo，桌面高度调整为约 `44px`，页脚约 `56px`，始终保持原始比例。
|
||
- 导航、账户入口和移动按钮改为显式 `768px` CSS 断点，桌面完整导航显示时移动菜单按钮隐藏。
|
||
- 标题和区块标题启用 `text-wrap: balance`，降低中文孤字断行概率；产品和 AI Lab 标题的栏宽同步放宽。
|
||
- 首页 Hero、产品、技术和 AI Lab 区块的纵向间距收紧，按钮横向留白略增，改善“大空白、小内容”比例。
|
||
- 产品抽象视觉仍明确标注“开发占位”，不作为真实产品素材验收。
|
||
|
||
本轮实际检查记录：
|
||
|
||
- 本地：`npm run typecheck` 通过，`npm run build` 通过。
|
||
- 测试站：重新构建并监听 `0.0.0.0:3000`，`http://192.168.199.22:3000/` 返回 `200`。
|
||
- 实际浏览器 viewport：未核实。
|
||
- 浏览器缩放比例：未核实。
|
||
- 桌面/移动真实截图：未生成，待用户在实际浏览器验收。
|
||
- 源码断点目标：`<768px` 移动导航，`>=768px` 桌面导航；这不是实际设备验收结果。
|
||
|
||
## 12. 部署一致性复核
|
||
|
||
用户反馈截图仍为旧视觉后，重新核对发现前一次增量传输使用了扁平目标路径：文件被写入部署根目录，而不是 `app/` 和 `components/` 子目录；实际构建因此继续使用旧源码。已删除误传根目录文件，并按正确子目录重新同步。
|
||
|
||
- 监听进程：PID `6505`，命令为 `next start -H 0.0.0.0 -p 3000`。
|
||
- 工作目录：`/home/flym/kaotings-www`。
|
||
- 当前构建提交号：`0e46643`。
|
||
- 页面页脚已显示 `build 0e46643`，用于浏览器端版本核对。
|
||
- 实际响应引用 CSS：`/_next/static/chunks/2911lr-pv0kp2.css`。
|
||
- 该 CSS 资源已核实包含 `1320px`、`desktop-nav`、`mobile-nav-trigger` 和 `min-width:768px` 规则。
|
||
- `app/globals.css`、`app/page.tsx`、`components/brand-mark.tsx`、`components/site-header.tsx`、`components/ui.tsx` 的服务器哈希已与本地视觉修正提交内容一致。
|
||
- 当前访问地址：[`http://192.168.199.22:3000/`](http://192.168.199.22:3000/)。
|
||
|
||
浏览器仍需强制刷新后重新截图，确认截图页脚出现 `build 0e46643`。真实 viewport、缩放比例、桌面/移动布局仍未由本执行环境直接测量，继续标记为待验收。
|
||
|
||
本次旧版本暴露了逐个文件传输的部署风险：后续必须改为保留目录结构的统一打包部署，并在构建、重启和切换后自动核对提交号、源码/构建清单、监听进程工作目录和页面版本标识。该改进已记录为 `DECISIONS.md` 的 D-07 和后续执行待办。
|