xuanzhi-wx/AGENTS.md

AI 开发入口 [!IMPORTANT]

• 本文档要求：本文档为当前仓库的项目级规范和重要导航，进入源码前必须先读。
• 本文档要求：优先在现有目录职责内做增删改；若要新增一级目录、基础设施或工程约定，必须先更新本文档和对应文档。
• 本文档要求：后续新增/删除 .ai-specs 文档时，必须同步更新 ## 项目文档。
• 文档要求：规范型文档是给 AI 的顶层入口文档，要求短、硬、可判定，不写泛泛背景说明。
• 代码优化：先复用再新增；允许抽公共逻辑，但边界必须清晰。
• 代码优化：优化时必须同时考虑冗余、命名、复杂度、边界条件、兼容性和包体积，不能只追求功能跑通。不要擅自修改 UI/UX 视觉效果，除非需求明确。
• 代码默认遵循：业务实现优先采用微信原生小程序主流做法，保持可维护、可调试、可发布。
• 代码默认遵循：强制工作流：按 ## 项目文档 定位需要的文档 -> 读取匹配文档 -> 进入源码。

工具使用规则

• 搜索范围限制：Grep/Glob 严禁全盘搜索，绝对禁止扫描 node_modules、miniprogram_npm、coverage 等生成或依赖目录。
• 读写：所有文件读取/写入统一使用 UTF-8（建议无 BOM）。
• 读写：PowerShell/脚本读取项目文件必须显式指定 -Encoding utf8。
• 生成产物：不要直接编辑微信开发者工具生成目录，例如 miniprogram_npm。
• 画图：优先使用 mermaid flowchart。
• 对话/文档编写：必须以中文为主体语言，技术术语保留英文原文。
• 命令执行：运行依赖、测试、格式化、CI 前，先读取 package.json 中已有 scripts，不重复发明命令入口。

项目架构

• 技术栈：本项目为 微信原生小程序 + JavaScript + npm + TDesign，运行时采用 glass-easel 组件框架；工程化使用 ESLint、Prettier、Jest、miniprogram-ci。

• 代码链路：本项目采用 Page / Component -> services/api -> services/request -> RuntimeConfig / SessionStore -> Backend。

• 状态与配置：config 管理环境与常量，stores 管理跨页共享状态，utils 只放纯工具函数。

  ├── app.js / app.json / app.wxss (应用初始化、路由注册、全局样式) ├── pages (主包页面：首屏、登录、公共能力) ├── packages (分包页面，按业务域拆分) ├── components │ ├── base (基础组件) │ └── biz (业务组件) ├── services │ ├── api (按业务模块封装接口) │ └── request (统一请求、鉴权、重试、去重) ├── stores │ └── modules (跨页共享状态) ├── config (环境配置、常量) ├── utils (纯工具函数) ├── tests (Jest 测试) └── scripts/ci (小程序 CI 脚本)

