# 泰昌 ERP 小程序（teichang_erp_mini）

基于 uni-app + Vue 3 + TypeScript 的微信小程序，复用 `teichang_erp_manager`（jeesharp，端口 34560，前缀 `/admin`）全部现有接口，**零后端改动**。技术栈 1:1 对齐参考项目 `xinghuacun_travel_mini_app`（uni-app 3.0.0-5000720260410001 + Vue 3.5.38 + TS 4.9 + Vite 5.2.8 + Pinia + uview-plus + jsencrypt + dayjs + sass）。

## 目录结构

```
src/
├── api/            # crud.ts（CRUD 工厂）+ modules/（auth/dict）
├── components/common/  # ErpEmpty/ErpLoadMore/ErpSearchBar/ErpListItem/ErpDetailCell/ErpStatusTag
├── composables/    # usePagedList（分页/防抖/防竞态）
├── config/         # env.ts（API 基址）/api.ts（超时/重试）
├── constants/      # routes.ts（路由常量）
├── modules/
│   ├── registry.ts # 模块注册表（49+ 模块唯一真源：apiPrefix/权限码/状态机动作）
│   └── bill/       # BillListView/BillDetailView/BillFormView 通用模板 + formSchemas
├── pages/          # 主包：login/workbench/bills/profile（tabBar 3 项）
├── package*/       # 9 个分包，每包仅 list/detail/edit 薄壳页（?module= 参数驱动）
├── store/          # user（token/权限码）+ dict（9 类字典 TTL 缓存）
└── utils/          # request（jeesharp 业务码适配）/rsa/storage/tokenStorage/auth/format
```

## 环境准备

1. Node.js ≥ 18（参考项目同版本）
2. 微信开发者工具（导入 `dist/dev/mp-weixin` 或 `dist/build/mp-weixin`）
3. 后端 `teichang_erp_manager` 已启动（默认 `http://127.0.0.1:34560`）

## 安装与启动

```bash
npm install

# 微信小程序开发构建（watch）
npm run dev:mp-weixin
# 微信开发者工具导入 dist/dev/mp-weixin

# H5 调试（vite proxy 已配 /admin → 127.0.0.1:34560）
npm run dev:h5

# 生产构建
npm run build:mp-weixin

# 类型检查
npm run type-check
```

## 环境变量

| 文件 | 变量 | 说明 |
|---|---|---|
| `.env.development` | `VITE_API_BASE_URL=http://127.0.0.1:34560/admin` | 开发基址 |
| `.env.production` | `VITE_API_BASE_URL`（占位） | **真机前必须替换为 HTTPS 备案域名**，并在小程序后台配置 request 合法域名 |

## 登录契约（已从 @fskj-admin/shell 源码实证）

1. `GET /admin/getRsaPublicKey` → base64 RSA 公钥（1024 位）
2. `GET /admin/login/captcha` → `{ enabled, uuid, img }`（enabled 由后端系统配置决定）
3. `POST /admin/login` → `{ username: RSA(用户名), password: RSA(密码), code?, uuid? }`，加密失败降级明文；响应取 `data.accessToken`（兜底 token/access_token）+ `data.ssoToken`（兜底 sso_token）
4. 后续请求头三件套：`access_token` + `Authorization: Bearer <token>` + `satoken`
5. 登出 `GET /admin/logout?accessToken=`；用户信息 `GET /admin/basic/sys/user/v1/currentUserInfo`

统一响应 `{ code, msg, data }`：200 成功、201 token 失效（清态跳登录）、205 无权限（toast 提示）。

## 架构要点

- **配置驱动**：所有模块在 `src/modules/registry.ts` 集中登记（apiPrefix/权限码/状态机动作），工作台宫格、单据 tab、列表/详情/编辑模板页全部由注册表驱动；新增模块 = 注册表一行 + （如已有分包）零页面改动
- **CRUD 工厂**：`src/api/crud.ts` 统一 `info/list/create/update/delete` + 扩展端点 `audit/unaudit/convert/finish/confirm/lock/unlock/from-bill/from-sales/calc`
- **详情页自动渲染**：info 响应标量字段 → KV 列表，数组字段 → 明细卡，无需逐模块写 schema
- **字典缓存**：供应商/客户/会员/仓库/结算账户/经手人/收支项目/商品类别/单位，TTL 10min + 写后失效，仅做展示翻译，提交以 id 为准
- **分包**：主包 0.35MB（红线 1.5MB），9 个分包均远小于 1.8MB；preloadRule 已配工作台→basic/material、采购→销售→零售流转链

## 联调步骤

1. 启动后端，`curl http://127.0.0.1:34560/admin/getRsaPublicKey` 确认联通
2. 微信开发者工具导入 `dist/dev/mp-weixin`，勾选「不校验合法域名」（开发期）
3. 管理员账号登录 → 工作台看板 → 各域列表/详情/审核操作抽验
4. 交付前按 `docs/sql/init-business-permissions.md`（后端仓库）为移动端角色授权

## 移动端裁剪说明

- Excel 导入（`import` 端点）不做，以 `uni.scanCode` 扫码快加明细行替代
- 复杂税率/折扣字段在表单中折叠为可选，详情全量展示