AGENTS.md

本文件面向 AI 编码代理，介绍本项目的架构、约定与开发方式。

项目概述

SHJ_APP（施工管理 App）是一个基于 uni-app + Vue 3 的跨端移动应用，服务于管道施工 / 焊接管理业务（点口管理、试压管理、包装管理、发货管理、预制组件管理、下料抽检、组对抽查、焊接日报、防腐处理等）。主要运行目标是微信小程序（manifest.json 中已配置 mp-weixin appid），同时兼容 H5 和 App（5+App）。

后端接口地址（见 utils/request.js）：

API：https://lygcgs.com.cn:8078/shjapi/api/
附件/文件：https://lygcgs.com.cn:8078/shj/

技术栈

框架：uni-app（Vue 3，manifest.json 中 vueVersion: "3"）+ Vite
状态管理：Pinia + pinia-plugin-persist-uni（状态持久化到本地存储）
UI 组件库：uview-pro（u-* 组件通过 easycom 自动引入）。组件用法/props 参考本地文档副本 docs/uview-pro-llms-full.txt（原始地址 https://uviewpro.cn/llms-full.txt，可按 url: 分节检索，共 147 个组件/主题文档）
样式：SCSS（全局样式在 App.vue 中引入；公共变量在 uni.scss，如 $app-primary: #2979ff）
条码：bwip-js（assets/js/js_sdk/，微信小程序需要 main.js 顶部的 atob polyfill）

构建与运行

package.json 中没有定义任何 scripts，也没有 vite.config.*。本项目通常通过 HBuilderX 开发调试（运行 → 运行到小程序模拟器 → 微信开发者工具），构建产物输出到 unpackage/（已 gitignore）。

依赖安装：pnpm install（仓库同时存在 pnpm-lock.yaml 与 package-lock.json，以 pnpm 为主）。

目录结构

pages/            主包页面：login（登录）、index（首页）、mine（我的）、todo（待办）
pipe/             分包（root: pipe）：diankou 点口、pressure 试压、packaging 包装、
                  deliver 发货、precast 预制组件
scanpages/        分包（root: scanpages）：hj/ 扫码与焊接相关页面（材料详情、下料抽检、
                  组对抽查、焊接日报、防腐处理、日报审核）、components/nbd-print-prop.vue
components/       全局公共组件，均为 nbd-* 前缀（easycom 自动注册）
api/              接口层：auth.js / user.js / base.js / hj.js，按业务模块划分
store/            Pinia：index.js 入口，modules/ 下 user.js（登录态/项目）、
                  menu.js（菜单权限/快捷应用）、large.js（焊接首页数据）
utils/            request.js（请求封装）、scanUtils.js（扫码解析）、constant.js
                  （常量/默认应用配置）、formatTime.js、bwipjs-polyfill.js
assets/           css/（page.scss、components.scss 全局样式）、icon/（nbd-icon 图标）、js/
docs/             参考文档（uview-pro-llms-full.txt 组件库文档副本）
static/           图片与 tabBar 图标
pages.json        页面路由、分包、tabBar、easycom 配置（修改路由必须改这里）
manifest.json     应用配置（appid、微信小程序 appid、Android 权限等）

代码约定

页面与组件统一使用 Vue 3 <script setup> 组合式 API；页面生命周期从 @dcloudio/uni-app 导入（onLoad、onShow 等），不要直接用 onMounted 代替页面级生命周期。
easycom 自动注册（见 pages.json）：
- u-* → uview-pro 组件
- nbd-* → @/components/nbd-*.vue（新增公共组件放到 components/ 并遵循 nbd- 命名，无需手动 import）
- nbd-print-prop → @/scanpages/components/nbd-print-prop.vue
新页面必须在 pages.json 的 pages 或对应 subPackages 中登记；pipe/、scanpages/ 是分包，页面路径引用时以 /pipe/...、/scanpages/... 开头。
接口层约定：所有请求函数定义在 api/*.js 中，命名前缀 req（如 reqHJIndexData），基于 utils/request.js 导出的 get / post：
- 后端约定 body.code === 1 为成功；非 1 自动 toast 报错并 reject；code === 401 自动登出并跳转登录页。
- 请求自动携带 token 请求头（取自 user store）；默认显示 loading，可通过 request(url, { loading: false, toast: false }) 控制。
- GET 参数用对象传入（get(url, { key: val })），会自动编码中文；也兼容旧的 URL 拼接风格。
- 附件上传用 api/base.js 的 uploadAttach；服务器返回的逗号分隔附件路径用 parseAttachUrls 解析为可展示列表。
状态管理：store 使用组合式写法（defineStore('user', () => {...})），通过 persist 选项持久化（如 user store 持久化 loginForm/userInfo/token/currentProject）。切换当前项目（currentProject）会自动触发菜单权限与焊接首页数据的重新拉取（store/modules/user.js 中的 watch）。
菜单权限：双重过滤（store/modules/menu.js 的 appVisible）——后端 getMenuPowerList（按 menuId GUID 匹配）+ 小程序端硬编码岗位权限。岗位权限规则（来源 requests/权限.xlsx，固定在 utils/constant.js 的 postMenuPermissions）：仅对登录返回 UserType === '3' 的现场人员按 WorkPostName 限制扫码类功能（sampling 下料抽检 / makeRight 组对抽查 / antiRust 防腐处理 / dailyPaper 焊接日报 / dailyAudit 日报审核，其中 dailyAudit 仅管理/技术岗位有），pipe 管理类应用（无 funcKey）对现场人员一律隐藏；其余用户不限制。扫码跳转页面前需用 menu store 的 canAccessPath 校验（首页扫一扫已接入）。
扫码：首页入口带 isScan: true 的应用走扫码流程，扫码结果统一由 utils/scanUtils.js 的 parseScanResult 解析（焊接接头二维码跳焊接日报；非 URL 视为材料编码）。
代码风格：缩进用 Tab，中文注释，单文件组件结构为 template / script / style(scoped scss)。列表页普遍采用「filter-header + scroll-view 下拉刷新/上拉加载 + card 列表」的模式，新列表页请参照 pipe/packaging/list.vue。

测试

项目没有测试框架、没有 lint/format 配置，无任何自动化测试。验证方式是在微信开发者工具 / HBuilderX 中手动运行页面确认。

安全注意事项

登录 token（即 PersonId）通过 Pinia 持久化存储在本地，并在每个请求的 token 请求头中携带；不要在日志中打印 token 或提交包含凭据的代码。
manifest.json 中包含微信小程序 appid 等发布配置，修改前请确认影响。
生产后端地址硬编码在 utils/request.js（baseUrl / baseFileUrl），修改会直接影响线上请求。

6.7 KiB Raw Blame History Unescape Escape