层级	职责	命名规范
App	初始化运行时配置、注册全局拦截与跳转、同步 globalData	固定使用 app.js、app.json、app.wxss
Page	承载页面数据、交互、路由跳转；不直接承载通用请求封装与跨页状态持久化	主包目录固定 pages/<name>/index.*；分包目录固定 packages/<pkg>/pages/<name>/index.*
Component	承载可复用视图和局部交互，通过 properties / events 与页面通信	基础组件放 components/base/<name>；业务组件放 components/biz/<name>
API	按业务封装接口方法，屏蔽 URL / Method / payload 细节；不直接持有页面 UI 状态	目录固定 services/api/<module>.js；聚合出口固定 services/api/index.js
Request	统一处理 baseURL、header、token、超时、鉴权失效、重试和请求去重	目录固定 services/request/index.js
Store	管理跨页共享和本地持久化状态；不与具体页面强耦合	模块固定 stores/modules/<name>.js；聚合出口固定 stores/index.js
Config	管理环境、常量、timeout、storage key；避免魔法值散落	目录固定 config/*.js
Utils	存放纯函数；禁止依赖页面实例、组件实例或全局 UI 状态	目录固定 utils/*.js

• 主包只放首屏、登录、Tab 和全局公共能力；新业务页面优先考虑放进对应分包。
• 页面和组件里不要直接调用 wx.request；统一走 services/request。
• 跨页共享状态统一放 stores；页面局部状态留在 Page / Component 的 data 内。
• 环境切换、baseURL 和 timeout 统一走 config/env.js 与 config/constants.js。
• 新增接口模块时，先补 services/api/<module>.js，再决定页面如何消费；不要把请求细节散落到页面。

架构关系

• 关系总线：Page / Component -> API -> Request -> Env + SessionStore -> Backend，其中 app.js 负责运行时初始化、登录态同步和未授权跳转。

flowchart LR
    APP["app.js<br/>运行时初始化 / 未授权跳转"] --> SESSION["stores/modules/session.js<br/>登录态持久化"]
    PAGE["Page / Component"] --> API["services/api/*.js"]
    PAGE --> COMPONENT["components/base + components/biz"]
    API --> REQUEST["services/request/index.js"]
    REQUEST --> ENV["config/env.js"]
    REQUEST --> SESSION
    SESSION --> STORAGE["wx storage"]
    REQUEST --> BACKEND["Backend API"]

• 改 app.json：必须同步检查 pages、subPackages、preloadRule、实际目录路径和页面跳转路径是否一致。
• 改 pages/* 或 packages/*：必须同步检查路由注册、导航目标、页面 JSON 中的组件注册、对应 API / Store 依赖。
• 改 components/base/* 或 components/biz/*：必须同步检查 index.js、index.json、index.wxml、index.wxss 四件套，以及引用方的 properties / events 契约。
• 改 services/api/*：必须同步检查 URL、Method、payload、response contract 和所有调用页的 loading / error / empty state。
• 改 services/request/index.js：必须同步检查 config/env.js、config/constants.js、stores/modules/session.js、app.js 的未授权处理，以及所有 API 模块的调用预期。
• 改 stores/modules/session.js：必须同步检查 storage key、app.js 中的 hydrate / subscribe、登录页和依赖权限的页面逻辑。
• 改 config/env.js 或 config/constants.js：必须同步检查请求层默认值、环境切换行为、CI 脚本和登录态相关逻辑。
• 新增/修改业务功能时，默认顺序是：先定页面归属与路由 -> 再定 API / Store 契约 -> 再落页面与组件 -> 最后回查 app.json、聚合导出和项目文档；禁止只改单点不回查上下游。

项目文档

• 当前已启用文档：根目录 README.md
• 预留扩展目录：.ai-specs（当前未创建；一旦创建必须在本节登记）
• 要求：开始修改前，先按任务类型定位文档；有对应文档必须先读；未命中时按本文件通用规则和现有同层代码风格实现。

root-docs

路径	用途	说明
README.md	项目启动、目录、命令、CI、分包落点说明	涉及本地运行、构建 npm、测试、格式化、CI 上传、目录归属时必读

.ai-specs 规划

分类	用途	说明
coding-specs	存放页面分包、接口封装、状态管理、组件复用等实现规范	仓库复杂度上来后优先补齐
logic-specs	存放业务流程、页面信息架构、角色权限等业务说明	涉及多页面串联和复杂交互时补齐
sys-specs	存放环境、发布、CI、版本管理等系统级规则	涉及发布流程和工程治理时补齐

可复用代码/组件

中文	代码文件名	说明
统一请求封装	services/request/index.js	统一处理 baseURL、token 注入、鉴权失效、超时、重试和请求去重
用户接口模块	services/api/user.js	用户资料查询与更新的 API 封装示例
Session Store	stores/modules/session.js	登录态持久化、hydrate、订阅变更
Store 聚合出口	stores/index.js	统一导出 store，供 app.js 和页面引用
App Button	components/base/app-button	基础按钮组件，透出常用主题、尺寸和形态
Entry Card	components/biz/entry-card	首页 / 工作台入口卡片组件
运行时环境配置	config/env.js	根据微信环境选择 baseURL 与 timeout