- 补齐 trust content 与模板版本 fixture 的必填字段\n- mock template-operations/failures 的完整响应结构\n- 补全完整浏览器回归的启动步骤与 CORS 要求\n\n完整回归 32 个用例全部通过。
105 lines
5.6 KiB
Markdown
105 lines
5.6 KiB
Markdown
# Taro 模板双端工程
|
||
|
||
本目录在独立迁移分支提供 Web 和微信小程序共用的 React 页面。后台、Prisma 和发布 API 不变;当前原生模板构建仍保留。
|
||
|
||
## 启动 Web
|
||
|
||
在仓库根目录执行:
|
||
|
||
```sh
|
||
pnpm install
|
||
pnpm --filter @personal-brand/types build
|
||
pnpm --filter @personal-brand/taro dev:h5
|
||
```
|
||
|
||
默认餐饮模板、default-brand、API http://localhost:3001,Web http://localhost:3002。
|
||
|
||
林境模板:
|
||
|
||
```sh
|
||
TEMPLATE_KEY=linjing-editorial PREVIEW_PORT=3003 pnpm --filter @personal-brand/taro dev:h5
|
||
```
|
||
|
||
API 地址通过 `API_BASE_URL` 设置,品牌通过 `BRAND_SLUG` 设置。H5 也可在地址查询参数使用 `?brand=linjing-doors`,但必须与构建模板匹配。环境变量通过命令环境传入;`.env.example` 是参数说明,不自动加载真实密钥。
|
||
|
||
## 构建
|
||
|
||
```sh
|
||
TEMPLATE_KEY=acheng-campus-food pnpm --filter @personal-brand/taro build:h5
|
||
TEMPLATE_KEY=acheng-campus-food pnpm --filter @personal-brand/taro build:weapp
|
||
TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:h5
|
||
TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:weapp
|
||
```
|
||
|
||
输出 `apps/taro/dist/<templateKey>/h5` 和 `weapp`。微信开发者工具导入对应 weapp 目录;构建时通过 `API_BASE_URL` 设置 API 地址,通过 `WEAPP_APP_ID` 或 `TARO_APP_ID` 设置小程序 AppID,并在微信公众平台配置请求合法域名。默认 touristappid 仅用于浏览,不含密钥。
|
||
|
||
页面结构和样式以 React 原型为参考,当前原生小程序用于校对字段、结构化来源、认证与提交行为。模板实现位于各 package 的 `taro/`;公共请求、表单、记录和状态位于此目录。新模板须提供 manifest、Taro 实现和验收用例,不新增全局 seed。
|
||
|
||
## 构建产物遮蔽
|
||
|
||
生产构建会调用构建后处理脚本 `config/mask-taro.cjs`,按 `config/mask.config.json` 替换产物里的 Taro 标识符(文件名与内容使用同一张表),遮蔽后仍命中 `forbidden` 词表时构建失败。`build:h5`、`build:weapp`、`build:preview` 都已接入,后台静态产物由根脚本 `pnpm build:admin:preview` 用 `admin` 目标覆盖;`dev:h5`、`dev:preview` 保持原始命名便于调试。改架构名只改 `config/mask.config.json`;复核某次产物是否干净用:
|
||
|
||
```sh
|
||
TEMPLATE_KEY=acheng-campus-food node config/mask-taro.cjs weapp --check
|
||
node config/mask-taro.cjs admin --check
|
||
```
|
||
|
||
由于产物名称与源码名称不同,产物契约测试用 `test/mask-names.mjs` 的 `unmask()` 还原后再断言,浏览器测试的选择器写成 `:is(<源码名>, <遮蔽名>)`。机制与取舍见 [docs/adr/0025-build-output-stack-masking.md](../../docs/adr/0025-build-output-stack-masking.md)。
|
||
|
||
## 使用边界
|
||
|
||
Web 支持真实已发布内容、导航、餐品搜索/分类、咨询表单填写和校验。未接入 Web 身份登录,因此没有微信会话时不会提交,不生成假咨询或伪造成功。微信小程序采用 Taro.login 和原 customer/session/wechat 接口。令牌按品牌隔离;请求失败保留表单输入,401 清理会话。
|
||
|
||
Web 与小程序来自同一套源码,H5 排版检查不等同微信原生验收。原生微信登录、拨号、剪贴板及真机排版须在微信环境最终核验。
|
||
|
||
## 验证
|
||
|
||
```sh
|
||
pnpm --filter @personal-brand/taro typecheck
|
||
pnpm --filter @personal-brand/taro lint
|
||
pnpm --filter @personal-brand/taro test
|
||
pnpm --filter @personal-brand/taro test:browser
|
||
```
|
||
|
||
完整浏览器回归需要同时启动四类服务,缺一会产生误导性的失败:
|
||
|
||
```sh
|
||
# 1. API(3001)。CORS 必须放行 Admin 与两个 H5 预览来源,否则浏览器报 Failed to fetch。
|
||
CORS_ORIGINS=http://localhost:3002,http://localhost:3003,http://localhost:3005 \
|
||
pnpm --filter @personal-brand/api dev
|
||
|
||
# 2. Admin(3005)。dev server 会把 /api 代理到 3001;静态 preview 没有该代理。
|
||
ADMIN_PORT=3005 pnpm --filter @personal-brand/admin dev
|
||
|
||
# 3. 餐饮 H5(3002)
|
||
TEMPLATE_KEY=acheng-campus-food PREVIEW_PORT=3002 pnpm --filter @personal-brand/taro dev:h5
|
||
|
||
# 4. 林境 H5(3003)
|
||
TEMPLATE_KEY=linjing-editorial PREVIEW_PORT=3003 pnpm --filter @personal-brand/taro dev:h5
|
||
```
|
||
|
||
然后执行:
|
||
|
||
```sh
|
||
ADMIN_URL=http://127.0.0.1:3005 PREVIEW_URL=http://127.0.0.1:3002 \
|
||
pnpm --filter @personal-brand/taro test:browser
|
||
```
|
||
|
||
`PREVIEW_URL` 指定餐饮预览地址,林境用例固定访问 `http://localhost:3003`,`CHROMIUM_PATH` 可指定本机 Chromium。测试只读取开发库,模拟错误响应用于失败路径,不写入真实数据。
|
||
|
||
当前 Taro 4.3 的 `dev:h5` watch 模式在本地会持续增长直至 OOM,而一次性构建正常。遇到该问题时改用 `TEMPLATE_KEY=<key> pnpm --filter @personal-brand/taro build:h5`,再通过静态服务器托管 `dist/<key>/h5`;静态托管同样需要把对应来源加入 `CORS_ORIGINS`。
|
||
|
||
PR 和本地可用轻量 smoke 验证 Admin 会话与创建品牌流程:
|
||
|
||
```sh
|
||
pnpm test:browser:smoke
|
||
```
|
||
|
||
该命令会自动构建 Admin 并启动静态预览;完整浏览器回归仍使用 `pnpm --filter @personal-brand/taro test:browser`。
|
||
|
||
## 回滚与切换
|
||
|
||
所有工作在 feat/taro-template-preview 独立 worktree。用户确认前不合并、不切换主工作区、不修改开发数据库或原 dist/miniapp。确认后另行切换默认构建;旧 template:dev 始终可用。
|
||
|
||
Taro 4.3 官方依赖树含部分旧依赖 deprecation 和 punycode 提示,跟进负责人为框架维护者;本项目固定版本并检查双端产物。Admin React 19 与 Taro React 18 在各 workspace 依赖边界独立,避免跨端插件 peer mismatch。
|