airz-uniapp/README.md

# AI 融资移动端

基于 uni-app x、Vue 3、UTS 的移动端原型，包含 25 个页面。使用 HBuilderX（VDOM 模式）开发，已验证 5.24 和 5.26 的本地编译；本项目没有独立的 npm 构建入口。

## 本地运行

在 HBuilderX 中导入当前目录，选择“运行 → 运行到浏览器”。共享请求配置位于 `services/api.uts`，账户、融资服务分别位于对应分包的 `services/`。现已接入本地后端密码登录、读取资料、退出及原密码改密；短信、贷款申请和 AI 服务尚未接入。

也可使用 HBuilderX CLI。以下 PowerShell 命令中的安装路径应按本机环境调整；在项目根目录执行：

```powershell
$hbuilderCli = 'D:\Develop\HBuilderX\cli.exe'
$projectPath = (Get-Location).Path
& $hbuilderCli open
& $hbuilderCli launch web --project $projectPath --compile false --continue-on-error false
```

## 各平台编译

以下命令仅本地编译，不上传、不发布：

```powershell
& $hbuilderCli launch mp-weixin --project $projectPath --compile true --continue-on-error false
& $hbuilderCli launch app-android --project $projectPath --compile true --continue-on-error false
& $hbuilderCli launch app-ios --project $projectPath --iosTarget simulator --compile true --continue-on-error false
```

产物位于 `unpackage/dist/dev/` 对应平台目录。Android 命令可检查 Kotlin/class 编译；Windows 上 iOS 命令只检查当前编译链生成的源码产物，不代表已完成 Xcode 构建或生成 IPA。

运行微信小程序需配置自己的 AppID，并开启微信开发者工具服务端口。Android 真机运行需启用 USB 调试；iOS 真机运行需相应签名环境。正式发行还需配置应用图标、签名、真实接口及平台要求的资料，并完成真机测试。

## 跨端维护约定

- 页面尺寸和安全区计算集中在 `services/layout.uts`。新增页面应复用这里的逻辑，并检查小屏、横屏、键盘弹出及底部安全区。
- 微信小程序首页在右侧预留胶囊区域与 8px 间距；公共页面标题采用左右对称的安全留白，始终按屏幕中心定位。获取胶囊失败时按 104px 避让。产品分享入口在小程序端放在内容区，App 和 Web 仍保留在标题栏右侧。导航不新增顶部空行，顶部按状态栏和安全区计算。
- 首页右上角依次为搜索、消息通知；微信端两个按钮与胶囊等高、顶部对齐，按钮组向左展开，左侧 Logo 对齐胶囊的垂直中心；其他端仍在导航栏内居中。AI 助手保留首页横幅及快捷入口。
- 原生样式遵循 uni-app x 支持范围。仅 Web/小程序支持的样式用条件编译隔离；修改 UTS 类型后应重新验证 Android 编译。
- 首页及跨包共用的轻量位图位于 `static/mobile/`，专属大图位于各分包的 `static/`，原始图片保留在 `static/images/` 与 `static/icons-generated/`。箭头继续使用 `static/icons/` 下的 SVG。
- 底栏使用 `static/mobile/navigation/` 的专用位图，由现有高清图标按可见边界裁切、等高居中得到。更换素材时保持一致的图案高度和画布留白，避免仅统一图片元素尺寸却出现视觉错位。
- 微信打包忽略原始图片目录和未使用的 `static/logo.png`，规则位于 `manifest.json` 的 `mp-weixin.packOptions.ignore`。新增资源要检查引用与排除规则，最终包体以微信开发者工具结果为准。
- API 环境配置在 `services/config.uts`，开发地址为 `http://127.0.0.1/api/v1`。共享请求已统一Bearer、FastAdmin响应解包及401处理；模拟开关关闭，缺服务配置时失败而非模拟成功。测试/生产地址待配置，生产只允许HTTPS。真机需改为可访问的局域网/正式地址，不能使用手机自身127.0.0.1。

## 当前前端交互

个人与企业评估分别保存本机草稿；选图仅供本机预览，资料上传和数据查询尚未接入。课程章节进度、消息已读与体验签到均保存在当前设备，不代表服务器账户数据。

