docs: introduce project and keep local reports out of source delivery
This commit is contained in:
cieanyau committed
1 parent
db5762abd4
commit
d37ce57d09
45 files changed
+232
-14820
No files matched your search
@@ -1,72 +1,145 @@
|
||||
# crashwork-console 完整前端工程（源码重建版）
|
||||
# 破碎工坊云 · 会员中心前端
|
||||
|
||||
这是根据当前 `20261025-kky-traffic-display` 发布包重建的独立工程，不是原始源码的逐字恢复。
|
||||
覆盖 52 个页面、104 个业务组件、4 套布局，包含现有图片、字体和样式。开发、构建和运行均不依赖旧发布目录。
|
||||
这里交付的是整个会员中心前端，不是仅含四个改写文件的示例。已只读核对服务器当前发布版本；
|
||||
模块元数据及其 735 个构建资源与重建依据一致。范围、证据与边界见 [完整项目交接说明](docs/project-completeness.md)。
|
||||
面向云服务和 IDC 业务的用户控制台，提供账号管理、商品选购、服务器管理、订单支付与售后服务等页面。
|
||||
本仓库是可独立安装、开发和构建的前端工程，不包含后端服务、数据库或生产环境凭证。
|
||||
|
||||
原工程的模板、注释和局部变量名已在编译时丢失。多数页面恢复为可编辑的 Vue 单文件组件及渲染函数，
|
||||
部分局部变量仍为短名；请求/会话核心、应用入口、鉴权、主题和图表集成已重新编写。
|
||||
第二轮已将登录页、旧平台登录入口、SSH 密钥页和公共认证布局改为手写 `<script setup>` 与 `<template>`，
|
||||
使用业务命名，保留原接口及样式契约；这四个文件合计净减少 863 行，未增加依赖。
|
||||
这不是“所有业务均已重新设计并完成线上验收”的声明。具体验证与限制见 [验收报告](docs/validation.md)。
|
||||
## 主要功能
|
||||
|
||||
## 开发
|
||||
- 账号与身份：密码 / 短信登录、注册、找回密码、第三方登录与绑定、个人资料、实名认证和 API 密钥。
|
||||
- 控制台与资源：会员首页、资源总览、云服务器和独立服务器列表、实例详情。
|
||||
- 商品与购买：商品分类、配置选购、购物车、订单创建、续费和升级入口。
|
||||
- 实例管理：监控、网络、磁盘、流量、访问凭据与远程控制；具体能力取决于后端接入的产品模块。
|
||||
- 账务与支付：订单、账单、余额、支付、发票、优惠券、转账和推广相关页面。
|
||||
- 安全与服务：SSH 密钥、安全组、域名、操作日志、工单、消息、公告和帮助内容。
|
||||
|
||||
需要 Node.js 22.12+ 与 npm，建议在团队中统一 Node 版本。
|
||||
当前包含 52 个页面、104 个业务组件和 4 套布局。上述列表说明前端覆盖范围，不代表所有业务已完成真实后端验收。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层次 | 技术 |
|
||||
| ---------- | --------------------------------------------------------- |
|
||||
| 应用框架 | Nuxt 4、Vue 3、Vue Router，客户端 SPA（`ssr: false`） |
|
||||
| 状态与界面 | Pinia、PrimeVue 4、PrimeUI 主题、本地 Lucide 图标 |
|
||||
| 图表与远控 | ECharts、vue-echarts、noVNC |
|
||||
| 源码 | JavaScript、Vue 单文件组件、CSS，Nuxt 配置使用 TypeScript |
|
||||
| 验证工具 | Node.js `node:test`、Playwright、源码检查脚本、Prettier |
|
||||
|
||||
依赖的精确版本以 `package-lock.json` 为准。
|
||||
|
||||
## 快速开始
|
||||
|
||||
需要 Node.js **22.12.0 或更高版本**及 npm，团队开发建议统一 Node.js 版本。
|
||||
|
||||
```sh
|
||||
git clone https://git.crash.work/cieanyau/console-dev.git
|
||||
cd console-dev
|
||||
npm ci
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
在 `.env` 中配置后端地址：
|
||||
|
||||
```dotenv
|
||||
NUXT_PUBLIC_API_BASE=http://127.0.0.1:8080
|
||||
```
|
||||
|
||||
```sh
|
||||
npm run dev
|
||||
```
|
||||
|
||||
在 `.env` 设置 `NUXT_PUBLIC_API_BASE` 为后端 origin，例如 `http://127.0.0.1:8080`。
|
||||
不要附加 `/console/v1`；代码会自动追加。空值表示同源，开发或部署的反向代理必须另行转发该路径。
|
||||
图形验证码的 `/captcha/` 和远控的 `/remote-console/sessions`（包括 WebSocket）仍走前端同源，
|
||||
必须另外配置对应后端/网关的反向代理；只设置 API origin 不会自动转发这两类请求。
|
||||
前端不会替你启动后端服务、短信、验证码、支付渠道或 VNC 网关。
|
||||
开发服务仅监听 `127.0.0.1`，实际访问地址以启动日志为准。
|
||||
|
||||
## 构建与验证
|
||||
### 接口与反向代理
|
||||
|
||||
`NUXT_PUBLIC_API_BASE` 只填写后端 origin，不要附加 `/console/v1`，请求层会自动追加该前缀。
|
||||
留空表示使用前端同源地址，需要在开发或部署环境配置接口反向代理。
|
||||
|
||||
以下地址始终走前端同源，必须单独转发到对应服务：
|
||||
|
||||
- `/captcha/`：图形验证码。
|
||||
- `/remote-console/sessions`：远控会话及 WebSocket 连接。
|
||||
|
||||
仅设置 API 地址不会自动代理这两类请求，也不会启动后端、验证码、短信邮件、支付渠道或远控网关。
|
||||
所有 `NUXT_PUBLIC_*` 配置都会暴露给浏览器，不能填写密码、访问令牌或数据库凭证。
|
||||
|
||||
## 常用命令
|
||||
|
||||
| 命令 | 用途 |
|
||||
| ----------------- | ----------------------------------------- |
|
||||
| `npm run dev` | 启动本地开发服务 |
|
||||
| `npm run check` | 检查应用源码语法、导入和历史部署路径依赖 |
|
||||
| `npm run build` | 构建生产版本，输出到项目根目录 `.output/` |
|
||||
| `npm run preview` | 运行已构建的 Node.js 服务 |
|
||||
| `npm test` | 对生产构建运行浏览器端到端测试 |
|
||||
| `npm run format` | 格式化应用、配置、脚本和测试代码 |
|
||||
|
||||
### 构建与本地预览
|
||||
|
||||
```sh
|
||||
npm run check
|
||||
npm run build
|
||||
npm test
|
||||
```
|
||||
|
||||
浏览器测试自动启动本地模拟接口与真实构建服务，并禁止访问外网。默认使用 macOS 已安装的 Chrome；
|
||||
其他环境请设置 `CHROME_PATH=/absolute/path/to/chrome`。详细说明见 [测试说明](tests/README.md)。
|
||||
当前离线验收为 21 项，包含短信配置与倒计时、SSH 增改删/末页恢复和旧入口失败后重试。
|
||||
|
||||
构建结果位于本工程的 `.output/`，不是仓库根目录的 `.output`。
|
||||
|
||||
```sh
|
||||
NUXT_PUBLIC_API_BASE=http://127.0.0.1:8080 HOST=127.0.0.1 PORT=3000 npm run preview
|
||||
```
|
||||
|
||||
## 源码结构
|
||||
预览命令直接运行 `.output/server/index.mjs`，不会自动读取项目 `.env`，请通过运行环境传入配置。
|
||||
正式部署应使用独立版本目录和进程管理，并配置 HTTPS、接口 / WebSocket 反向代理及回滚流程。
|
||||
本仓库的提交和构建不会自动修改生产服务器。
|
||||
|
||||
- `app/pages`、`app/layouts`、`app/components`：页面、布局和业务组件。
|
||||
- `app/lib/auth.js`：会话、接口协议、请求截止时间、购买前置校验及列表缓存。
|
||||
- `app/middleware/auth.global.js`：公开路由与鉴权、旧平台登录入口。
|
||||
- `app/plugins`：UI、站点初始化、跨标签页会话同步。
|
||||
- `app/config`：中文文案及 MIT 主题配置；图标由本地服务提供。
|
||||
- `tests`：通过真实页面操作和 HTTP 边界验证的回归场景。
|
||||
- `docs/module-inventory.json`：重建范围与路由清单。
|
||||
- `scripts/reconstruct.mjs`：一次性导入过程的留档；不是构建步骤，拒绝覆盖已有源码。
|
||||
## 源码目录
|
||||
|
||||
维护源码后执行正常构建即可，不要重新运行导入器覆盖修复，也不要手工修改生成的哈希 JS 文件。
|
||||
导入器仅留档用于可信的自有发布产物，不是通用归档解包器；不要给它提供第三方元数据或不可信构建输入。
|
||||
Vue、Vue Router、PrimeVue、Pinia、ECharts、noVNC 等通过正式 npm 依赖引用，不携带旧框架副本。
|
||||
保留的 CryptoJS AES 参数属于现有后端登录协议，不能在前后端未协商时单独修改。
|
||||
```text
|
||||
app/
|
||||
app.vue 应用入口、布局选择与会话隔离
|
||||
pages/ 文件路由与业务页面
|
||||
layouts/ 控制台、认证、公开购买及站点布局
|
||||
components/ 业务表单、实例管理、支付和公共界面
|
||||
lib/ 接口、会话、商品配置及业务工具
|
||||
middleware/ 路由鉴权
|
||||
plugins/ 界面注册、启动初始化、跨标签页会话同步
|
||||
config/ 中文文案和主题配置
|
||||
utils/ 访问规则及基础适配
|
||||
assets/styles/ 全局与业务样式
|
||||
public/ 图片、图标、字体等静态资源
|
||||
scripts/ 源码检查及一次性重建留档脚本
|
||||
tests/ 浏览器场景与独立 HTTP 测试后端
|
||||
nuxt.config.ts 应用与公开运行时配置
|
||||
.env.example 无凭证的环境配置示例
|
||||
```
|
||||
|
||||
## 发给员工与发布
|
||||
`docs/` 仅保留在本地，已加入 Git 忽略规则，不随后续源码版本上传；历史提交中的文档不会因此消失。
|
||||
不要使用 `git add -f docs` 将本地报告重新加入仓库。
|
||||
|
||||
交付本目录的源码压缩包或 Git 分支即可。员工运行 `npm ci`，配置自己的后端 origin，然后开发和验证。
|
||||
不要发送 `.env`、登录凭证、数据库备份、`node_modules` 或 Git 历史；示例配置不包含秘密。
|
||||
依赖包及保留静态资产应遵守各自许可证和你方资产授权。
|
||||
## 测试
|
||||
|
||||
本次没有修改线上发布指向，也没有部署。上线前应先在测试环境连接真实后端验证商品配置、验证码、
|
||||
安全验证、账务、支付和 VNC 反代；现有根目录发布脚本不会自动改为构建这个新工程。
|
||||
确认通过后，再按团队的版本发布/回滚流程发布本工程 `.output`，不要直接覆盖正在服务的版本。
|
||||
```sh
|
||||
npm run build
|
||||
npm test
|
||||
```
|
||||
|
||||
测试使用真实 Chrome / Chromium 操作生产构建，自动启动本地 HTTP 测试后端，禁止访问外网，
|
||||
不替换项目内部模块，也不预置登录令牌。默认使用 macOS 已安装的 Chrome；其他环境可指定：
|
||||
|
||||
```sh
|
||||
CHROME_PATH=/absolute/path/to/chrome npm test
|
||||
```
|
||||
|
||||
现有 21 个离线场景覆盖登录协议、短信倒计时、路由保护、会话失效、双标签页退出、SSH 密钥管理、
|
||||
请求超时、支付期限及旧登录入口等流程。测试产物保存在被忽略的 `tests/fixtures/runs/`。
|
||||
详细使用方式见 [测试说明](tests/README.md)。
|
||||
|
||||
真实支付、第三方登录 / CAPTCHA、安全挑战、短信邮件投递、供应商接口和 VNC 网关仍需在测试环境联调。
|
||||
|
||||
## 维护与交付说明
|
||||
|
||||
本工程根据 `20261025-kky-traffic-display` 发布产物重建，不是原始源码的逐字恢复。
|
||||
多数页面和组件保留恢复后的 Vue 渲染函数及部分短变量名；原始模板、注释和完整变量名无法从发布包完整找回。
|
||||
当前新增注释用于解释已核实的职责、流程和接口边界，不代表找回了原作者的注释，也不代表全站重新手写。
|
||||
|
||||
维护时直接修改当前源码并正常构建，不要编辑生成的哈希产物。
|
||||
`scripts/reconstruct.mjs` 仅是一次性导入留档，不是开发或发布步骤，且会拒绝覆盖现有页面；
|
||||
不要使用不可信的第三方发布产物运行该脚本。
|
||||
登录所用的 CryptoJS AES 参数属于现有后端协议，调整前必须与后端协商，不能将其视为替代 HTTPS 的安全措施。
|
||||
|
||||
向员工交付仓库和对应分支即可；每位开发者自行安装依赖、配置后端并执行验证。
|
||||
不要提交 `.env`、账号密码、令牌、数据库备份、`node_modules/`、`.output/` 或本地验收报告。
|
||||
依赖包与保留静态资源应遵守各自许可证及资产授权；本仓库未另行授予整体开源许可证。
|
||||
Reference in new issue
Block a user