kola-web
5 days ago
4 changed files with 240 additions and 34 deletions
@ -1,2 +0,0 @@
@@ -1,2 +0,0 @@
|
||||
1. 本项目使用 TypeScript + scss 进行开发 |
||||
2. 不使用测试框架 |
||||
@ -0,0 +1,221 @@
@@ -0,0 +1,221 @@
|
||||
# AGENTS.md — IGG4 微信小程序 |
||||
|
||||
## 项目概述 |
||||
|
||||
IGG4 重症肌无力（MG）患者社区微信小程序。两种用户角色：患者（loginType=1）和医生（loginType=2）。基于 TypeScript + SCSS 构建，无测试框架。 |
||||
|
||||
### 技术栈 |
||||
|
||||
| 类别 | 技术 | |
||||
|------|------| |
||||
| 语言 | TypeScript + SCSS + WXML | |
||||
| 包管理 | pnpm（非 npm/yarn） | |
||||
| UI 库 | Vant Weapp (`@vant/weapp`) | |
||||
| 图表 | ECharts（`ec-canvas` 组件）+ F2（JSX 语法，Babel 转译） | |
||||
| 日期 | dayjs（中文 locale + relativeTime 插件） | |
||||
| 工具库 | miniprogram-licia（curry、debounce 等） | |
||||
| 富文本 | mp-html | |
||||
| 精度计算 | number-precision | |
||||
| 代码规范 | @antfu/eslint-config + prettier（无分号、单引号、尾逗号、120 字符宽度） | |
||||
|
||||
## 命令 |
||||
|
||||
- `pnpm install` — 安装依赖（使用 pnpm，非 npm/yarn） |
||||
- `pnpm run lint:fix` — eslint 自动修复（使用 @antfu/eslint-config + prettier，stylistic 已禁用） |
||||
- `pnpm run beforeCompile` — babel 转译 `src/pages` 中的 `.jsx` 文件（通过 `project.config.json` scripts 在微信开发者工具编译/预览/上传前自动执行） |
||||
|
||||
无 `build`、`test` 或 `typecheck` 脚本。类型检查和编译由微信开发者工具处理。 |
||||
|
||||
## 架构 |
||||
|
||||
- **源码根目录**：`src/`（在 project.config.json 中设为 `miniprogramRoot`） |
||||
- **入口**：`src/app.ts` + `src/app.json` |
||||
- **路径别名**：`@/*` 映射到 `src/*`（tsconfig paths + app.json resolveAlias） |
||||
- **自定义 Page 包装器**：`src/utils/page.ts` 在 `app.ts` onLaunch 时全局替换 `Page()` — 注入 `imageUrl`/`Timestamp` 数据、滚动导航栏变色、默认分享行为、`handleMakePhoneCall`。所有页面都经过此包装器。 |
||||
- **HTTP 请求**：`src/api/request.ts` 将 `wx.request` 封装为 `wx.ajax`（通过 `licia.curry` 柯里化基础 URL）。所有 API 调用使用 `wx.ajax()`，而非 `wx.request()`。自动在 header 和 body 中注入 `loginState`。 |
||||
- **npm 包**：由微信开发者工具构建到 `src/miniprogram_npm/`（packNpmManually 配置）。不要直接编辑 miniprogram_npm。 |
||||
|
||||
### 登录与权限系统（app.ts） |
||||
|
||||
- **登录流程**：`onShow` → `startLogin()` → `wx.login` 获取 code → 后端 `init-login` 返回 `loginState` |
||||
- **用户等级**（`UserType`）： |
||||
- 1：空白用户 → 跳转登录页 |
||||
- 2：已注册用户 → 需完善资料 |
||||
- 3：已确诊患者 → 需上传认证 |
||||
- 4：已用药患者（VIP）→ 完整权限 |
||||
- **路由守卫**：`verifySys(pub)` 检查登录状态和角色，自动重定向： |
||||
- 未登录 + 医生端页面 → 医生登录页 |
||||
- 未登录 + 患者端页面 → 患者登录页（若 anyWhere 为 true 则"随便看看"模式） |
||||
- 患者访问医生端页面 → 重定向到患者首页 |
||||
- 医生访问患者端页面 → 重定向到医生中转页 |
||||
- **权限校验**：`permissionVerification(grade, registChannel, backPage, regBusinessId)` 按等级拦截 |
||||
- **注册验证**：`registrationVerification(callback, loginPage)` 根据审核状态引导用户（AuditStatus: 0=无证书, 1=审核中, 2=已拒绝） |
||||
- **关键全局变量**：`loginState`（令牌）、`isLogin`（0/1）、`isReg`、`loginType`（1=患者, 2=医生）、`anyWhere`（免登录浏览模式）、`first`（首次启动标志） |
||||
|
||||
### 数据监听机制 |
||||
|
||||
- `app.watch(key, method)` — 通过 Object.defineProperty 监听 globalData 变化 |
||||
- `app.registerListener(fn)` / `app.triggerListeners()` — 全局事件监听模式（custom-tab-bar 等使用） |
||||
- `setWatcher(page)`（来自 `utils/watch.ts`）— 页面级 watch 支持 |
||||
|
||||
### 自定义 TabBar（5 个 Tab） |
||||
|
||||
| Tab | 页面路径 | 名称 | |
||||
|-----|---------|------| |
||||
| 1 | `/pages/index/index` | 首页 | |
||||
| 2 | `/pages/repository/index` | MG全知道 | |
||||
| 3 | `/pages/live/index` | 周三大咖说 | |
||||
| 4 | `/pages/story/index` | 向往的生活 | |
||||
| 5 | `/pages/my/index` | 我的 | |
||||
|
||||
- 自定义 TabBar 使用 Vant `van-tabbar` 组件 |
||||
- Tab 4（向往的生活）在 `anyWhere` 为 true 时隐藏（浏览模式） |
||||
- Tab 2（MG全知道）在 `config.picTextEbookStatus === 1` 时可能重定向到 webview |
||||
- Tab 5（我的）需要 `permissionVerification(grade=2)` |
||||
- 主题支持：DRUG / PATIENT（当前始终解析为 PATIENT） |
||||
|
||||
### HTTP 响应约定（api/request.ts） |
||||
|
||||
- 成功：`code === 0` → 返回 `data` 字段 |
||||
- 错误且 `showMsg=true`（默认）：显示 toast 错误提示 |
||||
- `isJSON=true`：返回完整响应（不仅仅是 data） |
||||
- `loading=true`：显示/隐藏加载遮罩 |
||||
- 错误信息提取顺序：`data` → `msg` → `errMsg` → `detail.errMsg` → "未知错误" |
||||
|
||||
## 分包 |
||||
|
||||
| 分包 | 路径 | 页面数 | 说明 | |
||||
|------|------|--------|------| |
||||
| 主包 | `src/pages/` | 55+ | 患者端核心页面 | |
||||
| gift | `src/gift/` | 20 | 积分商城、健康档案、皮损记录 | |
||||
| doctor | `src/doctor/` | 22 | 医生端完整功能（含独立 tabbar 组件） | |
||||
| public | `src/public/` | 3 | 知情同意流程 | |
||||
| doc | `src/doc/` | 2 | 文档页面 | |
||||
| resource | `src/resource/` | 0 | 独立分包（当前为空） | |
||||
|
||||
### 主包页面（src/pages/） |
||||
|
||||
按功能分类： |
||||
- **认证流程**：`start`、`login`、`vipLogin`、`vipLoginReject`、`startReject`、`startPending`、`getUserInfo` |
||||
- **注册**：`enterInfo`、`uploadCert`、`certReslove`、`certPending` |
||||
- **首页**：`index` |
||||
- **知识库**：`repository`、`repositoryDetail`、`repositoryVideoDetail` |
||||
- **直播/会议**：`live`、`liveDetail`、`liveResult`、`myLive` |
||||
- **故事**：`story`、`storyDetail`、`storyEnter`、`storyEnterResult`、`storyList`、`storyGuide`、`publishStoryDetail` |
||||
- **ADL 评估**：`adl`、`adlShare`、`adlTest`、`adlResult` |
||||
- **个人中心**：`my`、`mySave`、`personalInformation`、`changePhone`、`changeUser`、`cancellation` |
||||
- **家庭**：`family`、`familyList`、`familyScan` |
||||
- **医疗**：`hospital`、`doctor`、`doctorDetail`、`drugRecord`、`infusionCenter`、`nrdl`、`nrdlDetail`、`nrdlTable` |
||||
- **其他**：`thePublic`、`privacyAgreement`、`taskAgreement`、`comIns`、`signIn`、`smallPage`、`webview`、`referral`、`interactivePatient`、`demo` |
||||
|
||||
### 医生端分包页面（src/doctor/） |
||||
|
||||
- **认证**：`d_login` |
||||
- **首页**：`d_home` |
||||
- **患者管理**：`d_patient`、`d_patientDetail`、`d_patientList` |
||||
- **任务**：`d_taskList`、`d_taskDetail`、`d_createTask` |
||||
- **互动**：`d_interactive`、`d_interactiveDoctor` |
||||
- **个人**：`d_my`、`d_userInfo`、`d_changePhone`、`d_changeDoctor` |
||||
- **邀请**：`d_invite` |
||||
- **导出**：`d_exportList`、`d_customExport`、`d_customExportMiddle` |
||||
- **转诊**：`d_transfer`、`d_transferLog`、`d_transferDetail` |
||||
- **路由中转**：`d_trans`（医生访问患者端页面的中转页） |
||||
|
||||
### 礼品分包页面（src/gift/） |
||||
|
||||
- **积分商城**：`giftList`、`giftDetail`、`conformOrder` |
||||
- **订单**：`orderEnd`、`orderDetail` |
||||
- **地址**：`siteList`、`siteEdit` |
||||
- **积分**：`myGift`、`priceDetail`、`scoreRule` |
||||
- **健康档案**：`myHealthRecord`、`myHealthRecordChart` |
||||
- **VIP**：`vipCert`、`vipReject`、`vipPending`、`vipStartPending` |
||||
- **DTP**：`dtpDurg` |
||||
- **皮损**：`cutaneous`、`cutaneousDetail`、`cutaneousVideo` |
||||
|
||||
## 全局组件（src/components/） |
||||
|
||||
| 组件 | 说明 | |
||||
|------|------| |
||||
| `calendar` | 日历选择器 | |
||||
| `customPoster` | 自定义海报生成 | |
||||
| `customTable` | 自定义数据表格 | |
||||
| `ec-canvas` | ECharts 画布包装器 | |
||||
| `freeAudio` | 音频播放 | |
||||
| `loginNavbar` | 登录页导航栏 | |
||||
| `navBar` | 通用导航栏 | |
||||
| `pageNavbar` | 页面级导航栏 | |
||||
| `pagination` | 分页组件（在 app.json 中全局注册） | |
||||
| `pickerArea` | 地区选择器 | |
||||
| `referralFrom` | 转诊来源选择器 | |
||||
| `star` | 星级评分 | |
||||
| `text-expandsion` | 文本展开/收起 | |
||||
| `timeOut` | 倒计时 | |
||||
| `toast` | 自定义弹窗提示 | |
||||
| `uploadFile` | 文件上传 | |
||||
| `viewFile` | 文件查看 | |
||||
| `viewVideo` | 视频播放器 | |
||||
|
||||
## 工具函数（src/utils/） |
||||
|
||||
| 文件 | 说明 | |
||||
|------|------| |
||||
| `page.ts` | Page() 全局替换：注入 imageUrl/Timestamp、滚动导航栏变色、默认分享、handleMakePhoneCall | |
||||
| `util.ts` | formatTime、formatNumber、getCurrentPageUrl、getCurrentPageUrlWithArgs、parseScene | |
||||
| `promisify.ts` | 基于 Proxy 的 wx API Promise 化（同步方法保留，异步方法返回 Promise） | |
||||
| `watch.ts` | 基于 Object.defineProperty 的页面级数据监听（setWatcher） | |
||||
| `doctorPatientTask.ts` | 医生端患者筛选列定义（ADL、激素剂量、抗体类型等） | |
||||
| `tools.wxs` | WXS 模板工具 | |
||||
| `dayjs/` | dayjs 插件（中文 locale、relativeTime） | |
||||
|
||||
## 类型定义（typings/index.d.ts） |
||||
|
||||
- `IAppOption` — App 实例接口，包含 globalData 结构和方法签名 |
||||
- `IAgaxParams` — 扩展的请求选项，含 `showMsg`、`loading`、`isJSON` |
||||
- `Response<T>` — 通用 API 响应结构 |
||||
- `globalSystemInfo` — 扩展的系统信息，含胶囊按钮位置 |
||||
- `WechatMiniprogram.Wx.ajax` — wx.ajax 的类型增强 |
||||
|
||||
## 页面结构 |
||||
|
||||
每个页面是一个目录，包含 4 个文件：`index.ts`、`index.wxml`、`index.scss`、`index.json`。组件遵循相同的 4 文件模式。 |
||||
|
||||
### 新增页面 |
||||
|
||||
1. 在对应分包下创建目录（如 `src/pages/myPage/`） |
||||
2. 创建 4 个文件：`index.ts`、`index.wxml`、`index.scss`、`index.json` |
||||
3. 在 `src/app.json` 中注册： |
||||
- 主包页面 → `pages` 数组 |
||||
- 分包页面 → `subpackages` 中对应分包的 `pages` 数组 |
||||
4. 如页面使用组件，在页面的 `index.json` 的 `usingComponents` 中注册 |
||||
|
||||
### 新增组件 |
||||
|
||||
1. 在 `src/components/` 下创建目录（医生端在 `src/doctor/components/`） |
||||
2. 创建 4 个文件：`index.ts`、`index.wxml`、`index.scss`、`index.json` |
||||
3. 在页面的 `index.json` 中注册：`"usingComponents": { "my-comp": "/components/myComp/index" }` |
||||
4. 全局注册则在 `app.json` 的 `usingComponents` 中添加 |
||||
|
||||
## 关键约定 |
||||
|
||||
- **JSX/F2 图表**：Babel 插件 `@babel/plugin-transform-react-jsx`，`jsxImportSource: "@antv/f2"` — 页面中的 `.jsx` 文件使用 F2 图表语法，由 beforeCompile 脚本转译 |
||||
- **微信全局变量**：`wx`、`App`、`Page`、`Component`、`getCurrentPages`、`getApp` 已在 ESLint globals 中声明 |
||||
- **CSS 单位**：使用 `rpx`（微信响应式像素），布局中不用 `px` |
||||
- **图片**：存储在 `src/images/`，通过 SVN 部署（非 git，图片已 gitignore）。使用 `dist.ps1`/`dist.sh`/`dist.nu` 脚本部署 |
||||
- **`noImplicitAny: false`** — 允许隐式 any |
||||
- **`removeComments: true`**（tsconfig）— 编译输出移除注释 |
||||
- **Prettier**：无分号、单引号、尾逗号、120 字符宽度；`.wxml` 按 HTML 解析，`.wxss` 按 CSS 解析，`.wxs` 按 babel 解析 |
||||
- **API URL 格式**：所有 API 调用使用 `?r=模块/动作` 格式（如 `?r=igg4/user/init-login`、`?r=igg4/account/info`） |
||||
- **默认分享**：患者端页面分享到 `/pages/index/index`，医生端页面分享到 `/doctor/pages/d_home/index`，标题："重症肌无力加油站，重拾生活掌控感！" |
||||
- **客服电话**：全局 `handleMakePhoneCall` 拨打 `4008102299` |
||||
|
||||
## 环境 / 部署 |
||||
|
||||
- 开发环境 API：`https://m.igg4.hbraas.com`（在 `app.ts` globalData 中硬编码） |
||||
- 生产环境 API：`https://m.igg4.hbsaas.com`（已注释，部署时切换） |
||||
- 上传 URL 与 API 同域名，末尾加 `/` |
||||
- 图片 URL：`{domain}/igg4/` |
||||
- 开发 AppID：`wxc3cdb3c4d4f62cea`，生产 AppID：`wx96f45ca4f1fa36ec` |
||||
- 微信开发者工具负责编译、npm 构建、预览和上传 |
||||
- `project.private.config.json` 本地覆盖 `project.config.json` |
||||
- 切换环境：取消 `app.ts` globalData 中生产 URL 的注释 + 修改 `project.config.json` 中的 appid |
||||
- 图片通过 `project.config.json` 中的 `packOptions.ignore` 排除上传 |
||||
Loading…
Reference in new issue