个人中心顶部的头像、昵称、手机号区域统一进入修改资料；账户安全独立提供修改密码、验证码重设密码及换绑手机号。昵称和头像缓存按稳定userId隔离，手机号仅保留为内部兼容键。头像编辑交互限制 500KB 以内的 JPG / PNG / WebP 数据，正式上传和持久化仍待开发，不修改融资档案的实名信息。密码登录、原密码改密及退出已接入Redis会话；短信验证和换绑尚未接入，不在本机模拟成功，也不保存密码、验证码或其散列。安全接口成功后清除当前会话并要求重新登录；验证码计时仅在服务端发送成功后启动。

账户接口集中在 `packages/account/services/account.uts`，请求携带当前会话的 `Authorization: Bearer <token>`；后端需根据 token 确定账户，校验验证码用途与有效期、限制发送频率并完成旧会话撤销。预留：

- `PUT /account/profile`：`nickname`、`avatar`（图片 data URL 或空字符串）；昵称 2–20 字符。当前本地缓存用于个人中心回显，后续应接入服务端资料读取和持久头像存储。
- `POST /account/security/sms-code`：`purpose`（`password` / `phone-current` / `phone-new`）与 `newPhone`（仅新号码验证传入）；当前号码从认证账户读取。
- `PUT /account/password`：`verification`（`password` / `sms`）、`oldPassword` 或 `code`、`newPassword`。新密码为 8–32 位可打印 ASCII，需含字母和数字，不允许空格。
- `PUT /account/phone`：`newPhone`、`currentCode`、`newCode`；后端验证两组验证码及新号码占用情况。

资产与负债包含 `creditLoanCount`（信用贷款笔数）、`totalDebtBalance`（欠款总余额）、`monthlyLoanPayment`（贷款月还款金额）、`creditCardCount`（银行信用卡张数）、`creditCardTotalLimit`（总额度）、`creditCardUsedLimit`（已使用总额度）、`house` / `car`（有 / 无）。移动端所有金额统一以万元输入和展示，最多六位小数；提交接口前精确换算成元的两位小数字符串，范围为 0–999999999.99 元（DECIMAL(11,2)）。数量为非负整数；保持原来的可跳过规则，填满八项后计为档案已完善。草稿使用 `moneyUnit: wan`、`draftVersion: 2` 标记；无标记旧草稿的月收入及贷款/信用卡金额从元换算成万元，年营收原本就是万元，保留原值。旧草稿的房车选项自动映射，新数字字段留空，不从旧存款区间或信用卡状态猜测金额；旧字段保留在草稿中以免丢失历史输入。

新闻与课程的数据定义位于 `packages/content/services/content.uts`，产品定义位于 `packages/finance/services/finance.uts`。产品列表与详情共用 ID；预留 `GET /matches`（`items` 数组）及 `GET /products/:id`（单个产品），字段见 `FinanceProduct`，其中视图模型的 `amount` 为万元数值、`rate` 为年化百分比数值。真实接口应返回 `amountYuan`（元的两位小数字符串），由适配层转换；旧 `amount`（万元）仅保留兼容。后端产品表使用独立的额度、期限和利率范围字段，匹配分数与理由属于评估结果。申请入口目前仅引导准备资料，不向金融机构提交申请。

首页搜索进入内容分包的 `search/search`，支持全部、新闻、融资课堂筛选及对应详情跳转。搜索服务位于 `packages/content/services/search.uts`，当前匹配本地标题、简介、分类和正文；空格分隔的多个关键词需同时命中。预留 `GET /content/search`，参数为 `keyword` 与 `type`（`all` / `news` / `lesson`），返回 `{ items: ContentSearchResult[] }`，每项包含 `id`、`type`、`title`、`summary`、`category`、`meta`、`image`。后端接入时需同步接入新闻和课程详情的数据源，确保返回的 ID 可查询详情。

## 页面与分包

