docs: 重写 AGENTS.md 和 README.md 项目文档

- AGENTS.md 精简 Codex 协作说明，聚焦扫码打卡链路等既有约定
- README.md 补充核心功能、目录结构、开发命令等项目描述

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

-## 项目介绍
+# lls_program
 
-基于Taro4的微信小程序模版，集成了常用的功能，如登录、注册、列表、详情、购物车等。
+`lls_program` 是一个基于 Taro 4 + Vue 3 + NutUI 的微信小程序项目，当前业务围绕家庭管理、活动参与、积分奖励，以及海报/扫码打卡展开。
+
+这不是一个通用模板仓库。当前代码里已经有比较明确的业务结构，尤其是扫码打卡链路、资料补全链路、家庭创建/加入链路，后续开发建议直接沿用现有实现方式，而不是重新搭一套平行流程。
 
 ## 技术栈
 
-- Taro4
-- Vue3
-- TypeScript
-- Pinia
+- Taro `4.1.7`
+- Vue `3.3`
+- NutUI Taro `4.3.13`
+- Pinia `3.0`
+- TailwindCSS `3.4`
 - Less
+- axios-miniprogram
+- Vitest
+
+## 核心功能
+
+- 微信小程序登录与静默授权
+- 家庭创建、加入、家庭资料维护
+- 用户资料补全与注册来源归因
+- 活动详情、海报打卡、扫码打卡
+- 积分、奖励、优惠券相关页面
+- 地理位置相关能力与位置权限接入
+
+## 当前重点业务链路
+
+### 扫码打卡
+
+当前扫码打卡已接入真实接口，主要页面和工具如下：
+
+- 列表页：`src/pages/ScanCheckinList/index.vue`
+- 详情页：`src/pages/ScanCheckinDetail/index.vue`
+- API：`src/api/map.js`
+- 地理围栏：`src/utils/checkinLocation.js`
+- 扫码参数解析：`src/utils/scanCheckin.js`
+- 回跳参数处理：`src/utils/returnUrl.js`
+- 富文本渲染：`src/components/RichTextRenderer.vue`
+
+当前流程：
+
+1. 用户进入扫码打卡详情页
+2. 点击“扫码打卡”时先检查是否已有家庭
+3. 没有家庭则提示后跳转 `Welcome`
+4. `Welcome -> AddProfile -> Welcome -> CreateFamily/JoinFamily -> 原详情页`
+5. 返回详情页后再次扫码
+6. 若关卡启用地理围栏，先重新静默获取当前位置并判断范围
+7. 调起微信扫码
+8. 从二维码结果中解析真实的 `activity_id` / `detail_id`
+9. 调用真实打卡接口
+10. 成功后跳到扫码关卡列表页
+
+补充约定：
+
+- 打卡参数来自二维码内容，不来自当前页面路由参数
+- 注册来源归因目前通过 `reg_source`、`reg_stage_id` 透传
+- `reg_activity_id` 已经不再使用
+- `return_url` 回跳统一通过 `src/utils/returnUrl.js` 处理
 
 ## 项目结构
 
-- src
-  - api：请求接口
-  - assets：静态资源
-  - components：全局组件
-  - config：项目配置
-  - pages：页面
-  - stores：状态管理
-  - utils：工具函数
-  - app.config.js：项目配置
-  - app.js：应用入口
-  - app.less：全局样式
-- taro.config.js：Taro配置
-- tsconfig.json：TypeScript配置
-- package.json：依赖配置
-
-## 项目运行
-
-1. 安装依赖
+```text
+src/
+├── api/                    # 接口定义，只放请求相关代码
+├── assets/                 # 静态资源
+├── components/             # 通用组件
+├── pages/                  # 页面
+├── stores/                 # Pinia 状态管理
+├── utils/                  # 工具函数、流程辅助
+├── app.config.js           # 页面注册、权限声明
+└── app.less                # 全局样式
+```
+
+几个常用目录说明：
+
+- `src/api/user.js`：用户认证、资料接口
+- `src/api/family.js`：家庭相关接口
+- `src/api/map.js`：地图、扫码关卡、扫码打卡相关接口
+- `src/utils/request.js`：请求拦截器、`sessionid` 注入
+- `src/utils/userProfile.js`：资料相关 helper
+- `src/components/RichTextRenderer.vue`：富文本渲染组件
+
+## 开发约定
+
+### API 与 helper 分层
+
+- `src/api/*.js` 只放接口调用
+- 参数拼装、字段解析、距离计算、回跳处理等逻辑放 `src/utils/`
+
+例如：
+
+- `buildUpdateUserProfilePayload` 在 `src/utils/userProfile.js`
+- 扫码结果解析在 `src/utils/scanCheckin.js`
+- 地理围栏判断在 `src/utils/checkinLocation.js`
+
+### 请求返回判断
+
+所有接口都要显式判断：
+
+```javascript
+if (res.code === 1) {
+  // success
+}
+```
+
+不要写成：
+
+```javascript
+if (res.code) {
+  // 不推荐
+}
+```
+
+### 小程序环境约束
+
+页面里不要使用浏览器 API：
+
+- `window`
+- `document`
+- `localStorage`
+- 原生 `fetch`
+
+统一使用 Taro API：
+
+- `Taro.navigateTo`
+- `Taro.redirectTo`
+- `Taro.switchTab`
+- `Taro.scanCode`
+- `Taro.getLocation`
+
+### 页面生命周期
+
+页面优先使用 Taro 提供的生命周期：
+
+- `useLoad`
+- `useShow`
+- `useDidShow`
+- `useReady`
+
+## 登录与认证
+
+项目当前通过 `sessionid` 维持服务端登录态：
+
+- 从 storage 读取 `sessionid`
+- 在请求拦截器中注入到 `cookie`
+- 401 交给现有授权/跳转逻辑处理
+
+需要注意：
+
+- `sessionid` 只是认证凭证
+- 它不等于“用户一定能继续后续业务流程”
+- 业务上是否可继续，仍要结合资料、家庭、活动规则等条件判断
+
+## 本地开发
+
+### 安装依赖
 
 ```bash
 npm install
 ```
 
-2. 运行项目
+### 微信小程序开发
 
 ```bash
 npm run dev:weapp
 ```
 
-3. 打包项目
+### 微信小程序构建
 
 ```bash
 npm run build:weapp
 ```
+
+### 其他常用命令
+
+```bash
+npm run dev:h5
+npm run dev:alipay
+npm run dev:tt
+npm run lint
+npm run format
+npm run test:run
+```
+
+## 页面注册与权限
+
+页面统一在 `src/app.config.js` 中注册。
+
+当前已经声明位置相关能力：
+
+- `requiredPrivateInfos: ['getLocation']`
+- `permission.scope.userLocation`
+
+这也是扫码打卡地理围栏能力能直接接上的基础配置。
+
+## 备注
+
+- NutUI 组件是自动导入的，不需要手动 import
+- `ScanCheckinDetail` 顶部 banner 现在使用 NutUI `nut-swiper`
+- `ScanCheckinDetail` 富文本展示统一使用 `RichTextRenderer`
+- 如果只是调整扫码详情页底部按钮视觉位置，优先改样式，不要顺手改业务逻辑