# 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`），修改会直接影响线上请求。