“帮助与反馈”从个人中心进入内容分包的 `help/help`，按账户使用、融资评估、资料与隐私分组展示可展开的问答，不跳转 AI 助手。数据与客服接入点位于 `packages/content/services/help.uts`；预留 `GET /help/faqs` 返回 `{ items: HelpQuestion[] }`。联系客服当前只展示暂未开放提示，不发起客服会话或提交反馈。

`pages/` 只保留 `home/home.uvue`，也是唯一主包页面。页面注册统一维护在 `pages.json` 的 `pages` 和 `subPackages`，分包内的 `path` 相对于 `root`。

| 目录 | 内容 | 页面数 |
| --- | --- | --- |
| `pages/home` | 首页 | 1 |
| `packages/finance` | 融资入口、评估、确认、分析、报告、匹配、产品、助手、档案 | 9 |
| `packages/account` | 启动引导、登录、个人中心、修改资料、账户安全、修改密码、更换手机号、积分、消息 | 9 |
| `packages/content` | 搜索、帮助与反馈、新闻、文章、融资课堂、课程详情 | 6 |

当前各模块体积较小，优先保持完整业务链；普通内容统一一个包。新增功能先放入所属分包，再根据微信编译产物大小决定是否细分。单包以 2 MiB 为保守预算，需预留增长空间，最终体积以微信开发者工具为准。

2026-09-20 使用 HBuilderX 5.26 本地微信开发编译，按 `packOptions.ignore` 排除原始素材后统计：主包约 887 KiB，融资包 378 KiB，账户包 148 KiB，内容包 355 KiB。此为磁盘产物统计，不等同于开发者工具上传后的压缩体积。

- 分包页面使用完整绝对路由 `/packages/<模块>/<页面>/<页面>`，包含路由比较和携带参数的跳转；主包首页仍为 `/pages/home/home`。
- 微信按 `subPackages` 下载分包。Android、iOS 使用相同目录、页面注册和路由编译为应用，不将小程序按需下载机制等同于 App 热更新。
- 保留现有自绘 `BottomNav`，新闻、消息、我的允许在分包中；不配置要求页面留在主包的原生 `tabBar`。底栏切换使用 `reLaunch`，详情使用 `navigateTo` / `navigateBack`。
- 冷启动首页通过 `services/launch.uts` 只触发一次账户引导，之后按登录状态进入首页或登录；直接打开分包页面和正常返回首页不会重复触发引导。
- `components/` 与 `services/` 只保留共享组件、布局、请求、会话和跨包草稿。主包或其他分包不得 import 某个分包的专属模块；分包间只通过路由与共享服务交互。
- 仅某个分包使用的图片放在该包 `static/`；首页也使用的插图及通用图标保留在根 `static/`，避免分包资源被主包引用。

参考：[uni-app x 页面与分包配置](https://doc.dcloud.net.cn/uni-app-x/collocation/pagesjson.html#subpackages)。

## 2026-09-22 金额与评估存储约定

`services/money.uts` 集中处理万元与元的精确转换；确认页与草稿均为万元，`submitAssessment` 仅在提交边界转换。后端每次评估对应一条 `fa_user_info`，其报告和产品快照保存在唯一关联的 `fa_ai_chat` 中。后端数据库及生命周期服务已准备，移动端已切换真实本地接口，未完成的评估、AI、上传及授权接口不会模拟成功，需按开发进度继续接入。


## 2026-09-22 开发启动状态

- 登录默认使用密码模式；需已有手机号账户。尚未配置短信服务商，发送验证码会展示后端503提示，不启动倒计时或生成demo Token。
- 会话包含userId/有效期，旧无身份的模拟会话作废。草稿、临时评估状态、昵称头像、课程本机进度、体验签到和消息已读统一经 `services/storage.uts` 按userId隔离。旧设备级草稿保留但不自动分配给登录用户；显式导入和敏感缓存生命周期后续补齐。
- 首批真实接口不等于25页已业务化。首页/资讯/课程等部分展示仍为原型；评估提交、产品匹配和AI助手接口尚未实现。各模块状态以 [开发进度](docs/开发进度.md)为准。
- 默认开发环境不代表正式部署；发布前需核验目标环境、API地址、HTTPS/CORS及所有必做依赖，禁止把本机地址作为生产配置。